119 lines
4.7 KiB
Markdown
119 lines
4.7 KiB
Markdown
# Execution & Context
|
|
|
|
In Pumpkin, command execution separates the **physical origin** of a command from its **runtime context**. This design enables complex command routing, dimension shifts, conditional execution, and vanilla-compliant `/execute` chaining.
|
|
|
|
---
|
|
|
|
## `CommandSender` vs. `CommandSource`
|
|
|
|
Understanding the distinction between `CommandSender` and `CommandSource` is fundamental to developing commands in Pumpkin:
|
|
|
|
| Attribute | `CommandSender` | `CommandSource` |
|
|
| :--- | :--- | :--- |
|
|
| **Concept** | The physical origin and network destination | The mutable runtime execution environment |
|
|
| **Mutability** | Immutable throughout command execution | Cloned and modified across `/execute` branches |
|
|
| **Key Fields** | Terminal socket, connection handle, RCON buffer | World, position coordinates, rotation, entity, silent flag |
|
|
| **Creation** | Instantiated on network connection or terminal input | Constructed via `sender.into_source(&server)` |
|
|
|
|
### 1. `CommandSender` (Physical Caller)
|
|
Represents the entity or socket that initiated the command and receives its output:
|
|
|
|
```rust
|
|
pub enum CommandSender {
|
|
Console,
|
|
Rcon(Arc<std::sync::Mutex<Vec<String>>>),
|
|
Player(Arc<Player>),
|
|
CommandBlock(Arc<CommandBlockEntity>, Arc<World>),
|
|
Dummy,
|
|
}
|
|
```
|
|
|
|
- **Output Target**: Determines where messages formatted with `send_message` are routed (e.g., standard out, RCON buffer, player packet, or block entity NBT).
|
|
- **Hard Permissions**: Holds fixed base permissions (e.g., Console has level 4 bypass; Command Blocks have level 2).
|
|
|
|
### 2. `CommandSource` (Execution Environment)
|
|
Represents the mutable runtime state during command evaluation:
|
|
|
|
```rust
|
|
pub struct CommandSource {
|
|
pub output: CommandSender,
|
|
pub world: Option<Arc<World>>,
|
|
pub entity: Option<Arc<dyn EntityBase>>,
|
|
pub position: Vector3<f64>,
|
|
pub rotation: Vector2<f32>,
|
|
pub name: String,
|
|
pub display_name: TextComponent,
|
|
pub server: Option<Arc<Server>>,
|
|
pub silent: bool,
|
|
pub command_result_taker: ResultValueTaker,
|
|
pub entity_anchor: EntityAnchor,
|
|
}
|
|
```
|
|
|
|
A sender converts into a `CommandSource` via `sender.into_source(&server)`.
|
|
|
|
---
|
|
|
|
## The `/execute` Command & Context Redirection
|
|
|
|
The `/execute` command manipulates `CommandSource` properties before passing control to a downstream command.
|
|
|
|
### Branching Modifiers
|
|
- **`as <targets>`**: Changes `context.source.entity` to target entities without altering position or rotation.
|
|
- **`at <targets>`**: Updates `context.source.world`, `position`, and `rotation` to match the target entity.
|
|
- **`positioned <pos>`**: Modifies `context.source.position` to new coordinates.
|
|
- **`in <dimension>`**: Changes `context.source.world` to the specified dimension (Overworld, Nether, The End).
|
|
- **`anchored (feet|eyes)`**: Adjusts coordinate offsets for line-of-sight and facing checks.
|
|
|
|
### Context Forking & Chaining
|
|
When `/execute` matches multiple targets (e.g., `/execute as @e run ...`), `pumpkin-command` uses **forking**:
|
|
1. The dispatcher forks the execution context once per matched target.
|
|
2. The child command executes independently for each cloned `CommandSource`.
|
|
3. The cumulative success count is aggregated across all executions.
|
|
|
|
---
|
|
|
|
## Result Values & Success Counts
|
|
|
|
Vanilla commands communicate results back through integer exit codes and return values.
|
|
|
|
### The Return Value Callback
|
|
Executors return `CommandExecutorResult` (`Result<i32, CommandSyntaxError>`). The returned integer signifies:
|
|
- **0**: Failure or zero entities affected.
|
|
- **> 0**: Number of entities affected, blocks changed, or items cleared.
|
|
|
|
For Command Blocks, this value is persisted into the block entity's `SuccessCount`:
|
|
|
|
```rust
|
|
pub fn set_success_count(&self, count: u32) {
|
|
if let Self::CommandBlock(c, _) = self {
|
|
c.success_count.store(count, Ordering::SeqCst);
|
|
}
|
|
}
|
|
```
|
|
|
|
### `/execute store`
|
|
When chained with `/execute store (result|success) ...`, Pumpkin intercepts the return value via `ReturnValueCallback` and writes it to scoreboards, bossbars, or entity NBT tags.
|
|
|
|
---
|
|
|
|
## Feedback & GameRules Integration
|
|
|
|
Sending output to the command sender is governed by server configuration and world game rules:
|
|
|
|
```rust
|
|
context.source.send_feedback(
|
|
TextComponent::text("Command executed successfully!"),
|
|
true, // Broadcast to server operators
|
|
);
|
|
```
|
|
|
|
### Output Rules Matrix
|
|
|
|
| Condition | Feedback Behavior |
|
|
| :--- | :--- |
|
|
| `silent == true` | Output is suppressed completely. |
|
|
| `send_command_feedback == false` | Player senders do not receive success feedback (errors are still displayed). |
|
|
| `command_block_output == false` | Command block execution output is not broadcast to online operators. |
|
|
| `broadcast_console_to_ops == true` | Server console and RCON commands emit a copy of their feedback to all online OP level 2+ players. |
|