Home

MagicUtils

MagicUtils is a modular toolkit for Bukkit/Paper/Folia, BungeeCord, Velocity, Fabric, and NeoForge. It provides shared building blocks for configuration, localisation, commands, logging, placeholders, HTTP clients, and platform adapters.

The same stack also works well in multi-module projects where platform adapters only bootstrap MagicRuntime and the real feature logic lives in shared common modules.

Why MagicUtils

Every server platform solves the same problems differently: styled text, config files, commands, permissions, per-player language. Writing a plugin and a mod usually means learning ChatColor on one side and Minecraft's Text on the other, hand-rolling config loaders, and branching command code per dispatcher.

MagicUtils gives you one API for all of it, built on Kyori Adventure so text you author once renders correctly on Bukkit, BungeeCord, Velocity, Fabric, and NeoForge. You write the feature once against MagicRuntime; the thin platform adapter is the only part that changes. Concretely, that means:

  • One string with MiniMessage or legacy & codes instead of per-platform colour handling.
  • Annotation-first commands with type parsers, options, and permissions instead of dispatcher plumbing.
  • Config models with validation and migrations instead of manual file parsing.
  • Per-player localisation and placeholders wired into the same call sites.

Highlights

  • Bootstrap-first setup for Bukkit/Paper/Folia, BungeeCord, Velocity, and Fabric via BukkitBootstrap, BungeeBootstrap, VelocityBootstrap, and FabricBootstrap.
  • MagicRuntime container for managed shutdown hooks, typed components, and named runtime resources.
  • Config manager with JSON/JSONC, YAML, and TOML support plus migrations.
  • Annotation-first command framework with type parsers, options, and Brigadier support where the platform supports it.
  • Adventure-based logger with rich formatting, sub-loggers, and help styling.
  • Language manager with MiniMessage, bundled messages, and per-player overrides.
  • HTTP client wrapper with JSON mapping, retries, multipart uploads, and runtime-bound profiles.
  • WebSocket client with the same builder pattern, config integration, and runtime profiles.
  • Platform-agnostic player lifecycle and message events.
  • Config validation annotations (@MinValue, @MaxValue, @ConfigSerializable).
  • Placeholder registry with Bukkit PlaceholderAPI and Fabric placeholder bridges.

Modules At A Glance

LayerArtifactsNotes
Platform APImagicutils-apiPlatform, Audience, TaskScheduler, and shared interfaces.
Core stackmagicutils-coreShared runtime container plus core config/lang/logger/placeholder wiring.
Feature modulesmagicutils-logger, magicutils-commands, magicutils-config, magicutils-lang, magicutils-placeholders, magicutils-http-clientMix and match for manual setups.
Format helpersmagicutils-config-yaml, magicutils-config-tomlEnable extra config formats.
Platform adaptersmagicutils-bukkit, magicutils-fabric, magicutils-velocity, magicutils-neoforgeWire MagicUtils to each runtime.
Platform bundlesmagicutils-bukkit-bundle, magicutils-fabric-bundleShared server-side installs for Bukkit/Paper and Fabric.
Fabric integrationsmagicutils-commands-fabric, magicutils-logger-fabric, magicutils-placeholders-fabricFabric-specific command, logger, and placeholder layers.
Brigadier integrationsmagicutils-commands-brigadier, magicutils-commands-neoforgeShared Brigadier base and NeoForge command wiring.

Quick Start

  1. Add the MagicUtils Maven repository.
  2. Add one platform entry point.
  3. Wire the runtime through the recommended bootstrap helper.
kotlin
repositories {    maven("https://maven.theroer.dev/releases")}
kotlin
dependencies {    implementation("dev.ua.theroer:magicutils-bukkit:1.22.0")}
java
BukkitBootstrap.RuntimeResult magic = BukkitBootstrap.forPlugin(this)        .enableCommands()        .buildRuntime();

buildRuntime() returns a managed MagicRuntime wrapper, so you can keep one runtime handle and close it cleanly on shutdown.

Where To Go Next

  • Read the Core / Common Logic page when your code lives mostly in magicutils-core.
  • Read the installation guide for bundle options and modular setups.
  • Jump to Quickstart for end-to-end bootstrap examples per platform.
  • Read the Runtime guide for MagicRuntime patterns and lifecycle management.
  • Use the Migration guide when updating older code samples or plugins.
  • Use the module pages for deeper API examples and config details.
  • Use the version selector in the header to switch between releases.