[{"data":1,"prerenderedAt":436},["ShallowReactive",2],{"docs-\u002Fbuild-logic\u002Fdev-server":3},{"id":4,"title":5,"body":6,"description":426,"extension":427,"meta":428,"navTitle":429,"navigation":430,"path":431,"rawbody":432,"seo":433,"stem":434,"__hash__":435},"docs\u002Fbuild-logic\u002Fdev-server.md","Dev Server & Smoke",{"type":7,"value":8,"toc":417},"minimark",[9,13,30,35,48,108,118,143,147,154,162,165,285,311,316,347,353,356,382,389,393,399,414],[10,11,5],"h1",{"id":12},"dev-server-smoke",[14,15,16,20,21,25,26,29],"p",{},[17,18,19],"code",{},"build-logic"," gives you two levels of runtime verification: a ",[22,23,24],"strong",{},"dev server"," for\niterating locally, and a ",[22,27,28],{},"compatibility smoke"," test that boots a real server\nper Minecraft version and gates on the runtime diagnostics verdict.",[31,32,34],"h2",{"id":33},"dev-servers","Dev Servers",[14,36,37,38,41,42,47],{},"Opt into a run task from a consumer module with ",[17,39,40],{},"devServer { }"," (see\n",[43,44,46],"a",{"href":45},"\u002Fbuild-logic\u002Fconsumer","Using It In A Mod","). Once enabled, the platform run task\nis available:",[49,50,51,64],"table",{},[52,53,54],"thead",{},[55,56,57,61],"tr",{},[58,59,60],"th",{},"Task",[58,62,63],{},"Runs",[65,66,67,78,88,98],"tbody",{},[55,68,69,75],{},[70,71,72],"td",{},[17,73,74],{},"runPaper",[70,76,77],{},"A Paper dev server with your plugin.",[55,79,80,85],{},[70,81,82],{},[17,83,84],{},"runFolia",[70,86,87],{},"A Folia dev server with your plugin.",[55,89,90,95],{},[70,91,92],{},[17,93,94],{},"runFabric",[70,96,97],{},"A Fabric dev server with your mod.",[55,99,100,105],{},[70,101,102],{},[17,103,104],{},"runVelocity",[70,106,107],{},"A Velocity proxy with your plugin.",[109,110,116],"pre",{"className":111,"code":113,"language":114,"meta":115},[112],"language-bash",".\u002Fgradlew runPaper\n.\u002Fgradlew runFabric -Ptarget=mc262\n","bash","",[17,117,113],{"__ignoreMap":115},[14,119,120,121,124,125,128,129,128,132,135,136,139,140,142],{},"The server versions default from the active target, so ",[17,122,123],{},"runFabric -Ptarget=mc262","\nboots the Minecraft version that target declares. ",[17,126,127],{},"motd",", ",[17,130,131],{},"port",[17,133,134],{},"online-mode",",\n",[17,137,138],{},"folia",", and Modrinth test dependencies come from the ",[17,141,40],{}," block.",[31,144,146],{"id":145},"compatibility-smoke","Compatibility Smoke",[14,148,149,150,153],{},"The smoke test is the release gate. For each declared entry it launches the\nstandalone MagicUtils bundle on a real server, waits for the success line, then\nruns the diagnostics export command and checks the verdict. It is declared in\n",[17,151,152],{},"magicMatrix { smoke { } }",":",[109,155,160],{"className":156,"code":158,"language":159,"meta":115},[157],"language-kotlin","magicMatrix {\n    smoke {\n        platform(\"bukkit\") {\n            runTask = \":bukkit-bundle:runServer -Pscenario=bukkit --args=nogui\"\n            successPattern = \"Done (\"\n            entry(\"paper-121x\") {\n                versions = listOf(\"1.21.10\")\n                smokeValues = listOf(\"1.21.10\")\n            }\n        }\n        platform(\"fabric\") {\n            runTask = \":fabric-bundle:runServer\"\n            successPattern = \"Done (\"\n            entry(\"fabric-121x\") {\n                versions = listOf(\"1.21.10\")\n                smokeValues = listOf(\"1.21.10\")\n            }\n        }\n    }\n}\n","kotlin",[17,161,158],{"__ignoreMap":115},[14,163,164],{},"Per-platform smoke options:",[49,166,167,180],{},[52,168,169],{},[55,170,171,174,177],{},[58,172,173],{},"Option",[58,175,176],{},"Default",[58,178,179],{},"Purpose",[65,181,182,195,210,225,240,255,270],{},[55,183,184,189,192],{},[70,185,186],{},[17,187,188],{},"runTask",[70,190,191],{},"—",[70,193,194],{},"Gradle task that boots the server.",[55,196,197,202,207],{},[70,198,199],{},[17,200,201],{},"successPattern",[70,203,204],{},[17,205,206],{},"Done (",[70,208,209],{},"Log line that marks a successful boot.",[55,211,212,217,222],{},[70,213,214],{},[17,215,216],{},"timeoutSeconds",[70,218,219],{},[17,220,221],{},"300",[70,223,224],{},"Max time to wait for the boot line.",[55,226,227,232,237],{},[70,228,229],{},[17,230,231],{},"diagnosticsRequired",[70,233,234],{},[17,235,236],{},"true",[70,238,239],{},"Run diagnostics after boot and gate on it.",[55,241,242,247,252],{},[70,243,244],{},[17,245,246],{},"diagnosticsCommand",[70,248,249],{},[17,250,251],{},"magicutils diagnostics export",[70,253,254],{},"Command executed in the server console.",[55,256,257,262,267],{},[70,258,259],{},[17,260,261],{},"diagnosticsTimeoutSeconds",[70,263,264],{},[17,265,266],{},"60",[70,268,269],{},"Max time to wait for the diagnostics result.",[55,271,272,277,282],{},[70,273,274],{},[17,275,276],{},"diagnosticsFailOnWarn",[70,278,279],{},[17,280,281],{},"false",[70,283,284],{},"Treat diagnostic warnings as failures.",[14,286,287,288,291,292,295,296,299,300,128,303,306,307,310],{},"Each ",[17,289,290],{},"entry(id) { }"," declares the Minecraft ",[17,293,294],{},"versions"," to launch and the\n",[17,297,298],{},"smokeValues"," used for the gate; ",[17,301,302],{},"target",[17,304,305],{},"primary",", and ",[17,308,309],{},"gradleProperties"," fine-tune\nwhich build target and flags a run uses.",[312,313,315],"h3",{"id":314},"folia-smoke","Folia smoke",[14,317,318,319,322,323,325,326,329,330,332,333,336,337,340,341,343,344,346],{},"Folia is a Paper fork with regionised multithreading. It is ",[22,320,321],{},"not"," a separate\npublished artifact — ",[17,324,138],{}," is just one of the ",[17,327,328],{},"bukkit"," bundle's Modrinth\nloaders — but a plugin must be Folia-aware to actually run on it. So the smoke\nmatrix declares a ",[17,331,138],{}," platform that boots the ",[22,334,335],{},"same"," ",[17,338,339],{},"bukkit-bundle"," jar\non a real Folia server via ",[17,342,84],{},", backing the ",[17,345,138],{}," loader claim with an\nactual boot + diagnostics check:",[109,348,351],{"className":349,"code":350,"language":159,"meta":115},[157],"platform(\"folia\") {\n    runTask = \":bukkit-bundle:runFolia -Pscenario=bukkit --args=nogui\"\n    successPattern = \"Done (\"\n    entry(\"folia-121x\") {\n        target = \"mc12110\"\n        versions = listOf(\"1.21-1.21.11\")\n        smokeValues = listOf(\"1.21.11\")   \u002F\u002F a Folia-available patch\n    }\n}\n",[17,352,350],{"__ignoreMap":115},[14,354,355],{},"Two details are Folia-specific:",[357,358,359,363],"ul",{},[360,361,362],"li",{},"Folia needs Java 21+, so only the 1.21+\u002F26.x targets are smoked.",[360,364,365,366,369,370,373,374,377,378,381],{},"Folia does not publish a build for every patch, so the ",[17,367,368],{},"smokeValue"," is a\nFolia-available version launched on the bundle jar built for a nearby patch\n(the jar built for ",[17,371,372],{},"+1.21.10"," runs fine on a 1.21.11 Folia server). Use\n",[17,375,376],{},"smokeGradleProperties"," to pin ",[17,379,380],{},"runMinecraftVersion"," to the available patch.",[14,383,384,385,388],{},"The Modrinth artifact generator skips this platform (there is no ",[17,386,387],{},"folia-bundle","\nmodule); it is smoke-only.",[31,390,392],{"id":391},"running-the-smoke","Running The Smoke",[109,394,397],{"className":395,"code":396,"language":114,"meta":115},[112],"# All declared smoke cases\n.\u002Fgradlew runCompatibilitySmoke\n\n# One case by id\n.\u002Fgradlew runCompatibilitySmoke -PsmokeCase=fabric-121x\n\n# List what the smoke matrix resolves to\n.\u002Fgradlew listSmokeMatrix\n",[17,398,396],{"__ignoreMap":115},[14,400,401,402,405,406,409,410,413],{},"Server logs are written under ",[17,403,404],{},"build\u002Fsmoke-logs\u002F",". The gate strictness can be\noverridden with ",[17,407,408],{},"-Psmoke_gate=",", but the default ",[17,411,412],{},"STRICT"," gate is what makes the\nsmoke a meaningful release check: a diagnostics failure fails the build.",[14,415,416],{},"This is the same two-level model MagicUtils uses for its own releases: unit tests\nplus a diagnostics-gated server boot per Minecraft version.",{"title":115,"searchDepth":418,"depth":418,"links":419},3,[420,422,425],{"id":33,"depth":421,"text":34},2,{"id":145,"depth":421,"text":146,"children":423},[424],{"id":314,"depth":418,"text":315},{"id":391,"depth":421,"text":392},"Run a MagicUtils-based mod on a real dev server and gate releases on a diagnostics-verified compatibility smoke test, all from build-logic.","md",{},null,true,"\u002Fbuild-logic\u002Fdev-server","---\ntitle: Dev Server & Smoke\ndescription: 'Run a MagicUtils-based mod on a real dev server and gate releases on a diagnostics-verified compatibility smoke test, all from build-logic.'\n---\n\n# Dev Server & Smoke\n\n`build-logic` gives you two levels of runtime verification: a **dev server** for\niterating locally, and a **compatibility smoke** test that boots a real server\nper Minecraft version and gates on the runtime diagnostics verdict.\n\n## Dev Servers\n\nOpt into a run task from a consumer module with `devServer { }` (see\n[Using It In A Mod](\u002Fbuild-logic\u002Fconsumer)). Once enabled, the platform run task\nis available:\n\n| Task | Runs |\n| --- | --- |\n| `runPaper` | A Paper dev server with your plugin. |\n| `runFolia` | A Folia dev server with your plugin. |\n| `runFabric` | A Fabric dev server with your mod. |\n| `runVelocity` | A Velocity proxy with your plugin. |\n\n```bash\n.\u002Fgradlew runPaper\n.\u002Fgradlew runFabric -Ptarget=mc262\n```\n\nThe server versions default from the active target, so `runFabric -Ptarget=mc262`\nboots the Minecraft version that target declares. `motd`, `port`, `online-mode`,\n`folia`, and Modrinth test dependencies come from the `devServer { }` block.\n\n## Compatibility Smoke\n\nThe smoke test is the release gate. For each declared entry it launches the\nstandalone MagicUtils bundle on a real server, waits for the success line, then\nruns the diagnostics export command and checks the verdict. It is declared in\n`magicMatrix { smoke { } }`:\n\n```kotlin\nmagicMatrix {\n    smoke {\n        platform(\"bukkit\") {\n            runTask = \":bukkit-bundle:runServer -Pscenario=bukkit --args=nogui\"\n            successPattern = \"Done (\"\n            entry(\"paper-121x\") {\n                versions = listOf(\"1.21.10\")\n                smokeValues = listOf(\"1.21.10\")\n            }\n        }\n        platform(\"fabric\") {\n            runTask = \":fabric-bundle:runServer\"\n            successPattern = \"Done (\"\n            entry(\"fabric-121x\") {\n                versions = listOf(\"1.21.10\")\n                smokeValues = listOf(\"1.21.10\")\n            }\n        }\n    }\n}\n```\n\nPer-platform smoke options:\n\n| Option | Default | Purpose |\n| --- | --- | --- |\n| `runTask` | — | Gradle task that boots the server. |\n| `successPattern` | `Done (` | Log line that marks a successful boot. |\n| `timeoutSeconds` | `300` | Max time to wait for the boot line. |\n| `diagnosticsRequired` | `true` | Run diagnostics after boot and gate on it. |\n| `diagnosticsCommand` | `magicutils diagnostics export` | Command executed in the server console. |\n| `diagnosticsTimeoutSeconds` | `60` | Max time to wait for the diagnostics result. |\n| `diagnosticsFailOnWarn` | `false` | Treat diagnostic warnings as failures. |\n\nEach `entry(id) { }` declares the Minecraft `versions` to launch and the\n`smokeValues` used for the gate; `target`, `primary`, and `gradleProperties` fine-tune\nwhich build target and flags a run uses.\n\n### Folia smoke\n\nFolia is a Paper fork with regionised multithreading. It is **not** a separate\npublished artifact — `folia` is just one of the `bukkit` bundle's Modrinth\nloaders — but a plugin must be Folia-aware to actually run on it. So the smoke\nmatrix declares a `folia` platform that boots the **same** `bukkit-bundle` jar\non a real Folia server via `runFolia`, backing the `folia` loader claim with an\nactual boot + diagnostics check:\n\n```kotlin\nplatform(\"folia\") {\n    runTask = \":bukkit-bundle:runFolia -Pscenario=bukkit --args=nogui\"\n    successPattern = \"Done (\"\n    entry(\"folia-121x\") {\n        target = \"mc12110\"\n        versions = listOf(\"1.21-1.21.11\")\n        smokeValues = listOf(\"1.21.11\")   \u002F\u002F a Folia-available patch\n    }\n}\n```\n\nTwo details are Folia-specific:\n\n- Folia needs Java 21+, so only the 1.21+\u002F26.x targets are smoked.\n- Folia does not publish a build for every patch, so the `smokeValue` is a\n  Folia-available version launched on the bundle jar built for a nearby patch\n  (the jar built for `+1.21.10` runs fine on a 1.21.11 Folia server). Use\n  `smokeGradleProperties` to pin `runMinecraftVersion` to the available patch.\n\nThe Modrinth artifact generator skips this platform (there is no `folia-bundle`\nmodule); it is smoke-only.\n\n## Running The Smoke\n\n```bash\n# All declared smoke cases\n.\u002Fgradlew runCompatibilitySmoke\n\n# One case by id\n.\u002Fgradlew runCompatibilitySmoke -PsmokeCase=fabric-121x\n\n# List what the smoke matrix resolves to\n.\u002Fgradlew listSmokeMatrix\n```\n\nServer logs are written under `build\u002Fsmoke-logs\u002F`. The gate strictness can be\noverridden with `-Psmoke_gate=`, but the default `STRICT` gate is what makes the\nsmoke a meaningful release check: a diagnostics failure fails the build.\n\nThis is the same two-level model MagicUtils uses for its own releases: unit tests\nplus a diagnostics-gated server boot per Minecraft version.\n",{"title":5,"description":426},"build-logic\u002Fdev-server","rnPcQH5zh1Ap5tP9HVr5gLWMN8zuerr-APufYJlUEAc",1783944486788]