MCME-Architect is the builder's toolkit of the MCME build server: one large Paper plugin that changes how blocks behave and gives builders their tools. It holds about twenty mostly independent features: resource-pack "special blocks" with their own placing rules, build inventories, kits, item blocks, the per-world no-physics list, editors for armor stands, banners, signs and paintings, its own copy and paste, resource-pack switching and releases, live biome tuning, and map layers on the dynmap web map. Its build tools ask TheGaffer whether a player may build at a spot, so they respect job areas. The code is on GitHub at MCME/MCME-Architect; this page describes release 3.3.1 on master.

The repository's own Developer Manual is the detailed reference (startup order, every subsystem, threading rules, pitfalls). This page is the overview; read the manual before changing code.

At a glance

How the code is organised

There is one main class, com.mcmiddleearth.architect.ArchitectPlugin. Each feature lives in its own package under com.mcmiddleearth.architect, usually as a manager or data class with static state, one or more listeners, and commands whose executors extend AbstractArchitectCommand. Shared helpers sit in com.mcmiddleearth.util.

Things to know before you read the code:

• Features are switched per world. Nearly every feature checks PluginData.isModuleEnabled(world, Modules.X). The 64 switches live in WorldConfig/<world>.yml, with WorldConfig/defaultWorldConfig.yml as fallback. A switch missing from both counts as on (and is written as true), so a new feature starts on in every world.
• Two code generations. The 2.x code (2016–2025) uses static managers and legacy ChatColor; the 3.x code (map layers, biome tuning, the game-mode switcher, /rp release feedback) uses small final classes, records and interfaces as test seams. New code follows the 3.x style.
• Architect starts before the worlds (load: STARTUP), so Bukkit.getWorlds() is empty in onEnable. Worlds are set up on WorldLoadEvent. This also lets Architect act as a world generator: a world with generator MCME-Architect or MCME-Architect:<name>_<size> gets a void world with one flat square of grass.
• Architect logs to its own files, plugins/MCME-Architect/logs/architect_*.log, not to the console, unless logging.file.alsoServerLog is true.
• Commands are classic plugin.yml commands (no Brigadier). No command has a permission: key; every check is in the executor.

Building and testing

mvn -B -ntp clean verify                     # build, run every test, make the jar (what CI runs)
mvn -B package -DskipTests                   # the jar only
mvn -B package -Dbuild.type=RELEASE          # a jar named as a release build
mvn -B test -Dtest=FbtCommandTest            # one test class

