Dev Server & Smoke

build-logic gives you two levels of runtime verification: a dev server for iterating locally, and a compatibility smoke test that boots a real server per Minecraft version and gates on the runtime diagnostics verdict.

Dev Servers#

Opt into a run task from a consumer module with devServer { } (see Using It In A Mod). Once enabled, the platform run task is available:

./gradlew runPaper./gradlew runFabric -Ptarget=mc262

The server versions default from the active target, so runFabric -Ptarget=mc262 boots the Minecraft version that target declares. motd, port, online-mode, folia, and Modrinth test dependencies come from the devServer { } block.

Compatibility Smoke#

The smoke test is the release gate. For each declared entry it launches the standalone MagicUtils bundle on a real server, waits for the success line, then runs the diagnostics export command and checks the verdict. It is declared in magicMatrix { smoke { } }:

magicMatrix {    smoke {        platform("bukkit") {            runTask = ":bukkit-bundle:runServer -Pscenario=bukkit --args=nogui"            successPattern = "Done ("            entry("paper-121x") {                versions = listOf("1.21.10")                smokeValues = listOf("1.21.10")            }        }        platform("fabric") {            runTask = ":fabric-bundle:runServer"            successPattern = "Done ("            entry("fabric-121x") {                versions = listOf("1.21.10")                smokeValues = listOf("1.21.10")            }        }    }}

Per-platform smoke options:

Each entry(id) { } declares the Minecraft versions to launch and the smokeValues used for the gate; target, primary, and gradleProperties fine-tune which build target and flags a run uses.

Folia smoke#

Folia is a Paper fork with regionised multithreading. It is not a separate published artifact — folia is just one of the bukkit bundle's Modrinth loaders — but a plugin must be Folia-aware to actually run on it. So the smoke matrix declares a folia platform that boots the same bukkit-bundle jar on a real Folia server via runFolia, backing the folia loader claim with an actual boot + diagnostics check:

platform("folia") {    runTask = ":bukkit-bundle:runFolia -Pscenario=bukkit --args=nogui"    successPattern = "Done ("    entry("folia-121x") {        target = "mc12110"        versions = listOf("1.21-1.21.11")        smokeValues = listOf("1.21.11")   // a Folia-available patch    }}

Two details are Folia-specific:

• Folia needs Java 21+, so only the 1.21+/26.x targets are smoked.
• Folia does not publish a build for every patch, so the smokeValue is a Folia-available version launched on the bundle jar built for a nearby patch (the jar built for +1.21.10 runs fine on a 1.21.11 Folia server). Use smokeGradleProperties to pin runMinecraftVersion to the available patch.

The Modrinth artifact generator skips this platform (there is no folia-bundle module); it is smoke-only.

Running The Smoke#

# All declared smoke cases./gradlew runCompatibilitySmoke# One case by id./gradlew runCompatibilitySmoke -PsmokeCase=fabric-121x# List what the smoke matrix resolves to./gradlew listSmokeMatrix

Server logs are written under build/smoke-logs/. The gate strictness can be overridden with -Psmoke_gate=, but the default STRICT gate is what makes the smoke a meaningful release check: a diagnostics failure fails the build.

This is the same two-level model MagicUtils uses for its own releases: unit tests plus a diagnostics-gated server boot per Minecraft version.