Skip to content

t1k:unity:dots-core:architecture

FieldValue
Moduledots-core
Version3.56.1
Efforthigh
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

/t1k:unity:dots-core:architecture

DOTS Architecture — Component & System Design

Section titled “DOTS Architecture — Component & System Design”

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)

  • 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

See t1k-gamedev-ecs-design § component-design.md (engine-neutral, theonekit-gamedev:ecs)

See t1k-gamedev-ecs-design § system-design.md; the Unity job decision and bridge example: system-decisions.md (references/system-decisions.md)

See t1k-gamedev-ecs-design § solid-for-ecs.md (engine-neutral, theonekit-gamedev:ecs)

See reusability-checklist.md (references/reusability-checklist.md)

See atomicity-guide.md (references/atomicity-guide.md)

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.

TierWhenEntity CountBurst?Example
1: Pure DOTSPer-entity gameplay10-10KYesCombat, Nav, AI, Stats, Spawning
2: DOTS Data + MB BridgeSingleton → managed API1NoCamera (Cinemachine), Audio, VFX, UI bindings
3: Pure MonoBehaviourNo ECS data0NoScene 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.

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:

  1. Config > Constants — tuning values belong in component data, not GameplayConstants
  2. Buffer priority — when filling fixed-capacity buffers, always prioritize important entries

When building systems that need to work in both 2D and 3D:

ApproachVerdictWhy
Position2D componentWRONGDuplicates Position, forces system branching
#if DOTS_2DWRONGForks library, doubles maintenance
ISystem<T2D, T3D> genericsWRONGOver-engineering, Burst unfriendly
float3 everywhere (z=0 for 2D)CORRECTAll math works identically; no branching
Conditional via dataCORRECTSystems auto-skip via [RequireMatchingQueriesForUpdate]
Enum fields for shape variantsCORRECTAoEShape.Circle/Cone/Line — single system handles all
Bool flags for behaviorCORRECTParabolicArc.IsFlat — linear vs parabolic in one system

Key pattern: Configuration authoring sets different data -> same systems produce different behavior.

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

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-PatternFix
Demo tuning values in GameplayConstantsMove to per-entity component config
Filling buffer without priority orderingAlways prioritize important entries (enemies > allies)
Main-thread SystemAPI.Get* in nested loopsJobify with ComponentLookup<T>
SystemBase for any new systemUse ISystem struct — 5x faster, full Burst support
Missing [BurstCompile] on system methodsSilent Mono fallback — 10-100x slower
Managed calls in [BurstCompile] codeSilent ISystem failure — system never registers, no error
Speed zone writing to MoveSpeed.ValueSpeed 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 packagesNEVER 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 implementationALWAYS 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 consumersRun 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 consumersIf 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).

  • 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 runtime AssetReferenceGameObject — pick the right tier. Both produce an Entity you can Instantiate, 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 bakes DirtyTag enabled (first-frame pass), the consumer (DerivedStatsSystem) recomputes it — the disable is a separate OrderLast clear system, DirtyTagClearSystem, which disables it only after a successful recalc, NOT DerivedStatsSystem itself — and EVERY producer that mutates the watched data raises the SAME DirtyTag (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.

→ 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

  • 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