Skip to content

t1k:unity:architecture:assembly-graph

FieldValue
Modulearchitecture
Version3.37.4
Effortmedium
Tools—

Keywords: architecture, asmdef, assembly-graph, c4 architecture view, class-diagram, cs2mermaid, dots, packages, roslyn, scriptableobject, upm package graph

/t1k:unity:architecture:assembly-graph

Unity diagram adapter for the T1K diagram toolchain. Produces four diagram types from Unity project sources:

  1. modules — Assembly-to-assembly reference graph from .asmdef files (no external tools required)
  2. classes — Per-assembly Roslyn class diagrams with Unity stereotypes via Cs2Mermaid
  3. packages — UPM dependency graph from Packages/manifest.json
  4. c4 — C4 architecture view inferred from asmdef prefix groupings

Install the full Unity toolchain:

t1k diagram install --preset unity

Or install cs2mermaid only (if mermaid-cli already present):

t1k diagram install cs2mermaid

The modules, packages, and c4 capabilities work without cs2mermaid. Only classes requires .NET 8 SDK + Cs2Mermaid.

Terminal window
# Auto-detect and generate all diagrams
t1k diagram refresh
# Generate specific type
bun scripts/generate.cjs --type modules --out-dir /tmp/out
bun scripts/generate.cjs --type classes --out-dir /tmp/out
bun scripts/generate.cjs --type packages --out-dir /tmp/out
bun scripts/generate.cjs --type c4 --out-dir /tmp/out
# Check if this adapter applies to a Unity project. Detection is scoped to
# Assets/ and Packages/ so bundled .claude fixtures cannot cause a false match.
bun scripts/detect.cjs [--project-root /path/to/unity-project] # exit 0 = match
# List available capabilities
bun scripts/list-capabilities.cjs
# Show tool requirements
bun scripts/requirements.cjs
CapabilityOutput
modulesmodules.md — Mermaid graph LR of assembly dependencies
classesclasses.md (index) + classes-{asmdef}.md per assembly
packagespackages.md — UPM dependency graph
c4architecture.md — C4 container/component view

See references/unity-stereotypes.md for the full detection rules. Key annotations:

  • MonoBehaviour / ScriptableObject — inheritance-based
  • {serialized} — fields with [SerializeField]
  • ..> requires — [RequireComponent(typeof(X))] edges
  • IComponentData / ISystem / IAspect — DOTS interfaces
  • {asset} — [CreateAssetMenu] classes
  • Roslyn syntactic analysis (no cross-file type resolution for ~30% of signatures)
  • Generated .cs files excluded by default — use —include-generated to include
  • GameObject hierarchies and scene references are runtime-only and cannot be represented from C# source
  • Semantic (DLL-based) class analysis is deferred to v2 (dll2mmd path)
  • Any hand-rolled asmdef-name index must include FOUR roots, not two. Omitting either of the last two manufactures false “dangling reference” reports in bulk: Assets/ · Packages/ · Library/PackageCache/ · <UnityEditor>/Data/Resources/PackageManager/BuiltInPackages/ (~250 asmdefs — com.unity.entities, com.unity.collections, com.unity.entities.graphics and friends ship inside the editor install on Unity 6, not in the project). Measured impact of omitting that root alone: 208 reported dangling refs → 45 real ones. Two further false-positive classes to filter before reporting: assemblies shipped as precompiled DLLs never appear in an asmdef-name index at all (index *.dll basenames alongside asmdef names), and GUID:-form references resolve through .asmdef.meta files rather than by name. Also skip dangling refs originating inside Library/PackageCache/ — those are upstream packages’ problems, not the project’s, and they drown out the ones you can act on.
  • modules.md (the modules capability’s output, above) is a persisted asmdef-name index — and nothing reads it back today. Every assembly this skill resolved is already a node in that Mermaid graph, generated fresh each run against the same four roots this section documents. docs/reuse-search-record.md’s pass registry declares an index pass, but that pass reads library-primitive-index.md (a curated DOTS-library artifact) — a DIFFERENT file — not modules.md; neither t1k-unity-base-brainstormer.md nor t1k-unity-base-developer.md’s reuse-search: step consults modules.md at all. Regenerating the four-root asmdef list on every reuse-search sweep when a same-day modules.md already exists is the same shape of waste as re-exporting an unread artifact — flagged here as a finding, not built: wiring modules.md into the pass registry is a behavior change for a future PR, not this one.

