oecs-sharp/docs/architecture.md

# Architecture Decisions: OECS

This document records the key architectural decisions made during the design of
OECS, with the rationale behind each one. It serves as a reference for
contributors and a guardrail against accidental complexity.

---

## ADR-001: Sparse Sets over Archetypes

**Status:** Accepted

**Context:** The ECS needs to store components and support iteration. The two
dominant patterns are archetypes (entities grouped by exact component
signature) and sparse sets (one dense array per component type).

**Decision:** Use sparse sets.

**Rationale:**

- The design prioritizes cheap add/remove operations because reactivity is a
  first-class concern. Sparse sets have O(1) add/remove via swap-remove.
- Archetypes require moving an entity to a new archetype when its component
  signature changes. This complicates change tracking — you must detect the
  move and emit events.
- Sparse sets have worse cache locality for multi-component queries (you probe
  multiple arrays), but for an observable-first ECS targeting UI workflows,
  query throughput is not the bottleneck.
- Sparse sets are simpler to implement and reason about.

**Consequences:**

- Multi-component queries probe N sparse sets. The smallest set drives
  iteration to minimize probes.
- Memory overhead: one `sparse` array per component type, sized to max entity
  ID. Acceptable for the expected entity counts (tens of thousands, not
  millions).

---

## ADR-002: 32-bit Entity with Version Bits

**Status:** Accepted

**Context:** Entities need to be cheap to copy, comparable, and safe against
use-after-free (accessing a recycled entity ID).

**Decision:** `readonly struct Entity` wrapping a `uint`. Lower 24 bits are the
ID, upper 8 bits are the version.

**Rationale:**

- 24-bit ID space supports ~16.7 million simultaneously alive entities. More
  than enough for observable-first use cases (UI entities, game objects in a
  typical scene).
- 8-bit version allows 256 generations before an ID wraps. With a free list,
  hot IDs are recycled quickly, making version collisions unlikely.
- 32-bit struct is 4 bytes — fits in a register, zero heap allocations.
- `Entity.Null` = `0` (ID=0, version=0). ID 0 is never allocated, so this is
  a natural sentinel.

**Alternatives considered:**

- `ulong` (64-bit): More headroom but 2× memory in every array and struct that
  references an entity. Overkill for the target scale.
- `Guid`: Heap-allocated when boxed, 16 bytes, not comparable by ref. Rejected
  for performance and ergonomics.

**Consequences:**

- `World` must track the current version per ID slot (a `byte[]` parallel to
  the free list).
- Entity equality checks both ID and version.

---

## ADR-003: Explicit Query Iteration over Auto-Injection

**Status:** Accepted

**Context:** Systems need to iterate entities matching a component signature.
Two API styles exist: auto-injection (the framework calls the system with the
right components) and explicit iteration (the system calls `foreach`).

**Decision:** Use explicit iteration via `world.Select<T1..T6>()`.

**Rationale:**

- Auto-injection hides the iteration cost. A system that looks like a simple
  method is actually O(N) — this is surprising.
- Explicit iteration makes the performance model visible. The system author
  sees the `foreach` call and understands they're iterating.
- Auto-injection requires either code generation or reflection to match
  parameters to component types. Explicit iteration uses generics, which are
  resolved at compile time.
- Explicit iteration is more flexible: a system can run multiple queries, or
  conditionally skip iteration.

**Consequences:**

- Slightly more verbose system code. Acceptable tradeoff for clarity.
- No source generators or reflection needed for system dispatch.

---

## ADR-004: Registration Order for System Execution

**Status:** Accepted

**Context:** Systems need a defined execution order. Options include
registration order, explicit dependency declarations, and stage-based
grouping.

**Decision:** Registration order determines execution order. No dependency
graph.

**Rationale:**

- Registration order is the simplest model that works. It's predictable and
  requires no additional API surface.
- For the target use case (observable ECS for UI-heavy applications), the
  number of systems is typically small (< 50). Manual ordering is manageable
  at this scale.
- Dependency graphs add complexity (cycle detection, topological sort) without
  proportional benefit at this scale.
- If needed later, `Before()`/`After()` constraints can be added to
  `SystemGroup` without breaking existing code.

**Consequences:**

- System authors must be mindful of registration order.
- `SystemGroup` is a simple ordered list, not a graph.

---

## ADR-005: Auto-Tracking for Component Modifications in Batching Scopes

**Status:** Accepted

**Context:** The reactivity system needs to know when a component value changes
so it can notify observers. Structural changes (add/remove) are detectable, but
in-place mutations via `ref T` are not.

**Decision:** Inside a batching scope (system run, command drain, foreach
iteration), component accesses via `GetComponent<T>`, `GetSingleton<T>`, and
`RefN` iterator properties are automatically tracked and marked as modified when
the scope ends. Outside a batching scope, explicit `world.MarkModified<T>(entity)`
is still required.

