|
guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
|
Base class of every system: a rule applied each frame to every entity that has a given set of components. More...
#include <headers/guillaume/ecs/system.hpp>


Public Member Functions | |
| System (Phase phase) | |
| Create a system that runs in a given phase, with an empty signature. | |
| virtual | ~System (void)=default |
| Virtual destructor. | |
| Phase | getPhase (void) const noexcept |
| Get the phase of the frame in which the system runs. | |
| Entity::Signature | getSignature (void) const noexcept |
| Get the component types an entity must declare to be visited by this system. | |
| void | routine (ecs::ComponentRegistry &componentRegistry, ecs::EntityRegistry &entityRegistry, const ecs::EntityTreeTraveler &traveler) |
| Run the system once over a scene: prepare(), update() on each matching entity, cleanup(). | |
| void | bindComponentRegistry (ecs::ComponentRegistry &componentRegistry) |
| Bind a component registry so update() can be called directly, without routine(). | |
| void | unbindComponentRegistry (void) |
| Drop the binding made by bindComponentRegistry(). | |
| virtual void | update (const ecs::Entity::Identifier &entityIdentifier)=0 |
| Apply the system's rule to one entity. Implemented by each system. | |
| virtual void | prepare (void) |
| Called once per pass, before the first update(). | |
| virtual void | cleanup (void) |
| Called once per pass, after the last update(). | |
Protected Member Functions | |
| template<InheritFromComponent... ComponentTypes> | |
| void | setSignature (void) |
| Replace the signature by the one made of the given component types. | |
| ecs::EntityRegistry & | getEntityRegistry (void) |
| Get the entity registry of the scene being processed. | |
| const ecs::EntityRegistry & | getEntityRegistry (void) const |
| Get the entity registry of the scene being processed, read-only. | |
| ecs::ComponentRegistry & | getComponentRegistry (void) |
| Get the component registry of the scene being processed. | |
| const ecs::ComponentRegistry & | getComponentRegistry (void) const |
| Get the component registry of the scene being processed, read-only. | |
| template<InheritFromComponent ComponentType> | |
| bool | hasComponent (const ecs::Entity::Identifier &entityIdentifier) const |
| Tell whether an entity has a component, in the bound registry. | |
| template<InheritFromComponent ComponentType> | |
| ComponentType & | getComponent (const ecs::Entity::Identifier &entityIdentifier) |
| Get a component of an entity from the bound registry, to read or modify it. | |
| template<InheritFromComponent ComponentType> | |
| const ComponentType & | getComponent (const ecs::Entity::Identifier &entityIdentifier) const |
| Get a component of an entity from the bound registry, read-only. | |
| template<InheritFromComponent ComponentType> | |
| bool | requireComponent (const ecs::Entity::Identifier &entityIdentifier) |
| Tell whether an entity has a component, and log a warning naming the entity and the component when it does not. | |
Base class of every system: a rule applied each frame to every entity that has a given set of components.
A system declares two things: a signature (the component types it needs) and a phase (when it runs in the frame). It keeps no per-entity state: everything it reads and writes is in components, reached by entity identifier.
What happens each frame. For each phase in order, Application::routine calls routine() on every system of that phase. routine() does this:
Every matching entity is visited every frame, whether or not its components changed, so update() must be cheap when there is nothing to do and must not write a value that is already there (component setters compare before marking the component changed).
Writing a system. Derive from SystemFiller, list the components, pick the phase, implement update(), and register an instance in a SystemRegistry:
Things to watch out for:
Definition at line 116 of file system.hpp.
| guillaume::ecs::System::System | ( | Phase | phase | ) |
Create a system that runs in a given phase, with an empty signature.
An empty signature matches every entity. Derive from SystemFiller to set the signature from a list of component types, or call setSignature() in the derived constructor.
| phase | The phase of the frame in which the system runs. It decides in which list SystemRegistry stores the system. |
Definition at line 27 of file system.cpp.
| void guillaume::ecs::System::bindComponentRegistry | ( | ecs::ComponentRegistry & | componentRegistry | ) |
Bind a component registry so update() can be called directly, without routine().
Meant for tests and for code that drives one entity by hand:
No entity registry is bound, so getEntityRegistry() still throws. routine() replaces this binding and clears it when it returns.
| componentRegistry | The registry getComponent() reads from. It must stay alive until unbindComponentRegistry(). |
Definition at line 113 of file system.cpp.
|
inlinevirtual |
Called once per pass, after the last update().
Does nothing by default. Override it to release what prepare() set up or to act on what the pass collected. The registries are still bound. It is called even when no entity matched.
Reimplemented in guillaume::systems::ArcRender, guillaume::systems::ElevationRender, guillaume::systems::EllipseRender, guillaume::systems::Focus, guillaume::systems::FocusRingRender, guillaume::systems::GlyphRender, guillaume::systems::HandButton, guillaume::systems::HandEventSystem< InteractionType, EventType >, guillaume::systems::HandEventSystem< components::HandSqueezeInteraction, utility::event::HandSqueezeEvent >, guillaume::systems::HandEventSystem< components::HandThumbRestInteraction, utility::event::HandThumbRestEvent >, guillaume::systems::HandEventSystem< components::HandThumbStickInteraction, utility::event::HandThumbStickEvent >, guillaume::systems::HandEventSystem< components::HandTriggerInteraction, utility::event::HandTriggerEvent >, guillaume::systems::HandMotion, guillaume::systems::ImageRender, guillaume::systems::KeyboardControl, guillaume::systems::LineRender, guillaume::systems::MeasureGlyph, guillaume::systems::MeasureMesh, guillaume::systems::MeasureText, guillaume::systems::MeshRender, guillaume::systems::MouseButton, guillaume::systems::MouseMotion, guillaume::systems::RectangleRender, guillaume::systems::RingRender, guillaume::systems::ScrimRender, guillaume::systems::StyleState, guillaume::systems::TextInput, and guillaume::systems::TextRender.
Definition at line 341 of file system.hpp.

