Project-M/.claude/skills/dots-dev/references/dots-conventions.md

# DOTS / Netcode for Entities — Conventions & Gotchas

Reusable rule set the `/dots-dev` skill enforces. Targets **Unity 6.5, Entities 6.5, Netcode for Entities 6.5 (≡ the old ~1.12/1.13 API lineage), Unity Physics 6.x** — the unified 6.x DOTS line. These APIs move fast — anything flagged **[verify]** must be confirmed via `ctx7`/`find-docs` at code-time (see [`context7-libraries.md`](context7-libraries.md)), not trusted from memory. The project's `CLAUDE.md` is authoritative where it differs.

These conventions **replace** classic MonoBehaviour/GameObject conventions. If a design reaches for a MonoBehaviour singleton, a ScriptableObject "service" for runtime simulation, `[SerializeField] private` data carriers, or coroutines for sim logic, it is almost certainly wrong for DOTS.

## 1. Code structure

- **`struct : IComponentData`** — the default. Unmanaged, blittable, Burst- and job-friendly. Use for nearly all data.
- **`class : IComponentData`** — managed component. Only for genuine managed refs (a `GameObject`, `Material`). Main-thread only, no Burst, no jobs. Keep out of hot paths.
- **`IBufferElementData`** — per-entity dynamic array (`DynamicBuffer<T>`): inventory, path points, command history.
- **`ISharedComponentData`** — groups entities into chunks by shared value; changing it is a **structural change**. Use sparingly; prefer unmanaged shared components.
- **`IEnableableComponent`** — toggle a component on/off **without a structural change**. Prefer over add/remove tag components for frequently-flipped state. Enabled by default.
- **Systems**: `ISystem` (struct, Burst-compatible — **default**) vs `SystemBase` (class, managed, main-thread, no Burst — only when you must touch managed objects). Tag system methods `[BurstCompile]`.
- **`SystemAPI`** is the entry point inside systems: `SystemAPI.Query<...>()`, `.GetComponent`, `.Time`, `.GetSingleton`. Source-generated; valid only inside `ISystem`/`SystemBase`.
- **Aspects (`IAspect`) are DEPRECATED as of Entities 1.4 — do not author new ones.** Use components + `SystemAPI.Query`/`IJobEntity` directly. `Entities.ForEach` is legacy; avoid. **[verify]** the current recommended replacement.
- **Naming**: components are nouns/adjectives (`Health`, `Velocity`, `MoveSpeed`); tags suffix-free or `…Tag`; authoring MonoBehaviours suffix `Authoring`; systems suffix `System`; buffer elements often `…Element`/`…BufferElement`.

## 2. Jobs & Burst

