[{"data":1,"prerenderedAt":489},["ShallowReactive",2],{"docs-\u002F":3},{"id":4,"title":5,"body":6,"description":479,"extension":480,"meta":481,"navTitle":482,"navigation":483,"path":484,"rawbody":485,"seo":486,"stem":487,"__hash__":488},"docs\u002Findex.md","MagicUtils",{"type":7,"value":8,"toc":470},"minimark",[9,12,25,30,41,55,81,85,147,151,326,330,342,352,429,438,442],[10,11],"hero",{},[13,14,15,16,20,21,24],"p",{},"The same stack also works well in multi-module projects where platform adapters\nonly bootstrap ",[17,18,19],"code",{},"MagicRuntime"," and the real feature logic lives in shared\n",[17,22,23],{},"common"," modules.",[26,27,29],"h2",{"id":28},"why-magicutils","Why MagicUtils",[13,31,32,33,36,37,40],{},"Every server platform solves the same problems differently: styled text,\nconfig files, commands, permissions, per-player language. Writing a plugin and a\nmod usually means learning ",[17,34,35],{},"ChatColor"," on one side and Minecraft's ",[17,38,39],{},"Text"," on the\nother, hand-rolling config loaders, and branching command code per dispatcher.",[13,42,43,44,51,52,54],{},"MagicUtils gives you one API for all of it, built on\n",[45,46,50],"a",{"href":47,"rel":48},"https:\u002F\u002Fdocs.advntr.dev\u002F",[49],"nofollow","Kyori Adventure"," so text you author once renders\ncorrectly on Bukkit, BungeeCord, Velocity, Fabric, and NeoForge. You write the\nfeature once against ",[17,53,19],{},"; the thin platform adapter is the only part\nthat changes. Concretely, that means:",[56,57,58,72,75,78],"ul",{},[59,60,61,62,67,68,71],"li",{},"One string with ",[45,63,66],{"href":64,"rel":65},"https:\u002F\u002Fdocs.advntr.dev\u002Fminimessage\u002Fformat.html",[49],"MiniMessage","\nor legacy ",[17,69,70],{},"&"," codes instead of per-platform colour handling.",[59,73,74],{},"Annotation-first commands with type parsers, options, and permissions instead\nof dispatcher plumbing.",[59,76,77],{},"Config models with validation and migrations instead of manual file parsing.",[59,79,80],{},"Per-player localisation and placeholders wired into the same call sites.",[26,82,84],{"id":83},"highlights","Highlights",[56,86,87,105,110,113,116,119,122,125,128,131,144],{},[59,88,89,90,93,94,93,97,100,101,104],{},"Bootstrap-first setup for Bukkit\u002FPaper\u002FFolia, BungeeCord, Velocity, and\nFabric via ",[17,91,92],{},"BukkitBootstrap",", ",[17,95,96],{},"BungeeBootstrap",[17,98,99],{},"VelocityBootstrap",", and\n",[17,102,103],{},"FabricBootstrap",".",[59,106,107,109],{},[17,108,19],{}," container for managed shutdown hooks, typed components, and\nnamed runtime resources.",[59,111,112],{},"Config manager with JSON\u002FJSONC, YAML, and TOML support plus migrations.",[59,114,115],{},"Annotation-first command framework with type parsers, options, and Brigadier\nsupport where the platform supports it.",[59,117,118],{},"Adventure-based logger with rich formatting, sub-loggers, and help styling.",[59,120,121],{},"Language manager with MiniMessage, bundled messages, and per-player\noverrides.",[59,123,124],{},"HTTP client wrapper with JSON mapping, retries, multipart uploads, and\nruntime-bound profiles.",[59,126,127],{},"WebSocket client with the same builder pattern, config integration, and\nruntime profiles.",[59,129,130],{},"Platform-agnostic player lifecycle and message events.",[59,132,133,134,93,137,93,140,143],{},"Config validation annotations (",[17,135,136],{},"@MinValue",[17,138,139],{},"@MaxValue",[17,141,142],{},"@ConfigSerializable",").",[59,145,146],{},"Placeholder registry with Bukkit PlaceholderAPI and Fabric placeholder\nbridges.",[26,148,150],{"id":149},"modules-at-a-glance","Modules At A Glance",[152,153,154,170],"table",{},[155,156,157],"thead",{},[158,159,160,164,167],"tr",{},[161,162,163],"th",{},"Layer",[161,165,166],{},"Artifacts",[161,168,169],{},"Notes",[171,172,173,196,209,237,253,275,291,310],"tbody",{},[158,174,175,179,184],{},[176,177,178],"td",{},"Platform API",[176,180,181],{},[17,182,183],{},"magicutils-api",[176,185,186,93,189,93,192,195],{},[17,187,188],{},"Platform",[17,190,191],{},"Audience",[17,193,194],{},"TaskScheduler",", and shared interfaces.",[158,197,198,201,206],{},[176,199,200],{},"Core stack",[176,202,203],{},[17,204,205],{},"magicutils-core",[176,207,208],{},"Shared runtime container plus core config\u002Flang\u002Flogger\u002Fplaceholder wiring.",[158,210,211,214,234],{},[176,212,213],{},"Feature modules",[176,215,216,93,219,93,222,93,225,93,228,93,231],{},[17,217,218],{},"magicutils-logger",[17,220,221],{},"magicutils-commands",[17,223,224],{},"magicutils-config",[17,226,227],{},"magicutils-lang",[17,229,230],{},"magicutils-placeholders",[17,232,233],{},"magicutils-http-client",[176,235,236],{},"Mix and match for manual setups.",[158,238,239,242,250],{},[176,240,241],{},"Format helpers",[176,243,244,93,247],{},[17,245,246],{},"magicutils-config-yaml",[17,248,249],{},"magicutils-config-toml",[176,251,252],{},"Enable extra config formats.",[158,254,255,258,272],{},[176,256,257],{},"Platform adapters",[176,259,260,93,263,93,266,93,269],{},[17,261,262],{},"magicutils-bukkit",[17,264,265],{},"magicutils-fabric",[17,267,268],{},"magicutils-velocity",[17,270,271],{},"magicutils-neoforge",[176,273,274],{},"Wire MagicUtils to each runtime.",[158,276,277,280,288],{},[176,278,279],{},"Platform bundles",[176,281,282,93,285],{},[17,283,284],{},"magicutils-bukkit-bundle",[17,286,287],{},"magicutils-fabric-bundle",[176,289,290],{},"Shared server-side installs for Bukkit\u002FPaper and Fabric.",[158,292,293,296,307],{},[176,294,295],{},"Fabric integrations",[176,297,298,93,301,93,304],{},[17,299,300],{},"magicutils-commands-fabric",[17,302,303],{},"magicutils-logger-fabric",[17,305,306],{},"magicutils-placeholders-fabric",[176,308,309],{},"Fabric-specific command, logger, and placeholder layers.",[158,311,312,315,323],{},[176,313,314],{},"Brigadier integrations",[176,316,317,93,320],{},[17,318,319],{},"magicutils-commands-brigadier",[17,321,322],{},"magicutils-commands-neoforge",[176,324,325],{},"Shared Brigadier base and NeoForge command wiring.",[26,327,329],{"id":328},"quick-start","Quick Start",[331,332,333,336,339],"ol",{},[59,334,335],{},"Add the MagicUtils Maven repository.",[59,337,338],{},"Add one platform entry point.",[59,340,341],{},"Wire the runtime through the recommended bootstrap helper.",[343,344,350],"pre",{"className":345,"code":347,"language":348,"meta":349},[346],"language-kotlin","repositories {\n    maven(\"https:\u002F\u002Fmaven.theroer.dev\u002Freleases\")\n}\n","kotlin","",[17,351,347],{"__ignoreMap":349},[353,354,356,373,387,401,415],"code-tabs",{":tabs":355},"[\"Bukkit\u002FPaper\u002FFolia\", \"BungeeCord\", \"Velocity\", \"Fabric\", \"NeoForge\"]",[357,358,359,365],"template",{"v-slot:bukkit-paper-folia":349},[343,360,363],{"className":361,"code":362,"language":348,"meta":349},[346],"dependencies {\n    implementation(\"dev.ua.theroer:magicutils-bukkit:1.27.1\")\n}\n",[17,364,362],{"__ignoreMap":349},[343,366,371],{"className":367,"code":369,"language":370,"meta":349},[368],"language-java","BukkitBootstrap.RuntimeResult magic = BukkitBootstrap.forPlugin(this)\n        .enableCommands()\n        .buildRuntime();\n","java",[17,372,369],{"__ignoreMap":349},[357,374,375,381],{"v-slot:bungeecord":349},[343,376,379],{"className":377,"code":378,"language":348,"meta":349},[346],"dependencies {\n    implementation(\"dev.ua.theroer:magicutils-bungee:1.27.1\")\n}\n",[17,380,378],{"__ignoreMap":349},[343,382,385],{"className":383,"code":384,"language":370,"meta":349},[368],"BungeeBootstrap.RuntimeResult magic = BungeeBootstrap.forPlugin(this, \"MyPlugin\")\n        .enableCommands()\n        .buildRuntime();\n",[17,386,384],{"__ignoreMap":349},[357,388,389,395],{"v-slot:fabric":349},[343,390,393],{"className":391,"code":392,"language":348,"meta":349},[346],"dependencies {\n    modImplementation(include(\"dev.ua.theroer:magicutils-fabric-bundle:1.27.1\"))\n    modCompileOnly(\"dev.ua.theroer:magicutils-fabric-bundle:1.27.1:dev\")\n    modRuntimeOnly(\"dev.ua.theroer:magicutils-fabric-bundle:1.27.1:dev\")\n}\n",[17,394,392],{"__ignoreMap":349},[343,396,399],{"className":397,"code":398,"language":370,"meta":349},[368],"FabricBootstrap.RuntimeResult magic = FabricBootstrap.forMod(\"mymod\", () -> server)\n        .enableCommands()\n        .buildRuntime();\n",[17,400,398],{"__ignoreMap":349},[357,402,403,409],{"v-slot:velocity":349},[343,404,407],{"className":405,"code":406,"language":348,"meta":349},[346],"dependencies {\n    implementation(\"dev.ua.theroer:magicutils-velocity:1.27.1\")\n}\n",[17,408,406],{"__ignoreMap":349},[343,410,413],{"className":411,"code":412,"language":370,"meta":349},[368],"VelocityBootstrap.RuntimeResult magic = VelocityBootstrap.forPlugin(proxy, this, \"MyPlugin\", dataDirectory)\n        .enableCommands()\n        .buildRuntime();\n",[17,414,412],{"__ignoreMap":349},[357,416,417,423],{"v-slot:neoforge":349},[343,418,421],{"className":419,"code":420,"language":348,"meta":349},[346],"dependencies {\n    implementation(\"dev.ua.theroer:magicutils-neoforge:1.27.1\")\n    implementation(\"dev.ua.theroer:magicutils-commands-neoforge:1.27.1\")\n}\n",[17,422,420],{"__ignoreMap":349},[343,424,427],{"className":425,"code":426,"language":370,"meta":349},[368],"NeoForgeBootstrap.RuntimeResult magic = NeoForgeBootstrap.forMod(\"mymod\", () -> currentServer())\n        .enableCommands()\n        .buildRuntime();\n",[17,428,426],{"__ignoreMap":349},[13,430,431,434,435,437],{},[17,432,433],{},"buildRuntime()"," returns a managed ",[17,436,19],{}," wrapper, so you can keep one\nruntime handle and close it cleanly on shutdown.",[26,439,441],{"id":440},"where-to-go-next","Where To Go Next",[56,443,444,449,452,455,461,464,467],{},[59,445,446,447,104],{},"Read the Core \u002F Common Logic page when your code lives mostly in\n",[17,448,205],{},[59,450,451],{},"Read the installation guide for bundle options and modular setups.",[59,453,454],{},"Jump to Quickstart for end-to-end bootstrap examples per platform.",[59,456,457,458,460],{},"Read the Runtime guide for ",[17,459,19],{}," patterns and lifecycle management.",[59,462,463],{},"Use the Migration guide when updating older code samples or plugins.",[59,465,466],{},"Use the module pages for deeper API examples and config details.",[59,468,469],{},"Use the version selector in the header to switch between releases.",{"title":349,"searchDepth":471,"depth":471,"links":472},3,[473,475,476,477,478],{"id":28,"depth":474,"text":29},2,{"id":83,"depth":474,"text":84},{"id":149,"depth":474,"text":150},{"id":328,"depth":474,"text":329},{"id":440,"depth":474,"text":441},"MagicUtils is a modular Minecraft toolkit for Bukkit\u002FPaper\u002FFolia, BungeeCord, Velocity, Fabric, and NeoForge. Shared building blocks for config, lang, commands, logging, placeholders, and HTTP clients.","md",{},null,true,"\u002F","---\ntitle: MagicUtils\ndescription: MagicUtils is a modular Minecraft toolkit for Bukkit\u002FPaper\u002FFolia, BungeeCord, Velocity, Fabric, and NeoForge. Shared building blocks for config, lang, commands, logging, placeholders, and HTTP clients.\n---\n\n::hero\n::\n\nThe same stack also works well in multi-module projects where platform adapters\nonly bootstrap `MagicRuntime` and the real feature logic lives in shared\n`common` modules.\n\n## Why MagicUtils\n\nEvery server platform solves the same problems differently: styled text,\nconfig files, commands, permissions, per-player language. Writing a plugin and a\nmod usually means learning `ChatColor` on one side and Minecraft's `Text` on the\nother, hand-rolling config loaders, and branching command code per dispatcher.\n\nMagicUtils gives you one API for all of it, built on\n[Kyori Adventure](https:\u002F\u002Fdocs.advntr.dev\u002F) so text you author once renders\ncorrectly on Bukkit, BungeeCord, Velocity, Fabric, and NeoForge. You write the\nfeature once against `MagicRuntime`; the thin platform adapter is the only part\nthat changes. Concretely, that means:\n\n- One string with [MiniMessage](https:\u002F\u002Fdocs.advntr.dev\u002Fminimessage\u002Fformat.html)\n  or legacy `&` codes instead of per-platform colour handling.\n- Annotation-first commands with type parsers, options, and permissions instead\n  of dispatcher plumbing.\n- Config models with validation and migrations instead of manual file parsing.\n- Per-player localisation and placeholders wired into the same call sites.\n\n## Highlights\n\n- Bootstrap-first setup for Bukkit\u002FPaper\u002FFolia, BungeeCord, Velocity, and\n  Fabric via `BukkitBootstrap`, `BungeeBootstrap`, `VelocityBootstrap`, and\n  `FabricBootstrap`.\n- `MagicRuntime` container for managed shutdown hooks, typed components, and\n  named runtime resources.\n- Config manager with JSON\u002FJSONC, YAML, and TOML support plus migrations.\n- Annotation-first command framework with type parsers, options, and Brigadier\n  support where the platform supports it.\n- Adventure-based logger with rich formatting, sub-loggers, and help styling.\n- Language manager with MiniMessage, bundled messages, and per-player\n  overrides.\n- HTTP client wrapper with JSON mapping, retries, multipart uploads, and\n  runtime-bound profiles.\n- WebSocket client with the same builder pattern, config integration, and\n  runtime profiles.\n- Platform-agnostic player lifecycle and message events.\n- Config validation annotations (`@MinValue`, `@MaxValue`, `@ConfigSerializable`).\n- Placeholder registry with Bukkit PlaceholderAPI and Fabric placeholder\n  bridges.\n\n## Modules At A Glance\n\n| Layer | Artifacts | Notes |\n| --- | --- | --- |\n| Platform API | `magicutils-api` | `Platform`, `Audience`, `TaskScheduler`, and shared interfaces. |\n| Core stack | `magicutils-core` | Shared runtime container plus core config\u002Flang\u002Flogger\u002Fplaceholder wiring. |\n| Feature modules | `magicutils-logger`, `magicutils-commands`, `magicutils-config`, `magicutils-lang`, `magicutils-placeholders`, `magicutils-http-client` | Mix and match for manual setups. |\n| Format helpers | `magicutils-config-yaml`, `magicutils-config-toml` | Enable extra config formats. |\n| Platform adapters | `magicutils-bukkit`, `magicutils-fabric`, `magicutils-velocity`, `magicutils-neoforge` | Wire MagicUtils to each runtime. |\n| Platform bundles | `magicutils-bukkit-bundle`, `magicutils-fabric-bundle` | Shared server-side installs for Bukkit\u002FPaper and Fabric. |\n| Fabric integrations | `magicutils-commands-fabric`, `magicutils-logger-fabric`, `magicutils-placeholders-fabric` | Fabric-specific command, logger, and placeholder layers. |\n| Brigadier integrations | `magicutils-commands-brigadier`, `magicutils-commands-neoforge` | Shared Brigadier base and NeoForge command wiring. |\n\n## Quick Start\n\n1. Add the MagicUtils Maven repository.\n2. Add one platform entry point.\n3. Wire the runtime through the recommended bootstrap helper.\n\n```kotlin\nrepositories {\n    maven(\"https:\u002F\u002Fmaven.theroer.dev\u002Freleases\")\n}\n```\n\n::code-tabs{:tabs='[\"Bukkit\u002FPaper\u002FFolia\", \"BungeeCord\", \"Velocity\", \"Fabric\", \"NeoForge\"]'}\n\n#bukkit-paper-folia\n\n```kotlin\ndependencies {\n    implementation(\"dev.ua.theroer:magicutils-bukkit:1.27.1\")\n}\n```\n\n```java\nBukkitBootstrap.RuntimeResult magic = BukkitBootstrap.forPlugin(this)\n        .enableCommands()\n        .buildRuntime();\n```\n\n#bungeecord\n\n```kotlin\ndependencies {\n    implementation(\"dev.ua.theroer:magicutils-bungee:1.27.1\")\n}\n```\n\n```java\nBungeeBootstrap.RuntimeResult magic = BungeeBootstrap.forPlugin(this, \"MyPlugin\")\n        .enableCommands()\n        .buildRuntime();\n```\n\n#fabric\n\n```kotlin\ndependencies {\n    modImplementation(include(\"dev.ua.theroer:magicutils-fabric-bundle:1.27.1\"))\n    modCompileOnly(\"dev.ua.theroer:magicutils-fabric-bundle:1.27.1:dev\")\n    modRuntimeOnly(\"dev.ua.theroer:magicutils-fabric-bundle:1.27.1:dev\")\n}\n```\n\n```java\nFabricBootstrap.RuntimeResult magic = FabricBootstrap.forMod(\"mymod\", () -> server)\n        .enableCommands()\n        .buildRuntime();\n```\n\n#velocity\n\n```kotlin\ndependencies {\n    implementation(\"dev.ua.theroer:magicutils-velocity:1.27.1\")\n}\n```\n\n```java\nVelocityBootstrap.RuntimeResult magic = VelocityBootstrap.forPlugin(proxy, this, \"MyPlugin\", dataDirectory)\n        .enableCommands()\n        .buildRuntime();\n```\n\n#neoforge\n\n```kotlin\ndependencies {\n    implementation(\"dev.ua.theroer:magicutils-neoforge:1.27.1\")\n    implementation(\"dev.ua.theroer:magicutils-commands-neoforge:1.27.1\")\n}\n```\n\n```java\nNeoForgeBootstrap.RuntimeResult magic = NeoForgeBootstrap.forMod(\"mymod\", () -> currentServer())\n        .enableCommands()\n        .buildRuntime();\n```\n\n::\n\n`buildRuntime()` returns a managed `MagicRuntime` wrapper, so you can keep one\nruntime handle and close it cleanly on shutdown.\n\n## Where To Go Next\n\n- Read the Core \u002F Common Logic page when your code lives mostly in\n  `magicutils-core`.\n- Read the installation guide for bundle options and modular setups.\n- Jump to Quickstart for end-to-end bootstrap examples per platform.\n- Read the Runtime guide for `MagicRuntime` patterns and lifecycle management.\n- Use the Migration guide when updating older code samples or plugins.\n- Use the module pages for deeper API examples and config details.\n- Use the version selector in the header to switch between releases.\n",{"title":5,"description":479},"index","YGGPwv-JlNSy0xl9GDGSggjvwfzF43DRL3WZwupSSOw",1783944484806]