Skip to content

t1k:unity:dots-testing:runtime-validator

FieldValue
Moduledots-testing
Version3.30.3
Effortmedium
Tools—

Keywords: DOTS, runtime validation, testing, validator

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

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

  • 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)
TaskCheck
Verify compilationConsole Clean (#1)
Confirm entities existEntities Spawn (#2)
Confirm renderingRendering Active (#3)
Debug invisible entitiesNaN Bounds (#4)
Confirm AI/navigationTroops Move (#5)
Confirm combat pipelineCombat Active (#6)
Debug camera issuesCamera Valid (#7)
Full battle testBattle Resolves (#8)

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).

CommandPurposeNote
t1k unity play enter / exit / statusEnter, leave, query Play modeWaits 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 errorError checking--since N, --limit N, --grep rx narrow it
t1k unity dots <action> [--flag value]Entity, SubScene, render and physics queriesAction 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 checksCompile 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)”
Terminal window
t1k unity console --level error --limit 5
t1k unity play enter
t1k unity dots list_worlds
t1k unity dots list_subscenes
t1k unity dots query_count --component-types DOTSCombat.Health
t1k unity dots get_render_stats
t1k unity eval 'UnityEditor.EditorApplication.isPaused = true'
t1k unity dots performance_snapshot --limit 5
t1k unity eval 'UnityEditor.EditorApplication.isPaused = false'
t1k unity play exit
#CheckCommandParamsPass ConditionPhase
1Console Cleant1k unity console--level error0 errorsPre-flight (Edit mode)
1bSubScene Presentt1k unity dots list_subscenes(Play mode: dots is World-bound)count > 0 OR Bootstrapper wires one at runtimePre-flight (Edit mode) — MANDATORY
1cGame-view Aspectinspect editor / ask useraspect matches project target form factormatches the project’s documented form factor (e.g., 2160x1080 Portrait)Pre-flight (Edit mode)
2Entities Spawnt1k unity dots query_count--component-types DOTSCombat.Healthcount > 0Play: T+5s
3Rendering Activet1k unity dots get_render_stats + t1k unity eval 'UnityEditor.UnityStats.drawCalls'-drawCalls > 10 AND rendered entities > 0Play: T+5s
3bVisuals Existt1k unity dots query_count + t1k unity eval--component-types Unity.Rendering.MaterialMeshInfo; screenshot via ScreenCapture.CaptureScreenshotcount > 0 (or Mono Renderer > 0) AND the captured frame shows gameplay visualsPlay: T+5s — MANDATORY
4No NaN Boundst1k unity dots query_entities--component-types Unity.Rendering.ChunkWorldRenderBoundsno NaN/Infinity in valuesPlay: T+5s
5Troops Movet1k unity dots query_entities--component-types Unity.Transforms.LocalTransform at T1 vs T2position delta > 0.1 for >50% entitiesPlay: PAUSE at T+10s
6Combat Activet1k unity dots query_count--component-types DOTSCombat.DeadTag (enabled only)count > 0Play: PAUSE at T+20s
7Camera Validt1k unity evalUnityEngine.Camera.main.farClipPlane and .transform.position.yfarClipPlane > camera.position.yPre-flight
8Battle Resolvest1k unity dots query_entities--component-types DOTSCombat.BattleStatewinner != 0Play: 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_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 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:

  1. the entity never arrived (bake/serialize/load), or
  2. it arrived and a system consumed and destroyed it (often by design), or
  3. 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 consumer
foreach (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:

Terminal window
grep -E "m_EditorClassIdentifier:" <working-demo>/Prefabs/UnitA.prefab
grep -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:

Terminal window
grep -rl "<DeadNamespace>.<DeadType>::" <demos-root>/ # any hit is a stale prefab

Take <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 Portrait for 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 drawn
Debug.Log("Renderers=" + Object.FindObjectsByType<Renderer>(
FindObjectsInactive.Include, FindObjectsSortMode.None).Length); // 0 ⇒ no Mono renderer either

MaterialMeshInfo == 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.

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”):

StepAgent
Poll each timeline check (t1k unity console, entity counts, rendering stats, battle state) to a terminal pass/fail against the stated conditiont1k-ci-watcher
Read specific entity counts / component counts / stats values off one t1k unity dots response and quote themt1k-fact-fetcher
Label each check pass / fail / blocked / not-run against the protocol tablet1k-list-classifier
Aggregate the check results into the validation tablet1k-metrics-reporter
Diagnose WHY a failing check failed (empty Play mode root cause, dead authoring reference, renderer never instantiated) and decide the fixreasoning 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-PatternSymptomFix
Not pausing to inspect stateMiss movement/combat windowsUse pause/resume at T+5s, T+15s, T+25s
Running dots outside Play mode“no World” failure read as a broken projectt1k unity play enter first, play exit last
Fixed sleep instead of pollingFlaky results on slow machinesPoll with timeout loop
Hardcoded entity counts (e.g., == 82)Fails when army size changesUse > 0 or percentage thresholds
Demo-specific component queriesBreaks in new projectsUse generic components: Health, DeadTag, LocalTransform
Checking DamageEvent buffer for combatBuffer cleared same frameCheck Health.Current decrease or DeadTag enabled count
Single position snapshot for movementCan’t detect movementTake TWO snapshots with 3-5s gap
Inheriting Play mode sessionBattle already endedALWAYS stop and re-enter Play mode
Not stopping Play mode on errorUnity stuck in bad stateALWAYS stop play mode in finally block

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