Struct World 

pub struct World { /* private fields */ }

The ECS world: owns entities, archetype storage, resources, and commands.

Implementations

impl World

pub fn new() -> Self

Create an empty world with a single empty archetype.

pub fn change_tick(&self) -> u64

The current change-detection tick. Starts at 1; 0 is the sentinel.

pub fn advance_tick(&mut self) -> u64

Advance the change-detection tick by one. Returns the new tick value.

pub fn spawn<B: Bundle>(&mut self, bundle: B) -> Entity

Spawn an entity with the given component bundle.

pub fn despawn(&mut self, entity: Entity) -> bool

Despawn an entity, removing all its components.

pub fn is_alive(&self, entity: Entity) -> bool

Check whether an entity is alive.

pub fn insert_resource<T: Send + 'static>(&mut self, value: T)

Insert a resource (world-global singleton).

pub fn resource<T: Send + 'static>(&self) -> &T

Get a reference to a resource. Panics if not present.

pub fn resource_mut<T: Send + 'static>(&mut self) -> &mut T

Get a mutable reference to a resource. Panics if not present.

pub fn try_resource<T: Send + 'static>(&self) -> Option<&T>

Try to get a reference to a resource. Returns None if not present.

pub fn take_resource<T: Send + 'static>(&mut self) -> T

Remove and return a resource. Panics if not present.

pub fn try_take_resource<T: Send + 'static>(&mut self) -> Option<T>

Try to remove and return a resource. Returns None if not present.

pub fn apply_commands(&mut self)

Drain and apply all queued commands.

Called automatically between schedule stages. Can also be called manually for setup code that uses deferred mutations.

pub fn command_buffer_mut(&mut self) -> &mut CommandBuffer

Get a mutable reference to the command buffer.

This is the low-level escape hatch for tests and setup code. Systems should use the Commands system parameter.

pub fn add_event<T: Send + 'static>(&mut self)

Register an event type and insert its Events<T> resource.

Must be called before any system uses EventWriter<T> or EventReader<T>. Idempotent:

• First call: inserts Events<T> resource and registers the updater closure.
• Duplicate call (resource still exists): no-op — does not reset queued events or duplicate the updater.
• Re-call after resource removal: restores a fresh Events<T> resource without duplicating the updater.

pub fn flush_render_events(&self)

Advance all registered event buffers.

Swaps each Events<T>’s current buffer into previous and clears current. Called automatically at the start of every Schedule::run() so that events written in tick N are readable in tick N+1. Flush registered render events from Events<T>::current into the [RenderEventRegistry] accumulation buffer.

Called by [Schedule::run] after all systems, before the next tick’s update_events() swaps the buffers. This ensures every tick’s events are captured even when multiple ticks run per render frame (same pattern as Bevy’s deferred buffer swap).

pub fn update_events(&mut self)

pub fn event_swap_epoch(&self) -> u64

Monotonic counter incremented each time update_events() swaps. Used by render-event extractors to detect swaps and reset offsets.

pub fn add_deadline_type<T: Send + 'static>(&mut self)

Register a deadline event type and insert its Deadlines<T> and Events<T> resources.

Must be called before scheduling deadlines of type T. Idempotent. Registers a drainer closure so that drain_all_deadlines() automatically fires overdue deadlines of this type.

pub fn schedule_deadline<T: Send + 'static>( &mut self, deadline: Timestamp, event: T, ) -> DeadlineId

Schedule an event to fire when now >= deadline.

Returns a DeadlineId for cancellation. The event type must have been registered with add_deadline_type::<T>().

Panics

Panics if Deadlines<T> has not been registered.

pub fn cancel_deadline<T: Send + 'static>(&mut self, id: DeadlineId) -> bool

Cancel a previously scheduled deadline.

Returns true if the deadline was found and removed.

Panics

Panics if Deadlines<T> has not been registered.

pub fn drain_deadlines<T: Send + 'static>(&mut self, now: Timestamp)

Drain all overdue deadlines of type T and write them as events.

Fires all entries where now >= deadline, supporting batch reconciliation. Can be called manually for a single type, but prefer drain_all_deadlines() which drains all registered types automatically.

