https://github.com/meverastudios/imperat
Enterprise command dispatching framework with optimal performance
https://github.com/meverastudios/imperat
api bukkit bungeecord command-framework command-line-interface commands minestom-library spigot velocity
Last synced: 3 months ago
JSON representation
Enterprise command dispatching framework with optimal performance
- Host: GitHub
- URL: https://github.com/meverastudios/imperat
- Owner: MeveraStudios
- License: other
- Created: 2024-08-20T20:11:26.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-09-03T04:21:36.000Z (4 months ago)
- Last Synced: 2025-09-03T23:03:40.141Z (4 months ago)
- Topics: api, bukkit, bungeecord, command-framework, command-line-interface, commands, minestom-library, spigot, velocity
- Language: Java
- Homepage:
- Size: 3.59 MB
- Stars: 36
- Watchers: 0
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# **Imperat** - The Blazing Fast Command Framework ⚡
[](https://search.maven.org/artifact/studio.mevera/imperat-core)
[](LICENSE)
[](https://discord.gg/McN4GMWApE)
[](https://docs.mevera.studio/Imperat)
[](https://java.com)
**The most performant, feature-rich command framework for Java applications**
[📚 **Documentation**](https://docs.mevera.studio/Imperat) • [💬 **Discord**](https://discord.gg/McN4GMWApE) • [🚀 **Get Started**](#-quick-start) • [✨ **Features**](#-features) • [📊 **Benchmarks**](#-performance)
---
## 🎯 **Why Imperat?**
Imperat isn't just another command framework—it's the **ultimate solution** for developers who demand both **blazing performance** and **rich features**.
Built by [Mqzen](https://github.com/Mqzen), Imperat delivers sub-microsecond command execution while maintaining an elegant, intuitive API.
---
### 📊 **Performance**
Imperat provides the optimum performance for command execution and suggestion providing.
We have proven this through running benchmarks using **JMH**:
| **Lightning Fast** ⚡ | **Feature Complete** 🎨 | **Multi-Platform** 🌍 |
|:---:|:---:|:---:|
| **29x faster** than Cloud
**10x faster** than Lamp | Annotations, builders, suggestions,
permissions, and much more | Bukkit, Velocity, BungeeCord,
Minestom, CLI, and more |
| Framework | Median Latency | Throughput | vs Imperat |
|:---------:|:--------------:|:----------:|:----------:|
| **Imperat** ⚡ | **470ns** | **2.14M/sec** | **Baseline** |
| Lamp | 5,016ns | 199K/sec | 10x slower |
| Cloud | 12,208ns | 82K/sec | 29x slower |
*Benchmarked on complex command trees with 10+ depth levels and multiple branches*
> 💡 **What does this mean?** On a busy Minecraft server with many players, Imperat adds only **0.47ms** overhead per 1000 commands, while Other framework like Cloud adds **12.2ms**—that's the difference between smooth gameplay and noticeable lag!
---
## ✨ **Features**
| **Core Features** | **Advanced Features** | **Developer Experience** |
|:--------------------------:|:----------------------------:|:------------------------:|
| Annotation-based commands | Async command execution | Zero boilerplate |
| Builder pattern API | Tab completion & suggestions | Extensive documentation |
| Unlimited subcommands | Permission management | IDE autocomplete support |
| Parameter validation | Dependency injection | Custom parameter types |
| Multiple usage patterns | Processing pipeline | Hot-reload support |
| Greedy parameters | Command cooldowns | Context resolvers |
---
## 🚀 **Quick Start**
### **Step 1: Add Imperat to Your Project**
Maven
```xml
studio.mevera
imperat-core
%LATEST_VERSION%
studio.mevera
imperat-bukkit
%LATEST_VERSION%
```
Gradle (Kotlin DSL)
```kotlin
dependencies {
implementation("studio.mevera:imperat-core:%LATEST_VERSION%")
// Add your platform module (e.g., for Bukkit)
implementation("studio.mevera:imperat-bukkit:%LATEST_VERSION%")
}
```
Gradle (Groovy)
```groovy
dependencies {
implementation 'studio.mevera:imperat-core:%LATEST_VERSION%'
// Add your platform module (e.g., for Bukkit)
implementation 'studio.mevera:imperat-bukkit:%LATEST_VERSION%'
}
```
### **Step 2: Initialize Imperat**
```java
public class YourPlugin extends JavaPlugin {
private BukkitImperat imperat;
@Override
public void onEnable() {
// Create Imperat instance with builder pattern
this.imperat = BukkitImperat.builder(this)
.applyBrigadier(true) // Enhanced suggestions on 1.13+
.build();
// Register your commands
imperat.registerCommand(new GameModeCommand());
}
}
```
### **Step 3: Create Your First Command**
```java
@Command({"gamemode", "gm"})
@Permission("server.gamemode")
@Description("Change player gamemode")
public class GameModeCommand {
@Usage
public void mainUsage(
Player source,
@Named("mode") GameMode gameMode,
@Default("me") @Named("target") Player target
) {
// Handle: /gamemode [target]
target.setGameMode(gameMode);
source.sendMessage("§aGamemode updated to " + gameMode.name());
if (target != source) {
target.sendMessage("§aYour gamemode was updated by " + source.getName());
}
}
// Independent root aliases.
@Command("gmc")
@Permission("server.gamemode.creative")
public void creative(Player source, @Default("me") Player target) {
mainUsage(source, GameMode.CREATIVE, target);
}
@Command("gms")
@Permission("server.gamemode.survival")
public void survival(Player source, @Default("me") Player target) {
mainUsage(source, GameMode.SURVIVAL, target);
}
}
```
That's it! You've just created a fully-functional command with:
- ✅ Multiple aliases (`/gamemode`, `/gm`)
- ✅ Multiple shortcuts/root-aliases (`/gmc`, `/gms`)
- ✅ Tab completion for GameMode and online players
- ✅ Optional parameters with smart defaults
- ✅ Permission checking
---
## 🎨 **Advanced Example - Complex Command Trees**
Click to see a real-world rank management system
```java
@Command({"rank", "group"})
@Permission("server.rank")
@Description("Complete rank management system")
public class RankCommand {
@Dependency
private RankManager rankManager;
@Usage
public void help(CommandSource source, CommandHelp help) {
help.display(source); // Auto-generated help menu
}
@SubCommand("create")
@Permission("server.rank.create")
public void createRank(
CommandSource source,
@Named("name") String rankName,
@Optional @Default("0") @Named("weight") int weight
) {
Rank rank = rankManager.createRank(rankName, weight);
source.reply("§aCreated rank: " + rank.getColoredName());
}
@SubCommand("delete")
@Permission("server.rank.delete")
public void deleteRank(
CommandSource source,
@Named("rank") Rank rank, // Custom parameter type!
@Switch("confirm") boolean confirm
) {
if (!confirm) {
source.error("§cAdd --confirm to delete this rank");
return;
}
rankManager.deleteRank(rank);
source.reply("§aDeleted rank: " + rank.getName());
}
@SubCommand("give")
@Permission("server.rank.give")
@Cooldown(value = 5, unit = TimeUnit.SECONDS)
public void giveRank(
CommandSource source,
@Named("player") Player target,
@Named("rank") Rank rank,
@Optional @Named("duration") Duration duration
) {
rankManager.setPlayerRank(target, rank, duration);
source.reply("§aGave " + rank.getColoredName() + " §ato " + target.getName());
}
}
```
---
## 🔧 **Platform Support**
| Platform | Module | Status |
|:--------:|:------:|:------:|
| **Bukkit/Spigot/Paper** | `imperat-bukkit` | ✅ Stable |
| **Velocity** | `imperat-velocity` | ✅ Stable |
| **BungeeCord** | `imperat-bungee` | ✅ Stable |
| **Minestom** | `imperat-minestom` | ✅ Stable |
| **CLI Applications** | `imperat-cli` | ✅ Stable |
| **Discord (JDA)** | `imperat-jda` | 🚧 Coming Soon |
| **Sponge** | `imperat-sponge` | 🚧 Planned |
---
## 🎯 **Key Features Explained**
### **⚡ Blazing Fast Performance**
- **Sub-microsecond execution**: 470ns median latency
- **Linear O(n) scaling**: Consistent performance even with deep command trees
- **Minimal allocations**: Optimized memory usage
### **🎨 Flexible Command Creation**
- **Annotations**: Clean, declarative command structure
- **Builder API**: Dynamic command generation
- **Mixed approach**: Use both patterns in the same project
### **🔌 Rich Parameter System**
- **Custom types**: Register your own parameter types
- **Validation**: Built-in `@Range`, `@Values`, and custom validators
- **Greedy parameters**: `@Greedy` for multi-word inputs
- **Flags & switches**: `--flag value` and `--switch` support
### **🛡️ Advanced Permission System**
- **Hierarchical permissions**: Command, subcommand, and parameter-level
- **Auto Permission Assignment**: Generate permission nodes automatically
- **Custom permission checks**: Implement complex permission logic
### **📊 Processing Pipeline**
- **Pre-processors**: Validate, log, or modify before execution
- **Post-processors**: Handle results, logging, or cleanup
- **Exception resolvers**: Centralized error handling
---
## 🤝 **Contributing**
We welcome contributions! Whether it's bug reports, feature requests, or pull requests.
## 📜 **License**
Imperat is licensed under the [MIT License](LICENSE).
---
### **Ready to supercharge your commands?**
[📚 **Read the Docs**](https://docs.mevera.studio/Imperat) • [💬 **Join our Discord**](https://discord.gg/McN4GMWApE) • [⭐ **Star on GitHub**](https://github.com/MeveraStudios/Imperat)
**Built with ❤️ by [Mqzen](https://github.com/Mqzen) and [iiAhmedYT](https://github.com/iiAhmedYT)**