05 · Archetype Tables (v3)¶
What it is¶
An alternative storage for components that are stable and read together (Transform, Velocity,
SpriteRenderer). Instead of one pool per component, entities that have exactly the
same set of table components share a table, with one column per component. Iterating a query over
those components walks the columns in lockstep, perfectly linearly.
This is a v3 feature. v1 accepts StorageKind::kTable on a component but stores it in a sparse set.
Why we need it¶
- R4 (generic): other games may have tens of thousands of entities with stable composition (crowds, particles, tiles), where tables iterate faster than sparse-set joins.
- R-Type itself does not need it: its counts are moderate and its composition changes often.
How others do it¶
| ECS | Model |
|---|---|
| Unity DOTS | Archetypes split into 16 KB chunks |
| Unreal Mass | Archetypes in chunks; shared and chunk fragments |
| flecs | Archetype tables, a graph of add/remove edges between tables, cached queries |
| Bevy | Tables for components by default, sparse sets as a per-component option |
| EnTT | No archetypes; groups reorder pools to get similar contiguity |
Our choice¶
Per-component choice, like Bevy. Each component's ComponentInfo::storage says kTable or
kSparseSet. Only kTable components define an entity's archetype; sparse-set components (tags,
states, most script components) never move it between tables.
How it works¶
Tables¶
flowchart LR
subgraph t1 ["Table {Position, Velocity}"]
direction TB
r4["e4 · Position · Velocity"]
r7["e7 · Position · Velocity"]
r9["e9 · Position · Velocity"]
end
subgraph t2 ["Table {Position, Velocity, Sprite}"]
direction TB
r2["e2 · Position · Velocity · Sprite"]
r9b["e9 · Position (moved) · Velocity (moved) · Sprite (new)"]
end
r9 -- "add Sprite to e9:<br/>its whole row moves" --> r9b
Each column is a ByteColumn with its tick arrays, the same building block as a pool.
Entity records¶
Each entity slot records where its table data is:
struct EntityRecord {
std::uint32_t generation;
TableId table; ///< The empty table when the entity has no table component.
std::uint32_t row;
};
Adding or removing a table component¶
- Find the destination table (the current set ± the component). An edge cache on each table
(
add Sprite → table 7) avoids recomputing the set every time, as flecs does. - Move the entity's row: each shared column moves its element; the new column constructs, or the removed column destroys.
- Swap-and-pop the hole in the source table, and update the record of the entity that moved into it.
- Update the entity's record.
Cost: one move per table component of the entity, which is why frequently toggled components stay in sparse sets.
Queries over mixed storage¶
flowchart TD
q["Query: Position, Velocity (tables)<br/>+ Shield (sparse) + Without Dead (sparse)"] --> match["Cached list of tables<br/>that contain Position and Velocity"]
match --> rows["Walk each table row by row"]
rows --> sparse["For each entity: Shield pool contains?<br/>Dead pool does not contain?"]
sparse --> yield["Yield"]
When a new table is created, every cached query checks once whether it matches and adds it to its list.
Why sparse components stay out of the archetype¶
If tags were part of the archetype, every combination of Invincible, Charging, Stunned,
OnFire... would create its own table, splitting entities into many small tables (fragmentation)
and moving rows on every toggle. Keeping them in sparse sets makes toggling free and keeps tables big.
Connections¶
- Uses: Component registry (
storagekind), theByteColumnfrom Pool, Entity (records per slot). - Used by: World, Queries.
Pitfalls¶
- Choosing
kTablefor a component that is added and removed often. Every toggle moves a row. - Query caches going stale. New tables must be offered to existing queries.
- Changing storage kind later. It must not change behavior, only performance, which is guaranteed because nothing outside the storage sees pools or tables.
Open questions¶
- Default storage for C++ components once tables exist:
kTable(Bevy's default) orkSparseSet? (ECS) - Chunked tables (Unity-style 16 KB chunks) for parallel iteration, or whole tables? (ECS, v3)