Getting Started

Getting Started

PowerLib is a cross-platform utility library for Minecraft plugins. It provides a single, consistent API for messages, configuration, items, inventories, commands, the scheduler, and cross-server messaging that behaves the same on Bukkit/Spigot/Paper, BungeeCord, and Velocity. Everything is built on top of Adventure, so colours, hex, click/hover events and (optionally) MiniMessage work uniformly across platforms.

The library is split into a platform-agnostic common module and a thin per-platform module that binds it to the running server or proxy. You depend on the module that matches your platform; it pulls in powerlib-common transitively.

Supported platforms

Platform	Module (artifactId)	Server API	Bootstrap call site
Bukkit / Spigot / Paper	powerlib-bukkit	paper-api 1.20.4	onEnable()
BungeeCord	powerlib-bungee	bungeecord-api	onEnable()
Velocity	powerlib-velocity	velocity-api 3.3.0	@Subscribe ProxyInitializeEvent

All three modules share it.mycraft:powerlib-common, which holds the cross-platform logic (Message, Configuration, ConfigManager, cross-server channels, …).

Requirements

• Java 17 or newer. The library is compiled at bytecode level 17.
• Adventure-capable server. On Bukkit, PowerLib bundles adventure-platform-bukkit, so any Spigot/Paper 1.16+ server works; native Adventure (Paper) is used directly where present. Bungee and Velocity are Adventure-native.
• The Bukkit module is built against paper-api 1.20.4. It runs on later versions; if you call version-specific item/inventory APIs, test against your target server build.

---

Adding the dependency

PowerLib is published to the CodeMC repository. Add the repository, then the module for your platform.

There are two ways to consume it, and they change the dependency scope:

1. As a runtime plugin dependency — you ship PowerLib as a separate plugin on the server and declare a dependency on it. Use provided scope so PowerLib's classes are not bundled into your jar. This is the lightest option and lets several plugins share one PowerLib instance. In this mode PowerLib bootstraps itself; you do not call inject(...).
2. Shaded into your plugin — you relocate and bundle PowerLib inside your own jar so there is no extra plugin to install. Use compile scope and the Shade plugin. In this mode you are the owning plugin, so you must call PowerLib.inject(...) yourself (see Bootstrapping).

The two modes are mutually exclusive. Pick one. If a standalone PowerLib plugin is present, shading also works but is redundant — prefer provided.

Maven

Repository:

<repositories>
    <repository>
        <id>codemc</id>
        <url>https://repo.codemc.io/repository/maven-public/</url>
    </repository>
</repositories>

Dependency — pick one module. Bukkit shown; swap the artifactId for powerlib-bungee or powerlib-velocity:

<dependency>
    <groupId>it.mycraft</groupId>
    <artifactId>powerlib-bukkit</artifactId>
    <version>1.3.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

Use <scope>provided</scope> when PowerLib runs as its own plugin (mode 1). Switch to <scope>compile</scope> only if you intend to shade it (mode 2).

Shading (mode 2 only)

Bundle and relocate PowerLib into your jar so it does not clash with other plugins that ship their own copy:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.5.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <relocations>
                            <relocation>
                                <pattern>it.mycraft.powerlib</pattern>
                                <shadedPattern>com.example.myplugin.libs.powerlib</shadedPattern>
                            </relocation>
                        </relocations>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Remember to set the dependency scope to compile when shading, otherwise the classes are not on the runtime classpath to relocate.

Gradle

repositories {
    maven("https://repo.codemc.io/repository/maven-public/")
}

dependencies {
    // Mode 1 — PowerLib runs as its own plugin:
    compileOnly("it.mycraft:powerlib-bukkit:1.3.1-SNAPSHOT")

    // Mode 2 — shade it instead (remove the line above):
    // implementation("it.mycraft:powerlib-bukkit:1.3.1-SNAPSHOT")
}

compileOnly is the Gradle equivalent of Maven's provided. For shading, use implementation together with the Shadow plugin and relocate it.mycraft.powerlib as shown above.

Add-on modules

The core platform module is enough for messages, config, items, inventories and the scheduler. The following modules are optional and only needed for the features they name. Add them with the same scope as your platform module.

