TheGaffer is MCME's build-protection plugin for the build map. The map is read-only by default: nobody may place or break a block unless TheGaffer allows it. Staff open a job, a bounded square area in one world where invited builders may build while the job runs; when the job ends, the area locks again. Since 3.0.0 TheGaffer also keeps jobs across restarts, counts what each builder places and breaks, groups jobs into projects, and ships a small Velocity proxy plugin so a builder can join a job running on any server. Other build tools, MCME-Architect in particular, ask TheGaffer whether a player may build at a spot. The code is on GitHub at MCME/TheGaffer; this page describes release 3.0.1 on master.

At a glance

How the code is organised

Three Maven modules under the parent com.mcmiddleearth:thegaffer-parent:

Packages in thegaffer-paper (all under com.mcmiddleearth.thegaffer):

How protection decides. Every place, break and protected interaction goes through ProtectionUtil.getBuildProtection(player, location), which returns a BuildProtection value with a message:

1. If any configured external deny handler says yes, the action is refused (this is checked first, before the bypass permission).
2. The action is allowed if the player has thegaffer.ignoreprotection, the world is listed in unprotectedworlds, or an external allow handler says yes.
3. Otherwise the player must be working in a running job, in the job's world, inside its area, and the job must not be paused. Each failure has its own refusal (no job, wrong world, not in a job, out of bounds, paused).

Storage. Jobs, projects and statistics are YAML files in plugins/TheGaffer/: jobs/<name>.yml (written atomically), projects/<name>.yml, stats/<job>-<endTime>.yml for finished jobs, and stats/active/ for live snapshots that survive a crash. Jobs are held in memory with a dirty flag, flushed every 60 seconds (the file write off the main thread) and synchronously on disable. Identity is by UUID; the scoreboard glow teams are the only thing keyed by name, because Bukkit's team API is name-based.

Building and testing

export JAVA_HOME="/path/to/jdk-25"
mvn -B package        # both jars
mvn -B test           # the test suite (200 tests in 3.0.1)

• JDK 25 is required even though the output targets Java 17 and 21: paper-api 26.2 ships Java 25 class files, and an older javac fails with cannot access org.bukkit.*. The poms use -source/-target rather than --release so a newer compiler can read the newer API.
• Both jars must shade thegaffer-core. Paper and Velocity each load one jar and know nothing of the Maven reactor. Without the shade the plugin enables and then throws NoClassDefFoundError the first time a job starts.
• Tests: JUnit 5 with MockBukkit (mockbukkit-v26.2 4.116.1, which must match the paper-api build). Notable classes: ProtectionApiContractTest (pins the reflective API), JobPersistenceTest, ProtectionUtilTest, the StatsManager*Test family, JoinRoutingTest and VelocityPluginDescriptorTest on the proxy side. MockBukkit cannot render a Dialog, reach Discord, or read ItemStacks back from YAML, so those paths are checked in game.
• Version bumps touch all four poms and the @Plugin(version = ...) annotation on VelocityGafferPlugin; the proxy's velocity-plugin.json is generated from that annotation, and VelocityPluginDescriptorTest fails the build when the two disagree.
• CI: .github/workflows/build.yml ("Build & Test") runs mvn -B -ntp clean verify on pushes to master and development and on pull requests, with JDK 25 (Temurin). On a v* tag it checks the tag against the pom version and against a ## [X.Y.Z] — YYYY-MM-DD section in CHANGELOG.md, deploys the parent pom, thegaffer-core, TheGaffer and thegaffer-velocity to the MCME Maven repository, and creates the GitHub release "TheGaffer X.Y.Z" with both jars and a SHA-256 for each. A manual run publishes whatever version the branch is at (that is how a -SNAPSHOT reaches the snapshots repository). A separate manual workflow, publish-release.yml, uploads the jars of an existing GitHub release.

Configuration

plugins/TheGaffer/config.yml (the bundled file is written on first start; the plugin never adds new keys to an existing file):

A key missing from an existing file falls back to the code default, which differs from the bundled file for two keys: jobDescription (code default false) and glowing.workerColor (LIGHT_PURPLE). The console command /job reloadConfig rereads the file.

Commands and permissions

APIs and extension points

The reflective protection API

Three public static methods on the main class com.mcmiddleearth.thegaffer.TheGaffer are a contract with other plugins, which find them by name through reflection rather than compiling against TheGaffer:

ProtectionApiContractTest fails the build if any of the three changes name, parameters, return type, or stops being public static. The consumer side matters as much: MCME-Architect looks the methods up with getMethod(...) and fails open, so if TheGaffer is missing or a signature drifts, Architect allows building. Change the two repositories together.

A sketch of the caller's side, as Architect's TheGafferUtil does it:

Plugin gaffer = Bukkit.getPluginManager().getPlugin("TheGaffer");
if (gaffer != null) {
    Method m = gaffer.getClass().getMethod("hasBuildPermission", Player.class, Location.class);
    boolean allowed = (boolean) m.invoke(null, player, location);
}

External protection handlers

The reverse direction is configured, not coded. Under externalProtectionHandlers in config.yml, name a plugin and a method on that plugin's main class: a public static boolean name(Player, Location). An allow method returning true lets the player build; a deny method returning true refuses, and deny handlers are checked before everything else. A handler whose plugin is missing or disabled counts as "no opinion". The bundled config has none configured.

externalProtectionHandlers:
  SomePlugin:
    allow: canBuildHere
    deny: mustNotBuildHere

Bukkit events

Other plugins can listen to these (package com.mcmiddleearth.thegaffer.events). They are informational; none is cancellable.

Statistics feed

/job stats export json writes leaderboard.json, a machine-readable feed (built by StatsFeed) meant for the website and infographics. /job stats export and /project export write CSV.

Adding an optional integration

Bukkit registers a listener class as a whole, so a class that names an optional plugin's types fails with NoClassDefFoundError (an Error, not caught by catch (Exception)) when that plugin is absent, and every handler in it is lost. Keep optional types in a nested class that loads only after an isPluginEnabled check, and catch Throwable at the boundary, as JobDiscordAnnouncer and JobMapIntegration do.

How it talks to other plugins and systems

flowchart LR
  AR[MCME-Architect] -- "reflection: hasBuildPermission,<br/>getBuildProtectionMessage,<br/>recordExternalBuild" --> TG[TheGaffer backend]
  TG -- "mcme:gaffer<br/>JOB_CREATED / JOB_DELETED / JOB_SYNC" --> TV[thegaffer-velocity on the proxy]
  TV -- "moves player, runs /job join" --> TG2[TheGaffer on another backend]
  TG -- "BungeeCord channel 'Message' to ALL<br/>(only without the proxy plugin)" --> PX[Velocity proxy]
  TG -- "embeds" --> DS[DiscordSRV]
  TG -- "marker set thegaffer.jobs" --> DM[dynmap / LiveAtlas]

The proxy plugin also greets a player on their first server connection with the running jobs, and intercepts /job check and /job join <name>. JoinRouting, a pure function with unit tests, makes the proxy step in only when the named job is on a different backend; local, unknown, differently-cased or ambiguous names fall through to the backend.

Further reading

• Readme and CHANGELOG on master
• Setting up, Contributing, Maven repository
• Architect, MCME-Connect
• For builders and job leaders: Working on jobs, Running jobs