MCME-Warps is the network's warp system. Players teleport to named places with /warp <name>, staff keep a set of public landmarks, and players keep their own private warps. A warp records the server and world it points at, so /warp can move a player to another backend server first. The plugin replaced the third-party MyWarp plugin and stores warps as YAML files, not in a database. This page describes 1.0.7, the latest release, from the MCME/MCME-Warps repository.

At a glance

How the code is organised

The guiding rule is the proxy decides, the backend acts. The Velocity half owns every warp, the config, all commands and permissions, and teleport routing. The Paper half executes teleports and draws Dynmap markers; it holds no state of its own.

src/main/java/com/mcmiddleearth/warps/
├── core/        shared by both halves (must not import Velocity or Bukkit classes)
│   ├── BaseWarp, SimpleLocation, WarpIcon, Utils, WarpLoader, SafeEnumSerializer
│   ├── Channels                 the three plugin-message channel names
│   └── messageprotocols/        the wire protocol (MessageFrame and the message classes)
├── velocity/    the proxy plugin
│   ├── WarpVelocity             @Plugin entry point: registers channels, loads config and warps, builds the commands
│   ├── Permission               every permission node, as an enum
│   ├── commands/                one class per Brigadier command, plus helpers/
│   ├── config/                  Config record + ConfigManager
│   ├── listener/MessageListener backend -> proxy messages
│   └── warps/                   the store: Warp, WarpManager, WarpStore, WarpFileIo, ConfigurateWarpIo, WarpPaths, ...
└── paper/       the backend plugin
    ├── WarpPaper                JavaPlugin entry point
    ├── WarpWatcher              watches the warps folder and updates map markers
    ├── DynmapAPI, MapAPI, Layer, LayerParser   Dynmap markers and layer config
    └── listener/MessageListener proxy -> backend messages

Key ideas:

• Storage. The proxy keeps one YAML file per warp: warps/<server>/<world>/<name>.yml for a public warp and warps/private-warps/<creatorId>/<name>.yml for a private one. Public warp names are unique across the network; private warps are keyed by creator and name, so two players can each own a home. A player's own private warp wins over a public warp of the same name.
• The store seam. All state and file writes go through WarpStore. WarpManager is a thin static facade over it, and disk access sits behind the WarpFileIo interface (ConfigurateWarpIo in production, a fake in tests). A change is written to disk before it shows in memory, a delete removes the file before the warp is forgotten, and a reload swaps in a complete new set in one step. Never load-modify-save a warp file directly.
• Names. Utils.normaliseString defines the lookup key (accents stripped, apostrophes dropped, spaces collapsed, lower case). WarpPaths turns a warp into its file path and refuses any path outside the warps folder.
• Visit counts are kept in memory and written on proxy shutdown, proxy reload and /wmanage reload.
• The backend's view of the data. The Paper half reads warp files from its own warps/ folder, which the README says to link to the proxy's per-server folder. Private warps live outside the per-server folders, so they never reach a backend or the map.
• Version string. Set it once, in build.gradle. It is filled into plugin.yml and into a generated BuildConstants class for the Velocity @Plugin annotation.

Building and testing

./gradlew build       # tests + the fat jar
./gradlew shadowJar   # jar only -> build/libs/MCME-Warps-<version>.jar
./gradlew test        # tests only

• JDK 25 is required. paper-api 26.x declares a Java 25 minimum in its Gradle metadata, and the jar is Java 25 bytecode.
• The Shadow plugin bundles the runtime dependencies (commons-text, relocated; mysql-connector-j, SquirrelID and fzf4j). paper-api, velocity-api, DynmapCoreAPI and configurate-yaml are compileOnly.
• Tests use JUnit Jupiter (junit-bom 6.1.3) and need no running server: WarpStoreTest (the store, including failed writes and deletes), MessageProtocolTest (round trips, stable opcodes, rejecting bad messages), WarpManagerPathTest (path containment), LayerParserTest (backend layer config), WarpTest and ConfigTest. Command classes and the two message listeners are not unit-tested; put logic worth testing in a pure helper.
• ./gradlew runVelocity and ./gradlew runServer (the run-paper / run-velocity plugins) start a local Velocity 3.4.0 proxy and a Paper 26.2 server with the jar installed. The DEV_MANUAL lists the forwarding settings that make them trust each other.

CI (.github/workflows/build.yml) builds and tests every push and pull request with JDK 25 and keeps the jar as a workflow artifact named MCME-Warps-<version>-<DEV|SNAPSHOT|RELEASE>-<commit>. A v* tag must match the version in build.gradle and sit on the release branch (a pre-release tag such as v1.1.0-rc1 may also come from development); it then creates a GitHub release with the jar and its SHA-256. MCME-Warps does not publish to the Maven repository.

Configuration

Proxy: plugins/mcme-warps-velocity/config.yml. Copied from default-velocity-config.yml on first start and read through Configurate into the Config record.

Backend: plugins/MCME-Warps-Paper/config.yml.

Run /wmanage reload (or reload the proxy) after changing the proxy config.

Commands and permissions

All commands are registered by the Velocity half with Brigadier. Subcommand names are case-sensitive (setPublic, not setpublic). The Paper half registers no commands.

The edit subcommands (delete, rename, move, members, setWelcome) only show for a player who can modify at least one warp.

These permissions are checked on the proxy, so they come from the proxy's permission plugin; there are no built-in defaults.

The warps manual explains the commands for players and staff.

APIs and extension points

MCME-Warps has no Java API for other plugins. Its extension points are inside the repository:

• Adding a command: write a class in velocity/commands/ with a register(Predicate<CommandSource>) method returning a Brigadier builder, add a node to the Permission enum, and wire it into the command tree in WarpVelocity.onProxyInitialization. Route every warp change through WarpManager.
• Adding a store operation: add it to WarpStore (write or delete on disk before changing memory), expose it on WarpManager, and add a WarpStoreTest case that injects a failed write.
• Adding a message or field: see the protocol below. Any layout change means bumping MessageFrame.PROTOCOL_VERSION.
• Re-check permissions inside message handlers. A handler reached through a plugin message must not assume the command that started it was allowed; the create and move handlers check permission and ownership again when the backend's reply arrives.

How it talks to other plugins and systems

The two halves talk over three plugin-message channels (core/Channels.java). Every message is a MessageFrame: byte 0 is the protocol version, byte 1 a stable opcode, then the body. A receiver on another protocol version rejects the whole message and logs that both jars need the same version, so the proxy and the backends must always run the same MCME-Warps version.

The proxy registers all three channels and consumes every message on them, so a message sent by a player's client is never passed on to a backend.

sequenceDiagram
    participant P as Player
    participant V as MCME-Warps-Velocity (proxy)
    participant B as MCME-Warps-Paper (target backend)
    P->>V: /warp Rivendell
    V->>V: look up warp, check access
    alt warp is on another server
        V->>P: connect player to the warp's server
    end
    V->>B: mcme:warp TeleportMessage
    B->>P: teleport
    B->>V: TeleportResult
    V->>V: count the visit

Creating or moving a warp is the reverse round trip: the proxy sends RequestLocationMessage, the backend answers with PlayerLocationMessage, and the proxy writes the warp.

tools/convert_warps.py (Python 3, standard library) is the one-time migration that removed the old zzz-<player>- prefix from private warp names; its README describes it.

Further reading

• README, Developer manual and User manual on GitHub
• Setting up for the JDK and Gradle
• Warps manual