02 · Component Registry¶
What it is¶
A component is plain data attached to an entity (Position, Health, Shield). The registry
is the catalog of every component type the world knows: for each one, its name, size, alignment, fields
and options. It gives each type a small numeric ComponentId used everywhere at runtime.
The registry is what lets the core work with components it has never seen at compile time: those declared by Luau scripts.
Why we need it¶
- R2 (Luau): script components only exist at runtime. The core must handle them by id and size, not by C++ type.
- R3 (network): the server and clients must agree on what each component is (name, fields, layout) even though their ids differ.
- R4 (generic): one description serves storage, queries, reflection, serialization and scripting.
Everything that stores or moves component data depends on it: Pool, Archetype tables, Reflection, Luau bridge, Replication.
How others do it¶
| ECS | Component types | Runtime definition? |
|---|---|---|
| EnTT | C++ types; ids from a per-type template counter | No |
| Bevy | Rust types; plus ComponentDescriptor for dynamic components |
Limited |
| flecs | Every component is registered at runtime with size, alignment, hooks; meta adds fields |
Yes, first-class |
| Unreal | USTRUCT reflected by the header tool; UScriptStruct at runtime |
Yes (Blueprint structs) |
| Unity DOTS | C# structs; TypeManager assigns indices |
No |
Our choice¶
A runtime registry (the flecs model) with a typed C++ layer on top. Every component, from C++ or
Luau, is described by one ComponentInfo. The core only ever looks at ComponentInfo.
- Ids are dense numbers local to a world (0, 1, 2, ...), so they can index plain vectors.
- Names are the stable identity (
"rtype.Position","game.Shield"): used by files, scripts and the network.
How it works¶
The description¶
namespace rtype::ecs {
using ComponentId = std::uint32_t;
enum class StorageKind : std::uint8_t { kSparseSet, kTable };
enum class Presence : std::uint8_t { kBoth, kServerOnly, kClientOnly };
enum class ReplicationMode : std::uint8_t { kNone, kEveryChange, kSpawnOnly };
enum class FieldType : std::uint8_t {
kBool, kI8, kI16, kI32, kI64, kU8, kU16, kU32, kU64, kF32, kF64,
kVec2, kVec3, kVec4, kEntity, kAssetId,
};
struct FieldInfo {
std::string name;
FieldType type;
std::uint32_t offset;
std::uint32_t count{1}; ///< Fixed array length.
};
struct TypeInfo { // type/TypeInfo.hpp: shared with resources
TypeId id;
std::string name;
std::size_t size; ///< 0 for tags.
std::size_t alignment;
Presence presence; ///< Server and clients, server only, or client only.
ReplicationMode replication; ///< Never sent, sent on every change, or sent once at spawn.
TypeHooks hooks; ///< construct / destruct / move / copy, null when trivial
bool copyable{true}; ///< Always true for a component.
std::vector<FieldInfo> fields;
std::uint64_t layoutHash;
};
struct ComponentInfo {
TypeInfo type; ///< Everything a resource has too.
StorageKind storage; ///< Only components have a storage.
};
} // namespace rtype::ecs
| Part | Used by |
|---|---|
type.size, type.alignment, type.hooks |
Storage: how to allocate, construct, move and destroy the bytes |
storage |
The world: which backend holds it |
type.fields |
Reflection, the Luau bridge, the serializer |
type.presence, type.replication |
Replication: what exists on which side, what is sent and how |
type.name, type.layoutHash |
Network manifest, hot reload, scene files |
The registry itself is ComponentRegistry = TypeRegistry<ComponentInfo>: the generic registry of the
type core, with a KindTraits<ComponentInfo> specialization for what only components have (the storage
option and the copyability rule). See "The type core" in the design.
Two enums, not bit flags¶
Presence and ReplicationMode replace an earlier bit-flag enum (kReplicated = 1U << 0U,
kServerOnly = 1U << 1U, kClientOnly = 1U << 2U). The shifts cost nothing (the compiler folds them)
and these options are read per component type, never per entity, so speed was never the issue:
| Problem with bit flags | With two enums |
|---|---|
Invalid combinations are representable (kServerOnly \| kClientOnly) |
Presence holds exactly one value |
| One bit cannot say how to replicate (every change, spawn only) | ReplicationMode names the modes |
enum class flags need hand-written \| / & operators and casts |
Plain comparisons and exhaustive switch |
The only invalid pair left, kClientOnly with a replication mode other than kNone, is rejected at
registration. Replication's per-tick work loops over a precomputed list of replicated component
ids kept by the registry, so it never tests these enums per entity.
Two ways in¶
flowchart LR
cpp["C++ struct<br/>+ RTYPE_ECS_COMPONENT"] --> traits["ComponentTraits of T<br/>name, hash, fields, hooks"]
traits --> register["registry.register(info)"]
luau["Luau export type"] --> desc["ComponentDescriptor<br/>name + fields (no offsets)"]
desc --> layout["Deterministic layout<br/>offsets, size, alignment"]
layout --> register
register --> info["ComponentInfo<br/>id assigned"]
From C++, the name and field list are written once, next to the struct:
struct Health {
std::int32_t value;
std::int32_t max;
[[nodiscard]] bool isDead() const noexcept { return value <= 0; } // pure helper: allowed
};
RTYPE_ECS_COMPONENT(Health, "rtype.Health", value, max);
The macro specializes rtype::ecs::ComponentTraits<Health>: the name, a compile-time hash of it, the
field list (names via #field, types and offsets via &Health::field) and hooks (null for trivially
copyable types).
From Luau, the bridge builds a ComponentDescriptor with names and types but no offsets; the
registry computes the layout (see Luau bridge).
Deterministic layout¶
The server and every client compute script layouts independently, and Luau does not guarantee table order. So the registry sorts fields by alignment (largest first), then by name, and places them in that order:
Declared as game.Shield { strength: f32, regen: f32, owner: Entity }, then sorted:
| Order | Field | Type | Alignment |
|---|---|---|---|
| 1 | owner |
Entity (u64) |
8 |
| 2 | regen |
f32 |
4 (same as strength: ordered by name) |
| 3 | strength |
f32 |
4 |
Resulting layout (size 16, alignment 8):
| Bytes | 0 – 7 | 8 – 11 | 12 – 15 |
|---|---|---|---|
| Field | owner |
regen |
strength |
Sorting by alignment also minimizes padding.
Layout hash¶
layoutHash hashes the name and every field (name, type, count). Two processes with the same hash
agree on the bytes. It is checked when a client connects (Replication) and when a
script is hot-reloaded (Luau bridge).
From a C++ type to an id¶
The typed layer needs ComponentId for T. It looks up ComponentTraits<T>::kHash in the world's
hash → id map. Queries do it once when they are built; per-entity calls like world.getComponents().get<T>(e)
do a hash-map lookup, which can be cached per world later if it ever shows in a profile.
Connections¶
- Uses: nothing; it is a foundation.
- Used by: Pool, Archetype tables, World, Reflection, Hooks, Luau bridge, Replication.
Pitfalls¶
- Type ids across shared libraries. The classic
staticcounter per template gives different ids in each.so/.dll(andrtype-ecs, the renderer and the engine are separate binaries). Ids come from the world's registry, keyed by name hash, never from statics. typeid(T).name(). It differs between Clang and MSVC, so a Windows client and a Linux server would disagree. Names are always explicit.- Same name, different layout. Registering an existing name succeeds only if the
layoutHashmatches (needed for hot reload); otherwise it is an error. - Logic in components. Only pure
consthelpers are allowed. The macro canstatic_assert(std::is_aggregate_v<T>)to block constructors and private members.
Open questions¶
- Should C++ components move to C++26 reflection once Clang, Apple Clang and MSVC all support it? (ECS, later)
- Strings in components: an interned
kStringIdfield type? (ECS + Charles)