| name | playtester |
| description | Execute end-to-end playtesting of the D&D 5E game using the embedded MCP server. Use this skill when the user says "let's playtest", "test our fix", "qa the game", "playtest this", "test the game", or wants to verify game functionality through actual gameplay. When working on a ticket, focuses testing on the specific functionality being addressed. |
Playtester
QA the D&D 5E game by playing it as a human player would, using the embedded MCP server.
Setup
Prefer headless mode by default (issue #362) — faster to launch, no window stealing focus, identical MCP behavior:
uv run dnd-2d --headless --dev --mcp
--headless implies --mcp. Add --dev so the spawn_monster, spawn_character, set_position, clear_enemies, set_seed, and load_scenario tools are available for reproducible setup. SIGINT / SIGTERM stops it cleanly.
Use windowed mode only when you genuinely need to see the rendering:
uv run dnd-2d --mcp --dev
Both modes route MCP commands through the same GameSession so behavior is identical.
MCP Tools
Core play tools (always available):
| Tool | Usage |
|---|
game_state() | Get ASCII map + JSON state |
game_move(direction) | Move "north"/"south"/"east"/"west" |
game_attack(target) | Attack enemy by index or entity ID (e.g., "goblin_0") |
game_wait() | Wait/pass turn in combat |
Dev tools (only available with --dev):
| Tool | Usage |
|---|
spawn_monster(monster_id, x, y) | Place a monster on the map and start combat |
spawn_character(class, race, weapons, x, y, ...) | Add a PC to the party |
set_position(entity_id, x, y) | Move any entity to a tile |
clear_enemies() | Wipe enemies, end combat |
set_seed(seed) | Reseed the dice roller for reproducible rolls |
load_scenario(path) | Load a YAML scenario (party + enemies + seed + map) |
Playtest Workflow
1. Context Check
If working on a ticket/issue, identify the specific functionality to test. Read the ticket to understand:
- What was changed
- Expected behavior
- Edge cases to verify
2. Start Session
game_state() → Observe initial state
3. Navigate to Test Area
Move systematically to reach the area/feature being tested. For ticket work, navigate to where the bug/feature manifests.
4. Execute Test Actions
Perform actions to exercise the functionality:
- Movement sequences
- Combat encounters
- Object interactions
- Edge cases from the ticket
5. Observe and Document
After each action, check game_state() for:
- Expected state changes occurred
- No unexpected errors in output
- Visual/map state is correct
- Entity positions are sensible
6. Bug Handling
When a bug is found:
Create a GitHub issue immediately:
gh issue create --title "Bug: [brief description]" --body "[details]"
Include in the issue:
- Steps to reproduce (the exact MCP calls made)
- Expected behavior
- Actual behavior
- Game state at time of bug (paste relevant JSON)
Severity decision:
- Blocking: Game crashes, cannot continue, core mechanic broken → End testing, report to user
- Non-blocking: Visual glitch, minor calculation error, cosmetic → Log issue, continue testing
7. Continue or Report
- If non-blocking bugs: continue exploring other functionality
- If blocking bug: stop and inform user immediately
- When testing complete: summarize findings (issues created, areas tested, pass/fail)
Test Strategies
Exploration test: Move in all directions, reveal full map, check fog of war
Combat test: Find enemy, attack until resolved, verify HP changes and death
Boundary test: Try invalid moves (into walls), verify rejection
State persistence: Check that position/HP persist across turns
