t1k:unity:dots-core:architecture
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | high |
| Tools | — |
Keywords: architecture, async file IO, camera pan, design patterns, DOTS, ECS, frozen snapshot registry, gesture, GestureCameraController, GestureInputSource, GestureRecognizer, ISnapshotSerializer, meta GUID preservation, MonoBehaviour move, MovedFrom, pinch zoom, tier 3
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:architectureDOTS Architecture — Component & System Design
Section titled “DOTS Architecture — Component & System Design”Skill Purpose
Section titled “Skill Purpose”Decision framework for Unity DOTS ECS architectural choices. Guides DOTS vs MonoBehaviour tier selection, component/system creation, SOLID principles for ECS, and anti-patterns that hurt reusability.
Library scope: gameplay mechanics ONLY. The DOTS library handles combat, AI, navigation, inventory, progression, puzzles, and game flow — pure gameplay data and logic. Rendering, UI, audio, and platform-specific code do NOT belong in DOTS packages. Use MonoBehaviour/UI Toolkit (Tier 2/3) for non-gameplay concerns — they are better suited and avoid unnecessary DOTS complexity.
Related skills:
t1k-unity-dots-core-ecs(API reference) ·t1k-unity-dots-combat-rpg(domain components) ·t1k-unity-dots-core-jobs-burst(performance) ·t1k-unity-dots-core-performance(profiling, chunk efficiency, parallelism)
When This Skill Triggers
Section titled “When This Skill Triggers”- Deciding whether to create a new component or extend an existing one
- Deciding whether to create a new system or add logic to an existing one
- Reviewing component granularity (too fat? too thin?)
- Reviewing system responsibility (doing too much?)
- Planning module boundaries for a reusable DOTS package
- Refactoring ECS code for reusability across projects
- Checking for demo-specific logic in reusable packages
Quick Decision Trees
Section titled “Quick Decision Trees”Create vs Update Component?
Section titled “Create vs Update Component?”See t1k-gamedev-ecs-design § component-design.md (engine-neutral, theonekit-gamedev:ecs)
Create vs Update System?
Section titled “Create vs Update System?”See t1k-gamedev-ecs-design § system-design.md; the Unity job decision and bridge example: system-decisions.md (references/system-decisions.md)
SOLID for ECS
Section titled “SOLID for ECS”See t1k-gamedev-ecs-design § solid-for-ecs.md (engine-neutral, theonekit-gamedev:ecs)
Reusability Checklist
Section titled “Reusability Checklist”See reusability-checklist.md (references/reusability-checklist.md)
Atomicity Audit
Section titled “Atomicity Audit”See atomicity-guide.md (references/atomicity-guide.md)
Refactor / Rename a Library Symbol
Section titled “Refactor / Rename a Library Symbol”See refactor-rename-checklist.md (references/refactor-rename-checklist.md)
Addressables-First Pattern (library v2.0.0+)
Section titled “Addressables-First Pattern (library v2.0.0+)”See addressables-pattern.md (references/addressables-pattern.md) — AssetReferenceGameObject authoring → AssetReferenceBakerExtensions.BakeAssetReference → runtime Entity prefab. Enforcement test bans Resources.Load( / AssetDatabase.LoadAssetAtPath / non-ECS Object.Instantiate(GameObject) in Runtime asmdefs. Consumer projects MUST ship AddressablesBuildPlayerProcessor + AddressablesEnforcement.Allowlist.
Generic Persistence — ISnapshotSerializer + Self-Registering Modules (H2)
Section titled “Generic Persistence — ISnapshotSerializer + Self-Registering Modules (H2)”See generic-persistence.md (references/generic-persistence.md) — DOTSCore.Persistence references ZERO game modules. Each module ships a *SaveSerializers : ISnapshotSerializer and self-registers it via [RuntimeInitializeOnLoadMethod(SubsystemRegistration)] into SnapshotSerializerRegistry (Stats=core, Combat/Economy/Inventory/Progression in their own packages). SaveSystem/LoadSystem iterate the frozen GetSnapshot() array, never the live list. This inverts the former core→module dependency back to module→core. Async file I/O: snapshot on main thread → Task.Run write; resolve Application.persistentDataPath BEFORE Task.Run. Reference covers the interface contract, SkipRead byte-count invariant, binary format, and the RegisterForTests() Test-Runner pattern.
3-Tier Architecture (DOTS vs MonoBehaviour)
Section titled “3-Tier Architecture (DOTS vs MonoBehaviour)”See dots-vs-mono-tiers.md (references/dots-vs-mono-tiers.md) for full decision framework.
| Tier | When | Entity Count | Burst? | Example |
|---|---|---|---|---|
| 1: Pure DOTS | Per-entity gameplay | 10-10K | Yes | Combat, Nav, AI, Stats, Spawning |
| 2: DOTS Data + MB Bridge | Singleton → managed API | 1 | No | Camera (Cinemachine), Audio, VFX, UI bindings |
| 3: Pure MonoBehaviour | No ECS data | 0 | No | Scene loading, Save/Load, Localization |
Quick rule: 10+ entities → Tier 1. Singleton + managed API → Tier 2. No ECS → Tier 3.
Bridge Helpers — Use These for ALL ECS-Reading MonoBehaviours
Section titled “Bridge Helpers — Use These for ALL ECS-Reading MonoBehaviours”ECSMonoBehaviourBase is the canonical base class for any runtime MonoBehaviour that reads ECS singletons — not just UI. Audit (2026-04-26) found the World.DefaultGameObjectInjectionWorld != null && IsCreated guard duplicated in 28 demo files (input handlers, camera controllers, bootstraps). All should inherit ECSMonoBehaviourBase and override OnECSUpdate(EntityManager em) instead of re-implementing the world-ready guard.
Sibling helper: SubsceneBypassBootstrap<TLevelData> — for JSON-driven config bootstraps that need to skip SubScene baking. Override OnConfigure(EntityManager em, TLevelData data); base class handles JSON parse + world-readiness guard.
Rule: any non-DOTS MonoBehaviour reading ECS state in Update() / LateUpdate() MUST inherit one of these two helpers. No raw World.DefaultGameObjectInjectionWorld checks in new code.
Key Principles
Section titled “Key Principles”Engine-neutral principles (data in components and logic in systems, one system one job, tag over enum dispatch, bridge pattern for external dependencies, atomicity) live in t1k-gamedev-ecs-design § core-model.md, § system-design.md and § atomicity.md. The library’s named atomicity exceptions and violation record: atomicity-guide.md (references/atomicity-guide.md). The Unity-flavoured remainder:
- Config > Constants — tuning values belong in component data, not
GameplayConstants - Buffer priority — when filling fixed-capacity buffers, always prioritize important entries
Dimension-Agnostic Design
Section titled “Dimension-Agnostic Design”When building systems that need to work in both 2D and 3D:
| Approach | Verdict | Why |
|---|---|---|
Position2D component | WRONG | Duplicates Position, forces system branching |
#if DOTS_2D | WRONG | Forks library, doubles maintenance |
ISystem<T2D, T3D> generics | WRONG | Over-engineering, Burst unfriendly |
| float3 everywhere (z=0 for 2D) | CORRECT | All math works identically; no branching |
| Conditional via data | CORRECT | Systems auto-skip via [RequireMatchingQueriesForUpdate] |
| Enum fields for shape variants | CORRECT | AoEShape.Circle/Cone/Line — single system handles all |
| Bool flags for behavior | CORRECT | ParabolicArc.IsFlat — linear vs parabolic in one system |
Key pattern: Configuration authoring sets different data -> same systems produce different behavior.
Performance Architecture
Section titled “Performance Architecture”-> See t1k-unity-dots-core-performance skill for chunk efficiency calculator, system parallelism rules, and profiling workflows.
Key performance principles for architectural decisions:
- Smaller components = more entities per 16KB chunk = better cache
- IEnableableComponent over add/remove for frequently changing state (no archetype move)
- ISystem + [BurstCompile] always — never SystemBase for new code (5x faster)
- ScheduleParallel for >100 entities, SystemAPI.Query for <100, Run for <10
- Split systems when they process 2+ independent data sets (enables parallelism)
Anti-Patterns (Never Do)
Section titled “Anti-Patterns (Never Do)”Engine-neutral rows (enum branching, god component, mixed-concern systems, too many namespaces) live in t1k-gamedev-ecs-design § anti-patterns-and-when-not-to-use.md. Unity rows:
| Anti-Pattern | Fix |
|---|---|
Demo tuning values in GameplayConstants | Move to per-entity component config |
| Filling buffer without priority ordering | Always prioritize important entries (enemies > allies) |
Main-thread SystemAPI.Get* in nested loops | Jobify with ComponentLookup<T> |
SystemBase for any new system | Use ISystem struct — 5x faster, full Burst support |
Missing [BurstCompile] on system methods | Silent Mono fallback — 10-100x slower |
Managed calls in [BurstCompile] code | Silent ISystem failure — system never registers, no error |
Speed zone writing to MoveSpeed.Value | Speed zones are transient — store multiplier in WaypointFollower.SpeedMultiplier, apply locally. Mutating the canonical stat component corrupts StatSyncSystem’s derived pipeline |
| Duplicating utility loops (FindWalletIndex, FindDefinition) | Extract to static [BurstCompile] utility class in {Domain}/Utilities/ folder. Pattern: CurrencyWalletUtility, QuestUtility, AIHelpers |
| Game-specific OR over-specific instance names in library packages | NEVER use game/demo names (ColorFit, BackpackCrawler) in Packages/ code. Beyond demo names, also name the generic ROLE, not a concrete instance: ProjectileRegistryTag not ArrowRegistryTag (when a generic ProjectileData/ProjectileCollisionSystem already exists, Arrow is an inconsistent island); QueuePuzzle not ColorFitGameState. Mage/Knight/Sword/Arrow belong in enum values or demo content, never in a type name. Ask: “Would this name make sense in a different game?” See library-quality-mandate-unity.md § “Naming charter” (SSOT). |
| Skipping Play mode validation after implementation | ALWAYS run Play mode test (t1k unity play enter, or t1k-unity-dots-core-validator) after implementing new systems. EditMode tests only verify logic — Play mode catches baking failures, SubScene issues, system ordering bugs, and rendering problems |
| Renaming/deleting a public library symbol without grepping consumers | Run grep -rn "OldName" Packages/ Assets/Demos/ BEFORE the deletion. Migrate every caller in the SAME commit. See refactor-rename-checklist.md (references/refactor-rename-checklist.md) |
| Moving a Runtime helper to a Tests asmdef without checking Runtime consumers | If consumer Runtime code (e.g. Assets/Demos/**/Runtime/**) extends or references the type, the move breaks the consumer. Check consumers and either keep in Runtime, or migrate the consumer in the same commit |
Foundation asmdef references a mode/genre asmdef (e.g. DOTSCore.UI → DOTSGameModes.Survivor) | Layering inversion — dependencies must flow DOWN only. Route the shared data through the infrastructure layer (dots-bridges) or a foundation-owned event type instead. dots-core → dots-bridges → mode-package is the only clean DAG. See Gotchas → “Package layering”. |
Refactor / Rename a Library Symbol — Pre-Delete Checklist
Section titled “Refactor / Rename a Library Symbol — Pre-Delete Checklist”Before deleting OR renaming OR relocating ANY public type, method, namespace, or asmdef in a consumed DOTS library package: grep both halves of the workspace, migrate every caller in the SAME commit, check asmdef/namespace-continuity constraints, and run t1k unity console --level error before pushing. Full checklist (file moves, partial classes, attribute duplication, asmdef visibility, submodule pointer drift): refactor-rename-checklist.md (references/refactor-rename-checklist.md).
Hard rules
Section titled “Hard rules”-
System update order is set per-world, not per-group — moving a system between groups changes its phase silently if the group’s update order isn’t documented.
-
SystemBase vs ISystem performance differs in Burst — ISystem is fully Burst-compilable; SystemBase has managed glue. Use ISystem when latency matters.
-
EntityCommandBuffer playback at the END of system update — not where it’s recorded — race conditions appear if you assume immediate effect.
-
World destruction order matters — destroying child worlds before parent leaks system instances.
-
Bake-time
GetEntity(prefab)vs runtimeAssetReferenceGameObject— pick the right tier. Both produce anEntityyou canInstantiate, but the failure modes differ sharply — bake-time only works when the prefab is guaranteed present at SubScene-open, loaded once, small, and not swapped/cross-referenced; addressable otherwise.Resources.Load<GameObject>(...)in a Runtime asmdef is a banned silent-failure anti-pattern. Full decision tree + the tells for each tier:references/prefab-loading-tiers.md. -
One canonical dirty flag —
DOTSCore.DirtyTag— is the SSOT for the “data changed, recalculate” signal across ALL packages. Per-package variants (DOTSCore.StatsDirtyTag, etc.) are now[Obsolete]separate ECS types kept for back-compat and scheduled for removal — do NOT introduce new per-package dirty tags. A recompute loop is correct only when the WHOLE chain shares one tag: the baker bakesDirtyTagenabled (first-frame pass), the consumer (DerivedStatsSystem) recomputes it — the disable is a separateOrderLastclear system,DirtyTagClearSystem, which disables it only after a successful recalc, NOTDerivedStatsSystemitself — and EVERY producer that mutates the watched data raises the SAMEDirtyTag(SetComponentEnabled<DirtyTag>(e, true)). Producers span packages: combat (PartyBuffSystem,SynergyResolutionSystem,DamageBucketAggregationSystem,StageCurveSystem,TalentUnlockSystem), inventory (EquipmentSystem,ItemSetBonusSystem,PassiveEffectSystem), core (LoadSystem— restored state must re-trigger derivation). A producer that forgets to raise the flag is a silent stat-miss: the change persists in the buffer but the recompute never runs. Because DOTS archetypes are type-keyed, a separate per-package dirty type is invisible to the shared consumer — that is exactly the drift this SSOT prevents.
Architecture References (W4.5)
Section titled “Architecture References (W4.5)”→ Chunk fill rate and DOTS archetype rules: references/archetype-design.md; storage models and the structural-change cost model: t1k-gamedev-ecs-design § storage-models.md
→ System group hierarchy, UpdateInGroup, ECB system selection: references/system-group-ordering.md
→ Baker patterns: TransformUsageFlags, singletons, buffers, DependsOn: references/baker-patterns.md
→ World bootstrap, VContainer DI bridge, ManagedEventQueue: references/world-bootstrap-di.md
Related rules
Section titled “Related rules”docs/library-feature-discovery-protocol.md— run the corpus-first reuse search before implementing new functionality; always update this skill with what you find (or with the new code if you implement it)rules/kit-wide-fix-discipline.md— if you manually inject library/API knowledge into a teammate brief, that knowledge belongs in this skill, not the brief