t1k:unity:dots-testing:runtime-validator

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	dots-testing
Version	2.1.7
Effort	medium
Tools	—

Keywords: DOTS, runtime validation, testing, validator

How to invoke

/t1k:unity:dots-testing:runtime-validator

---

DOTS Runtime Validator

Validates full ECS pipeline end-to-end via MCP tools during Play mode. Generic — works for ANY project using the dots-rpg library.

When This Skill Triggers

• After implementing/modifying systems or components
• After scene setup changes or prefab updates
• Before committing code changes (final verification)
• Debugging “troops don’t move”, “entities invisible”, “no combat” issues
• After clearing Library/EntityScenes/ cache

Quick Reference

Task	Check
Verify compilation	Console Clean (#1)
Confirm entities exist	Entities Spawn (#2)
Confirm rendering	Rendering Active (#3)
Debug invisible entities	NaN Bounds (#4)
Confirm AI/navigation	Troops Move (#5)
Confirm combat pipeline	Combat Active (#6)
Debug camera issues	Camera Valid (#7)
Full battle test	Battle Resolves (#8)

MCP Tools Required

Load ALL via ToolSearch before validation:

Tool	Purpose	Note
mcp__UnityMCP__manage_editor	Enter/pause/stop Play mode	Use action="play", "pause", "stop"
mcp__UnityMCP__read_console	Error checking	Filter with types=["error"]
mcp__UnityMCP__manage_dots	Entity queries (count, list, inspect)	Use DIRECTLY — NOT through execute_custom_tool
mcp__UnityMCP__batch_execute	rendering_stats via batch	batch_execute(commands=[{"tool":"rendering_stats","params":{...}}])
mcp__UnityMCP__find_gameobjects	Find Camera, NavMeshSurface	Edit mode checks
mcp__UnityMCP__manage_components	Read camera/component properties	Edit mode only
mcp__UnityMCP__manage_scene	SubScene hierarchy checks	Edit mode checks
mcp__UnityMCP__validation_snapshot	Aggregated validation data (capture/compare)	Use this FIRST — replaces 15+ individual MCP calls with 1

CRITICAL: manage_dots is a DIRECT MCP tool — call it directly as mcp__UnityMCP__manage_dots. rendering_stats is NOT a direct MCP tool — call it via batch_execute(commands=[{"tool":"rendering_stats","params":{"action":"get_stats"}}]).

PREFERRED: If validation_snapshot tool is available, use it instead of individual manage_dots + rendering_stats calls. It aggregates entity counts, rendering stats, position snapshots, and combat state in a single response.

Validation Protocol

#	Check	MCP Tool	Action/Params	Pass Condition	Phase
1	Console Clean	read_console	types=["error"]	0 errors	Pre-flight (Edit mode)
1b	SubScene Present	manage_dots_subscene	action="list_subscenes"	count > 0 OR Bootstrapper wires one at runtime	Pre-flight (Edit mode) — MANDATORY
1c	Game-view Aspect	inspect editor / ask user	aspect matches project target form factor	matches the project’s documented form factor (e.g., 2160x1080 Portrait)	Pre-flight (Edit mode)
2	Entities Spawn	manage_dots	action="query_count", component DOTSCombat.Health	count > 0	Play: T+5s
3	Rendering Active	execute_custom_tool	rendering_stats, action="get_stats"	drawCalls > 10 AND triangles > 100	Play: T+5s
4	No NaN Bounds	manage_dots	action="query_entities", ChunkWorldRenderBounds	no NaN/Infinity in values	Play: T+5s
5	Troops Move	manage_dots	query_entities LocalTransform at T1 vs T2	position delta > 0.1 for >50% entities	Play: PAUSE at T+10s
6	Combat Active	manage_dots	action="query_count", DeadTag (enabled only)	count > 0	Play: PAUSE at T+20s
7	Camera Valid	manage_components	read Camera on MainCamera	farClipPlane > camera.position.y	Pre-flight
8	Battle Resolves	manage_dots	query DOTSCombat.BattleState	winner != 0	Play: poll until done

Pre-flight gate 1b — Empty Play mode root cause

If manage_dots_subscene list_subscenes returns count=0 AND no Bootstrapper is wired:

• Play mode WILL render an empty Game view (only Camera + Light visible)
• manage_dots list_worlds will show ONLY default systems (no Converted Scene:* worlds)
• Fix path: run the demo’s Tools/<DemoName>/Setup Scene menu item (idempotent per the project’s “Editor SceneSetup idempotency” rule) BEFORE entering Play mode
• This precondition is MANDATORY because the symptom (“nothing renders”) otherwise looks like a rendering bug, not a scene-setup gap
• Generic for any Unity DOTS project — applies any time a demo scene is committed without a SubScene component wired up

Pre-flight gate 1c — Game-view aspect mismatch

If Unity Game-view aspect doesn’t match the project’s documented target form factor:

• Demo UI Canvas may scale to wrong dimensions
• Camera viewport may letterbox or squeeze the playable area
• User will report “nothing visible” or “everything is tiny/squashed”
• Target form factor MUST be documented in the project’s CLAUDE.md (e.g., 2160x1080 Portrait for portrait-mobile demos)
• Cannot be set programmatically via current MCP tools — ASK USER to switch aspect via Game-view Aspect dropdown before declaring validation pass
• Generic for any Unity project that has a documented target form factor

-> See references/validation-protocol-guide.md for full phase-by-phase workflow, pause/resume strategy, and optimized validation_snapshot workflow.

Anti-Patterns

Anti-Pattern	Symptom	Fix
Not pausing to inspect state	Miss movement/combat windows	Use pause/resume at T+5s, T+15s, T+25s
Using execute_custom_tool for manage_dots	Indirect call, slower	Call manage_dots DIRECTLY as MCP tool
Fixed sleep instead of polling	Flaky results on slow machines	Poll with timeout loop
Hardcoded entity counts (e.g., == 82)	Fails when army size changes	Use > 0 or percentage thresholds
Demo-specific component queries	Breaks in new projects	Use generic components: Health, DeadTag, LocalTransform
Skipping console check	Miss compilation errors	ALWAYS check console FIRST
Checking DamageEvent buffer for combat	Buffer cleared same frame	Check Health.Current decrease or DeadTag enabled count
Single position snapshot for movement	Can’t detect movement	Take TWO snapshots with 3-5s gap
Inheriting Play mode session	Battle already ended	ALWAYS stop and re-enter Play mode
Not stopping Play mode on error	Unity stuck in bad state	ALWAYS stop play mode in finally block

-> See references/troubleshooting-guide.md for common failures table and 19 documented gotchas.