⚠️ A dangling asmdef reference is NOT fatal in Unity 6

Section titled “⚠️ A dangling asmdef reference is NOT fatal in Unity 6”

Do not treat “assembly X references missing assembly Y” as a build blocker. Unity 6 drops an unresolvable references entry with a warning and compiles the assembly anyway.

Verified 2026-08-12 by direct comparison of two projects on the same machine: a working project carried 74 asmdefs referencing a UITemplate.Scripts assembly that exists nowhere in its tree, and still built 974 assemblies, 642 of them in exactly the subtree holding those dangling references. A second project with the same dangling references failed to build — for an unrelated reason.

This matters because the opposite belief is expensive and self-confirming. A post-submodule-bump audit surfaces a long list of missing assemblies; if you assume they’re fatal, that list looks like the root cause, and you can spend an entire session “fixing” version skew that was never blocking anything. Diagnose the actual compile errors instead.

Correct triage order when a project won’t build:

  1. Read the real errors, scoped to the last compile pass (see t1k-unity-editor-cli). Dangling-reference warnings are not among them.
  2. Separate cascade from cause. A wave of CS0246 "type or namespace X could not be found" usually means assembly X itself never emitted. Check whether errors originate inside X’s own package — if zero do, X is a victim, not the cause. Chase why X produced no DLL.
  3. Check whether the DLL exists at all, not just in Library/ScriptAssemblies/ but anywhere under Library/ (Bee writes Library/Bee/artifacts/**/<name>.dll and a post-processed/ copy). Absent from both means Unity never attempted it — a graph/registration problem, categorically different from a compile failure.
  4. Only then look at version skew.

Corollary: an empty assembly shipped purely to satisfy a dangling reference (a “compat shim” asmdef) is usually unnecessary. Unity would have compiled without it. Confirm the reference is genuinely load-bearing before adding one — and note that a script-less asmdef emits no DLL at all, so a shim needs at least one real source file to produce anything.

Diffing against a known-good sibling project

Section titled “Diffing against a known-good sibling project”

The fastest way to resolve “why does this project fail when the other one works” is a direct diff against a project on the same machine that currently builds — it is empirical, where deriving a good version set from changelogs is guesswork.

Compare, in rough order of yield: Packages/manifest.json dependency versions · Packages/packages-lock.json resolved versions (catches transitive pins the manifest doesn’t show) · submodule SHAs (git submodule status) · Unity editor version — a working reference on a different patch release is not authoritative, since deprecations land between patches and can account for an entire class of CS0619 obsolete errors on their own.

Watch for version islands: a package pinned to an old major while its declared siblings sit several majors ahead. Read the dependency block of the stale package and compare it against what’s actually installed — e.g. a package declaring foo: 1.1.0 while foo@5.4.1 is installed, which is also how assemblies get “renamed out of existence” (a .DI suffix in a 1.x line becoming .VContainer in 5.x).

Caveat learned the hard way: matching a working project’s pins does not guarantee a fix. Verify by re-measuring the error count, and be prepared for it to go up.

Generating the diagrams is mechanical: the scripts/generate.cjs / detect.cjs runs and reading the emitted Mermaid files carry no judgment, so a cheap-tier agent runs them (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
Run detect.cjs / generate.cjs and report the output filest1k-fact-fetcher
Count assemblies, edges and packages from the generated grapht1k-metrics-reporter
Decide whether a dangling or cyclic reference is a real defectreasoning tier — t1k-debugger; a cause is not a verdict
FileContent
references/unity-stereotypes.mdDetection rules + regex patterns for Unity annotations
references/asmdef-guid-resolution.mdHow GUID: refs are resolved via .asmdef.meta files
references/asmdef-reference-resolution.mdWhy a linked asmdef still fails — overrideReferences/precompiledReferences, precompiled DLL vs asmdef, CS0246/CS0122/CS1061 triage
references/cs2mermaid-integration.mdCs2Mermaid wrapper design, security review, fallback