96 lines
2.8 KiB
Markdown
96 lines
2.8 KiB
Markdown
# Creating Your First Command
|
|
|
|
Registering and handling custom commands in Pumpkin with Python is designed to be straightforward and expressive.
|
|
|
|
---
|
|
|
|
## 1. Quick Example
|
|
|
|
Here is a complete, minimal Python plugin (`main.py`) that registers a `/hello` command with permission checks and sends a response back to the player.
|
|
|
|
```python [main.py]
|
|
from pumpkin_api import (
|
|
Plugin, PluginMetadata, register_plugin,
|
|
permission, command, context, server
|
|
)
|
|
|
|
class HelloCommand:
|
|
def handle(self, sender: command.CommandSender, srv: server.Server, args: command.ConsumedArgs) -> int:
|
|
sender.send_message("Hello from Python Plugin!")
|
|
return 1
|
|
|
|
class MyPlugin(Plugin):
|
|
def metadata(self) -> PluginMetadata:
|
|
return PluginMetadata(
|
|
name="my_python_plugin",
|
|
version="0.1.0",
|
|
authors=["Developer"],
|
|
description="My first Pumpkin Python plugin"
|
|
)
|
|
|
|
def on_load(self, ctx: context.Context) -> None:
|
|
# 1. Register permission node
|
|
ctx.register_permission(permission.Permission(
|
|
node="my_python_plugin:hello",
|
|
description="Allows executing the /hello command",
|
|
default=permission.PermissionDefault.ALLOW,
|
|
children=[]
|
|
))
|
|
|
|
# 2. Build the command tree with aliases & executor
|
|
cmd = command.Command(["hello", "hi"], "Greets the player")
|
|
cmd.execute(HelloCommand())
|
|
|
|
# 3. Register the command
|
|
ctx.register_command(cmd, "my_python_plugin:hello")
|
|
|
|
register_plugin(MyPlugin)
|
|
```
|
|
|
|
---
|
|
|
|
## 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. Register it with `permission.PermissionDefault.ALLOW` to allow execution by default:
|
|
```python
|
|
ctx.register_permission(permission.Permission(
|
|
node="my_python_plugin:hello",
|
|
description="Allows executing the /hello command",
|
|
default=permission.PermissionDefault.ALLOW,
|
|
children=[]
|
|
))
|
|
```
|
|
|
|
### Step 2: Build the Command Tree
|
|
Create a `command.Command` instance with primary names and aliases, then attach your handler with `.execute(...)`:
|
|
```python
|
|
cmd = command.Command(["hello", "hi"], "Greets the player")
|
|
cmd.execute(HelloCommand())
|
|
```
|
|
|
|
### Step 3: Register with Context
|
|
Pass the command tree and permission node string to `ctx.register_command`:
|
|
```python
|
|
ctx.register_command(cmd, "my_python_plugin:hello")
|
|
```
|
|
|
|
:::
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- Check out [Events](./events) to handle player actions and server events in Python.
|
|
- Learn more about [Basic Logic](./basic-logic).
|