Bukkit/Paper/Folia

Bukkit/Paper

Use magicutils-bukkit to wire MagicUtils to Bukkit, Paper, and Folia.

If you want a shared install for multiple plugins, use magicutils-bukkit-bundle as a standalone plugin and add a dependency on it in your plugin.yml (depend: [MagicUtils] or softdepend).

Folia support

magicutils-bukkit runs on Folia with no extra configuration. BukkitBootstrap detects the Folia runtime at startup and installs a region-aware platform, so runOnMain(...) schedules on the global region and runForAudience(player, ...) resolves the correct entity region. On regular Bukkit/Paper the same calls run on the main server thread.

For direct control, the BukkitThreading helper works on both Folia and regular servers:

  • BukkitThreading.isFoliaRuntime() reports whether Folia is active.
  • runGlobal(plugin, task) runs on the global region (or the main thread).
  • runEntity(plugin, entity, task) / runForSender(plugin, sender, task) run on the region that owns the entity/sender.
  • isGlobalThread() / isOwnedByCurrentRegion(entity) are guards for region-sensitive code.
java
public final class MyPlugin extends JavaPlugin {    private BukkitBootstrap.RuntimeResult magic;    @Override    public void onEnable() {        magic = BukkitBootstrap.forPlugin(this)                .enableCommands()                .configureCommands(registry -> registry.registerCommand(new ExampleCommand()))                .buildRuntime();    }    @Override    public void onDisable() {        if (magic != null) {            magic.runtime().close();            magic = null;        }    }}

build() returns the legacy bootstrap view. buildRuntime() additionally gives you a managed MagicRuntime.

Manual Wiring

java
Platform platform = new BukkitPlatformProvider(plugin);ConfigManager configManager = new ConfigManager(platform);Logger logger = new Logger(platform, plugin, configManager);

Use the manual path only when you need full control over how the services are created.

Bootstrap Options

BukkitBootstrap.Builder supports the following configuration:

MethodDescription
logger(logger)Bind an existing java.util.logging.Logger.
enableCommands()Create a CommandRegistry during bootstrap.
permissionPrefix(prefix)Set the permission node prefix for commands.
configureCommands(consumer)Register commands during bootstrap.
enableDiagnostics()Enable the diagnostics service.
configureDiagnostics(consumer)Register custom diagnostic checks.
initLanguage(boolean)Enable/disable language manager initialization.
bindLoggerLanguage(boolean)Bind the language manager to the logger.
setMessagesManager(boolean)Set the global Messages language manager.
registerMessages(boolean)Register the plugin's messages scope.
addMagicUtilsMessages(boolean)Register built-in MagicUtils messages.
bindClientLocaleSync(boolean)Follow each player's client locale.
translations(consumer)Configure additional translations.

Commands

BukkitBootstrap.enableCommands() creates a CommandRegistry for the plugin. The registry registers commands directly with the Bukkit CommandMap, so you do not need to declare them in plugin.yml.

Permission nodes are resolved using the prefix passed to permissionPrefix(...) or, by default, the plugin name.

Placeholders

When PlaceholderAPI is installed, MagicUtils placeholders can be bridged into PlaceholderAPI through the Bukkit integration layer.