Table of Contents

• Player Commands Reference
• Overview
  • Command Execution Flow
  • Prerequisites
  • CONNECT_PLAYER
    • Syntax
    • Parameters
    • Outputs
    • Response Structure
    • Example
    • Related Commands
  • DISCONNECT_PLAYER
    • Syntax
    • Parameters
    • Outputs
    • Example
    • Related Commands
  • PLAYER_COMMAND
    • Syntax
    • Parameters
    • Outputs
    • Common Minecraft Player Commands
    • Example
    • Related Commands
  • EXECUTE_PLAYER_COMMAND
    • Syntax
    • Parameters
    • Outputs
    • Example
    • Related Commands
  • EXECUTE_PLAYER_RAW
    • Syntax
    • Parameters
    • Outputs
    • Example
    • Related Commands
• Command Summary
• See Also

Player Commands Reference

Primitive player commands are framework-level operations for player lifecycle management and command execution that cannot be accomplished using normal Minecraft player commands.

Overview

Pilaf provides primitive player commands for framework-level operations:

• Player Lifecycle: Connect and disconnect players through testing clients

• Command Execution: Execute Minecraft commands as a player

Primitive Commands vs. Player Commands Primitive player commands are framework-level operations that cannot be done with Minecraft commands: - Player connection/disconnection through testing clients (Mineflayer, HeadlessMc) - Command execution through the testing framework For in-game player actions, use PLAYER_COMMAND with standard Minecraft syntax: - Movement (/tp) - Items (/give, /clear) - Interactions (click simulation, /attack) - Data queries (/data get entity @s)

Command Execution Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                         Pilaf Test Story                                 │
│  ┌─────────────────┐    ┌──────────────────┐    ┌────────────────────┐ │
│  │  Player Action  │───►│ Mineflayer Bridge│───►│  Minecraft Client  │ │
│  │  (Framework)    │    │   (Node.js)      │    │   (Headless)       │ │
│  └─────────────────┘    └──────────────────┘    └────────────────────┘ │
│                              │                                          │
│                              ▼                                          │
│                       ┌──────────────────┐                              │
│                       │   Response       │                              │
│                       │   Parsing        │                              │
│                       └──────────────────┘                              │
└─────────────────────────────────────────────────────────────────────────┘

Prerequisites

Before using player commands, ensure:

1. The Mineflayer bridge server is running and healthy (for Mineflayer backend)

2. The Minecraft server is accessible and accepting connections

3. Player names are unique and not already connected

4. The server allows connections from the bridge IP

---

CONNECT_PLAYER

Connect a player to the Minecraft server using the Mineflayer bridge. This is a framework-level primitive that establishes a player session through the testing client.

Syntax

- action: "CONNECT_PLAYER"
  player: "player_name"                  (1)
  id: "unique_step_id"                   (2)
  name: "Human-readable name"            (3)

1	Player username to connect (must be unique)
2	Step ID for output referencing (optional)
3	Descriptive name for logging and reports (optional)

Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be "CONNECT_PLAYER"
player	string	Yes	Player username to connect (must not already be connected)
id	string	No	Step identifier for referencing outputs
name	string	No	Human-readable description for reports

Outputs

Output	Type	Description
result	string	Connection status message
status	string	"success" or "failure"
message	string	Detailed status information
player	string	Name of connected player

Response Structure

{
  "result": "Player pilaf_tester connected successfully",
  "status": "success",
  "message": "Connection established to localhost:25565",
  "player": "pilaf_tester"
}

Example

# Connect a test player
- action: "CONNECT_PLAYER"
  id: "connect_tester"
  name: "Connect test player"
  player: "pilaf_tester"

Related Commands

• DISCONNECT_PLAYER - Disconnect player

• PLAYER_COMMAND - Execute command as player

• CHECK_SERVICE_HEALTH - Verify backend health

---

DISCONNECT_PLAYER

Disconnect a player from the Minecraft server. This is a framework-level primitive for clean player session termination.

Syntax

- action: "DISCONNECT_PLAYER"
  player: "player_name"                  (1)
  id: "unique_step_id"                   (2)
  name: "Human-readable name"            (3)

1	Player username to disconnect
2	Step ID for output referencing (optional)
3	Descriptive name (optional)

Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be "DISCONNECT_PLAYER"
player	string	Yes	Player username to disconnect
id	string	No	Step identifier
name	string	No	Human-readable description

Outputs

Output	Type	Description
result	string	Disconnection status message
status	string	"success" or "failure"
message	string	Detailed status information
player	string	Name of disconnected player

Example

# Disconnect test player
- action: "DISCONNECT_PLAYER"
  id: "disconnect_tester"
  name: "Disconnect test player"
  player: "pilaf_tester"

Related Commands

• CONNECT_PLAYER - Connect player

• PLAYER_COMMAND - Execute command before disconnect

---

PLAYER_COMMAND

Execute a Minecraft server command as a player through the RCON interface. This framework primitive allows executing any player command using standard Minecraft syntax.

Syntax

- action: "PLAYER_COMMAND"
  id: "unique_step_id"                   (1)
  name: "Human-readable name"            (2)
  player: "player_name"                  (3)
  command: "minecraft_command"           (4)

