Command Reference

Complete reference for Pilaf framework primitives - commands that cannot be accomplished using normal Minecraft server commands or player commands.

Overview

Pilaf provides framework-level primitives organized into three categories:

Server Commands - Framework primitives for server-level operations
Player Commands - Framework primitives for player-level operations
Workflow & Assertion Commands - Control flow, state management, and validation

Framework Primitives vs. Minecraft Commands

The commands documented here are framework primitives that cannot be done with normal Minecraft commands: - Service health checks - State capture and comparison - Player connection/disconnection - Framework-level assertions

For game operations, use SERVER_COMMAND or PLAYER_COMMAND with Minecraft syntax.

Server Commands

Server commands are framework-level primitives that interact with the Minecraft server through RCON.

Primitive	Description
SERVER_COMMAND	Execute any Minecraft server command via RCON (framework primitive)
CHECK_SERVICE_HEALTH	Verify service availability (framework health check)

Primitive

Description

SERVER_COMMAND

Execute any Minecraft server command via RCON (framework primitive)

CHECK_SERVICE_HEALTH

Verify service availability (framework health check)

Use SERVER_COMMAND for Game Operations

For all game operations, use SERVER_COMMAND with standard Minecraft syntax: - /summon instead of SPAWN_ENTITY - /kill instead of KILL_ENTITY - /op instead of MAKE_OPERATOR - /time instead of GET_WORLD_TIME/SET_TIME - /weather instead of GET_WEATHER/SET_WEATHER

Player Commands

Player commands are framework primitives for player lifecycle management through connected clients (Mineflayer, HeadlessMc).

Primitive	Description
CONNECT_PLAYER	Connect a player to the server (framework lifecycle)
DISCONNECT_PLAYER	Disconnect a player from the server (framework lifecycle)
PLAYER_COMMAND	Execute a Minecraft command as a player (framework primitive)
EXECUTE_PLAYER_COMMAND	Execute a command through the Mineflayer client (framework primitive)
EXECUTE_PLAYER_RAW	Execute raw command through Mineflayer client (framework primitive)

Primitive

Description

CONNECT_PLAYER

Connect a player to the server (framework lifecycle)

DISCONNECT_PLAYER

Disconnect a player from the server (framework lifecycle)

PLAYER_COMMAND

Execute a Minecraft command as a player (framework primitive)

EXECUTE_PLAYER_COMMAND

Execute a command through the Mineflayer client (framework primitive)

EXECUTE_PLAYER_RAW

Execute raw command through Mineflayer client (framework primitive)

Use PLAYER_COMMAND for Game Actions

For player game actions, use PLAYER_COMMAND with Minecraft syntax: - /give instead of GIVE_ITEM - /tp instead of MOVE_PLAYER - /data get entity @s instead of GET_PLAYER_INVENTORY - /attack or click simulation instead of ATTACK_ENTITY

Workflow & Assertion Commands

Workflow and assertion commands are framework-level primitives for controlling test flow, managing state, and validating results.

Primitive	Description
WAIT	Pause test execution for specified duration (system-level wait)
STORE_STATE	Store result for later comparison (framework state management)
COMPARE_STATES	Compare two stored states (framework state management)
EXTRACT_WITH_JSONPATH	Extract specific values from JSON data (data extraction)
FILTER_ENTITIES	Filter entities by criteria (post-processing)
ASSERT_ENTITY_EXISTS	Assert that a specific entity exists (validation)
ASSERT_ENTITY_MISSING	Assert that a specific entity does not exist (validation)
ASSERT_RESPONSE_CONTAINS	Assert response contains expected content (validation)
ASSERT_JSON_EQUALS	Assert JSON structure matches (validation)
ASSERT_LOG_CONTAINS	Assert log contains pattern (validation)
ASSERT_CONDITION	Assert custom condition (validation)

Primitive

Description

WAIT

Pause test execution for specified duration (system-level wait)

STORE_STATE

Store result for later comparison (framework state management)

COMPARE_STATES

Compare two stored states (framework state management)

EXTRACT_WITH_JSONPATH

Extract specific values from JSON data (data extraction)