Module (artifactId)	Adds
powerlib-minimessage	MiniMessage parsing for messages
powerlib-components	Adventure component builders / helpers
powerlib-commands-api	Platform-agnostic command framework (depend on this for shared command code)
powerlib-commands-bukkit	Command framework binding for Bukkit
powerlib-commands-bungee	Command framework binding for BungeeCord
powerlib-commands-velocity	Command framework binding for Velocity

<dependency>
    <groupId>it.mycraft</groupId>
    <artifactId>powerlib-minimessage</artifactId>
    <version>1.3.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

There is also an aggregate powerlib-all artifact that pulls every module together. It is intended for the standalone PowerLib plugin build; for a normal consumer, depend only on the modules you use.

---

Bootstrapping PowerLib

Each platform module exposes a static it.mycraft.powerlib.<platform>.PowerLib holder with an inject(...) method. It stores the owning plugin and creates the Adventure platform handle. Call it once, as early as possible in your plugin's startup, before you use any messaging API.

If you ship PowerLib as a standalone plugin (mode 1), it injects itself and you can skip this — just declare a dependency on the PowerLib plugin in your plugin.yml / Bungee / Velocity metadata. If you shade PowerLib (mode 2), the snippets below are mandatory.

Bukkit / Spigot / Paper

PowerLib.inject(Plugin) stores your plugin, builds the BukkitAudiences Adventure handle, and registers optional integrations (e.g. the Nexo custom-item bridge, a no-op unless Nexo is installed).

package com.example.myplugin;

import it.mycraft.powerlib.bukkit.PowerLib;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        PowerLib.inject(this);

        // ... your plugin setup ...
    }
}

The Adventure platform is torn down implicitly when the server disables your plugin; afterwards PowerLib.adventure() throws IllegalStateException. Do not cache audiences across a reload.

BungeeCord

Identical pattern in onEnable(). inject(Plugin) binds the plugin and creates the BungeeAudiences handle.

package com.example.myplugin;

import it.mycraft.powerlib.bungee.PowerLib;
import net.md_5.bungee.api.plugin.Plugin;

public final class MyPlugin extends Plugin {

    @Override
    public void onEnable() {
        PowerLib.inject(this);

        // ... your plugin setup ...
    }
}

Velocity

Velocity plugins are constructed by the proxy and have no onEnable(). Bootstrap PowerLib from a method annotated with @Subscribe that listens for ProxyInitializeEvent. The proxy is injected into your plugin's constructor.

PowerLib.inject(ProxyServer, Object) binds both the proxy and your plugin instance so the scheduler can build tasks bound to your plugin.

package com.example.myplugin;

import com.google.inject.Inject;
import com.velocitypowered.api.event.Subscribe;
import com.velocitypowered.api.event.proxy.ProxyInitializeEvent;
import com.velocitypowered.api.plugin.Plugin;
import com.velocitypowered.api.proxy.ProxyServer;
import it.mycraft.powerlib.velocity.PowerLib;

@Plugin(id = "myplugin", name = "MyPlugin", version = "1.0.0")
public final class MyPlugin {

    private final ProxyServer proxy;

    @Inject
    public MyPlugin(ProxyServer proxy) {
        this.proxy = proxy;
    }

    @Subscribe
    public void onProxyInitialization(ProxyInitializeEvent event) {
        PowerLib.inject(proxy, this);

        // ... your plugin setup ...
    }
}

There is a deprecated single-argument PowerLib.inject(ProxyServer) overload. Prefer the two-argument form — without the plugin instance, the scheduler cannot bind tasks to your plugin.

---

Modules at a glance

Once PowerLib is bootstrapped, every feature is reachable from the common API. Each area has its own page:

Module	What it does
Messages	Message — colour/hex/legacy + Adventure, placeholders, multi-line, click/hover, broadcast
Scheduler	Unified sync/async task scheduling across all three platforms
Cross-Server Messaging	Send data between proxy and backends over plugin messaging channels
Configuration	ConfigManager / Configuration — create, load, read and save YAML configs
Items	Fluent ItemStack / item builders, including custom-item plugin bridges
Inventories	Build and manage GUIs and inventory menus
Commands	The commands-api framework and its per-platform bindings
Utilities	Assorted helpers shared across the library