bevy::ecs

Module lifecycle

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 RemovedComponents system parameter, which offers an event-style interface.
Using the Added query 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. See ComponentHooks::on_add for more information.
ComponentHooks: World-mutating functions that run as part of lifecycle events of a Component.
Despawn: EntityEvent emitted for each component on an entity when it is despawned. See ComponentHooks::on_despawn for more information.
HookContext: 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. See ComponentHooks::on_insert for 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_remove for more information.
RemovedComponentEntity: Wrapper around Entity for RemovedComponents. Internally, RemovedComponents uses these as an Messages<RemovedComponentEntity>.
RemovedComponentMessages: Stores the RemovedComponents event buffers for all types of component in a given World.
RemovedComponentReader: Wrapper around a MessageCursor<RemovedComponentEntity> so that we can differentiate messages between components.
RemovedComponents: A SystemParam that yields entities that had their T Component removed 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: EventKey for Add
DESPAWN: EventKey for Despawn
INSERT: EventKey for Insert
REMOVE: EventKey for Remove
REPLACE: EventKey for Replace

Type Aliases§

ComponentHook: The type used for Component lifecycle hooks such as on_add, on_insert or on_remove.
OnAddDeprecated: Deprecated in favor of Add.
OnDespawnDeprecated: Deprecated in favor of Despawn.
OnInsertDeprecated: Deprecated in favor of Insert.
OnRemoveDeprecated: Deprecated in favor of Remove.
OnReplaceDeprecated: Deprecated in favor of Replace.
RemovedComponentEventsDeprecated: Renamed to RemovedComponentMessages.
RemovedIter: Iterator over entities that had a specific component removed.
RemovedIterWithId: Iterator over entities that had a specific component removed.