Architecture

Architecture

Ownership

A World owns entity hosts, component storage, the dispatcher, addons, and cached queries. A SystemStage is created for one world and should be reused and disposed explicitly.

World
├─ hosts and entities
├─ dispatcher and addons
├─ cached queries
└─ system stages

Actors

Binding a WorldActor to a world makes that actor's thread the only one allowed to mutate it; every other thread posts work into its mailbox instead of calling Send/Execute directly. ActorRuntime is an optional shared worker pool for many actors instead of one dedicated thread per world.

other thread → actor.Post(...) → mailbox → actor's owner thread → World

Use this when a world is ticked or mutated from more than one thread; a single-threaded world does not need an actor at all.

Archetypes

An archetype is one exact component-type set. Sia represents it as an HList type and stores entities with the same archetype together in a contiguous host buffer.

Adding or removing a component moves an entity to another host. Its slot can change, so never cache the slot or structurally mutate the host currently being iterated.

Mutation

Sia has two deliberate mutation paths:

Get<T>() + ref write   → changes data silently
generated View/command → changes data and sends an event

Use direct references in tight internal loops. Use generated views or commands when other systems must observe the change.

Queries and systems

A matcher selects hosts containing required component types. ForEach supplies entity handles; ForSlice supplies component references directly.

Systems combine a matcher with behavior. Optional event triggers make a system reactive. SystemChain describes system order; CreateStage(world) builds the runtime stage; Tick() runs it.

Events and parallel work

Dispatcher.Send invokes listeners synchronously on the sending thread. EventQueue buffers multi-producer work for one drainer. EventChannel supports priority and deferral but needs external synchronization.

CurrentThreadRunner runs inline. ParallelRunner uses workers, and RunnerBarrier represents completion and worker exceptions. Parallel callbacks must still avoid shared unsynchronized writes.

Source layout

Folder	Responsibility
Auxiliary, Buffers, Components	Generic foundations, storage, offsets, callbacks, and bundles.
Entities	Entity handles, hosts, matchers, queries, and iteration.
Events, Runners	Dispatch, buffering, sequential and parallel scheduling.
Worlds, Systems	Ownership, commands, actors, addons, system chains, and stages.
Serialization	MemoryPack-backed world snapshots.