116 lines
3.3 KiB
Markdown
116 lines
3.3 KiB
Markdown
# Creating Your First Command
|
|
|
|
Registering and handling custom commands in Pumpkin is designed to be developer-friendly, fast, and structured like Mojang's Brigadier system.
|
|
|
|
---
|
|
|
|
## 1. Quick Example
|
|
|
|
Here is a complete, minimal Rust plugin that registers a `/hello` command with permission checks and sends a response back to the player.
|
|
|
|
```rust [src/lib.rs]
|
|
use pumpkin_plugin_api::{
|
|
command::{CommandHandler, CommandSender, ConsumedArgs, CommandError, Command},
|
|
permission::{Permission, PermissionDefault},
|
|
Context, Plugin, PluginMetadata, Server,
|
|
};
|
|
|
|
struct HelloExecutor;
|
|
|
|
impl CommandHandler for HelloExecutor {
|
|
fn handle(
|
|
&self,
|
|
sender: CommandSender,
|
|
_server: Server,
|
|
_args: ConsumedArgs,
|
|
) -> Result<i32, CommandError> {
|
|
sender.send_message("Hello from Pumpkin!");
|
|
Ok(1)
|
|
}
|
|
}
|
|
|
|
pub struct MyPlugin;
|
|
|
|
impl Plugin for MyPlugin {
|
|
fn new() -> Self {
|
|
MyPlugin
|
|
}
|
|
|
|
fn metadata(&self) -> PluginMetadata {
|
|
PluginMetadata {
|
|
name: "my_plugin".into(),
|
|
version: env!("CARGO_PKG_VERSION").into(),
|
|
authors: vec!["Developer".into()],
|
|
description: "My first Pumpkin plugin".into(),
|
|
}
|
|
}
|
|
|
|
fn on_load(&mut self, context: Context) -> pumpkin_plugin_api::Result<()> {
|
|
// 1. Register permission node
|
|
context.register_permission(&Permission {
|
|
node: "my_plugin:hello".to_string(),
|
|
description: "Allows executing the /hello command".to_string(),
|
|
default: PermissionDefault::Allow,
|
|
children: Vec::new(),
|
|
})?;
|
|
|
|
// 2. Build the command tree with aliases & executor
|
|
let names = ["hello".to_string(), "hi".to_string()];
|
|
let command = Command::new(&names, "Greets the player").execute(HelloExecutor);
|
|
|
|
// 3. Register the command
|
|
context.register_command(command, "my_plugin:hello")?;
|
|
|
|
Ok(())
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. In-Game Preview
|
|
|
|
Once registered, your command automatically gains client-side autocompletion, syntax validation, and color highlighting in Minecraft:
|
|
|
|
<img src="/assets/first_command_preview.png" alt="In-Game Command Autocompletion Preview" width="500"/>
|
|
|
|
---
|
|
|
|
## 3. How It Works
|
|
|
|
::: details Step-by-Step Breakdown
|
|
|
|
### Step 1: Define the Permission
|
|
Commands in Pumpkin require a permission node. Using `PermissionDefault::Allow` allows all players to execute it by default:
|
|
```rust
|
|
context.register_permission(&Permission {
|
|
node: "my_plugin:hello".to_string(),
|
|
description: "Allows executing the /hello command".to_string(),
|
|
default: PermissionDefault::Allow,
|
|
children: Vec::new(),
|
|
})?;
|
|
```
|
|
|
|
### Step 2: Build the Command Tree
|
|
Use `Command::new` to define primary names and aliases, then attach your `CommandHandler` struct with `.execute(...)`:
|
|
```rust
|
|
let names = ["hello".to_string(), "hi".to_string()];
|
|
let command = Command::new(&names, "Greets the player")
|
|
.execute(HelloExecutor);
|
|
```
|
|
|
|
### Step 3: Register with Context
|
|
Pass the command tree and the permission node string to `context.register_command`:
|
|
```rust
|
|
context.register_command(command, "my_plugin:hello")?;
|
|
```
|
|
|
|
:::
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- Explore complex subcommands and argument parsing in the [Rock-Paper-Scissors Tutorial](./rock-paper-scissors).
|
|
- Learn how to handle inventory and GUI interactions in plugin logic.
|