|
protected |
Get a component of an entity from the bound registry, to read or modify it.
| ComponentType | The component type to get. |
| entityIdentifier | The identifier of the entity, which can be any entity of the scene (a child, the parent). |
| std::runtime_error | When no registry is bound. |
| EntityComponentNotFoundException<ComponentType> | When the entity does not have the component. |

|
protected |
Get a component of an entity from the bound registry, read-only.
| ComponentType | The component type to get. |
| entityIdentifier | The identifier of the entity. |
| std::runtime_error | When no registry is bound. |
| EntityComponentNotFoundException<ComponentType> | When the entity does not have the component. |
|
protected |
Get the component registry of the scene being processed.
| std::runtime_error | When no registry is bound. |
Definition at line 53 of file system.cpp.

|
protected |
Get the component registry of the scene being processed, read-only.
| std::runtime_error | When no registry is bound. |
Definition at line 62 of file system.cpp.
|
protected |
Get the entity registry of the scene being processed.
| std::runtime_error | When called outside routine(). bindComponentRegistry() does not bind an entity registry. |
Definition at line 35 of file system.cpp.
|
protected |
Get the entity registry of the scene being processed, read-only.
| std::runtime_error | When called outside routine(). |
Definition at line 44 of file system.cpp.
|
noexcept |
Get the phase of the frame in which the system runs.
Definition at line 71 of file system.cpp.
|
noexcept |
Get the component types an entity must declare to be visited by this system.
Definition at line 76 of file system.cpp.

|
protected |
Tell whether an entity has a component, in the bound registry.
Use it for the components that are optional for the system; the ones of its signature are expected to be there.
| ComponentType | The component type to look for. |
| entityIdentifier | The identifier of the entity, which can be any entity of the scene, not only the one being updated. |

|
inlinevirtual |
Called once per pass, before the first update().
Does nothing by default. Override it for work that is done once per frame rather than once per entity, such as taking the next input event from a queue. The registries are already bound.
Reimplemented in guillaume::systems::Animation, guillaume::systems::ArcRender, guillaume::systems::Clip, guillaume::systems::Drag, guillaume::systems::ElevationRender, guillaume::systems::EllipseRender, guillaume::systems::Focus, guillaume::systems::FocusRingRender, guillaume::systems::GlyphRender, guillaume::systems::HandButton, guillaume::systems::HandEventSystem< InteractionType, EventType >, guillaume::systems::HandEventSystem< components::HandSqueezeInteraction, utility::event::HandSqueezeEvent >, guillaume::systems::HandEventSystem< components::HandThumbRestInteraction, utility::event::HandThumbRestEvent >, guillaume::systems::HandEventSystem< components::HandThumbStickInteraction, utility::event::HandThumbStickEvent >, guillaume::systems::HandEventSystem< components::HandTriggerInteraction, utility::event::HandTriggerEvent >, guillaume::systems::HandMotion, guillaume::systems::ImageRender, guillaume::systems::KeyboardControl, guillaume::systems::LineRender, guillaume::systems::MeasureGlyph, guillaume::systems::MeasureMesh, guillaume::systems::MeasureText, guillaume::systems::MeshRender, guillaume::systems::MouseButton, guillaume::systems::MouseMotion, guillaume::systems::Overlay, guillaume::systems::RectangleRender, guillaume::systems::RingRender, guillaume::systems::ScrimRender, guillaume::systems::Scroll, guillaume::systems::StyleState, guillaume::systems::TextInput, and guillaume::systems::TextRender.
Definition at line 330 of file system.hpp.

