| name | run-match-audit |
| description | Run the headless AI-vs-AI match auditor to find gameplay bugs. Use when user wants to stress-test the engine, find card bugs automatically, run the auditor, or simulate matches — e.g. "run the auditor", "simulate some matches", "stress test the engine", "find bugs automatically". |
Run Match Audit
Run the headless AI-vs-AI match auditor, which plays full matches between two AI players using random decks from the entire card catalog and audits every trigger resolution and event for rule violations.
Arguments
$ARGUMENTS — Optional. Can specify:
- A number of matches (e.g., "20 matches", "50") — updates
NUM_MATCHES in the script before running
- A specific focus (e.g., "focus on invade cards", "test ward interactions") — noted for analysis but the auditor runs all checks regardless
If no arguments, run with the current default (10 matches).
Step 1: Adjust Match Count (if requested)
If the user specified a match count, edit tests/headless_match_auditor.gd and change the NUM_MATCHES constant.
Step 2: Run the Auditor
/Applications/Godot.app/Contents/MacOS/Godot --headless --log-file /tmp/godot.log --path /Users/flinnburgess/Development/Godot/ElderScrollsLegends --script res://tests/headless_match_auditor.gd
Important: This requires dangerouslyDisableSandbox: true because Godot writes to ~/Library/Application Support/Godot/ for logging.
Filter the output to show match results and violations:
... 2>&1 | grep -E "^(=| Match|Matches|Total|Violations|HEADLESS|Writ|\[| Check| Detail)"
Step 3: Report Results
Present a summary:
- How many matches ran, total actions, win distribution
- Number of violations found (0 = clean run)
- For each violation: the check type, the card involved, and what went wrong
Step 4: Handle Violations
If violations were found:
- The auditor automatically wrote bug report files to
reports/bug-reports/
- Note that these can be processed by the
fix-bug-reports skill
- Offer to investigate and fix the violations now, or let the user run
/fix-bug-reports later
- If fixing now, read the generated report files and follow the same investigation workflow as fix-bug-reports
If zero violations:
- Report a clean run
- No further action needed
Current Audit Checks
The auditor validates:
| Check | What it catches |
|---|
subtype_filter | Effects with target_filter_subtype affecting cards without that subtype |
cost_lock_enforcement | Cards played at a cost that was locked (e.g., by Seducer Darkfire) |
trigger_family_event_mismatch | Triggers firing on the wrong event type (e.g., pilfer on summon) |
ward_not_consumed | Ward still present after a ward_removed event |
Notes
- Matches use random 30-card decks from all 1100+ cards in the catalog — good for broad coverage but not targeted testing
- Each match typically runs 15-23 turns with 50-90 actions
- The auditor re-uses deterministic seeds per match index, so the same match index always produces the same game (useful for reproducing issues)
- Bug reports are prefixed with
[AUDITOR:check_type] in the comment field so fix-bug-reports can distinguish them from player-reported bugs
- If the auditor crashes mid-run (e.g., unhandled engine error), the matches before the crash still produce valid results
