t1k:unity:dots-testing:runtime-validator
| Field | Value |
|---|---|
| Module | dots-testing |
| Version | 3.30.3 |
| Effort | medium |
| Tools | — |
Keywords: DOTS, runtime validation, testing, validator
How to invoke
Section titled “How to invoke”/t1k:unity:dots-testing:runtime-validatorDOTS Runtime Validator
Section titled “DOTS Runtime Validator”Validates full ECS pipeline end-to-end via
t1k unitycommands during Play mode. Generic — works for ANY project using the dots-rpg library.
When This Skill Triggers
Section titled “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 renaming
Library/EntityScenes/aside (Editor closed)
Quick Reference
Section titled “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) |
t1k unity Commands Required
Section titled “t1k unity Commands Required”Activate t1k-unity-editor-cli first. Every command prints one JSON envelope; check ok and the exit code (4 = run t1k unity setup, 14 = no Editor open).
| Command | Purpose | Note |
|---|---|---|
t1k unity play enter / exit / status | Enter, leave, query Play mode | Waits until the Editor settles after the domain reload |
t1k unity eval 'UnityEditor.EditorApplication.isPaused = true' | PAUSE (= false to RESUME) | No pause verb; this is the recipe |
t1k unity console --level error | Error checking | --since N, --limit N, --grep rx narrow it |
t1k unity dots <action> [--flag value] | Entity, SubScene, render and physics queries | Action table: the dots-actions reference of the t1k-unity-editor-cli skill (the one table; not copied here) |
t1k unity eval '<C# expr>' | Camera, NavMeshSurface, scene and screenshot checks | Compile error is exit 6 |
Window rule (applies to every dots command): all t1k unity dots actions are bound to the live World, so they return data only in Play mode, and the Editor must have settled after entering it. Outside Play they fail with “no World”, which is not a broken project. There is no aggregate snapshot command: each of the 8 checks is one or two calls, and queries work while the Editor is paused. The pair list_component_types / list_subscenes may also run headless via t1k unity run --command, and only when no Editor has the project open.
Smoke script (copy-paste; every line must exit 0)
Section titled “Smoke script (copy-paste; every line must exit 0)”t1k unity console --level error --limit 5t1k unity play entert1k unity dots list_worldst1k unity dots list_subscenest1k unity dots query_count --component-types DOTSCombat.Healtht1k unity dots get_render_statst1k unity eval 'UnityEditor.EditorApplication.isPaused = true't1k unity dots performance_snapshot --limit 5t1k unity eval 'UnityEditor.EditorApplication.isPaused = false't1k unity play exitValidation Protocol
Section titled “Validation Protocol”| # | Check | Command | Params | Pass Condition | Phase |
|---|---|---|---|---|---|
| 1 | Console Clean | t1k unity console | --level error | 0 errors | Pre-flight (Edit mode) |
| 1b | SubScene Present | t1k unity dots list_subscenes | (Play mode: dots is World-bound) | 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 | t1k unity dots query_count | --component-types DOTSCombat.Health | count > 0 | Play: T+5s |
| 3 | Rendering Active | t1k unity dots get_render_stats + t1k unity eval 'UnityEditor.UnityStats.drawCalls' | - | drawCalls > 10 AND rendered entities > 0 | Play: T+5s |
| 3b | Visuals Exist | t1k unity dots query_count + t1k unity eval | --component-types Unity.Rendering.MaterialMeshInfo; screenshot via ScreenCapture.CaptureScreenshot | count > 0 (or Mono Renderer > 0) AND the captured frame shows gameplay visuals | Play: T+5s — MANDATORY |
| 4 | No NaN Bounds | t1k unity dots query_entities | --component-types Unity.Rendering.ChunkWorldRenderBounds | no NaN/Infinity in values | Play: T+5s |
| 5 | Troops Move | t1k unity dots query_entities | --component-types Unity.Transforms.LocalTransform at T1 vs T2 | position delta > 0.1 for >50% entities | Play: PAUSE at T+10s |
| 6 | Combat Active | t1k unity dots query_count | --component-types DOTSCombat.DeadTag (enabled only) | count > 0 | Play: PAUSE at T+20s |
| 7 | Camera Valid | t1k unity eval | UnityEngine.Camera.main.farClipPlane and .transform.position.y | farClipPlane > camera.position.y | Pre-flight |
| 8 | Battle Resolves | t1k unity dots query_entities | --component-types DOTSCombat.BattleState | winner != 0 | Play: poll until done |
Pre-flight gate 1b — Empty Play mode root cause
Section titled “Pre-flight gate 1b — Empty Play mode root cause”If t1k unity dots list_subscenes returns count=0 AND no Bootstrapper is wired:
- Play mode WILL render an empty Game view (only Camera + Light visible)
t1k unity dots list_worldswill show ONLY default systems (noConverted Scene:*worlds)- Fix path: run the demo’s
Tools/<DemoName>/Setup Scenemenu 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 1b-2 — “0 entities at runtime” does NOT mean they never arrived
Section titled “Pre-flight gate 1b-2 — “0 entities at runtime” does NOT mean they never arrived”Before investigating baking, serialization, or the SubScene load path, prove which of these three you are looking at. They produce an identical steady-state reading and are routinely conflated:
- the entity never arrived (bake/serialize/load), or
- it arrived and a system consumed and destroyed it (often by design), or
- it arrived, spawned its output, and the output was destroyed downstream.
A late-frame count cannot tell them apart — by the time you measure, the evidence is gone.
Decisive experiment (~2 minutes, no re-bake, no code change). Disable the suspect consumer, then re-stream the SubScene and re-count:
var h = world.GetExistingSystem(typeof(MySystem));ref var st = ref world.Unmanaged.ResolveSystemStateRef(h);st.Enabled = false; // stop the consumerforeach (var s in Object.FindObjectsByType<SubScene>(FindObjectsSortMode.None)) s.enabled = false; // unload (next call: = true to re-stream)Entities present with the consumer off ⇒ arrival is fine; the bug is downstream. Always query with
EntityQueryOptions.IncludePrefab | IncludeDisabledEntities so prefab/disabled entities aren’t
silently excluded.
If the consumer’s output also vanishes, spawn the output yourself (em.Instantiate(prefab)) and
re-count a few hundred frames later. If your hand-made copies die too, the spawner is innocent —
find the destroyer. Disable DeathSystem + DeathAnimationSystem and re-read Health: 0/0 on an
entity whose prefab authored a positive value means the stats pipeline zeroed it (see gotcha #0
in t1k:unity:dots-combat:core), not combat damage.
What skipping this gate has cost in practice: references/troubleshooting-guide.md § Pre-flight gate case files.
Pre-flight gate 1b-3 — Units exist but never move or fight → count their components
Section titled “Pre-flight gate 1b-3 — Units exist but never move or fight → count their components”If entities spawn and survive but stand inert, do NOT start by debugging AI logic, navigation tuning, or targeting. First count the components on one unit and compare against a demo known to work.
var types = em.GetComponentTypes(unit, Allocator.Temp); // then tally by namespace prefix// a healthy unit carries the behaviour-tree + pathfinding families; an inert one carries neither// (observed per-demo baselines: references/troubleshooting-guide.md § Pre-flight gate case files)Zero Opsive.* ⇒ no behaviour tree. Zero ProjectDawn.* ⇒ no pathfinding. The entity cannot act
because it lacks the components that act — nothing downstream is worth debugging until that is fixed.
Cause: a dead authoring reference on the prefab. When a prefab’s MonoBehaviour script reference
no longer resolves to a loadable type, Unity drops the component, so its Baker never runs and the
baked entity silently comes out without that subsystem — no error at bake time. Diagnose from the
prefab YAML, which records the expected assembly + type:
grep -E "m_EditorClassIdentifier:" <working-demo>/Prefabs/UnitA.prefabgrep -E "m_EditorClassIdentifier:" <broken-demo>/Prefabs/UnitB.prefab # diff them⚠️ [MovedFrom] does not always rescue you — if the migration left no class behind, there is no
type for the attribute to redirect from and the reference dies silently. Observed migration pairs and
the assembly/namespace moves behind them: references/troubleshooting-guide.md § Pre-flight gate case files.
Fix = regenerate, never hand-edit the YAML: re-run the demo’s prefab-generation chain in order —
Tools/<DemoName>/Create Unit Prefabs → the project’s addressables-registration item → its
behavior-tree build item → Tools/<DemoName>/Setup Scene. Related tell: prefab generation failing
with script '' does not derive from MonoBehaviour is the same dead reference surfacing at save
time.
Audit a whole project with the dead identifier the diff above surfaced:
grep -rl "<DeadNamespace>.<DeadType>::" <demos-root>/ # any hit is a stale prefabTake <DeadNamespace>.<DeadType> from the m_EditorClassIdentifier line present in the working
prefab and absent in the broken one — hardcoding one project’s namespace returns zero hits and a
false all-clear anywhere else. Concrete observed pairs: references/troubleshooting-guide.md § Pre-flight gate case files.
Pre-flight gate 1c — Game-view aspect mismatch
Section titled “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 Portraitfor portrait-mobile demos) - Cannot be set from
t1k unity— 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
Gate 3b — “the data layer is verified” is NOT a playtest
Section titled “Gate 3b — “the data layer is verified” is NOT a playtest”A demo can have a perfect, fully-verified simulation and still render an entirely blank screen. Querying ECS data proves the data exists; it proves nothing about whether a player can see it. These are different claims, and they are routinely conflated in handoffs as “verified end-to-end in Play mode”.
The failure shape: entities carry LocalTransform (so they have positions, and every data query looks
healthy) but never receive MaterialMeshInfo / RenderBounds — because a baker created them with
CreateAdditionalEntity instead of instantiating a visual prefab, or baked the prefab reference into a
singleton that no system ever consumes. Nothing errors. Nothing warns.
// Decisive, ~5 seconds. Run it before claiming any Play-mode verification:var em = World.DefaultGameObjectInjectionWorld.EntityManager;var t = System.Type.GetType("Unity.Rendering.MaterialMeshInfo, Unity.Entities.Graphics");var q = em.CreateEntityQuery(new EntityQueryDesc { All = new[]{ ComponentType.ReadOnly(t) }, Options = EntityQueryOptions.IncludePrefab | EntityQueryOptions.IncludeDisabledEntities });Debug.Log("MaterialMeshInfo=" + q.CalculateEntityCount()); // 0 ⇒ NOTHING can be drawnDebug.Log("Renderers=" + Object.FindObjectsByType<Renderer>( FindObjectsInactive.Include, FindObjectsSortMode.None).Length); // 0 ⇒ no Mono renderer eitherMaterialMeshInfo == 0 and Renderer == 0 ⇒ the world is unrenderable by construction. Stop; do
not debug the camera, lighting, culling mask, aspect ratio, or NaN bounds — none of them are reachable
causes. Go find the system that was supposed to instantiate the visual prefab.
Always also capture the frame (t1k unity eval 'UnityEngine.ScreenCapture.CaptureScreenshot("Temp/dots-validate.png")',
then Read the PNG) and look at it. One screenshot falsifies an entire session of data queries.
⚠️ Check 3 alone will not save you here — a UI Canvas supplies draw calls and triangles, so
get_render_stats and UnityStats.drawCalls can pass on a world containing zero gameplay visuals.
What skipping this gate has cost in practice: references/troubleshooting-guide.md § Pre-flight gate case files.
-> See references/validation-protocol-guide.md for full phase-by-phase workflow, pause/resume strategy, and the compact t1k unity sequence.
Executed by
Section titled “Executed by”The per-check validation sweep delegates to cheap-tier agents, mirroring the haiku validator
pattern in the cocos kit; only the failure investigation stays on a reasoning tier (routing SSOT:
rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Step | Agent |
|---|---|
Poll each timeline check (t1k unity console, entity counts, rendering stats, battle state) to a terminal pass/fail against the stated condition | t1k-ci-watcher |
Read specific entity counts / component counts / stats values off one t1k unity dots response and quote them | t1k-fact-fetcher |
Label each check pass / fail / blocked / not-run against the protocol table | t1k-list-classifier |
| Aggregate the check results into the validation table | t1k-metrics-reporter |
| Diagnose WHY a failing check failed (empty Play mode root cause, dead authoring reference, renderer never instantiated) and decide the fix | reasoning tier — the pre-flight gates 1b / 1b-2 / 1b-3 and gate 3b exist precisely because a failed check’s cause is routinely mis-read |
The pass conditions are spelled out per check (count > 0, drawCalls > 10, winner != 0), so
labeling a captured reading against them is fully specified before the agent starts. The moment a
check fails and the question turns from which check failed? to did the entity ever arrive or did
a consumer destroy it?, it has changed tier — that decisive-experiment reasoning is
t1k-unity-dots-core-debugger territory, and this skill’s own troubleshooting guide is the
evidence that the diagnosis is not mechanical
Anti-Patterns
Section titled “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 |
Running dots outside Play mode | “no World” failure read as a broken project | t1k unity play enter first, play exit last |
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 |
| 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.