# Warps

Server-wide teleport destinations in three types: **server warps** (admin), **player warps** (bought by players, always public) and **team warps**. Teams choose per warp whether it is **public** (shows up in /warps like any other warp, just owned by a team) or **team-only** (appears exclusively in the team menu under Home & Warps and in the team tab of the web panel). Warp jumps run through the [teleport engine](teleport.html).

## Commands

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| `/warp` | `/warp <name>` | `warp.use` | `true` | Teleports to a warp |
| `/warps` | `/warps` (alias `/warplist`) | `warp.use` | `true` | Warp browser GUI with category and type filters |
| `/warp create` | `/warp create <player\|team> <name> [category] [public\|private]` | `warp.player.use` / `warp.team.use` | `true` | Buys a warp at your position (team warps default to team-only) |
| `/warp delete` | `/warp delete <name>` | `warp.player.use` / `warp.team.use` | `true` | Deletes your warp (free) |
| `/warp move` | `/warp move <name>` | like create | `true` | Moves it to your position (edit cost) |
| `/warp rename` | `/warp rename <name> <new>` | like create | `true` | Renames it (edit cost) |
| `/warp icon` | `/warp icon <name>` | like create | `true` | Icon = item in main hand (edit cost) |
| `/warp desc` | `/warp desc <name> <text>` | like create | `true` | Description, max 128 characters (edit cost) |
| `/warp category` | `/warp category <name> <category>` | like create | `true` | Changes the category (edit cost) |
| `/warp list` | `/warp list` | like create | `true` | Your own and team warps incl. limit |
| `/setwarp` | `/setwarp <name> [permission] [icon] [group]` | `warp.admin` | `false` | Sets/overwrites a server warp (`-` = skip a parameter) |
| `/delwarp` | `/delwarp <name>` (alias `/removewarp`, `/remwarp`) | `warp.admin` | `false` | Deletes a server warp |

## Additional permissions

| Permission | Default | Description |
|---|---|---|
| `warp.player.limit.<n>` | `false` | Raises the player warp limit to n (highest value wins, hard cap 100) |
| `warp.player.limit.unlimited` | `false` | Removes the player warp limit (cap stays 100) |

## Warp browser (GUI)

`/warps` opens the warp browser. It lists server warps, player warps and public team warps; team-only warps never appear here, not even for their own members (they live in the team menu). Everything around warps works entirely without commands:

- **Top row:** category filter. The nether star shows all categories; next to it every configured category appears, even ones that are still empty. The active filter glows.
- **Type filter:** the hopper at the bottom cycles between all warps, server warps, player warps and team warps.
- **Clicking a warp:** left-click teleports (any cost shows in the description). Right-click opens management when the warp is yours, you hold the team right Manage Warps, or you have `warp.admin`.
- **My warps:** the ender pearl at the bottom left shows only the warps you can manage yourself.

### Creating a warp

Left-click on the emerald starts a player warp, right-click a team warp, shift-click an admin warp (needs `warp.admin`). First the name is typed in an anvil (it checks live whether the name is free and valid), then the **setup menu** opens: icon, category, description and, for team warps, the visibility (public or team-only) are all configured BEFORE paying. Only the create button charges the creation price, so no edit costs are ever needed for the initial setup. Cancelling discards the draft for free.

### Warp management

Management shows every function as a button, each action states its cost up front:

| Button | Function |
|---|---|
| Ender pearl | Teleports to the warp |
| Recovery compass | Moves the warp to your position |
| Name tag | Renames the warp (anvil input) |
| Painting | Changes the icon: the item in your main hand becomes the icon (the button explains it) |
| Book | Opens the category picker |
| Book and quill | Type the description in chat (up to 128 characters), right-click clears it |
| Ender pearl/eye | Team warps only: toggles the visibility (public or team-only) |
| TNT | Deletes the warp: for safety you retype the warp name in an anvil |

Your own warps cost the configured edit price per change. Admins manage server warps and foreign warps free of charge and additionally see a button for the warp permission on server warps.

> **Note:** Warp names are unique across all types; the management words (`create`, `delete`, `move`, ...) are reserved as names. Team-only warps are reported as "not found" to outsiders. All checks (limit, name, category, world, foreign claims) run BEFORE charging; edits cost the price times the number of changed fields and are charged only after full validation.

## Team warps

Team warps belong to the team, not to a player. Creating, editing and deleting needs the team right **Manage Warps**, using them the team right **Use Warps** (both configurable per rank). They are created in the warp browser, in the team menu under Home & Warps, or with `/team setwarp <name>`; the team menu lists all team warps including team-only ones. The creator pays the creation cost. Public team warps can be used by everyone, team-only ones by members only. The per-team limit is configured by the admin (`default-limit`), or grows with the team level instead.

## Configuration (modules/warps.yml)

```yaml
# Enables or disables the warp module.
enabled: true

warps:
  # Maximum warp name length.
  max-name-length: 32
  # Categories players may pick on create/category.
  categories:
    - "General"
    - "Shops"
    - "Farms"
    - "Arenas"
    - "Bases"
  # Category /setwarp assigns automatically (never selectable by players).
  admin-category: "Admin"
  # Worlds where player/team warps may be created. Empty = all worlds.
  creation-worlds: []
  player-warps:
    # May players buy personal warps?
    enabled: true
    # One-time creation price (icon/category/description included).
    create-cost: 5000
    # Fixed price PER edit action (move, rename, icon, desc, category).
    edit-cost: 1000
    # Warps without extra permission. More via warp.player.limit.<n>.
    default-limit: 1
  team-warps:
    # Creating/editing needs the team right MANAGE_WARPS.
    # Limit = team level: level 1 = 1 warp, each level adds one.
    enabled: true
    create-cost: 5000
    edit-cost: 1000
  # Allowed icon materials. Empty = built-in default set.
  allowed-icons: []

cooldown:
  commands:
    warp: 5

cost:
  commands:
    warp: 0

warmup:
  commands:
    warp:
      duration: 3
```

## Complete example config

```yaml
enabled: true

warps:
  max-name-length: 24
  categories:
    - "Cities"
    - "Shops"
    - "Farms"
    - "Events"
  admin-category: "Server"
  creation-worlds:
    - world
  player-warps:
    enabled: true
    create-cost: 10000
    edit-cost: 2500
    default-limit: 2
  team-warps:
    enabled: true
    create-cost: 7500
    edit-cost: 2000
  allowed-icons: []

cooldown:
  commands:
    warp: 15

cost:
  commands:
    warp: 5.0

warmup:
  commands:
    warp:
      duration: 5
```