2026-07-18 19:03:37 +08:00
|
|
|
# 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
|
|
|
|
|
|
2026-07-18 19:07:22 +08:00
|
|
|
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.
|
2026-07-18 19:03:37 +08:00
|
|
|
|
|
|
|
|
## 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.
|
