Uniform/README.md

Uniform is cross-platform wrapper for making Brigadier commands, based on BrigadierWrapper by Tofaa2, which itself was inspired by EmortalMC's command-system.

Compatibility

Versions are available on maven in the format net.william278.uniform:ARTIFACT:VERSION. See below for a table of supported platforms.

Note that Uniform versions omit the v prefix. Fabric versions are suffixed with the target Minecraft version (e.g. 1.2.1+1.21) and also require Fabric API installed on the server. Sponge versions are suffixed with the target Sponge API version (e.g. 1.2.1+11).

Uniform Version Table
Platform	Artifact	Minecraft ver.	Java ver.	Uniform ver.
Common	uniform-common	N/A	≥17
Supported Platforms
Bukkit / Spigot	uniform-bukkit	≥1.17.1	≥17
Paper	uniform-paper
Velocity (3.3.0)	uniform-velocity	≥1.8.9
Sponge (api 11)	uniform-sponge	=1.20.6	≥21
Fabric (1.20.1)	uniform-fabric	=1.20.1
Fabric (1.21)		=1.21
Formerly Supported Platforms
Fabric (1.20.6)	uniform-fabric	=1.20.6	≥21	v1.1.8

Example: To target Uniform on Bukkit, the artifact is net.william278.uniform:uniform-bukkit:1.2.1 (check that this version is up-to-date – make sure you target the latest available!).

Setup

Uniform is available on Maven. You can browse the Javadocs here.

Gradle setup instructions

First, add the Maven repository to your build.gradle file:

repositories {
    maven { url "https://repo.william278.net/releases" }
}

Then, add the dependency itself. Replace VERSION with the latest release version. (e.g., 1.2.1) and PLATFORM with the platform you are targeting (e.g., paper). If you want to target pre-release "snapshot" versions (not recommended), you should use the /snapshots repository instead.

dependencies {
    implementation "net.william278.uniform:uniform-PLATFORM:VERSION"
}

Using Maven/something else? There's instructions on how to include Uniform on the repo browser.

Basic use

Uniform lets you create commands either natively per-platform, or cross-platform (by compiling against uniform-common in a common module, then implementing uniform-PLATFORM in each platform, getting the platform specific Uniform manager instance and registering your commands).

Check example-plugin for a full example of a cross-platform command being registered on Paper.

Cross-platform commands

Cross-platform commands can be created by registering Command objects; you can create these from @CommandNode annotated objects, or by extending Command and providing these yourself.

Using annotations

You can use the @CommandNode annotations to easily create cross-platform Brigadier commands (since: v1.2). This is the recommended way to create commands.

@CommandNode(
        value = "helloworld",
        aliases = {"hello", "hi"},
        description = "A simple hello world command",
        permission = @PermissionNode(
                value = "example.command.helloworld",
                defaultValue = Permission.Default.TRUE
        )
)
public class AnnotatedCommand {

    @Syntax
    public void execute(CommandUser user) {
        user.getAudience().sendMessage(Component.text("Hello, world!"));
    }

    @Syntax
    public void pongMessage(
            CommandUser user,
            @Argument(name = "message", parser = Argument.StringArg.class) String message
    ) {
        user.getAudience().sendMessage(Component.text("Hello, " + message, NamedTextColor.GREEN));
    }
    
    @CommandNode(
            value = "subcommand",
            aliases = {"sub", "hi"}
    )
    static class SubCommand {
        @Syntax
        public void execute(CommandUser user) {
            user.getAudience().sendMessage(Component.text("Subcommand executed!"));
        }
    }

}

By extending the Command class.

You can also extend the Command class to create a Command object you can register. You'll want to use BaseCommand#getUser to get a platform-agnostic User from which you can acquire the adventure Audience to send messages to.

public class ExampleCrossPlatCommand extends Command {
    public ExampleCrossPlatCommand() {
        super("example", "cross-platform");
    }

    @Override
    public <S> void provide(@NotNull BaseCommand<S> command) {
        // What gets executed when no args are passed. 
        // For tidiness, feel free to delegate this stuff to methods!
        command.setDefaultExecutor((context) -> {
            // Use command.getUser(context.getSource()) to get the user
            final Audience user = command.getUser(context.getSource()).getAudience();
            user.sendMessage(Component.text("Hello, world!"));
        });

        // Add syntax to the command
        command.addSyntax((context) -> {
            final Audience user = command.getUser(ctx.getSource()).getAudience();
            user.sendMessage(Component.text("Woah!!!!"));
            String arg = context.getArgument("message", String.class);
            user.sendMessage(MiniMessage.miniMessage().deserialize(arg));
        }, stringArg("message"));

        // Sub-commands, too
        command.addSubCommand("subcommand", (sub) -> {
            sub.setDefaultExecutor((context) -> {
                final Audience user = sub.getUser(context.getSource()).getAudience();
                user.sendMessage(Component.text("Subcommand executed!"));
            });
        });
    }
}

Platform-specific commands

If you need platform-specific features, extend the platform-specific PlatformCommand class and add your Brigadier syntax.

public class ExampleCommand extends PaperCommand {
    public ExampleCommand() {
        super("example", "platform-specific");
        command.setDefaultExecutor((context) -> {
            context.getSource().getBukkitSender().sendMessage("Hello, world!");
        });
        addSyntax((context) -> {
            context.getSource().getBukkitSender().sendMessage("Woah!!!!");
            String arg = context.getArgument("message", String.class);
            context.getSource().getBukkitSender()
                .sendMessage(MiniMessage.miniMessage().deserialize(arg));
        }, stringArg("message"));
    }
}

Registering

Then, register the command with the platform-specific Uniform instance (e.g. FabricUniform.getInstance(), PaperUniform.getInstance(), etc...)

Building

To build Uniform, run clean build in the root directory. The output JARs will be in target/.

License

Uniform is licensed under GPL v3 as it derives from BrigadierWrapper. See LICENSE for more information.