Expand description
This module contains various tools to allow you to react to component insertion or removal, as well as entity spawning and despawning.
There are four main ways to react to these lifecycle events:
- Using component hooks, which act as inherent constructors and destructors for components.
- Using observers, which are a user-extensible way to respond to events, including component lifecycle events.
- Using the
RemovedComponentssystem parameter, which offers an event-style interface. - Using the
Addedquery filter, which checks each component to see if it has been added since the last time a system ran.
§Types of lifecycle events
There are five types of lifecycle events, split into two categories. First, we have lifecycle events that are triggered when a component is added to an entity:
Add: Triggered when a component is added to an entity that did not already have it.Insert: Triggered when a component is added to an entity, regardless of whether it already had it.
When both events occur, Add hooks are evaluated before Insert.
Next, we have lifecycle events that are triggered when a component is removed from an entity:
Replace: Triggered when a component is removed from an entity, regardless if it is then replaced with a new value.Remove: Triggered when a component is removed from an entity and not replaced, before the component is removed.Despawn: Triggered for each component on an entity when it is despawned.
Replace hooks are evaluated before Remove, then finally Despawn hooks are evaluated.
Add and Remove are counterparts: they are only triggered when a component is added or removed
from an entity in such a way as to cause a change in the component’s presence on that entity.
Similarly, Insert and Replace are counterparts: they are triggered when a component is added or replaced
on an entity, regardless of whether this results in a change in the component’s presence on that entity.
To reliably synchronize data structures using with component lifecycle events,
you can combine Insert and Replace to fully capture any changes to the data.
This is particularly useful in combination with immutable components,
to avoid any lifecycle-bypassing mutations.
§Lifecycle events and component types
Despite the absence of generics, each lifecycle event is associated with a specific component.
When defining a component hook for a Component type, that component is used.
When observers watch lifecycle events, the B: Bundle generic is used.
Each of these lifecycle events also corresponds to a fixed ComponentId,
which are assigned during World initialization.
For example, Add corresponds to ADD.
This is used to skip TypeId lookups in hot paths.
Structs§
- Add
- Trigger emitted when a component is inserted onto an entity that does not already have that
component. Runs before
Insert. SeeComponentHooks::on_addfor more information. - Component
Hooks World-mutating functions that run as part of lifecycle events of aComponent.- Despawn
EntityEventemitted for each component on an entity when it is despawned. SeeComponentHooks::on_despawnfor more information.- Hook
Context - Context provided to a
ComponentHook. - Insert
- Trigger emitted when a component is inserted, regardless of whether or not the entity already
had that component. Runs after
Add, if it ran. SeeComponentHooks::on_insertfor more information. - Remove
- Trigger emitted when a component is removed from an entity, and runs before the component is
removed, so you can still access the component data.
See
ComponentHooks::on_removefor more information. - Removed
Component Entity - Wrapper around
EntityforRemovedComponents. Internally,RemovedComponentsuses these as anMessages<RemovedComponentEntity>. - Removed
Component Messages - Stores the
RemovedComponentsevent buffers for all types of component in a givenWorld. - Removed
Component Reader - Wrapper around a
MessageCursor<RemovedComponentEntity>so that we can differentiate messages between components. - Removed
Components - A
SystemParamthat yields entities that had theirTComponentremoved or have been despawned with it. - Replace
- Trigger emitted when a component is removed from an entity, regardless of whether or not it is later replaced.
Constants§
- ADD
EventKeyforAdd- DESPAWN
EventKeyforDespawn- INSERT
EventKeyforInsert- REMOVE
EventKeyforRemove- REPLACE
EventKeyforReplace
Type Aliases§
- Component
Hook - The type used for
Componentlifecycle hooks such ason_add,on_insertoron_remove. - OnAdd
Deprecated - Deprecated in favor of
Add. - OnDespawn
Deprecated - Deprecated in favor of
Despawn. - OnInsert
Deprecated - Deprecated in favor of
Insert. - OnRemove
Deprecated - Deprecated in favor of
Remove. - OnReplace
Deprecated - Deprecated in favor of
Replace. - Removed
Component Events Deprecated - Renamed to
RemovedComponentMessages. - Removed
Iter - Iterator over entities that had a specific component removed.
- Removed
Iter With Id - Iterator over entities that had a specific component removed.