Warps

Warps are named teleport points owned by a town. Each warp tracks its weekly visit count so that the warp list can be sorted by popularity, and players can pin warps as favourites.

Model

Field	Type	Description
`uniqueId`	UUID	Primary key.
`townId`	UUID	Owning town.
`name`	String	Unique within the town.
`world`/`x`/`y`/`z`/`yaw`/`pitch`	location	Stored as `NetworkLocation`.
`serverId`	UUID	Origin server.
`weeklyVisits`	int	Transient counter materialised from the `warp_visits` table.

CRUD

Command	Permission	Effect
`/town warp create <name>`	`WARPS`	Records the player's current position. Must be inside a town claim (`WARP_NOT_IN_TOWN_CLAIM`). Validated for name length and uniqueness.
`/town warp delete <name>`	`WARPS`	Removes the warp.
`/town warp list`	member	Opens the warp menu.
`/town warp <name>`	depends	Teleports the player.

/townwarp is registered as a short-form alias.

Teleport

Teleport rejects:

Cause	Message
Warp does not exist in the selected town	`WARP_NOT_FOUND`
Player is banned from the warp's town	`WARP_TELEPORT_BANNED`
Anyone obstructs the warp location	`CANNOT_OBSTRUCT_WARP`

Successful teleport sends TELEPORTED_TO_WARP and records a row in warp_visits (used to compute weeklyVisits).

WarpListener blocks block placement that would obstruct the warp.

Sorted listing

WarpService.sortedWarps() returns every cached warp ordered by weeklyVisits descending. The %towns_warps% placeholder returns the sorted list as an ItemProvider so menus can paginate it without extra wiring.

Favourites (pins)

Each player can pin warps to their TownPlayerData.favoriteWarps set via the pin-warp action:

- "[pin-warp] %warp_id%"

The action toggles — pinning an already-pinned warp removes it. Confirmation messages: WARP_PINNED/WARP_UNPINNED.

%towns_favoriteWarps% returns the player's pinned warps as an ItemProvider.

The %warp_pinned% placeholder is true when the viewer has the warp pinned, so you can build a one-menu toggle:

items:
  pin-button:
    item-stack:
      material: NETHER_STAR
      name: "%warp_pinned% ? <yellow>Unpin : <gold>Pin"
    actions:
      LEFT:
        - "[pin-warp] %warp_id%"
        - "[refresh]"

Last modified: 25 July 2026