guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::ecs::System Class Referenceabstract

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>

Inheritance diagram for guillaume::ecs::System:
Collaboration diagram for guillaume::ecs::System:

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.

Detailed Description

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:

  1. binds the scene's registries, so getComponent() and getEntityRegistry() work;
  2. calls prepare() once;
  3. asks the traveler of the phase for every entity of the scene, in order, and calls update(identifier) on each entity whose signature contains the system's signature;
  4. calls cleanup() once;
  5. unbinds the registries.

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:

// Opacity is a component defined by the application.
class Fade: public ecs::SystemFiller<components::Color, Opacity>
{
public:
Fade(void)
: ecs::SystemFiller<components::Color, Opacity>(
{
}
void update(const ecs::Entity::Identifier &identifier) override
{
auto &color = getComponent<components::Color>(identifier);
auto &opacity = getComponent<Opacity>(identifier);
// read opacity, write color
}
};
systemRegistry.registerNewSystem(std::make_unique<Fade>());
std::size_t Identifier
The key under which an entity's components are stored. Systems and components refer to entities by th...
Definition entity.hpp:86
The base class to derive a system from: a System whose signature is the list of component types given...
ComponentType & getComponent(const ecs::Entity::Identifier &entityIdentifier)
Get a component of an entity from the bound registry, to read or modify it.
virtual void update(const ecs::Entity::Identifier &entityIdentifier)=0
Apply the system's rule to one entity. Implemented by each system.
State. Every class here is plain data attached to an entity.
The entity-component-system core, independent of any widget.
Definition component.hpp:28
Phase
The four steps of a frame. Every system belongs to one of them.

Things to watch out for:

See also
SystemFiller
SystemRegistry
Phase

Definition at line 116 of file system.hpp.

Constructor & Destructor Documentation

◆ System()

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.

Parameters
phaseThe 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.

Member Function Documentation

◆ bindComponentRegistry()

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:

system.bindComponentRegistry(registry);
system.update(identifier);
system.unbindComponentRegistry();

No entity registry is bound, so getEntityRegistry() still throws. routine() replaces this binding and clears it when it returns.

Parameters
componentRegistryThe registry getComponent() reads from. It must stay alive until unbindComponentRegistry().

Definition at line 113 of file system.cpp.

◆ cleanup()

virtual void guillaume::ecs::System::cleanup ( void )
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.

Here is the caller graph for this function:

◆ getComponent() [1/2]

template<InheritFromComponent ComponentType>
ComponentType & guillaume::ecs::System::getComponent ( const ecs::Entity::Identifier & entityIdentifier)
protected

Get a component of an entity from the bound registry, to read or modify it.

Template Parameters
ComponentTypeThe component type to get.
Parameters
entityIdentifierThe identifier of the entity, which can be any entity of the scene (a child, the parent).
Returns
Reference to the stored component.
Exceptions
std::runtime_errorWhen no registry is bound.
EntityComponentNotFoundException<ComponentType>When the entity does not have the component.
Here is the caller graph for this function:

◆ getComponent() [2/2]

template<InheritFromComponent ComponentType>
const ComponentType & guillaume::ecs::System::getComponent ( const ecs::Entity::Identifier & entityIdentifier) const
protected

Get a component of an entity from the bound registry, read-only.

Template Parameters
ComponentTypeThe component type to get.
Parameters
entityIdentifierThe identifier of the entity.
Returns
Const reference to the stored component.
Exceptions
std::runtime_errorWhen no registry is bound.
EntityComponentNotFoundException<ComponentType>When the entity does not have the component.

◆ getComponentRegistry() [1/2]

ecs::ComponentRegistry & guillaume::ecs::System::getComponentRegistry ( void )
protected

Get the component registry of the scene being processed.

Returns
Reference to the registry given to routine() or to bindComponentRegistry().
Exceptions
std::runtime_errorWhen no registry is bound.

Definition at line 53 of file system.cpp.

Here is the caller graph for this function:

◆ getComponentRegistry() [2/2]

const ecs::ComponentRegistry & guillaume::ecs::System::getComponentRegistry ( void ) const
protected

Get the component registry of the scene being processed, read-only.

Returns
Const reference to the registry given to routine() or to bindComponentRegistry().
Exceptions
std::runtime_errorWhen no registry is bound.

Definition at line 62 of file system.cpp.

◆ getEntityRegistry() [1/2]

ecs::EntityRegistry & guillaume::ecs::System::getEntityRegistry ( void )
protected

Get the entity registry of the scene being processed.

Returns
Reference to the registry given to routine().
Exceptions
std::runtime_errorWhen called outside routine(). bindComponentRegistry() does not bind an entity registry.

Definition at line 35 of file system.cpp.

◆ getEntityRegistry() [2/2]

const ecs::EntityRegistry & guillaume::ecs::System::getEntityRegistry ( void ) const
protected

Get the entity registry of the scene being processed, read-only.

Returns
Const reference to the registry given to routine().
Exceptions
std::runtime_errorWhen called outside routine().

Definition at line 44 of file system.cpp.

◆ getPhase()

Phase guillaume::ecs::System::getPhase ( void ) const
noexcept

Get the phase of the frame in which the system runs.

Returns
The phase given to the constructor.

Definition at line 71 of file system.cpp.

◆ getSignature()

Entity::Signature guillaume::ecs::System::getSignature ( void ) const
noexcept

Get the component types an entity must declare to be visited by this system.

Returns
A copy of the signature.

Definition at line 76 of file system.cpp.

Here is the caller graph for this function:

◆ hasComponent()

template<InheritFromComponent ComponentType>
bool guillaume::ecs::System::hasComponent ( const ecs::Entity::Identifier & entityIdentifier) const
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.

Template Parameters
ComponentTypeThe component type to look for.
Parameters
entityIdentifierThe identifier of the entity, which can be any entity of the scene, not only the one being updated.
Returns
True when the component exists; false when it does not or when no registry is bound.
Here is the caller graph for this function:

◆ prepare()

virtual void guillaume::ecs::System::prepare ( void )
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.

Here is the caller graph for this function:

◆ requireComponent()

template<InheritFromComponent ComponentType>
bool guillaume::ecs::System::requireComponent ( const ecs::Entity::Identifier & entityIdentifier)
protected

Tell whether an entity has a component, and log a warning naming the entity and the component when it does not.

return;
}
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...
Template Parameters
ComponentTypeThe component type the system cannot work without.
Parameters
entityIdentifierThe identifier of the entity.
Returns
True when the component exists; false (after the warning) when it does not or when no registry is bound.
Here is the caller graph for this function:

◆ routine()

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.

Parameters
componentRegistryThe component registry of the scene; the one getComponent() reads during the call.
entityRegistryThe entity registry of the scene; its entities and the ones nested below are the candidates.
travelerThe order in which the entities are visited, given by the phase (SystemPhase::getTraveler).

Definition at line 81 of file system.cpp.

Here is the call graph for this function:

◆ setSignature()

template<InheritFromComponent... ComponentTypes>
void guillaume::ecs::System::setSignature ( void )
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.

Template Parameters
ComponentTypesThe component types an entity must declare for update() to be called on it.

◆ unbindComponentRegistry()

void guillaume::ecs::System::unbindComponentRegistry ( void )

Drop the binding made by bindComponentRegistry().

Definition at line 118 of file system.cpp.

◆ update()

virtual void guillaume::ecs::System::update ( const ecs::Entity::Identifier & entityIdentifier)
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.

Parameters
entityIdentifierThe 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.

Here is the caller graph for this function:

The documentation for this class was generated from the following files: