# Observable ECS in C#.

An ECS system that focuses on a clean obserable api surface rather than performance.

## Entity

Entity should be an opaque integer type.

Divided into identifer bits and version bits.

## Component

C# structs/classes marked with `[MessagePackObject]` and `[Key]` attributes for
[MessagePack-CSharp](https://github.com/MessagePack-CSharp/MessagePack-CSharp) serialization.

- Types must be `public` — MessagePack requires public accessibility.
- Use indexed integer keys (`[Key(0)]`) for best performance and smallest binary
  size. String keys are available for debugging/interop but slower.
- For contractless usage, `[MessagePackObject(keyAsPropertyName: true)]` is
  available.
- The `MessagePackAnalyzer` package provides compile-time validation and AOT-safe
  source-generated formatters.

Components are stored in sparse-sets so they can cheaply be added/removed.

## Relationship

special components that automanage the source/target.

can be iterated by target for easy reverse lookup.

## Commands

serializable structs like components, not in ecs but in a queue.

have a `run` that gets called when you consume the command queue.

## Singletons

a special entity is used to carry singletons.

## System

Queries are composable with `With<TComponent>` and `Without<TComponent>` . Iterable for `ref TComponent`.

Systems are callbacks registered to queries when a tick happens. Ordering of systems is determined at registration time.

ticks can be `timed`(with deltaTime) or `logical`(without args).

## Reactivity

Use [R3](https://github.com/Cysharp/R3) for reactivity api.

Queries can be observed for changes. This is different from iteration for entity/component refs; System always run in ticks and not reactively.

Query subscriptions are not bound to entities but typically bound to, for example, frontend UI lifecycles.

Changes include entity add/remove, or entity component add/remove.

Changes need to be marked and then posted.

### In Systems

When a `System` makes changes in its `run` function, changes are posted after the `run`.

When `run` happens in a tick, those changes are posted after the tick.

When not in a system `run`, changes are not posted automatically.

Marking components for updates is manual. structural changes are auto marked.

## Serialization

Entities/Components can be serialized from `.csv` files or [MasterMemory](https://github.com/Cysharp/MasterMemory) tables.