Skip to content

t1k:unity:dots-core:ecs

FieldValue
Moduledots-core
Version3.56.1
Effortmedium
Tools—

Keywords: archetype, auto-destroy, component, cooldown, cooldown timer, CooldownTickHelper, CooldownTimer, csv, DeadTagLifetimeSystem, despawn, DeterministicRandom, dirty, dirty flag, DirtyTag, DOTS, ECS, editor utilities, entity component system, event cleanup, EventCleanupHelper, flat index, grid math, GridMath, ICooldownState, IEnableableComponent signal, lifetime, Lifetime, LifetimeSystem, one-frame event, respawn, respawn reset, RespawnResetHelper, seed guard, SelectNearestTargetSystem, shared primitives, stat ratio, StatMath, system, target selection, TargetEntity, targeting, TargetSelection, TargetSelectionMode, TargetSelector, team, team affiliation, TeamId, timer, unit prefab, weighted sampling, WeightedSampler

/t1k:unity:dots-core:ecs

Contribute back on bug-fix: when this session resolved a non-obvious DOTS gotcha (silent IJobEntity skip, query dedupe, structural-change invalidation, baking order, etc.) that future sessions would benefit from, emit a marker BEFORE your final summary so the lesson reaches the kit: [t1k:lesson kit="theonekit-unity" skill="dots-core:ecs" fragment="references/<file>.md" reason="<one-line>"] The lesson-collector.cjs Stop hook captures it; a background /t1k:sync-back sub-agent files the PR on origin. See skills/t1k-watzup/references/telemetry.md (theonekit-core) for the full pipeline. (The auto-lesson-from-skill-edit.cjs PostToolUse hook in theonekit-core v1.16+ does this automatically when the same session edits a gotchas reference file — but emitting the marker yourself is still the canonical path when the fix lives in code only.)

  • DOTS — Data-Oriented Technology Stack
  • ECS — Entity Component System
  • ECB — EntityCommandBuffer

Engine-neutral definitions (entity, component, system, world, archetype, query, command buffer): t1k-gamedev-ecs-design § core-model.md.

Reference for Unity Entities 1.4.x patterns. Covers the full authoring-to-runtime pipeline: baking GameObjects into entities, defining components, writing Burst-compiled systems, querying entities, and performing structural changes safely.

IAspect is deprecated in Entities 1.4+ (will be removed in a future release) — prefer direct SystemAPI.Query usage.

Related skills: t1k-unity-dots-core-jobs-burst (Jobs, Burst, Collections, Math) · t1k-unity-dots-combat-physics (Physics) · t1k-unity-dots-rendering-graphics (Rendering).


  • Writing IComponentData, ICleanupComponentData, IEnableableComponent, ISharedComponentData, IBufferElementData
  • Implementing ISystem or SystemBase systems
  • Using SystemAPI.Query, SystemAPI.GetComponent, SystemAPI.GetSingleton
  • Creating Baker(T) authoring components or baking systems
  • Using EntityCommandBuffer, EntityManager, EntityQuery
  • Writing IJobEntity jobs with ECS
  • Setting up LocalTransform, parent/child hierarchies
  • Configuring system ordering, update groups, custom worlds

Before searching this skill by hand, check the generated library-primitive-index.md (at Packages/unity-dots-library/library-primitive-index.md in a consumer project — this file is generated at build time and never ships in this kit repo) — a source-derived component/system inventory of Packages/unity-dots-library/com.the1studio.dots-*/Runtime/ that can’t drift the way a hand-maintained table can. It doesn’t replace the reference files below (it’s a flat index, not a guide), but it’s the fastest way to check “does a primitive for this already exist” before writing a new one.

