Playtest Guide¶

Run deterministic gameplay scenarios with assertions and state snapshots.

Overview¶

Playtesting executes a script of gameplay steps: move, wait, assert state, check console. Results are compressed for readability.

Quick Start¶

script = """MOVE /Player TO 5,0,0
WAIT 1.0
ASSERT /Player|Health|hp > 0
ASSERT_CONSOLE_CLEAN"""

await editor(action="play")
try:
    result = await run_playtest(script=script, timeout=30.0)
finally:
    await editor(action="stop")

# PLAYTEST: 4/4 (1.1s) OK

run_playtest requires Play Mode. Successful step details are removed from the compact result; failures, snapshots, and logs remain.

run_playtest Parameters¶

At least one of script or path is required; they are mutually exclusive.

# From file
await run_playtest(path="Assets/Playtests/combat.playtest")

# With defs and fresh start
await run_playtest(
    script="ASSERT $player|Health|hp > 0",
    defs="VAL $player /Player",
    fresh=True,
    snapshot_on_failure=True,
)

run_playtest_suite¶

Run multiple .playtest files sequentially with a compact pass/fail matrix.

Exactly one of paths or suite_path must be provided.

await run_playtest_suite(paths="Playtests/*.playtest", stop_on_fail=True)
# → SUITE: 5/6 passed (42s)
#   ✓ movement.playtest (3s)
#   ✗ combat.playtest (8s) — ASSERT Health > 0 FAIL
#   ...

lint_playtest¶

Static DSL validation without executing. Checks: unresolved $alias, deprecated ALIAS keyword, unknown CALL targets, mixed AND/OR, missing ASSERT_CONSOLE_CLEAN.

await lint_playtest(script="ASSERT $unknown|Health > 0")
# → WARN:1: unresolved alias $unknown

await lint_playtest(path="Assets/Playtests/combat.playtest")
# → OK

lint_playtest_suite(paths=..., suite_path=...) lints multiple files at once.

DSL Quick Reference¶

Core Commands¶

Assertions¶

Capture & Monitor¶

Flow Control¶

Compound Commands (parse-time expansion)¶

Directives (not emitted as steps)¶

SWEEP_PATH Example¶

SWEEP_PATH /Player DWELL 0.5
  0,0,0 > 5,0,0 > 10,0,0
UNTIL /Player|Trigger|activated == true TIMEOUT 10

Expands at parse time to Move+Wait per waypoint, then a WaitUntil.

Aliases & Substitution¶

Define once, use everywhere. Sigil syntax is $name (no curly braces).

VAL $spawn 100,0,0
VAL $alive true

TELEPORT /Player $spawn
ASSERT /Player|IsAlive == $alive

Three alias types:

Aliases work in batch and all direct MCP tools. Suffix preserved: $alias|Comp|field expands to expanded-path|Comp|field.

Use INCLUDE path/to/file.defs to import alias definitions from external files.

Path Special Characters¶

Handle literal slashes and backslashes in GameObject names using backslash escaping or bracket protection.

Escaping Rules: - \/ — literal forward slash in the GameObject name - \\ — literal backslash in the GameObject name - [Name/With/Slashes] — bracket protection (entire segment as one path component, no escaping needed)

Examples:

# GameObject named "Day/Night"
ASSERT /Day\/Night|Health|hp == 100

# GameObject named "Folder\Path" (Windows-style)
ASSERT /Folder\\Path|Component|field == value

# Using brackets for "Zone A/Zone B"
ASSERT /[Zone A/Zone B]/Child|Comp|field == value

Round-trip guarantee: GetPath(go) → parse → FindObject(path) always finds the original object.

GameObject Property Shorthands¶

Assert on GameObject properties without specifying a component:

ASSERT /Player|activeSelf
ASSERT /Player|activeInHierarchy
ASSERT /Player|tag == Player
ASSERT /Player|layer == 0
ASSERT /Player|name == Player

Bool fields like activeSelf don't need == true — bare ASSERT is sufficient.

Virtual Fields¶

Synthetic fields on well-known components:

ASSERT /Enemy|Animator|currentState == Idle
ASSERT /Ball|Rigidbody|speed > 0

FOR Loops¶

FOR $i IN 0..5
  ASSERT /Slot_$i|activeSelf
END_FOR

Range is exclusive (0..5 = 0,1,2,3,4). Max 10000 iterations.

Macros¶

MACRO check_health
  ASSERT /Player|Health|value > 0
  ASSERT_CONSOLE_CLEAN
END_MACRO

CALL check_health

Macros expand at parse time. Nested macros are not supported.

Full Example: Combat Test¶

script = """
LOG Starting combat scenario
SECTION "Setup"

# Snapshot initial state
CAPTURE initial_health /Player|Health|value

# Trigger combat
INVOKE /Enemy EnemyAI AttackPlayer
WAIT_CAPTURED initial_health DECREASED TIMEOUT 5

# Verify damage
SECTION "Verification"
ASSERT_CAPTURED initial_health DECREASED
ASSERT_CONSOLE_CLEAN IGNORE "test_warning"
ASSERT /Player|Health|value > 0

LOG Combat completed
SNAPSHOT /Player|Health
"""

await run_playtest(script=script, timeout=60.0)

Comparison Operators¶

Common Patterns¶

Before/after snapshots:

CAPTURE $hp /Player|Health|value
SET /Player Health value 25
ASSERT_CHANGED $hp

Frame comparison (animation playing):

CAPTURE_FRAMES 5 INTERVAL 0.1 LABEL walk_anim
ASSERT_FRAMES_DIFFER walk_anim

Exclusive camera check:

ASSERT_ONE_ACTIVE /Cam_Intro /Cam_Menu /Cam_Game

Physics conservation check:

MONITOR /Player|Velocity
SIMULATE physics DURATION 3.0
ASSERT /Player|Position != (0,0,0)

Timeout & Performance¶

Error Handling¶

Use abort_on_fail=True or the ABORT_ON_FAIL directive to stop at first failure.

Use snapshot_on_failure=True to capture alias values and console errors on failure.

Console Filtering¶

Ignore known warnings:

ASSERT_CONSOLE_CLEAN IGNORE "DeprecationWarning", "test_info"

Report Compression¶

Long reports (>300 chars) are auto-summarized by Haiku:

[Compressed] 24/25 passed
  [3] ASSERT Player/Health > 0 — FAIL
  [15] WAIT_UNTIL enemy_dead timeout=5 — TIMEOUT

See also: Runtime Tools for multi-step verification.