Installation

MagicUtils is split into modules. For most projects you only need one platform entry point (magicutils-bukkit, magicutils-bungee, magicutils-velocity, magicutils-fabric-bundle, or magicutils-neoforge) plus optional format helpers.

Use the modular artifacts only when you need a custom wiring path.

Choose A Version

This documentation is versioned. The examples below use 1.22.0 which matches the current docs version.

If you want to hardcode it in your build, replace it with the exact number (for example 1.10.0).

Repositories

Add the MagicUtils Maven repository.

kotlin

repositories {    maven("https://maven.theroer.dev/releases")}

Which Artifact Do I Need?

Scenario	Recommended artifacts	Notes
Bukkit/Paper plugin	`magicutils-bukkit`	Default choice for most plugins.
Shared Bukkit server install	`magicutils-bukkit-bundle` + plugin `compileOnly` dependency	Use when multiple plugins should share one install.
Fabric mod	`magicutils-fabric-bundle`	Default choice for most mods.
Shared Fabric server install	`magicutils-fabric-bundle:dev` without `include(...)`	Install the bundle mod on the server.
Modular Fabric setup	`magicutils-fabric` + Fabric integration modules	Use only when you want custom wiring.
BungeeCord plugin	`magicutils-bungee`	Includes config/logger/lang/commands/diagnostics support.
Velocity plugin	`magicutils-velocity`	Includes config/logger/lang/commands support.
NeoForge mod	`magicutils-neoforge` + `magicutils-commands-neoforge`	`NeoForgeBootstrap` lives in `magicutils-commands-neoforge`. Placeholder bridge not available yet.
Shared NeoForge server install	`magicutils-neoforge-bundle`	Standalone bundle mod for the server, like the Fabric bundle.
Extra config formats	`magicutils-config-yaml`, `magicutils-config-toml`	Optional helpers for YAML and TOML.
HTTP client	`magicutils-http-client`	Optional runtime-aware HTTP/WebSocket clients.

Quick Install

Pick your platform, then your Gradle DSL. The DSL choice is remembered across the page, so you only set Kotlin or Groovy once.

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-bukkit:1.22.0")}

The sections below cover bundle options, shared server installs, and modular setups per platform.

Bukkit/Paper

The Bukkit/Paper adapter bundles the core modules (config, logger, commands, lang, placeholders). Add optional format helpers only when you need them.

You can use it in two ways:

Embed MagicUtils into your plugin.
Use a shared MagicUtils plugin (magicutils-bukkit-bundle) so multiple plugins reuse the same runtime.

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-bukkit:1.22.0")    implementation("dev.ua.theroer:magicutils-config-yaml:1.22.0")    implementation("dev.ua.theroer:magicutils-config-toml:1.22.0")}

Shared Bukkit Bundle

If you want a single shared MagicUtils install for multiple plugins, use the bundle plugin and do not embed MagicUtils inside your plugins.

Dependencies (compile-only):

kotlin

dependencies {    compileOnly("dev.ua.theroer:magicutils-bukkit-bundle:1.22.0")}

Install the bundle on the server:

Drop magicutils-bukkit-bundle-1.22.0.jar into plugins/.
Add depend: [MagicUtils] (or softdepend) to your plugin.yml.

Fabric

You have two options:

Embed The Bundle Inside Your Mod

This is the recommended approach for single-mod setups and avoids requiring server owners to install MagicUtils separately.

kotlin

dependencies {    modImplementation(include("dev.ua.theroer:magicutils-fabric-bundle:1.22.0"))    modCompileOnly("dev.ua.theroer:magicutils-fabric-bundle:1.22.0:dev")    modRuntimeOnly("dev.ua.theroer:magicutils-fabric-bundle:1.22.0:dev")}

Depend On A Shared Bundle Mod

If you want one shared MagicUtils install for multiple mods, use a standard dependency and install the bundle mod on the server.

kotlin

dependencies {    modImplementation("dev.ua.theroer:magicutils-fabric-bundle:1.22.0:dev")}

If you pick the shared bundle, add the magicutils-fabric-bundle mod to the server mods/ folder and do not embed it inside other mods.

You can download the bundle from the Maven repository: magicutils-fabric-bundle-1.22.0.jar

You can also add a dependency in your fabric.mod.json:

json

{  "depends": {    "magicutils-fabric-bundle": ">=1.22.0"  }}

Modular Fabric Dependencies

Use this only when you want to wire specific modules yourself instead of using the bundle. FabricBootstrap lives in the command integration layer, so a bootstrap-first modular setup usually pulls both the platform adapter and the Fabric integration modules.

kotlin

dependencies {    modImplementation("dev.ua.theroer:magicutils-fabric:1.22.0:dev")    modImplementation("dev.ua.theroer:magicutils-logger-fabric:1.22.0:dev")    modImplementation("dev.ua.theroer:magicutils-commands-fabric:1.22.0:dev")    modImplementation("dev.ua.theroer:magicutils-placeholders-fabric:1.22.0:dev")    modImplementation("dev.ua.theroer:magicutils-config:1.22.0")    modImplementation("dev.ua.theroer:magicutils-lang:1.22.0")}

NeoForge

NeoForge exposes platform, config, logger, and Brigadier command integrations. There is no NeoForge placeholder bridge yet. NeoForgeBootstrap lives in magicutils-commands-neoforge, so include it even if you register no commands.

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-neoforge:1.22.0")    implementation("dev.ua.theroer:magicutils-commands-neoforge:1.22.0")}

See NeoForge for the NeoForgeBootstrap wiring example.

Shared NeoForge Bundle

If you want a single shared MagicUtils install for multiple mods, install the standalone bundle mod on the server and do not embed MagicUtils inside your mods. It works like the Fabric bundle: drop the bundle jar in mods/ and depend on it from your neoforge.mods.toml.

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-neoforge-bundle:1.22.0")}

BungeeCord

The BungeeCord adapter exposes platform, config, logger, lang, command, and diagnostics integration in a single artifact.

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-bungee:1.22.0")}

See BungeeCord for the BungeeBootstrap wiring example.

Velocity

The Velocity adapter exposes platform, config, logger, lang, and command integration in a single artifact.

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-velocity:1.22.0")}

Optional Format Helpers

magicutils-config-yaml enables YAML support.
magicutils-config-toml enables TOML support.

Without them, MagicUtils uses JSON or JSONC (Fabric default).

Optional HTTP Client

kotlin

dependencies {    implementation("dev.ua.theroer:magicutils-http-client:1.22.0")}

Notes On Shaded Artifacts

Local builds produce *-all artifacts (shaded). The published Maven repository (maven.theroer.dev) does not include these files, so do not depend on them.