TaskReference File
IComponentData, tags, ICleanupComponentData, IEnableableComponentcomponents-guide.md (references/components-guide.md)
ISharedComponentData, Chunk Components, DynamicBufferbuffers-shared-guide.md (references/buffers-shared-guide.md)
ISystem, SystemBase, SystemAPI.Querysystems-guide.md (references/systems-guide.md)
EntityQuery builder, system ordering, update groupsquery-ordering-guide.md (references/query-ordering-guide.md)
Worlds, bootstrap, custom worlds, IAspect (deprecated)worlds-aspect-guide.md (references/worlds-aspect-guide.md)
EntityManager, EntityCommandBuffer, structural changes, ECB parallel writerentities-ecb-guide.md (references/entities-ecb-guide.md)
Baker, authoring MonoBehaviour, subscenes, baking systems, blob assets in bakerbaking-guide.md (references/baking-guide.md)
LocalTransform, parent/child hierarchy, TransformUsageFlagstransforms-guide.md (references/transforms-guide.md)
IJobEntity scheduling, parallel writer, query filteringjobs-guide.md (references/jobs-guide.md)
Advanced system patterns, system state, singleton patternssystems-advanced-guide.md (references/systems-advanced-guide.md)
IEnableableComponent pattern, LINQ policy, performance prioritypatterns-guide.md (references/patterns-guide.md)
Editor utils: UnitArchetypeConfig, UnitAttackType, UnitPrefabUtility, CsvReadereditor-utilities-guide.md (references/editor-utilities-guide.md)
EventCleanupHelper — generic ClearBuffer / DisableEnableable for one-frame eventsevent-cleanup-helper-guide.md (references/event-cleanup-helper-guide.md)
CooldownTimer / CooldownTimerSystem / ICooldownState — countdown timer patterncooldown-timer-guide.md (references/cooldown-timer-guide.md)
Lifetime / LifetimeSystem / DeadTagLifetimeSystem — auto-destroy countdown + dead-entity bridgelifetime-guide.md (references/lifetime-guide.md)
TargetEntity / TargetSelector / SelectNearestTargetSystem / PickLowestHp / PickHighestThreat — generic target selectiontargeting-guide.md (references/targeting-guide.md)
RespawnResetHelper — standard respawn-ready query builderrespawn-reset-helper-guide.md (references/respawn-reset-helper-guide.md)
DirtyTag — generic enableable dirty/recalculate signal (replaces StatsDirtyTag etc.)dirty-tag-guide.md (references/dirty-tag-guide.md)
TeamId — canonical team affiliation component (SSOT)team-id-guide.md (references/team-id-guide.md)
Shared Burst primitives — GridMath, StatMath.Ratio, WeightedSampler, CooldownTickHelper, DeterministicRandom (dots-core SSOT)shared-burst-primitives.md (references/shared-burst-primitives.md)

Anti-Patterns for Cross-Project Reusability

Section titled “Anti-Patterns for Cross-Project Reusability”

Engine-neutral rows (god component, factory switch, god orchestrator, cross-module enum, mixed constants, boolean config, monolithic respawn) live in t1k-gamedev-ecs-design § anti-patterns-and-when-not-to-use.md. Unity rows:

Anti-PatternSymptomFix
Embedded componentComponent defined inside system fileOne type per file, in Components/ folder
Visual transform feedback loopPresentationSystemGroup modifies Position each frame → simulation reads modified value next frame → positions collapse exponentiallySave/restore pattern: store canonical value in dedicated component (e.g., SideViewGameZ) → restore at SimulationSystemGroup OrderFirst → simulate on canonical data → remap in PresentationSystemGroup

See: atomicity-guide.md (../t1k-unity-dots-core-architecture/references/atomicity-guide.md) for full audit checklist.

→ See references/patterns-guide.md for IEnableableComponent pattern, LINQ policy, and performance priority rules.

Namespace layout convention:

  • [YourProject] — root
  • [YourProject].Components — IComponentData structs
  • [YourProject].Systems — ISystem structs
  • [YourProject].Authoring — MonoBehaviour + Baker(T)
  • [YourProject].Jobs — IJobEntity structs
  • [YourProject].Physics — physics components and systems
  • [YourProject].Rendering — rendering components and material overrides

Package versions:

  • com.unity.burst 1.8.28
  • com.unity.mathematics 1.3.2
  • com.unity.entities, com.unity.entities.graphics, com.unity.physics, com.unity.collections — do not pin. Since Unity 6000.5 these are builtin packages at the editor’s own version; the registry’s 1.x line is the abandoned legacy branch, and pinning it downgrades a 6.5.0 install.