1	Step ID for output referencing
2	Descriptive name for logging
3	Player to execute command as
4	Complete Minecraft command

Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be "PLAYER_COMMAND"
id	string	No	Step identifier for output referencing
name	string	No	Human-readable description
player	string	Yes	Player name to execute command as
command	string	Yes	Complete Minecraft command (e.g., "give @p diamond")

Outputs

Output	Type	Description
result	string	Full command response from the server
status	string	"success" or "failure"
message	string	Human-readable status message

Common Minecraft Player Commands

Use PLAYER_COMMAND with these standard Minecraft commands:

Minecraft Command	Purpose
give <player> <item> [count]	Give items to player
clear [player] [item] [count]	Clear player inventory
teleport <target> <destination>	Teleport entity
tp <player> <destination>	Teleport player
effect give <player> <effect>	Give status effect
data get entity @s	Get player data (position, inventory, etc.)
gamemode <mode> [player]	Change game mode

Example

# Give player a diamond
- action: "PLAYER_COMMAND"
  id: "give_diamond"
  name: "Give diamond to player"
  player: "pilaf_tester"
  command: "give @p diamond"

# Get player position
- action: "PLAYER_COMMAND"
  id: "get_pos"
  name: "Get player position"
  player: "pilaf_tester"
  command: "data get entity @s Pos"

# Teleport player
- action: "PLAYER_COMMAND"
  name: "Teleport to spawn"
  player: "pilaf_tester"
  command: "tp @p 0 100 0"

Related Commands

• EXECUTE_PLAYER_COMMAND - Execute through Mineflayer client

• SERVER_COMMAND - Execute server command

• EXTRACT_WITH_JSONPATH - Extract values from response

---

EXECUTE_PLAYER_COMMAND

Execute a command as a connected player through the Mineflayer client. This framework primitive sends commands through the Mineflayer bridge rather than RCON.

Syntax

- action: "EXECUTE_PLAYER_COMMAND"
  id: "unique_step_id"                   (1)
  name: "Human-readable name"            (2)
  player: "player_name"                  (3)
  command: "/command or command"         (4)

1	Step ID for output referencing
2	Descriptive name (optional)
3	Player to execute as
4	Command (with or without /)

Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be "EXECUTE_PLAYER_COMMAND"
id	string	No	Step identifier
name	string	No	Human-readable description
player	string	Yes	Player to execute command as
command	string	Yes	Command to execute (with or without /)

Outputs

Output	Type	Description
result	string	Command response
status	string	"success" or "failure"
message	string	Status message
player	string	Player who executed

Example

# Connect player first
- action: "CONNECT_PLAYER"
  name: "Connect test player"
  player: "pilaf_tester"

# Execute player command
- action: "EXECUTE_PLAYER_COMMAND"
  id: "set_home"
  name: "Set home location"
  player: "pilaf_tester"
  command: "/home set"

# Execute home teleport
- action: "EXECUTE_PLAYER_COMMAND"
  id: "go_home"
  name: "Teleport to home"
  player: "pilaf_tester"
  command: "/home"

Related Commands

• EXECUTE_PLAYER_RAW - Raw command execution

• CONNECT_PLAYER - Connect player first

---

EXECUTE_PLAYER_RAW

Execute a raw command as a player without any processing. This framework primitive provides direct access to the player’s command channel.

Syntax

- action: "EXECUTE_PLAYER_RAW"
  id: "unique_step_id"                   (1)
  name: "Human-readable name"            (2)
  player: "player_name"                  (3)
  command: "raw_command_string"          (4)

1	Step ID for output referencing
2	Descriptive name (optional)
3	Player to execute as
4	Raw command string

Parameters

Parameter	Type	Required	Description
action	string	Yes	Must be "EXECUTE_PLAYER_RAW"
id	string	No	Step identifier
name	string	No	Human-readable description
player	string	Yes	Player to execute command as
command	string	Yes	Raw command string

Outputs

Output	Type	Description
result	string	Raw response from server
status	string	"success" or "failure"
message	string	Status message

Example

# Connect player
- action: "CONNECT_PLAYER"
  name: "Connect player"
  player: "pilaf_tester"

# Send raw command with NBT data
- action: "EXECUTE_PLAYER_RAW"
  id: "give_sword"
  name: "Give enchanted sword"
  player: "pilaf_tester"
  command: "give pilaf_tester diamond_sword 1 {ench:[{id:0,lvl:5}]}"

Unlike EXECUTE_PLAYER_COMMAND, this sends the command exactly as provided without any preprocessing or argument parsing.

Related Commands

• EXECUTE_PLAYER_COMMAND - Command with processing

---

Command Summary

Command	Purpose	Key Outputs
CONNECT_PLAYER	Connect player to server	player, status
DISCONNECT_PLAYER	Disconnect player from server	player, status
PLAYER_COMMAND	Execute Minecraft command as player (via RCON)	result, status
EXECUTE_PLAYER_COMMAND	Execute command through Mineflayer client	result, status
EXECUTE_PLAYER_RAW	Execute raw command through Mineflayer	result, status

See Also

• Server Commands - Server-side operations

• Workflow & Assertion Commands - Control flow and validation

• Writing Stories - How to use commands in stories