Pumpkin-Docs/docs/en/developer/commands/execution-and-context.md

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:

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:

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:

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:

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.