Critical rules:

  • To use Burst on an ISystem, mark both the struct and each method [BurstCompile], and make the struct partial
  • To defer structural changes inside a job, use EntityCommandBuffer.ParallelWriter with [ChunkIndexInQuery] sort key
  • To enable/disable a component without archetype moves, implement both IComponentData and IEnableableComponent
  • NEVER use GetSingletonEntity<T>(), HasSingleton<T>(), or TryGetSingletonEntity<T>() on IEnableableComponent types — throws InvalidOperationException. Use SystemAPI.Query<RefRW<T>>().WithPresent<T>().WithEntityAccess() instead
  • To bake a moving entity, pass TransformUsageFlags.Dynamic to GetEntity() in the Baker
  • To build large read-only shared data, use BlobAsset and register via baker.AddBlobAsset()
  • To detect entity destruction, use ICleanupComponentData — it survives DestroyEntity until explicitly removed

→ See references/hard-rules-structural.md for stale cache after type changes, SetComponentEnabled structural change gotcha, two-pass pattern, the default (uninitialized) EntityQuery NRE (guard .IsEmpty/.CalculateEntityCount() with query.IsCreated), and Entity.Index recycling (never use as a creation-order or identity proxy — compare whole Entity values, or stamp a timestamp component).

Three patterns for one-frame inter-system events:

  • IEnableableComponent (*Event/*DirtyTag) — stateless signals, no payload. Cleanup system disables via IJobEntity at OrderFirst.
  • DynamicBuffer per-entity (*Event : IBufferElementData) — payloaded events scoped to one entity. Consumer or cleanup system calls buffer.Clear().
  • DynamicBuffer singleton (EntityEvent) — global cross-system queue with EntityEventType discriminator. Cleared by CoreEventCleanupSystem.

Cross-assembly gotcha: IJobEntity in a cleanup system MUST live in the same assembly as the event component type. Cross-assembly job definitions cause Burst source generation job safety errors.

→ Engine-neutral patterns (one-frame signal, per-entity buffer, global queue): t1k-gamedev-ecs-design § events-and-communication.md.

→ Full patterns, checklist, and cleanup system map: event-conventions.md (../t1k-unity-dots-combat-rpg/references/event-conventions.md)

Since unity-dots-library v2.0.0 (2026-05-23) all prefab fields in library bakers + demo authoring use AssetReferenceGameObject, not raw GameObject. The bake helper is AssetReferenceBakerExtensions.BakeAssetReference(...) (SSOT in com.the1studio.dots-core).

  • Runtime-asmdef bans (enforced by AddressablesEnforcementTests): no Resources.Load(, no AssetDatabase.LoadAssetAtPath, no Object.Instantiate(GameObject) outside the per-project allowlist. ECS-side EntityManager.Instantiate(Entity) and ecb.Instantiate(Entity) are fine — different overload, different target.
  • In a Baker, never call GetEntity(prefab) directly on an AssetReferenceGameObject. Use the helper — it handles the weak-reference indirection and produces a baked Entity reference for runtime spawning.

→ See addressables-pattern.md (../t1k-unity-dots-core-architecture/references/addressables-pattern.md) for the full authoring → baker → runtime flow.

Best Practices Audit Checklist (W4.4) + H4 Hardening

Section titled “Best Practices Audit Checklist (W4.4) + H4 Hardening”

Every ISystem must satisfy the merge checklist (Burst on struct + lifecycle methods, RMQFU on guard-less systems except one that only delegates to a static query-building helper — that deadlocks, no structural changes in OnUpdate loops, cached lookups, [ChunkIndexInQuery] sort keys) plus the H4 hardening patterns for hot paths (buffer capacity caps, O(n²)→hash-lookup, job-dependency chaining discipline, NaN/overflow guards, EnabledRefRW<T> over SetComponentEnabled). Full checklist + W4 baseline stats + H4 patterns: references/h4-hardening-patterns.md (also links to the 38-pattern references/best-practices.md).

→ IEnableableComponent vs. DisabledTag decision guide: references/ienableable-vs-disabledtag.md → ComponentLookup/BufferLookup caching patterns: references/component-lookup-caching.md → ECB system selection, parallel writer, sort key gotchas: references/ecb-patterns.md → BlobAssetReference construction, baker registration, runtime lifetime: references/blob-assets.md → ISharedComponentData partitioning, uniqueness ceiling, chunk fragmentation: references/shared-components.md → SystemState vs. SystemAPI access pattern decision guide: references/system-state-vs-systemapi.md → Burst + source-gen gotchas — BC1028, OnCreate no-op, missing [BurstCompile] clusters, SGFE011 (open-generic DynamicBuffer in SystemAPI.Query), BC1063 (bool in IComponentData), BC1016 (new FixedStringNBytes(string) vs literal assignment): references/hard-rules-burst.md

  • The stat dirty flag is the canonical DOTSCore.DirtyTag — StatsDirtyTag is now [Obsolete]. DOTSCore.DirtyTag (the generic enableable “data changed, recalculate” flag) is the SSOT; DOTSCore.StatsDirtyTag is a separate, back-compat-only ECS type scheduled for removal — new code MUST use DirtyTag. Both live at Core/Components/{DirtyTag,StatsDirtyTag}.cs and declare namespace DOTSCore (NOT DOTSCore.Stats) — writing using DOTSCore.Stats; then referencing either gives CS0246 even though Level/Experience/BaseStats ARE under DOTSCore.Stats; add using DOTSCore;. SSOT producer-completeness: the recompute chain is correct only when the baker, the consumer (DerivedStatsSystem, which recomputes but does NOT itself disable the flag), the clear system (DirtyTagClearSystem, OrderLast — disables the flag, and only after a successful recalc), AND every producer set/read the SAME DOTSCore.DirtyTag — combat (PartyBuffSystem/SynergyResolutionSystem/DamageBucketAggregationSystem/StageCurveSystem/TalentUnlockSystem), inventory (EquipmentSystem/ItemSetBonusSystem/PassiveEffectSystem), and core LoadSystem (restored state must re-trigger derivation). A producer that forgets to raise DirtyTag is a silent stat-miss: the change persists but the recompute never runs. Because DOTS archetypes are type-keyed, a per-package dirty type is invisible to the shared consumer — that drift is exactly what the single DirtyTag prevents.

  • Colour contract: SpriteColor.Value and OriginalSpriteColor.Value are ALWAYS LINEAR. Every tint/palette constant is stored linear; anything crossing in from authored sRGB converts exactly once, at the authoring boundary, via ColorSpaceUtility.GammaToLinear / SpriteColor.FromGamma. Symptom of getting it wrong: the ECS data reads exactly to spec while the pixel renders wrong — a water tile authored blue rendered grey-green. State-side verification cannot see it (see t1k-unity-testing-workflow § “Verify on the OUTPUT side”).

    The seam is the colour’s SPACE, not its construction site — and this is the part that bites. SpriteColor is IComponentData { public float4 Value; }, a bare public mutable field, because ECS ref/RefRW mutation requires it — readonly + constructor-only would break every per-frame system that blends a tint inside a Burst job. So a FromGamma/FromLinear factory is a strong convention, not an enforced contract: it cannot stop a system holding a ref from assigning .Value directly, and two systems legitimately do exactly that every frame.

    Consequence: grep "new SpriteColor" is necessary but NOT sufficient. It misses every site that math.lerps an existing .Value against a second raw constant — and converting only at construction would make those sites newly wrong, blending a now-correctly-linear value against a still-gamma operand. The conversion must live at two layers: (a) the construction factory, and (b) every constant table that can ever be a blend operand, converted at its own definition. Fixing only (a) looks complete — every construction site has the factory — while silently breaking the blend sites.

    Correct-by-inheritance sites carry a comment for a reason. Four call sites needed zero change because they read a constant that is now already linear. They are commented explicitly so a later reader does not “fix” them into a double-convert. Do not remove those comments.

    Constants feeding [BurstCompile] consumers are pinned literals with derivation tests, not computed at static-init — see t1k-unity-dots-core-jobs-burst § “Burst restricts statics”. Shipped in The1Studio/unity-dots-library#72.

  • Generic persistence (H2): SaveSystem/LoadSystem reference ZERO game modules. Serialization is driven by ISnapshotSerializer registered into SnapshotSerializerRegistry; each module self-registers via [RuntimeInitializeOnLoadMethod(SubsystemRegistration)]. To add save support for a new component, implement ISnapshotSerializer in the OWNING module (not in core) and register it — do NOT edit SaveSystem/LoadSystem. Full pattern: t1k-unity-dots-core-architecture/references/generic-persistence.md (../t1k-unity-dots-core-architecture/references/generic-persistence.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