- **`IJobEntity`** — preferred per-entity job (source-generated `Execute` over a query). **`IJobChunk`** — lower-level, chunk-wide/manual iteration. **`SystemAPI.Query`** — main-thread iteration.
- **Scheduling** — `Schedule()` / `ScheduleParallel()`; thread the returned `JobHandle` through `state.Dependency`. Avoid manual `.Complete()` unless you need results now (it's a sync point).
- **Burst breaks on** — managed types, `try/catch`/exceptions, `typeof`/reflection, virtual calls, `string` ops, GC allocation, most of `System.*`. Keep job code `unmanaged`.
- **Collections** — `NativeArray/List/HashMap`, `NativeQueue`, etc. Allocators: `Allocator.Temp` (frame/scope, auto-freed, **not** across job boundaries), `Allocator.TempJob` (one job, must dispose), `Allocator.Persistent` (long-lived, must dispose). **Always dispose** non-Temp, or `.Dispose(jobHandle)`.
- Mark inputs `[ReadOnly]` to allow parallel access; write-aliasing across parallel jobs is a safety error.

## 3. Baking (authoring → entities)

- **Why**: authoring data is converted **offline at edit/import time** into entities — no runtime conversion cost, deterministic, streamable.
- **Pattern**: a `MonoBehaviour` named `…Authoring` + `class FooBaker : Baker<FooAuthoring>` whose `Bake()` calls `GetEntity(...)` then `AddComponent(entity, new Foo{...})`.
- **Subscenes** hold baked entities and stream in/out asynchronously — entities are **not present the instant a subscene reference exists**; gate logic on load state.
- **Mistakes**: referencing other entities without `GetEntity(authoring, TransformUsageFlags.…)`; not declaring `DependsOn` (so bake doesn't re-run on asset change); doing runtime-only work in `Bake()`; forgetting `TransformUsageFlags` (→ missing `LocalTransform`).

## 4. Netcode for Entities

- **Ghosts** = replicated entities. Mark a prefab with **`GhostAuthoringComponent`**; mark replicated fields with **`[GhostField]`**; tune per-component replication with **`[GhostComponent]`** (e.g. `SendToOwner`). Variants via **`IGhostComponentVariation`**. **[verify]** attribute parameters.
- **Predicted vs interpolated ghosts**: predicted = simulated locally + rolled back (player-controlled, fast reaction). Interpolated = smoothed display of past server state (remote/non-critical).
- **Prediction & rollback**: core sim runs in **`PredictedSimulationSystemGroup`**, a **fixed-step** group on **both client and server**. On each new snapshot the client re-simulates from the oldest received tick → systems run **multiple times per frame**; sim code must be idempotent/deterministic. Filter queries with **`.WithAll<Simulate>()`** so only currently-simulated entities run. **[verify]** group internals/names.
- **Server-authoritative**: server is truth; clients send **input**, not state.
- **Input**: prefer **`IInputComponentData`** (auto-buffered to `InputBufferData<T>`); `ICommandData` is the lower-level command-buffer form. Don't read raw `UnityEngine.Input` in sim systems. **[verify]** helper signatures.
- **RPCs**: `struct : IRpcCommand` for one-off events (connect, requests). Not for per-tick state.
- **Determinism**: no `Time.deltaTime`/wall-clock in sim — use the netcode fixed tick. Avoid non-deterministic float sources, `System.Random`, ordering by hash. Cross-machine float determinism is fragile — keep predicted sim simple and consistent.
- **Worlds & bootstrap**: separate **client** and **server** `World`s; subclass **`ClientServerBootstrap`** (`CreateClientWorld`/`CreateServerWorld`) to customize. Annotate systems with `[WorldSystemFilter(...)]` to target client/server/thin. **[verify]** bootstrap method names + `WorldSystemFilterFlags`.

## 5. Common footguns

- **Structural changes** (add/remove component, create/destroy entity, set shared component) **invalidate `Entity`/component handles & references** and cause sync points. Batch via **ECB**.
- **ECB (`EntityCommandBuffer`)**: record now, play back later. Use built-in `Begin/EndSimulationEntityCommandBufferSystem` (and `BeginInitialization…`). One ECB per job; in parallel jobs use `.AsParallelWriter()`. Don't read back values you just recorded.
- **System order**: `[UpdateInGroup]`, `[UpdateBefore/After]`. Key groups: `InitializationSystemGroup`, `SimulationSystemGroup`, `PresentationSystemGroup`; netcode adds `PredictedSimulationSystemGroup`, `GhostSimulationSystemGroup`. **[verify]** netcode group set.
- **Main-thread-only**: managed components, `EntityManager` structural ops, most `World`/managed access. Keep out of Burst jobs.
- **No managed refs in unmanaged components** — won't compile / breaks Burst. Use a managed `IComponentData`, a `BlobAssetReference`, or an `Entity` reference instead.
- **Subscene timing & GO↔entity mixing**: entities may not exist yet; bridging GameObjects↔entities is manual and a known pain point — design around it, don't sprinkle hybrid links.

## 6. Testing (what "compiles clean" misses)

- **Default = plain-Entities EditMode test:** `new World` → register the system in `SimulationSystemGroup` → `SortSystems` → `Update()` → assert. Public API, version-independent. This is the project's actual harness.
- **Extract pure logic to a `*Math.cs` helper and unit-test it** — deterministic, fast, version-proof. Cover swept hit-detection with a **tunnelling regression** (a point-based test won't catch the tunnel).
- **Netcode coverage = one live Play smoke:** boot client+server (`execute_code`), step ticks, assert **server == client** for the replicated surface (identify worlds by `world.Name == "ServerWorld"/"ClientWorld"`). **`NetCodeTestWorld` is `internal`** in this line (exposed only to a fixed allow-list) and **0 of the project's test files use it** — do not prescribe it as the primary path. (Thin clients via Multiplayer PlayMode Tools exist for soak/load testing if ever needed — not in current practice.)
- Burst/source-gen failures surface at **editor compile/play**, not a plain C# build. Determinism desync, rollback bugs, sync-point stalls, and structural-change invalidation only show at **runtime under prediction** — always run a play/tick test, not just a build.

## 7. Verify via context7 at code-time (volatile — do NOT hardcode)

- Aspect deprecation status & the recommended replacement.
- Exact **system group names/order** and netcode prediction-group internals.
- **Input** API (`IInputComponentData` vs `ICommandData`) helper signatures.
- Ghost attribute options (`[GhostField]`/`[GhostComponent]` parameters, variants).
- Bootstrap/world-creation method names and `WorldSystemFilterFlags`.
- ECB system names + allocator/Collections API surface.