t1k:unity:dots-core:ecs
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:ecsUnity DOTS ECS Core
Section titled “Unity DOTS ECS Core”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>"]Thelesson-collector.cjsStop hook captures it; a background/t1k:sync-backsub-agent files the PR on origin. Seeskills/t1k-watzup/references/telemetry.md(theonekit-core) for the full pipeline. (Theauto-lesson-from-skill-edit.cjsPostToolUse hook intheonekit-corev1.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.)
Terminology
Section titled “Terminology”- 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.
Skill Purpose
Section titled “Skill Purpose”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).
When This Skill Triggers
Section titled “When This Skill Triggers”- Writing
IComponentData,ICleanupComponentData,IEnableableComponent,ISharedComponentData,IBufferElementData - Implementing
ISystemorSystemBasesystems - Using
SystemAPI.Query,SystemAPI.GetComponent,SystemAPI.GetSingleton - Creating
Baker(T)authoring components or baking systems - Using
EntityCommandBuffer,EntityManager,EntityQuery - Writing
IJobEntityjobs 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(atPackages/unity-dots-library/library-primitive-index.mdin a consumer project — this file is generated at build time and never ships in this kit repo) — a source-derived component/system inventory ofPackages/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.
Quick Reference
Section titled “Quick Reference”| Task | Reference File |
|---|---|
| IComponentData, tags, ICleanupComponentData, IEnableableComponent | components-guide.md (references/components-guide.md) |
| ISharedComponentData, Chunk Components, DynamicBuffer | buffers-shared-guide.md (references/buffers-shared-guide.md) |
| ISystem, SystemBase, SystemAPI.Query | systems-guide.md (references/systems-guide.md) |
| EntityQuery builder, system ordering, update groups | query-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 writer | entities-ecb-guide.md (references/entities-ecb-guide.md) |
| Baker, authoring MonoBehaviour, subscenes, baking systems, blob assets in baker | baking-guide.md (references/baking-guide.md) |
| LocalTransform, parent/child hierarchy, TransformUsageFlags | transforms-guide.md (references/transforms-guide.md) |
| IJobEntity scheduling, parallel writer, query filtering | jobs-guide.md (references/jobs-guide.md) |
| Advanced system patterns, system state, singleton patterns | systems-advanced-guide.md (references/systems-advanced-guide.md) |
| IEnableableComponent pattern, LINQ policy, performance priority | patterns-guide.md (references/patterns-guide.md) |
| Editor utils: UnitArchetypeConfig, UnitAttackType, UnitPrefabUtility, CsvReader | editor-utilities-guide.md (references/editor-utilities-guide.md) |
| EventCleanupHelper — generic ClearBuffer / DisableEnableable for one-frame events | event-cleanup-helper-guide.md (references/event-cleanup-helper-guide.md) |
| CooldownTimer / CooldownTimerSystem / ICooldownState — countdown timer pattern | cooldown-timer-guide.md (references/cooldown-timer-guide.md) |
| Lifetime / LifetimeSystem / DeadTagLifetimeSystem — auto-destroy countdown + dead-entity bridge | lifetime-guide.md (references/lifetime-guide.md) |
| TargetEntity / TargetSelector / SelectNearestTargetSystem / PickLowestHp / PickHighestThreat — generic target selection | targeting-guide.md (references/targeting-guide.md) |
| RespawnResetHelper — standard respawn-ready query builder | respawn-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) |
Documentation
Section titled “Documentation”- Engine-neutral concepts:
t1k-gamedev-ecs-design(theonekit-gamedev:ecs); concept-to-DOTS map: neutral-ecs-map.md (references/neutral-ecs-map.md) - Entities Manual
- Entities API
- Entities 1.4.5 Changelog
- ECS Samples
- Context7 library:
/needle-mirror/com.unity.entities(1187 snippets, High reputation, score 82.4)
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-Pattern | Symptom | Fix |
|---|---|---|
| Embedded component | Component defined inside system file | One type per file, in Components/ folder |
| Visual transform feedback loop | PresentationSystemGroup modifies Position each frame → simulation reads modified value next frame → positions collapse exponentially | Save/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.
Key Conventions
Section titled “Key Conventions”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.burst1.8.28com.unity.mathematics1.3.2com.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’s1.xline 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 structpartial - To defer structural changes inside a job, use
EntityCommandBuffer.ParallelWriterwith[ChunkIndexInQuery]sort key - To enable/disable a component without archetype moves, implement both
IComponentDataandIEnableableComponent - NEVER use
GetSingletonEntity<T>(),HasSingleton<T>(), orTryGetSingletonEntity<T>()onIEnableableComponenttypes — throwsInvalidOperationException. UseSystemAPI.Query<RefRW<T>>().WithPresent<T>().WithEntityAccess()instead - To bake a moving entity, pass
TransformUsageFlags.DynamictoGetEntity()in the Baker - To build large read-only shared data, use
BlobAssetand register viabaker.AddBlobAsset() - To detect entity destruction, use
ICleanupComponentData— it survivesDestroyEntityuntil 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).
Event Communication
Section titled “Event Communication”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 callsbuffer.Clear(). - DynamicBuffer singleton (
EntityEvent) — global cross-system queue withEntityEventTypediscriminator. Cleared byCoreEventCleanupSystem.
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)
Addressables-First (library v2.0.0+)
Section titled “Addressables-First (library v2.0.0+)”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): noResources.Load(, noAssetDatabase.LoadAssetAtPath, noObject.Instantiate(GameObject)outside the per-project allowlist. ECS-sideEntityManager.Instantiate(Entity)andecb.Instantiate(Entity)are fine — different overload, different target. - In a Baker, never call
GetEntity(prefab)directly on anAssetReferenceGameObject. 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 DynamicBufferbool in IComponentData), BC1016 (new FixedStringNBytes(string) vs literal assignment): references/hard-rules-burst.md
Hard rules
Section titled “Hard rules”-
The stat dirty flag is the canonical
DOTSCore.DirtyTag—StatsDirtyTagis now[Obsolete].DOTSCore.DirtyTag(the generic enableable “data changed, recalculate” flag) is the SSOT;DOTSCore.StatsDirtyTagis a separate, back-compat-only ECS type scheduled for removal — new code MUST useDirtyTag. Both live atCore/Components/{DirtyTag,StatsDirtyTag}.csand declarenamespace DOTSCore(NOTDOTSCore.Stats) — writingusing DOTSCore.Stats;then referencing either gives CS0246 even thoughLevel/Experience/BaseStatsARE underDOTSCore.Stats; addusing 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 SAMEDOTSCore.DirtyTag— combat (PartyBuffSystem/SynergyResolutionSystem/DamageBucketAggregationSystem/StageCurveSystem/TalentUnlockSystem), inventory (EquipmentSystem/ItemSetBonusSystem/PassiveEffectSystem), and coreLoadSystem(restored state must re-trigger derivation). A producer that forgets to raiseDirtyTagis 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 singleDirtyTagprevents. -
Colour contract:
SpriteColor.ValueandOriginalSpriteColor.Valueare ALWAYS LINEAR. Every tint/palette constant is stored linear; anything crossing in from authored sRGB converts exactly once, at the authoring boundary, viaColorSpaceUtility.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 (seet1k-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.
SpriteColorisIComponentData { public float4 Value; }, a bare public mutable field, because ECSref/RefRWmutation requires it —readonly+ constructor-only would break every per-frame system that blends a tint inside a Burst job. So aFromGamma/FromLinearfactory is a strong convention, not an enforced contract: it cannot stop a system holding areffrom assigning.Valuedirectly, and two systems legitimately do exactly that every frame.Consequence:
grep "new SpriteColor"is necessary but NOT sufficient. It misses every site thatmath.lerps an existing.Valueagainst 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 — seet1k-unity-dots-core-jobs-burst§ “Burst restricts statics”. Shipped in The1Studio/unity-dots-library#72. -
Generic persistence (H2):
SaveSystem/LoadSystemreference ZERO game modules. Serialization is driven byISnapshotSerializerregistered intoSnapshotSerializerRegistry; each module self-registers via[RuntimeInitializeOnLoadMethod(SubsystemRegistration)]. To add save support for a new component, implementISnapshotSerializerin the OWNING module (not in core) and register it — do NOT editSaveSystem/LoadSystem. Full pattern:t1k-unity-dots-core-architecture/references/generic-persistence.md(../t1k-unity-dots-core-architecture/references/generic-persistence.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