Installation¶

MagicUtils is split into modules. For most projects you only need one platform entry point (magicutils-bukkit, magicutils-fabric-bundle, magicutils-velocity, 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.14.3 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 GitHub Pages Maven repository.

repositories {
    maven("https://theroer.github.io/MagicUtils/maven/")
}

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.
Velocity plugin	`magicutils-velocity`	Includes config/logger/lang/commands support.
NeoForge mod	`magicutils-neoforge` + `magicutils-commands-neoforge`	Placeholder bridge is not available yet.
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.

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 DSL:

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

Groovy DSL:

dependencies {
    implementation 'dev.ua.theroer:magicutils-bukkit:1.14.3'
    implementation 'dev.ua.theroer:magicutils-config-yaml:1.14.3'
    implementation 'dev.ua.theroer:magicutils-config-toml:1.14.3'
}

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):

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

Install the bundle on the server:

Drop magicutils-bukkit-bundle-1.14.3.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 DSL:

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

Groovy DSL:

dependencies {
    modImplementation(include('dev.ua.theroer:magicutils-fabric-bundle:1.14.3'))
    modCompileOnly 'dev.ua.theroer:magicutils-fabric-bundle:1.14.3:dev'
    modRuntimeOnly 'dev.ua.theroer:magicutils-fabric-bundle:1.14.3: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.

dependencies {
    modImplementation("dev.ua.theroer:magicutils-fabric-bundle:1.14.3: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.14.3.jar

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

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

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.

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

NeoForge¶

NeoForge exposes platform, config, logger, and Brigadier command integrations. There is no NeoForge placeholder bridge yet.

Kotlin DSL:

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

Groovy DSL:

dependencies {
    implementation 'dev.ua.theroer:magicutils-neoforge:1.14.3'
    implementation 'dev.ua.theroer:magicutils-commands-neoforge:1.14.3'
}

Velocity¶

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

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

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¶

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

Notes On Shaded Artifacts¶

Local builds produce *-all artifacts (shaded). The GitHub Pages repository does not include these files due to the 100 MB limit, so do not depend on them.