Batching scopes nest: `SystemGroup` wraps the entire tick, each system's `Run`
extension adds a nested scope, and each `foreach` iteration adds another. Only
the outermost scope flush triggers auto-marking.

**Rationale:**

- C# structs returned by `ref` have no built-in change detection. Auto-tracking
  within known scopes eliminates the most common source of forgotten
  `MarkModified` calls.
- The `RefN`/`ValN` iterator property pattern lets the user opt in to tracking
  per-component: `RefN` tracks, `ValN` does not. This avoids false positives
  from read-only iterations.
- Outside batching scopes, manual marking is still required — but these are
  rare (one-off mutations outside systems).

**Alternatives considered:**

- **Dirty flag on every component:** Requires a wrapper struct, breaks `ref`
  returns, adds per-component memory overhead.
- **Hash-based change detection:** Compute hash on write, compare on post.
  Expensive for large components, false positives on hash collisions.
- **Copy-on-write:** Store previous value, compare on post. Doubles memory for
  all components.

**Consequences:**

- System authors rarely need to call `MarkModified` — only for mutations outside
  batching scopes.
- `ValN` accessors on iterators are the safe default for read-only access.
- No per-component memory or CPU overhead for change detection.

---

## ADR-006: Deferred Mutation Batching and Change Posting

**Status:** Accepted

**Context:** Changes made during a system's `Run` need to be communicated to
observers. Posting immediately would interleave observer callbacks with system
logic, leading to reentrancy bugs. Structural mutations (add/remove component,
destroy entity) during iteration also need to be deferred to avoid invalidating
iterators.

**Decision:** Use nested batching scopes (`BeginBatching`/`EndBatching`).
`SystemGroup` wraps the entire tick in a batching scope. Each system's `Run`
extension, each command drain, and each `foreach` iteration add nested scopes.

Within a batching scope:
- Structural mutations are buffered and applied when the outermost scope ends.
- Component accesses via `GetComponent<T>`, `GetSingleton<T>`, and `RefN`
  iterator properties are tracked for auto-dirty-marking.

Pending mutations are flushed between systems so each system sees the prior
system's changes. Changes are posted after each system and after the full tick.

**Rationale:**

- Prevents observers from seeing partially-updated state mid-system.
- Allows batching: multiple changes to the same entity/component are collapsed
  into one notification.
- Matches the mental model of "the tick is the atomic unit of work."
- Nesting means `foreach` loops inside systems are safe — adding/removing
  components mid-iteration is deferred.

**Consequences:**

- Observers always see state after a complete system or tick, never during.
- If an observer needs to react mid-tick, they must split their logic into
  multiple systems.
- `FlushPendingMutations` between systems ensures chained work is visible.

---

## ADR-007: R3 for Reactivity

**Status:** Accepted

**Context:** The ECS needs a reactive programming library for observable
queries and change subscriptions.

