Aller au contenu principal

Introduction

Imperat is a powerful command dispatching framework, it allows you to create commands and converts them into the form of multiple data-condensed objects like Command, CommandUsage and CommandParameter These objects are registered/injected into the class Imperat which handles all information about each command and then dispatches/executes the command requested.

Installation

Imperat is a versatile command dispatching framework designed to work across various platforms with the appropriate implementation. This is will guide you through the installation step by step.

Repository setup​

Most builds won't require special repository configuration as Imperat artifacts are hosted on Maven Central. However, if you need to explicitly declare it:

<repositories>
  <repository>
    <id>maven-central</id>
    <url>https://repo1.maven.org/maven2/</url>
  </repository>
</repositories>

Core Dependency setup​

Before adding any platform-specific module, you must include the core Imperat dependency:

<dependency>
  <groupId>dev.velix</groupId>
  <artifactId>imperat-core</artifactId>
  <version>loading...</version>
</dependency>

Platform Dependency setup​

Choose the platform you are developing for to see specific setup instructions.

Implementation for Bukkit-based Minecraft servers (like Spigot, Paper).

  • Imperat Class: BukkitImperat
  • Command Source: BukkitSource

Installation

<dependency>
  <groupId>dev.velix</groupId>
  <artifactId>imperat-bukkit</artifactId>
  <version>loading...</version>
</dependency>
Brigadier Integration

You can integrate Imperat with Mojang's Brigadier for enhanced command features (like suggestions and argument types) on compatible servers (Minecraft 1.13+). Call this applyBrigadier method while configuring imperat's instance, the method must be the FIRST one to be called in the builder's chain like the following example:

BukkitImperat imperat = BukkitImperat.builder(this)
    .applyBrigadier(true)
    .build();
Important

Do NOT register your commands within your plugin's plugin.yml file. Imperat handles registration dynamically.

Note on Versions

Ensure you use the same version (loading...) for both imperat-core and the platform-specific module (e.g., imperat-bukkit) to avoid compatibility issues.

Initiazling your Imperat

Frequently asked question: What's a command dispatcher/Imperat ??
Answer: It's the Ultimate class handling all data needed when processing and registering commands objects (Command). You have to create new instance of the imperat. on the start of your platform by calling YourPlatformImperat#builder (the method is static) to configure your imperat instance, then finally end the chain with build method to return a new instance of YourPlatformImperat type.

TIP

Creation of an instance of your PlatformImperat depends mainly on which platform you are using.

Creation of Commands

There's mainly 2 ways of creating commands:

I will be giving an intro to the easier way for creating commands which is the annotations.

Annotated Commands​

Creating commands with annotations is easy with 2 steps only:

  1. Create a class that will represent your command class
  2. Add unique annotations to it that allows the dispatcher to identify it as a command class

Quick example (Same results as the one above, but with annotations):

@Command("example")  
public final class ExampleCommand {

  @Usage  
  public void defaultUsage(BukkitSource source) {  
   source.reply("This is just an example with no arguments entered");  
  }  

  @Usage  
  public void exampleOneArg(
	  BukkitSource source, 
	  @Named("firstArg") int firstArg
  ) { 
   source.reply("Entered required number= " + firstArg);  
  }
}

Register your commands

Register your command by calling the method imperat.registerCommand(command) Note: the method is called from the YourPlatformImperat instance that you should have created

Here's a quick bukkit example:

public class YourPlugin extends JavaPlugin {

  private BukkitImperat imperat;

  @Override
  public void onEnable() {
    //initializing imperat
    imperat = BukkitImperat.builder(plugin).build();

    //registering the command
    imperat.registerCommand(new ExampleCommand());
  }

}

Customizing Imperat

If you wanted to register a Context Resolver or a Parameter Type , or even set a Suggestion Resolver for tab-completion in commands, You would have to call some methods while configuring imperat.

With Imperat, you can even register your own sender/source type, check out Source Resolver For a complete detailed guide on this, please check out Dispatcher API

Big-example:

BukkitImperat imperat = BukkitImperat.builder(plugin)
    .parameterType(Arena.class, new ArenaParameterType()) //registering custom type 'Arena'
    .parameterType(Kit.class, new KitParameterType()) //registering custom type 'Kit'
    .parameterType(DuelMode.class, new DuelModeParameterType()) //registering custom type 'DuelMode'
    .sourceResolver(CustomSource.class, CustomSource::new) //registering custom command sender/source type 'CustomSource'
  .build();
attention

If you ever wanted to create your own implementation of Imperat interface, you will not receive any support and your issue will be instantly ignored/discarded

Tutorials

Check out all the Imperat tutorials here!