• JDK 25 and Maven 3.9. Dependencies resolve from Maven Central, the PaperMC, Mojang, EngineHub, ProtocolLib, ViaVersion and dynmap repositories, and repo.mcmiddleearth.com for PluginUtils and MCME-Connect. Reading needs no credentials. See Setting up.
• Jar name: MCME-Architect-<version>-<build.type>-<commit>.jar in target/. build.type is DEV by default. The commit id comes from git-commit-id-maven-plugin; in a linked git worktree pass -Dgit.commit.id.abbrev=$(git rev-parse --short=7 HEAD), because the plugin can read the wrong HEAD there.
• Everything is provided, nothing is shaded. The server supplies Paper, PluginUtils, WorldEdit, ProtocolLib, dynmap, ViaVersion, MCME-Connect, TheGaffer and a MySQL JDBC driver (the pom declares none).
• Only four resources go into the jar: plugin.yml, config.yml, protocolVersions.yml and items.json, all filtered. The other files in src/main/resources (old release scripts, pre-1.13 inventories) are not packaged. A new resource needs an <include> in the pom.
• Tests: JUnit Jupiter 6.1 and MockBukkit for Paper 26.2 (mockbukkit-v26.2 4.116.1); 118 test classes in 3.3.1. Surefire runs every test class in a fresh JVM (reuseForks=false) because of static state. The rule is one MockBukkit.mock() and one MockBukkit.load(ArchitectPlugin.class) per class. Hand-written fakes stand in for other systems: FakeGaffer (TheGaffer's reflective API), FakeDynmap and FakeMarkerApi, FakeMysql, FakeScript (release scripts) and FakeNmsBridge (Minecraft internals). Guard tests to know about: PluginYmlPermissionsTest, DynmapIsolationTest, ConfigFileTest, RpTableSchemaTest.
• Run the tests through Maven. They read the filtered plugin.yml; the source copy has name: ${project.artifactId}, which Bukkit rejects.
• CI: .github/workflows/build.yml runs mvn -B -ntp clean verify on every push, every pull request and every v* tag, and uploads the DEV jar as an artifact. On a v* tag it checks that the tag equals v plus the pom version, then publishes a RELEASE build to repo.mcmiddleearth.com. A manual run also publishes, without the tag check, so run it only on a commit that really is that version. The workflow does not create GitHub Releases; maintainers attach the published jar and a .sha256 to a GitHub Release by hand.

Configuration

Architect's data folder is plugins/MCME-Architect/. The files a developer meets most:

Two rules shape all config.yml code:

• The bundled config.yml is the default for every key a server's file lacks, but new keys are never written into an existing file. Only put safe defaults in it.
• Never call saveConfig(). Every write goes through ConfigFile.update(config -> ...), which rereads the file first so servers sharing it do not overwrite each other. ConfigFileTest fails if any other class saves the config.

Sections of the bundled config.yml:

Three keys are read but not in the bundled file: CopyPasteUndoLimit, CustomHeadUploadPath (written when missing) and inventoryUpload (/inv upload fails until it is set).

/architect reload runs loadData() only. Changes to logging.*, biomeTuning.*, rpSettingsDatabase, and anything that onEnable registers need a server restart. The User Manual's Running Architect chapter explains every per-world switch.

Commands and permissions

Every command also answers to the mcme-architect: prefix (for example /mcme-architect:undo when WorldEdit owns /undo). Most commands also need their per-world switch to be on.

Permission structure. Nodes follow architect.<feature>[.<sub>] in camelCase and are listed in the Permission enum. Four rank bundles nest, each including the one below: architect.ranks.headDesigner → designer → artist → adventurer; architect.* grants headDesigner. Notable nodes outside the bundles:

The full tree, with every description, is in plugin.yml and the User Manual's Permissions chapter.

APIs and extension points

Architect has no formal API module, but other plugins rely on a few public static methods. Keep them stable:

To compile against Architect, depend on com.mcmiddleearth:MCME-Architect (scope provided) from the Maven repository.

Inside the plugin, the extension points are:

• A new feature: a package of its own, a command in plugin.yml (without permission:), a node in plugin.yml with a description: and in the Permission enum, an executor extending AbstractArchitectCommand, registration in onEnable, and usually a Modules switch. The DEV_MANUAL's Adding a feature checklist has twelve steps; PluginYmlPermissionsTest checks the plugin.yml side.
• A new special-block type: a constant in SpecialBlockType, a class with a static loadFromConfig(ConfigurationSection, String) that overrides getBlockState, and a case in SpecialBlock.createSpecialBlock.
• A new map layer: implement MapLayer (marker-set id, label, shapes()), build it in ArchitectLayers.fromConfig, and call MapLayers.changed(markerSetId) when its data changes. Never name dynmap types outside DynmapBackend; DynmapIsolationTest fails the build if you do.
• Soft dependencies stay in classes of their own, loaded only after isPluginEnabled: dynmap in DynmapBackend and ELogDynmapUtil, ProtocolLib in the *Protocol classes, MCME-Connect in RpListener.

How it talks to other plugins and systems

flowchart LR
  A[MCME-Architect]
  A -- "reflection: hasBuildPermission,<br/>getBuildProtectionMessage,<br/>recordExternalBuild" --> G[TheGaffer]
  A -- "depend (Maven + plugin.yml)" --> PU[PluginUtils]
  A -- "selections, regions" --> WE[WorldEdit]
  A -- "marker API via DynmapBackend" --> D[dynmap / LiveAtlas]
  C[MCME-Connect] -- "PlayerConnectEvent" --> A
  I[MCME-Introduction] -- "RpManager API" --> A
  A -- "runs release script,<br/>reads its output" --> R[ResourcePackScripts]
  A -- "JDBC, table architect_rp" --> DB[(Pack settings DB)]

Further reading

• README, Developer Manual and User Manual on master
• Setting up, Contributing, Maven repository
• PluginUtils, TheGaffer
• For builders and staff: Architect for builders, Architect staff tools