16 · Hooks and Observers¶
What it is¶
Hooks are functions the storage calls when a component's bytes are created, moved, copied or destroyed. Observers are callbacks that run immediately when something happens to a component (added, removed, set) or when an event fires.
Our ECS has hooks from v1, but only for memory. Observers are left for later.
Why we need it¶
- Hooks: the pool stores raw bytes. For a C++ component with a
std::vectormember, copying bytes withmemcpywould be wrong; the storage must call the C++ constructor, move constructor and destructor. Hooks are how a type-erased storage does that. - Observers: convenient for reactions ("when
Spriteis added, load its texture"), but they run logic outside the schedule.
How others do it¶
| ECS | Lifecycle hooks | Observers |
|---|---|---|
| flecs | ctor, dtor, move, copy, plus on_add / on_remove / on_set hooks |
Observers on any event, with queries |
| Bevy | Component hooks (on_add, on_insert, on_replace, on_remove) |
Observers and triggers |
| EnTT | Constructors run by typed storage | Signals: on_construct, on_update, on_destroy |
| Unity DOTS | Structs only (no lifecycle) | None built in |
Our choice¶
| Mechanism | v1 | Purpose |
|---|---|---|
Memory hooks (construct, destruct, move, copy) |
Yes | Manage the component's own memory, nothing else |
| Gameplay reactions | Through Added<T> filters and events |
Keep all logic in scheduled systems |
| Observers | v3, if a real need appears | Immediate reactions that cannot wait for a phase |
How it works¶
Memory hooks¶
struct TypeHooks {
void (*construct)(void* dst){nullptr};
void (*destruct)(void* dst){nullptr};
void (*move)(void* dst, void* src){nullptr};
void (*copy)(void* dst, const void* src){nullptr};
};
detail::makeHooks<T>() (in the type core, used by RTYPE_ECS_COMPONENT and later by resources)
generates them from the C++ type, and leaves them null when the operation is trivial, or when the type
does not support it (no default constructor: no construct; move-only: no copy). A null hook means "use memset / memcpy / nothing", which is the fast path and
the case for every Luau component.
| Storage action | Hook called | When null |
|---|---|---|
emplace |
construct |
zero-fill |
swap-and-pop remove |
move (last → hole), then destruct (last) |
memcpy, nothing |
| Column growth | move for each element |
memcpy of the whole block |
| Capsule spawn | copy |
memcpy |
Reactions without observers¶
"When a player joins, give it a ship" and "when SpriteRenderer is added, check that its texture is
known" are written as systems:
void checkNewSprites(rtype::ecs::Query<const SpriteRenderer, rtype::ecs::Added<SpriteRenderer>> sprites,
rtype::ecs::Res<rtype::plugins::graphics::TextureAssets> textures) {
for (auto [entity, sprite] : sprites) {
if (textures->get(sprite.texture) == nullptr) {
std::cerr << "A SpriteRenderer uses a texture nobody loaded\n";
}
}
}
The reaction happens at a known point of the frame, in a known order with other systems, and is visible in the schedule. An observer would run in the middle of whatever triggered it.
When observers would be worth it¶
- Keeping an index in sync (a spatial grid that must update the moment a
Collideris removed). - Editor tooling that reacts to every change.
If those needs appear, observers can be added on top of the same events, without touching hooks.
Connections¶
- Uses: Component registry (hooks live in
ComponentInfo). - Used by: Pool, Archetype tables, Capsules.
Pitfalls¶
- Gameplay in hooks. A
constructhook that plays a sound would run during a flush, in storage code, with no access to the world. Hooks only touch the component's own bytes. - Throwing from a hook. A hook runs in the middle of a storage operation; it must not throw (
moveanddestructarenoexcept). - Non-trivial Luau components. There are none: Luau components are plain data by design.
Open questions¶
- Is there an R-Type feature that truly needs immediate observers (a spatial index for collisions)?
(Team, after
CollisionPlugindesign)