FILTER_ENTITIES

Filter entities by criteria (post-processing)

ASSERT_ENTITY_EXISTS

Assert that a specific entity exists (validation)

ASSERT_ENTITY_MISSING

Assert that a specific entity does not exist (validation)

ASSERT_RESPONSE_CONTAINS

Assert response contains expected content (validation)

ASSERT_JSON_EQUALS

Assert JSON structure matches (validation)

ASSERT_LOG_CONTAINS

Assert log contains pattern (validation)

ASSERT_CONDITION

Assert custom condition (validation)

Why Framework Primitives?

Pilaf focuses on framework-level operations that cannot be done with normal Minecraft commands:

Service Health: Check if services are available and responsive
State Management: Capture and compare states between test phases
Data Extraction: Query JSON responses with JSONPath
Player Lifecycle: Connect/disconnect players through testing clients
Assertions: Framework-level validation primitives

All game operations (spawning entities, giving items, changing time) should use SERVER_COMMAND or PLAYER_COMMAND with standard Minecraft syntax.

Examples

Basic Story with Framework Primitives

name: "Test Player Connection"
description: "Verify player can connect and execute commands"

setup:
  - action: "CHECK_SERVICE_HEALTH"
    name: "Check server health"

  - action: "SERVER_COMMAND"
    name: "Grant operator status"
    command: "op pilaf_tester"

steps:
  - action: "CONNECT_PLAYER"
    name: "Connect test player"
    player: "pilaf_tester"

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

  - action: "ASSERT_RESPONSE_CONTAINS"
    name: "Verify diamond given"
    source: "${{ steps.give_diamond.outputs.result }}"
    contains: "diamond"

  - action: "STORE_STATE"
    id: "store_inventory"
    name: "Capture inventory state"
    sourceVariable: "${{ steps.give_diamond.outputs.result }}"
    variableName: "inventory_state"

cleanup:
  - action: "DISCONNECT_PLAYER"
    name: "Disconnect test player"
    player: "pilaf_tester"

  - action: "SERVER_COMMAND"
    name: "Remove operator status"
    command: "deop pilaf_tester"

Entity Testing with SERVER_COMMAND

name: "Test Entity Spawning"
description: "Verify entity spawning and removal"

setup:
  - action: "SERVER_COMMAND"
    name: "Clear existing zombies"
    command: "kill @e[type=zombie]"

steps:
  - action: "ASSERT_ENTITY_MISSING"
    name: "Verify no zombies exist"
    entity: "zombie"

  - action: "SERVER_COMMAND"
    name: "Spawn test zombie"
    command: "summon zombie ~ ~ ~ {CustomName:'\"test_zombie\"'}"

  - action: "WAIT"
    name: "Wait for entity spawn"
    duration: 2000

  - action: "ASSERT_ENTITY_EXISTS"
    name: "Verify zombie spawned"
    entity: "zombie"

  - action: "SERVER_COMMAND"
    name: "Remove test zombie"
    command: "kill @e[type=zombie,custom_name=test_zombie]"

  - action: "ASSERT_ENTITY_MISSING"
    name: "Verify zombie removed"
    entity: "zombie"

State Comparison Example

name: "Test World Time Changes"
description: "Verify time manipulation and state comparison"

setup:
  - action: "SERVER_COMMAND"
    id: "initial_time"
    name: "Get initial time"
    command: "time query gametime"

  - action: "STORE_STATE"
    name: "Store initial time"
    sourceVariable: "${{ steps.initial_time.outputs.result }}"
    variableName: "start_time"

steps:
  - action: "SERVER_COMMAND"
    name: "Set to noon"
    command: "time set noon"

  - action: "SERVER_COMMAND"
    id: "final_time"
    name: "Get final time"
    command: "time query gametime"

  - action: "STORE_STATE"
    name: "Store final time"
    sourceVariable: "${{ steps.final_time.outputs.result }}"
    variableName: "end_time"

  - action: "COMPARE_STATES"
    name: "Compare time states"
    state1: "start_time"
    state2: "end_time"

cleanup:
  - action: "SERVER_COMMAND"
    name: "Reset time"
    command: "time set day"