|
protected |
Tell whether an entity has a component, and log a warning naming the entity and the component when it does not.
| ComponentType | The component type the system cannot work without. |
| entityIdentifier | The identifier of the entity. |

| void guillaume::ecs::System::routine | ( | ecs::ComponentRegistry & | componentRegistry, |
| ecs::EntityRegistry & | entityRegistry, | ||
| const ecs::EntityTreeTraveler & | traveler ) |
Run the system once over a scene: prepare(), update() on each matching entity, cleanup().
Called by Application::routine for every system, phase after phase. The registries are bound for the duration of the call and unbound when it returns normally. See the class description for the exact steps.
| componentRegistry | The component registry of the scene; the one getComponent() reads during the call. |
| entityRegistry | The entity registry of the scene; its entities and the ones nested below are the candidates. |
| traveler | The order in which the entities are visited, given by the phase (SystemPhase::getTraveler). |
Definition at line 81 of file system.cpp.

|
protected |
Replace the signature by the one made of the given component types.
SystemFiller calls it from its constructor. With no type, the signature is empty and the system visits every entity.
| ComponentTypes | The component types an entity must declare for update() to be called on it. |
| void guillaume::ecs::System::unbindComponentRegistry | ( | void | ) |
Drop the binding made by bindComponentRegistry().
Definition at line 118 of file system.cpp.
|
pure virtual |
Apply the system's rule to one entity. Implemented by each system.
routine() calls it once per frame for every entity whose signature contains the system's signature, in traveler order.
| entityIdentifier | The identifier of the entity to process. Its components are reached with getComponent(). |
Implemented in guillaume::systems::Animation, guillaume::systems::AppBar, guillaume::systems::ArcRender, guillaume::systems::Backdrop, guillaume::systems::Badge, guillaume::systems::Button, guillaume::systems::Card, guillaume::systems::Checkbox, guillaume::systems::Chip, guillaume::systems::Clip, guillaume::systems::CommonButton, guillaume::systems::Dialog, guillaume::systems::Divider, guillaume::systems::Drag, guillaume::systems::ElevationRender, guillaume::systems::EllipseRender, guillaume::systems::ExtendedFloatingActionButton, guillaume::systems::FloatingActionButton, guillaume::systems::FloatingActionButtonMenu, guillaume::systems::Focus, guillaume::systems::FocusRingRender, guillaume::systems::GlyphRender, guillaume::systems::HandButton, guillaume::systems::HandEventSystem< InteractionType, EventType >, guillaume::systems::HandEventSystem< components::HandSqueezeInteraction, utility::event::HandSqueezeEvent >, guillaume::systems::HandEventSystem< components::HandThumbRestInteraction, utility::event::HandThumbRestEvent >, guillaume::systems::HandEventSystem< components::HandThumbStickInteraction, utility::event::HandThumbStickEvent >, guillaume::systems::HandEventSystem< components::HandTriggerInteraction, utility::event::HandTriggerEvent >, guillaume::systems::HandMotion, guillaume::systems::HandRaySystem< InteractionType, EventType >, guillaume::systems::HandRaySystem< components::HandPinchInteraction, utility::event::HandPinchEvent >, guillaume::systems::HandRaySystem< components::HandPokeInteraction, utility::event::HandPokeEvent >, guillaume::systems::IconButton, guillaume::systems::ImageRender, guillaume::systems::KeyboardControl, guillaume::systems::Layout, guillaume::systems::LineRender, guillaume::systems::List, guillaume::systems::LoadingIndicator, guillaume::systems::MeasureGlyph, guillaume::systems::MeasureMesh, guillaume::systems::MeasureText, guillaume::systems::Menu, guillaume::systems::MeshRender, guillaume::systems::MouseButton, guillaume::systems::MouseMotion, guillaume::systems::NavigationBar, guillaume::systems::NavigationBarDestination, guillaume::systems::NavigationDrawer, guillaume::systems::NavigationDrawerDestination, guillaume::systems::Overlay, guillaume::systems::ProgressIndicator, guillaume::systems::RadioButton, guillaume::systems::RadioGroup, guillaume::systems::RectangleRender, guillaume::systems::RingRender, guillaume::systems::ScrimRender, guillaume::systems::Scroll, guillaume::systems::Search, guillaume::systems::SegmentedButton, guillaume::systems::Selection, guillaume::systems::Snackbar, guillaume::systems::StyleState, guillaume::systems::SurfaceTone, guillaume::systems::Switch, guillaume::systems::TextField, guillaume::systems::TextInput, guillaume::systems::TextRender, guillaume::systems::Tooltip, and guillaume::systems::Typography.
