t1k:unity:base:static-ref-check
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
Keywords: addressables audit, asset check, broken reference, content id, dangling reference, dead reference, guid check, missing addressable, parallel safe check, prefab refs, reference health, static check, sub-agent fan-out, unresolved icon
How to invoke
Section titled “How to invoke”/t1k:unity:base:static-ref-checkUnity Static Reference Check — Fast, No-Editor, PARALLEL-SAFE Asset/Prefab Health
Section titled “Unity Static Reference Check — Fast, No-Editor, PARALLEL-SAFE Asset/Prefab Health”The headline property: no Editor means no mutex
Section titled “The headline property: no Editor means no mutex”One Editor holds a project at a time, and t1k unity serializes its mutating verbs behind a per-project
lock (Temp/t1k-unity.lock). This project runs 6+ concurrent Claude sessions; ANY check that touches the Editor
(t1k unity test, eval, play, screenshots) is therefore a serial mutex — agents queue on the lock
(exit 10 when it times out), and a source edit landing mid-t1k unity test can kill a
whole suite run via an unplanned domain reload.
This skill’s checks read files off disk. N agents can run them concurrently, on different id
families or scan roots, with zero contention and zero risk to anyone’s in-flight compile or test
run. That is why this is the check to fan out, and Play mode is the one to keep serial — not a
speed preference, a structural one. See references/parallel-fanout-recipe.md for the
copy-pasteable brief text.
Triggers
Section titled “Triggers”- “check prefab refs”, “check asset references”, “are these icons wired”
- “find broken references”, “dangling guid”, “missing addressable”
- “audit content ids”, “unresolved icon ids”, “reference health check”
- “run this in parallel / with sub-agents without touching the Editor”
Why this exists — the same defect class, three times, always found late
Section titled “Why this exists — the same defect class, three times, always found late”The three dated instances (the item-icon address table, the HUD glyph ids, the achievement rows) and their costs are tabled in references/incident-log.md, § Incident history.
The generalization: in this project a C#-declared id and its Addressables address are
maintained by different mechanisms — usually a hand-written, per-family Editor registration
tool — and nothing structurally forces the two sets to agree. A family with no registration
tool is silently 100% unresolved. Nothing goes red: it compiles, tests pass, the screen opens,
and the failure is a blank rectangle or a runtime exception, found only by a human looking at a
screenshot. All three instances were a pure two-file-set join — the static join this skill
scripts is the right instrument, and belongs in CI, not in someone’s memory. Full detail + live
numbers: references/worked-example-hud-gap.md.
The decision rule
Section titled “The decision rule”| Defect shape | Detectable how | Tool | Parallel-safe? |
|---|---|---|---|
| Declared content id has no matching Addressables address (§ above, all 3 instances) | Static — string-literal ∩ m_Address join | unity-static-ref-check.cjs ids | YES |
Address exists but points at nothing (dead guid: / Addressables m_GUID: group entry) | Static — guid:/m_GUID: ∩ .meta join | unity-static-ref-check.cjs refs | YES |
A <sprite name="X"> TMP tag names a nonexistent sprite asset | Static — same idea, scoped --id-prefix or manual grep | ids / manual | YES |
| Icon/sprite wired but visually wrong size (stretched, clipped, mispositioned) | Requires Play mode — geometry only exists once layout runs | GetWorldCorners batch | NO — mutex on the single bridge |
| A button/panel sits off-screen or overlapping | Requires Play mode | GetWorldCorners batch | NO |
| Test suite pass/fail | Requires Editor | t1k unity test | NO |
Prescribed sequence: static check first (parallel, cheap, exhaustive) → fix what it finds → THEN one serial Editor pass to verify geometry and capture evidence. Not: Play mode → N screenshots → eyeball → find defects that a two-file join would have caught for free.
Running the script
Section titled “Running the script”.claude/scripts/unity-static-ref-check.cjs — read-only, pure Node, no Unity. Emits JSON facts
only; this skill (or you) supplies the judgment, per rules/ai-driven-design.md.
# ids — declared content id ↔ Addressables address (two-hop: id → resolver → address)bun .claude/scripts/unity-static-ref-check.cjs ids \ --source-root "Assets/Demos/Farming/TinyTerraces" \ --id-prefix "hud." \ --addressables-dir "Assets/AddressableAssetsData/AssetGroups" \ --exclude-paths "LocKeys" \ # ALMOST ALWAYS WANT THIS — see below --min-declared 10 # optional — assert an expected floor
# refs — GUID reference ↔ .meta ownershipbun .claude/scripts/unity-static-ref-check.cjs refs \ --scan-roots "Assets/Demos/Farming/TinyTerraces"| Flag | Default | Why |
|---|---|---|
--exclude-paths a,b | none | Substring match on path. Pass LocKeys on this project by default — localization keys (building.next, item.unknown) share the dotted-prefix shape of content ids but name a string-table row, so every one is a guaranteed false positive |
--include-tests | off (tests excluded) | Test fixtures declare synthetic sample ids (creature.0, creature.99). Counting them made a healthy family read as 100% unresolved. Only pass this when auditing the tests themselves |
--no-cache | cache on | Skips the shared GUID index. Use when a .meta’s guid may have been rewritten in place without any file being added or removed — the one case the fingerprint cannot see |
ids scans every .cs under --source-root for double-quoted literals starting with
--id-prefix, at their declaration site — finds the id regardless of which array or call
site later assembles it. refs builds known GUIDs from every .meta under --meta-roots
(default Assets,Packages,Library/PackageCache — dropping Library/PackageCache false-positives
third-party refs as broken), scans .prefab/.unity/.asset/.mat/.controller/... for guid: and Addressables m_GUID:,
excludes Unity’s 2 builtin-resource GUIDs + the null guid, and skips (never mis-parses) binary
files. Full flag list: script header comment.
Third check — C# syntax, also no-Editor, also parallel-safe
Section titled “Third check — C# syntax, also no-Editor, also parallel-safe”.claude/scripts/unity-csharp-syntax-check.sh answers “did my edit produce structurally valid
C#?” without an Editor compile.
git diff --name-only -- '*.cs' | .claude/scripts/unity-csharp-syntax-check.sh --stdin.claude/scripts/unity-csharp-syntax-check.sh path/to/One.cs path/to/Two.csExit 0 = no syntax faults · 1 = faults (prints file(line,col): error CS1xxx) · 2 = no compiler,
or none of the given paths exist — reported as NOT_CHECKED, never as a pass.
Known boundary (dated in incident-log). Assert.Multiple(...) is valid C# calling a
method Unity’s bundled NUnit does not expose. The parse pass reported OK; the Editor compile
reported CS0117. That is the tool working as designed — it buys you “not a typo”, never
“it compiles” — but do not let a green here talk you out of the one Editor compile.
What it does NOT do: type-check. It compiles with -nostdlib+ and no references, so every
missing type is expected and filtered out; only CS1xxx (parser) errors are reported. A clean run
does not predict that Unity will compile — it means the one Editor compile you do run will not
be spent discovering a typo.
Why it earns its place. A failed Unity compile leaves the previous DLL untouched, so
“no compile ran” and “compiled and failed” have an identical mtime signature — on this project a
single dropped ; was read as “still compiling” for four minutes
(rules/ai-velocity-batch-compile-unity.md). This catches that class before the mutex is involved.
⚠️ Use Roslyn (csc), never Mono’s mcs. Measured (dated in incident-log): mcs, even with
-langversion:latest, tops out near C# 7 and reported 41 syntax errors across untouched files
— every one a target-typed new(...), a C# 9 form this codebase uses widely. All false positives.
csc (Roslyn 3.9) reports zero on the same set. A checker that cries wolf on correct code is worse
than none: it teaches you to ignore it. Override the binary with T1K_CSC if needed.
Falsifiability confirmed rather than assumed — the same file passes clean, fails with CS1002
when one semicolon is removed, and reports NOT_CHECKED on a path that does not exist.
Reading the output — coverageStatus is the field to read FIRST
Section titled “Reading the output — coverageStatus is the field to read FIRST”ids output always carries coverageStatus + coverageNote. Read it before the raw counts —
declaredCount: 0 is NOT_CHECKED, never a pass. It means no string literal matched your
prefix, which is exactly what happens when a family is declared via a generated table,
ScriptableObject, or CSV instead of literal strings (the item-icon family’s
TinyTerracesItemIconAddressTable.g.cs is one — regenerated by an Editor tool, no "Icons/..."
literals to grep). A family invisible to this join reports 0/0/0, which reads exactly like green.
Confirm the declaration idiom (or use --min-declared to assert an expected floor) before
trusting a NOT_CHECKED result at all.
ZERO_RESOLVED (declared > 0, resolved = 0) is a distinct, louder result from
PARTIAL_COVERAGE on purpose — per the three-instance history above, 100%-unresolved almost
always means “no registration mechanism exists for this family” (write/extend a tool), not “a
few assets are missing” (author art). Don’t let a 100% miss read as a long tail. Each
unresolved entry now carries a cause: resolver-target-address-not-registered (a resolver
claims the id but its target address has no Addressables row — author/register the asset) versus
no-address-and-no-resolver (nothing claims this id at all — write the mechanism). Different
bugs, different fixes.
NOT_VERIFIABLE_COMPUTED_RESOLVER means a resolver claims this prefix but builds its address in
code (CreatureIconAddressResolver strips the prefix and parses the remainder as an index). A
literal-table scan structurally cannot follow that. This is reported as UNKNOWN, never as a
failure — see the false-RED section below for why that distinction is the whole point.
⚠️ The false RED — this tool’s own worst failure
Section titled “⚠️ The false RED — this tool’s own worst failure”A false RED on a fan-out tool is worse than a false green. A false green ends one investigation; a false RED sends N agents chasing a defect that does not exist, and then trains every reader to discount the tool’s reds — which is how the next real one gets ignored.
This tool emitted exactly that. Asked for the hud. family it reported ZERO_RESOLVED, 16
declared, 0 resolved — against a family that was, verified by hand the same hour, 100%
healthy: 14 resolver rows, 14 registered addresses, all matching. Three independent defects
stacked up to produce it, all now fixed: the one-hop join, prose counted as declarations, and test fixtures counted as content, plus a fourth noise source (localization keys) handled by --exclude-paths. The defect table and fixes are in references/incident-log.md.
The lesson, and it generalizes past this script: the tool was confidently wrong in the
direction that costs the most. When it cannot follow a mapping it must say NOT_CHECKED or
NOT_VERIFIABLE_COMPUTED_RESOLVER — an honest unknown — never a red. Per
rules/green-that-proves-nothing.md, unknown must not render as good; the mirror obligation is
that unknown must not render as bad either.
Before acting on any ZERO_RESOLVED: confirm the family does not resolve through an idiom
this scan cannot see. Read the resolver, or ask the resolver itself from an EditMode test.
Measured performance
Section titled “Measured performance”Speed matters here specifically because this is the check you fan out — every gain multiplies across N concurrent agents, while every Editor-bound check serialises behind the mutex.
Dated per-phase timings, the end-to-end cold and warm numbers, the shared GUID-index cache and the rejected packed-cache format: references/incident-log.md. Do not “optimize” the JSON cache back; V8’s JSON parser already wins.
refs mode has no NOT_CHECKED caveat — a guid absent from every .meta in scope literally
cannot resolve, so its findings are direct evidence. Falsifiability check (a zero never seen
going non-zero proves nothing, per rules/green-that-proves-nothing.md): the same command
against a wider scope found 4 real broken GUIDs in unrelated animation controllers — both runs
side by side in references/worked-example-hud-gap.md.
When you DO need Play mode — batch it, keep it serial, don’t screenshot-per-screen
Section titled “When you DO need Play mode — batch it, keep it serial, don’t screenshot-per-screen”Layout geometry only exists once a Canvas has actually laid out. Measure every screen’s
RectTransform corners in one t1k unity eval call, not one screenshot per screen — and run
it on the ONE thread holding the Editor, per the parallel-safety section above. Recipe, the
fully-qualified-names rule for eval snippets (a compile error is exit 6 with the compiler message, not a timeout), and
the GetWorldCorners interpretation table: references/layout-geometry-escape-hatch.md.
References
Section titled “References”references/incident-log.md— the dated incident detail (three-instance history, v1.2.0 false-RED defect table, meas-perf table), kept out of the body for tightnessreferences/parallel-fanout-recipe.md— how a lead briefs N sub-agents to run this script over different families/scopes simultaneously, with the copy-pasteable “no Editor verbs” constraint.references/worked-example-hud-gap.md— the livehud.*numbers, the refs-mode clean-vs-dirty pair, the GUID/.metaidentity model.references/layout-geometry-escape-hatch.md— the Play-mode escape hatch, batched and serial.
Related skills
Section titled “Related skills”t1k:unity:base:addressables— Addressables API usage (Load/Release); this skill checks whether the address exists at all, not how to load it.t1k:unity:base:asset-import— the_Incoming/promotion pipeline, a different workflow.t1k:unity:ui:hud-layout— HUD authoring; consult when a finding is a zone-structure problem rather than a missing asset.rules/game-asset-slot-handoff-unity.md— the GUID-is-identity modelrefsmode is built on.
Security
Section titled “Security”Read-only. Never writes inside the project except a validated --json-out path. No Editor verb, no
network, no mutation — exactly what makes it safe to fan out across concurrent agents.