Panics

Panics if Deadlines<T> or Events<T> has not been registered.

pub fn drain_all_deadlines(&mut self)

Drain all overdue deadlines for every registered deadline type.

Reads the Clock resource to determine “now”, then calls drain_deadlines::<T>(now) for each type registered via add_deadline_type::<T>().

Called automatically by Schedule::run() before update_events(), so that fired deadline events are readable by EventReader<T> in the same tick.

If no Clock resource is present, this is a no-op (deadlines are only active when a clock is installed).

pub fn get<T: Component>(&self, entity: Entity) -> Option<&T>

Get a component for an entity.

pub fn get_mut<T: Component>(&mut self, entity: Entity) -> Option<Mut<'_, T>>

Get a mutable component for an entity.

Returns Mut<T> — reading via Deref does not stamp the change tick; only writing via DerefMut does.

pub fn one<Q: QuerySpec>(&self, entity: Entity) -> Option<Q::Item<'_>>

Fetch a typed query item for a single entity.

pub fn one_mut<Q: QuerySpecMut>( &mut self, entity: Entity, ) -> Option<Q::Item<'_>>

Fetch a typed mutable query item for a single entity.

pub fn insert<C: Component>(&mut self, entity: Entity, value: C)

Insert a component into an entity. If the entity already has this component type, the value is overwritten in place. Otherwise, the entity migrates to an archetype that includes the new component.

Change detection

When overwriting an existing component, only changed_tick is stamped at the current tick. added_tick is preserved from the original insertion (typically spawn). Use query_added to detect newly added components; it will not fire for overwrites.

pub fn remove<C: Component>(&mut self, entity: Entity)

Remove a component from an entity. If the entity doesn’t have this component, this is a no-op. Otherwise, the entity migrates to an archetype without the component.

pub fn component_removals_since<C: Component>( &self, since_tick: u64, ) -> impl Iterator<Item = Entity> + '_

Entities that had component C removed after since_tick (exclusive of since_tick, inclusive of the current World::change_tick).

Recorded only for successful World::remove::<C> calls (not despawns). The same entity may appear more than once if removals occurred on different ticks; callers typically deduplicate.

pub fn query<Q: QuerySpec>(&self) -> QueryIter<'_, Q>

Query all entities matching Q.

pub fn query_filtered<Q: QuerySpec, F: QueryFilter>( &self, ) -> QueryIter<'_, Q, F>

Query all entities matching Q and F.

pub fn query_mut<Q: QuerySpecMut>(&mut self) -> QueryIterMut<'_, Q>

Query all entities mutably matching Q.

pub fn query_filtered_mut<Q: QuerySpecMut, F: QueryFilter>( &mut self, ) -> QueryIterMut<'_, Q, F>

Query all entities mutably matching Q and F.

pub fn query2<A: Component, B: Component>(&self) -> Query2Iter<'_, A, B>

Convenience wrapper for two-component immutable queries.

pub fn query2_mut<A: Component, B: Component>( &mut self, ) -> Query2MutIter<'_, A, B>

Convenience wrapper for two-component mutable queries.

pub fn query3<A: Component, B: Component, C: Component>( &self, ) -> Query3Iter<'_, A, B, C>

Convenience wrapper for three-component immutable queries.

pub fn query3_mut<A: Component, B: Component, C: Component>( &mut self, ) -> Query3MutIter<'_, A, B, C>

Convenience wrapper for three-component mutable queries.

pub fn query_changed<T: Component>(&self, since_tick: u64) -> ChangedIter<'_, T>

Iterate entities whose component T changed after since_tick.

pub fn query_added<T: Component>(&self, since_tick: u64) -> AddedIter<'_, T>

Iterate entities whose component T was added after since_tick.

pub fn entity_count(&self) -> usize

Returns the number of alive entities.

pub fn archetypes(&self) -> &ArchetypeStore

Shared access to the archetype store (for change-detection inspection).

pub fn entity_location(&self, entity: Entity) -> Option<EntityLocation>

Look up where an entity lives in archetype storage.

Trait Implementations

impl Default for World

fn default() -> Self

Returns the “default value” for a type.