Warps

Commands

Configuration

All warp settings live under the warp: section in config.yml.

warp:
  # Enable or disable the warp system entirely.
  enabled: true

  # Seconds between warp teleports for the same player.
  # Set to 0 to disable. Bypassed by: essentialsc.warp.bypass.cooldown
  cooldown: 5

  # Seconds the player must stand still before teleporting.
  # Set to 0 for instant teleport. Bypassed by: essentialsc.warp.bypass.warmup
  warmup: 3

  # Cancel the warp if the player moves during warmup.
  cancel-on-movement: true

  # Play particles on arrival.
  particles: true

  # Play sounds during warp events.
  sounds: true

  # Worlds where /warp is completely blocked.
  blocked-worlds:
    - world_example_blocked

  # Maximum length of a warp name.
  max-name-length: 16

  # Limit how many warps each player can create.
  # Warps are counted by the prefix "PlayerName_".
  limit-enabled: true
  max-per-player: 5

  # Group the /warps list by category instead of a flat alphabetical list.
  group-by-category: false

Permissions

Warp Names

Warp names must follow these rules:

• Characters — Only letters, numbers, underscores, and hyphens: ^[a-zA-Z0-9_-]+$
• Length — Maximum 16 characters (configurable via warp.max-name-length)
• Case — Names are case-insensitive for lookup. Spawn and spawn refer to the same warp.
• Uniqueness — Warp names are globally unique across the entire server. You cannot have two warps named spawn.

A common naming convention for player-owned warps is PlayerName_warpname (e.g., GodlyCow_shop). This makes per-player limit counting work correctly.

Teleport Mechanics

When you run /warp <name>, the teleport goes through several checks in this order:

1. Warp existence — The warp must exist in the database and cache.
2. Per-warp permission — If the warp has a permission set (via /warpadmin setperm), the player must have it. Bypassed by essentialsc.warp.bypass.
3. Blocked world check — If the player is in a world listed in warp.blocked-worlds, the teleport is cancelled.
4. Cooldown — If the player warped recently, they must wait. Bypassed by essentialsc.warp.bypass.cooldown.
5. Economy cost — If the warp has a cost and Vault is hooked, the player's balance is checked. Insufficient funds cancel the teleport. Bypassed by essentialsc.warp.free.
6. Warmup — If warmup is enabled, the player must stand still. Moving cancels the teleport if cancel-on-movement is true. Countdown ticks play a pling sound that increases in pitch during the last 3 seconds.
7. Async teleport — The actual teleport is performed asynchronously (safe for Folia).
8. Effects — Portal and End Rod particles spawn at the destination. An Enderman teleport sound plays. Usage is recorded in the database.

Quitting the server while a warmup is active automatically cancels the pending teleport and clears all tracking state.

Admin Management

The /warpadmin command provides full control over individual warps:

Database

Warps are stored in plugins/EssentialsC/database/warps.db (SQLite). The schema is:

CREATE TABLE warps (
    name TEXT PRIMARY KEY,
    world TEXT NOT NULL,
    x REAL NOT NULL,
    y REAL NOT NULL,
    z REAL NOT NULL,
    yaw REAL NOT NULL,
    pitch REAL NOT NULL,
    permission TEXT,
    cost REAL DEFAULT 0.0,
    hidden INTEGER DEFAULT 0,
    description TEXT DEFAULT '',
    category TEXT DEFAULT 'default'
);

CREATE TABLE player_warp_usage (
    uuid TEXT NOT NULL,
    warp_name TEXT NOT NULL,
    uses INTEGER DEFAULT 0,
    last_used INTEGER DEFAULT 0,
    PRIMARY KEY (uuid, warp_name)
);

All database operations are async. A memory cache of all warps is maintained for instant lookup and tab-completion. The cache is rebuilt on /warpadmin reload and /essc reload. Usage statistics are tracked per player per warp for analytics.

Warp Listing

The /warps command supports two display modes controlled by warp.group-by-category:

• Flat mode (default) — All visible warps sorted alphabetically, 20 per page. Warp names are clickable MiniMessage components that run /warp <name> on click.
• Category mode — Warps grouped by their category header, then sorted alphabetically within each group. Same pagination applies.

Hovering over a warp name in the list shows its description and cost (if economy is enabled and cost is greater than 0). Hidden warps are excluded from the list entirely. Warps with permission requirements are only shown to players who have that permission.

Migration from EssentialsX

When migrating from EssentialsX, warps are imported from plugins/Essentials/warps/<name>.yml:

• Each .yml file in the warps/ folder becomes one database record
• World name, coordinates, yaw, and pitch are preserved exactly
• Default category is default, cost is 0.0, hidden is false
• Conflicting warp names use the migration conflict strategy (skip, overwrite, or rename)

Run /migration essentialsx to start the import. See the Migration Guide for full details.

Troubleshooting

"You have reached the warp limit"

The player has hit their per-player warp creation limit (warp.max-per-player). Grant essentialsc.setwarp.unlimited to bypass, or increase the config limit.

"Warp teleport blocked in this world"

The player is in a world listed in warp.blocked-worlds. Remove the world from the config or grant essentialsc.warp.bypass.

"You do not have permission for this warp"

The warp has a per-warp permission set via /warpadmin setperm. Grant the specific permission to the player, or use /warpadmin setperm <warp> none to make it public.

Warp not found after world rename

Warps store the world name (not UUID). If you rename the world folder, warps in that world will fail to load. Use /warpadmin move <warp> to relocate them, or manually update the world column in warps.db.

Cost not deducting

Ensure Vault is installed, the economy module is enabled (economy.enabled: true), and the player has sufficient funds. Check console for Vault hook errors on startup.

Warmup sounds not playing

Check that warp.sounds: true is set in config. The pling sound during warmup and the Enderman teleport on arrival both require this to be enabled.

Next Steps