Velocity

magicutils-velocity exposes platform wiring, config, logger, lang, and command integration in one artifact.

Shared Bundle Install

If several plugins on the proxy use MagicUtils, install magicutils-velocity-bundle as a standalone proxy plugin instead of shading MagicUtils into each one. It is a drop-in magicutils plugin that boots one shared MagicRuntime and registers /magicutils (alias mu) with diagnostics sub-commands. Downstream plugins declare a dependency on it (via @Plugin(dependencies = ...)) and register with the shared runtime through VelocityMagicUtilsConsumerRegistry, so /magicutils mods lists them live. The published bundle jar is a shaded runnable artifact — the same one exercised by the compatibility smoke.

Do not do both: either embed MagicUtils in your plugin, or depend on the shared bundle — not both on the same proxy.

Dependency

kotlin

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

Recommended Bootstrap

java

@Plugin(id = "myplugin", name = "MyPlugin", version = "1.0.0")public final class MyPlugin {    private final ProxyServer proxy;    private final org.slf4j.Logger slf4j;    private final Path dataDirectory;    private VelocityBootstrap.RuntimeResult magic;    @Inject    public MyPlugin(ProxyServer proxy,                    org.slf4j.Logger slf4j,                    @DataDirectory Path dataDirectory) {        this.proxy = proxy;        this.slf4j = slf4j;        this.dataDirectory = dataDirectory;    }    @Subscribe    public void onProxyInitialize(ProxyInitializeEvent event) {        magic = VelocityBootstrap.forPlugin(proxy, this, "MyPlugin", dataDirectory)                .slf4j(slf4j)                .enableCommands()                .configureCommands(registry -> registry.registerCommand(new ExampleCommand()))                .buildRuntime();    }    @Subscribe    public void onProxyShutdown(ProxyShutdownEvent event) {        if (magic != null) {            magic.runtime().close();            magic = null;        }    }}

VelocityBootstrap creates the Platform, ConfigManager, LoggerCore, LanguageManager, and optional CommandRegistry for the plugin.

Commands

Velocity commands register directly with the proxy command manager.

Use enableCommands() to create the registry during bootstrap.
Use configureCommands(...) to register commands right away.
Use asyncExecutor(...) when you want to override the default async executor used by the command layer.

Sending Messages To A Player

Unlike Bukkit/Fabric, the Velocity module ships no Logger wrapper — the bootstrap gives you a LoggerCore, not the Logger convenience type. To send a MiniMessage-formatted line to a specific command sender, resolve them to a MagicUtils Audience through the Platform and hand it to the logger:

java

Platform platform = magic.platform();LoggerCore logger = magic.logger();void message(CommandSource source, String miniMessage) {    Audience audience = source instanceof Player player            ? platform.playerByName(player.getUsername()) // by username on the proxy            : platform.console();    if (audience != null) {        logger.info().to(audience).send(miniMessage); // MiniMessage tags render,                                                       // including <click>/<hover>    }}

platform.playerByName(...) and platform.console() are the supported way to obtain an Audience; the concrete Velocity audience type is package-private, so there is no new VelocityAudience(...). Because the logger formats through MiniMessage, <click:run_command:'...'> and <hover:show_text:'...'> in the message become interactive chat components — handy for clickable command menus.

Bootstrap Options

VelocityBootstrap.Builder supports additional configuration beyond the basics:

Method	Description
`slf4j(logger)`	Bind SLF4J logger for console output.
`enableCommands()`	Create a `CommandRegistry` during bootstrap.
`permissionPrefix(prefix)`	Set the permission node prefix for commands.
`asyncExecutor(executor)`	Override the async executor used by the command layer.
`configureCommands(consumer)`	Register commands during bootstrap.
`enableDiagnostics()`	Enable the diagnostics service.
`configureDiagnostics(consumer)`	Register custom diagnostic checks.
`bindClientLocaleSync(boolean)`	Follow each player's client locale.
`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.
`translations(consumer)`	Configure additional translations.

Player Events

Velocity supports the platform-agnostic player lifecycle and message events:

java

platform.subscribePlayerLifecycle(event -> {    if (event.type() == PlayerLifecycleType.JOIN) {        logger.info(event.playerName() + " connected");    }});

See Core / Common Logic for the full event API.

Notes

Platform.runOnMain(...) executes immediately because Velocity has no main game thread.
buildRuntime() returns a managed MagicRuntime and wires shutdown cleanup through the plugin instance you pass to the platform provider.