**Decision:** Use [R3](https://github.com/Cysharp/R3).

**Rationale:**

- R3 is the de facto standard for reactive programming in modern .NET (the
  successor to UniRx).
- It's actively maintained by Cysharp (same author as MessagePack-CSharp).
- Zero-allocation observables, `IObservable<T>` compatible, `AddTo` for
  lifecycle management.
- First-party support for `IDisposable` subscription handles — natural fit for
  UI lifecycle binding.

**Alternatives considered:**

- **System.Reactive (Rx.NET):** Heavier, more allocation-heavy, less
  game-dev-friendly.
- **Custom event system:** Reinventing the wheel. R3 provides operators
  (Where, Select, Throttle) for free.

**Consequences:**

- Dependency on R3. Acceptable — it's the same ecosystem as MessagePack.
- Subscribers use standard Rx patterns (`Subscribe`, `AddTo`).

---

## ADR-008: Commands as Serializable Structs

**Status:** Accepted

**Context:** The design calls for a command queue where commands are
serializable and executed deferred.

**Decision:** Commands are `[MessagePackObject]` structs implementing
`ICommand`. They live in a `CommandQueue`, not in ECS sparse sets.

**Rationale:**

- Structs avoid heap allocations per command.
- MessagePack serialization enables networking, replay, and save/load of
  command streams.
- Separation from ECS state: commands are transient actions, not persistent
  data. Mixing them into sparse sets would blur this distinction.

**Consequences:**

- Commands cannot be queried like components. This is intentional.
- `ICommand` interface on a struct causes boxing if passed as `ICommand`.
  Mitigation: `CommandQueue.Enqueue<T>(T command) where T : struct, ICommand`
  uses constrained generics to avoid boxing. Internal storage still boxes
  (heterogeneous queue), but the enqueue path is allocation-free.

---

## ADR-009: Singleton as Reserved Entity

**Status:** Accepted

**Context:** Singletons (global state like `Time`, `Config`, `InputState`) need
a home in the ECS.

**Decision:** Reserve entity ID `1` as the singleton entity. Provide
convenience accessors (`SetSingleton<T>`, `GetSingleton<T>`). Exclude from
normal queries.

**Rationale:**

- Reuses existing component storage — no separate dictionary or global
  variables.
- Query exclusion prevents accidental iteration over singleton data in entity
  queries.
- Simpler than a separate "resource" system (as in Bevy). One concept (entity +
  components) covers both entities and singletons.

**Consequences:**

- Entity ID `1` is permanently reserved.
- `DestroyEntity` on the singleton entity is a no-op or throws.

---

## ADR-010: Single-Threaded by Default

**Status:** Accepted

**Context:** Should systems run in parallel? Should component access be
thread-safe?

**Decision:** Single-threaded execution. No locks, no `ConcurrentDictionary`,
no parallel scheduling.

**Rationale:**

- The target use case (observable ECS for UI) is inherently single-threaded.
  UI frameworks require main-thread access.
- Parallel system execution adds significant complexity: dependency analysis,
  component access arbitration, synchronization.
- If needed later, systems can declare read/write access sets for automatic
  parallel scheduling. This is an additive change.

**Consequences:**

- All systems run sequentially on the calling thread.
- No thread-safety guarantees. Calling `World` methods from multiple threads is
  undefined behavior.
- Simpler implementation, easier debugging.

---

## ADR-011: .NET 8 Target

**Status:** Accepted

**Context:** The library needs a target framework.

**Decision:** Target `net8.0` (LTS).

**Rationale:**

- .NET 8 is the current LTS release with support through November 2026.
- `ref struct` improvements, generic math, and performance enhancements over
  .NET 6/7.
- R3 and MessagePack both support .NET 8.
- No need for .NET 9 preview features.

**Consequences:**

- Consumers must be on .NET 8 or later.
- Can use `ref` returns, `readonly struct`, and other modern C# features.

---

## ADR-012: Public Types Required for MessagePack Serialization

**Status:** Accepted

**Context:** Component types must be serializable by MessagePack-CSharp. The
library imposes constraints on type design.

**Decision:** Component types must be `public` and annotated with
`[MessagePackObject]` and `[Key]` attributes. The `MessagePackAnalyzer` NuGet
package is included for compile-time validation.

**Rationale:**

- MessagePack-CSharp requires public types for its dynamic formatter generation
  and source-generated formatters.
- `MessagePackAnalyzer` provides AOT-safe source-generated formatters (critical
  for Unity IL2CPP) and catches misconfigured types at compile time.
- Indexed integer keys (`[Key(0)]`) produce the fastest and most compact
  serialization, which aligns with the ECS performance goal.

**Consequences:**

- Component authors cannot use `private` or `internal` types.
- The `MessagePackAnalyzer` package is a compile-time dependency.
- `[Key]` indices should be sequential starting from 0 to avoid null
  placeholders in the binary output.

---

## ADR-013: Interrupts for System-Blocking Prompts

**Status:** Accepted

**Context:** Systems sometimes need to pause execution until an external
response arrives (e.g., a UI confirmation dialog). The pause must be
serialization-safe (the world is fully consistent when blocked) and
must not interrupt mid-tick (which would leave partial state).

**Decision:** Add an interrupt system. Interrupts are issued via
`world.Interrupt<T>(interrupt)` and block the **next** tick, not the
current one. The interrupt is stored in an `InterruptStore` owned by
`SystemGroup`. A matching `IInterruptHandlerCommand<T>` (a regular
`ICommand`) resolves the interrupt when executed.

**Rationale:**

- Deferring the block to the next tick avoids mid-tick state
  inconsistency. The current tick completes normally, all mutations
  are flushed, and the world is serializable before the block takes
  effect.
- The interrupt store lives in `SystemGroup`, not `World`. This keeps
  `World` lean and means interrupts are a no-op when no `SystemGroup`
  is managing the world.
- Resolution is done via a regular `ICommand` with a default
  `Execute` implementation. The handler's `TryResolve` method receives
  the interrupt data and can inspect it before accepting or rejecting
  the resolution.
- One interrupt per type ensures no ambiguity about which handler
  resolves which interrupt.

**Alternatives considered:**

- **Mid-tick blocking:** Would leave partial system state, making
  serialization and recovery unsafe.
- **Storing interrupts in World:** Adds complexity to `World` without
  benefit — interrupts are a tick-level concern, not a component-level
  one.

**Consequences:**

- Systems that issue interrupts must be prepared for the next tick to
  be skipped entirely.
- Interrupts are transient — they are not serialized and do not survive
  save/load.
- `IInterruptHandlerCommand<T>` types must be `[MessagePackObject]`
  structs (like all commands) to enable serialization for replay.