Struct double_dot_state::World

pub struct World { /* private fields */ }

Stores and exposes operations on entities, components, resources, and their associated metadata.

Each Entity has a set of components. Each component can have up to one instance of each component type. Entity components can be created, updated, removed, and queried using a given World.

For complex access patterns involving SystemParam, consider using SystemState.

To mutate different parts of the world simultaneously, use World::resource_scope or SystemState.

Resources

Worlds can also store Resources, which are unique instances of a given type that don’t belong to a specific Entity. There are also non send resources, which can only be accessed on the main thread. See Resource for usage.

Implementations

impl World

pub fn new() -> World

Creates a new empty World

Panics

If usize::MAX Worlds have been created. This guarantee allows System Parameters to safely uniquely identify a World, since its [WorldId] is unique

pub fn id(&self) -> WorldId

Retrieves this World’s unique ID

pub fn as_unsafe_world_cell(&mut self) -> UnsafeWorldCell<'_>

Creates a new [UnsafeWorldCell] view with complete read+write access.

pub fn as_unsafe_world_cell_readonly(&self) -> UnsafeWorldCell<'_>

Creates a new [UnsafeWorldCell] view with only read access to everything.

pub fn entities(&self) -> &Entities

Retrieves this world’s [Entities] collection

pub unsafe fn entities_mut(&mut self) -> &mut Entities

Retrieves this world’s [Entities] collection mutably

Safety

Mutable reference must not be used to put the [Entities] data in an invalid state for this World

pub fn archetypes(&self) -> &Archetypes

Retrieves this world’s [Archetypes] collection

pub fn components(&self) -> &Components

Retrieves this world’s [Components] collection

pub fn storages(&self) -> &Storages

Retrieves this world’s [Storages] collection

pub fn bundles(&self) -> &Bundles

Retrieves this world’s [Bundles] collection

pub fn removed_components(&self) -> &RemovedComponentEvents

Retrieves this world’s [RemovedComponentEvents] collection

pub fn cell(&mut self) -> WorldCell<'_>

Retrieves a [WorldCell], which safely enables multiple mutable World accesses at the same time, provided those accesses do not conflict with each other.

pub fn init_component<T>(&mut self) -> ComponentId

where T: Component,

Initializes a new Component type and returns the [ComponentId] created for it.

pub fn init_component_with_descriptor( &mut self, descriptor: ComponentDescriptor ) -> ComponentId

Initializes a new Component type and returns the [ComponentId] created for it.

This method differs from World::init_component in that it uses a [ComponentDescriptor] to initialize the new component type instead of statically available type information. This enables the dynamic initialization of new component definitions at runtime for advanced use cases.

While the option to initialize a component from a descriptor is useful in type-erased contexts, the standard World::init_component function should always be used instead when type information is available at compile time.

pub fn component_id<T>(&self) -> Option<ComponentId>

where T: Component,

Returns the [ComponentId] of the given Component type T.

The returned ComponentId is specific to the World instance it was retrieved from and should not be used with another World instance.

Returns None if the Component type has not yet been initialized within the World using World::init_component.

use bevy_ecs::prelude::*;

let mut world = World::new();

#[derive(Component)]
struct ComponentA;

let component_a_id = world.init_component::<ComponentA>();

assert_eq!(component_a_id, world.component_id::<ComponentA>().unwrap())

pub fn entity(&self, entity: Entity) -> EntityRef<'_>

Retrieves an [EntityRef] that exposes read-only operations for the given entity. This will panic if the entity does not exist. Use World::get_entity if you want to check for entity existence instead of implicitly panic-ing.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let position = world.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 0.0);

pub fn entity_mut(&mut self, entity: Entity) -> EntityMut<'_>

Retrieves an [EntityMut] that exposes read and write operations for the given entity. This will panic if the entity does not exist. Use World::get_entity_mut if you want to check for entity existence instead of implicitly panic-ing.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let mut entity_mut = world.entity_mut(entity);
let mut position = entity_mut.get_mut::<Position>().unwrap();
position.x = 1.0;

pub fn inspect_entity(&self, entity: Entity) -> Vec<&ComponentInfo>

Returns the components of an Entity through ComponentInfo.

pub fn get_or_spawn(&mut self, entity: Entity) -> Option<EntityMut<'_>>

Returns an [EntityMut] for the given entity (if it exists) or spawns one if it doesn’t exist. This will return None if the entity exists with a different generation.

Note

Spawning a specific entity value is rarely the right choice. Most apps should favor World::spawn. This method should generally only be used for sharing entities across apps, and only when they have a scheme worked out to share an ID space (which doesn’t happen by default).

pub fn get_entity(&self, entity: Entity) -> Option<EntityRef<'_>>

Retrieves an [EntityRef] that exposes read-only operations for the given entity. Returns None if the entity does not exist. Use World::entity if you don’t want to unwrap the [EntityRef] yourself.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let entity_ref = world.get_entity(entity).unwrap();
let position = entity_ref.get::<Position>().unwrap();
assert_eq!(position.x, 0.0);

pub fn iter_entities(&self) -> impl Iterator<Item = EntityRef<'_>>

Returns an Entity iterator of current entities.

This is useful in contexts where you only have read-only access to the World.

pub fn get_entity_mut(&mut self, entity: Entity) -> Option<EntityMut<'_>>

Retrieves an [EntityMut] that exposes read and write operations for the given entity. Returns None if the entity does not exist. Use World::entity_mut if you don’t want to unwrap the [EntityMut] yourself.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let mut entity_mut = world.get_entity_mut(entity).unwrap();
let mut position = entity_mut.get_mut::<Position>().unwrap();
position.x = 1.0;

pub fn spawn_empty(&mut self) -> EntityMut<'_>

Spawns a new Entity and returns a corresponding [EntityMut], which can be used to add components to the entity or retrieve its id.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}
#[derive(Component)]
struct Label(&'static str);
#[derive(Component)]
struct Num(u32);

let mut world = World::new();
let entity = world.spawn_empty()
    .insert(Position { x: 0.0, y: 0.0 }) // add a single component
    .insert((Num(1), Label("hello"))) // add a bundle of components
    .id();

let position = world.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 0.0);

pub fn spawn<B>(&mut self, bundle: B) -> EntityMut<'_>

where B: Bundle,

Spawns a new Entity with a given Bundle of components and returns a corresponding [EntityMut], which can be used to add components to the entity or retrieve its id.

use bevy_ecs::{bundle::Bundle, component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

#[derive(Component)]
struct Velocity {
    x: f32,
    y: f32,
};

#[derive(Component)]
struct Name(&'static str);

#[derive(Bundle)]
struct PhysicsBundle {
    position: Position,
    velocity: Velocity,
}

let mut world = World::new();

// `spawn` can accept a single component:
world.spawn(Position { x: 0.0, y: 0.0 });
// It can also accept a tuple of components:
world.spawn((
    Position { x: 0.0, y: 0.0 },
    Velocity { x: 1.0, y: 1.0 },
));
// Or it can accept a pre-defined Bundle of components:
world.spawn(PhysicsBundle {
    position: Position { x: 2.0, y: 2.0 },
    velocity: Velocity { x: 0.0, y: 4.0 },
});

let entity = world
    // Tuples can also mix Bundles and Components
    .spawn((
        PhysicsBundle {
            position: Position { x: 2.0, y: 2.0 },
            velocity: Velocity { x: 0.0, y: 4.0 },
        },
        Name("Elaina Proctor"),
    ))
    // Calling id() will return the unique identifier for the spawned entity
    .id();
let position = world.entity(entity).get::<Position>().unwrap();
assert_eq!(position.x, 2.0);

pub fn spawn_batch<I>( &mut self, iter: I ) -> SpawnBatchIter<'_, <I as IntoIterator>::IntoIter>

where I: IntoIterator, <I as IntoIterator>::Item: Bundle,

Spawns a batch of entities with the same component Bundle type. Takes a given Bundle iterator and returns a corresponding Entity iterator. This is more efficient than spawning entities and adding components to them individually, but it is limited to spawning entities with the same Bundle type, whereas spawning individually is more flexible.

use bevy_ecs::{component::Component, entity::Entity, world::World};

#[derive(Component)]
struct Str(&'static str);
#[derive(Component)]
struct Num(u32);

let mut world = World::new();
let entities = world.spawn_batch(vec![
  (Str("a"), Num(0)), // the first entity
  (Str("b"), Num(1)), // the second entity
]).collect::<Vec<Entity>>();

assert_eq!(entities.len(), 2);

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

where T: Component,

Retrieves a reference to the given entity’s Component of the given type. Returns None if the entity does not have a Component of the given type.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let position = world.get::<Position>(entity).unwrap();
assert_eq!(position.x, 0.0);

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

where T: Component,

Retrieves a mutable reference to the given entity’s Component of the given type. Returns None if the entity does not have a Component of the given type.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
let mut position = world.get_mut::<Position>(entity).unwrap();
position.x = 1.0;

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

Despawns the given entity, if it exists. This will also remove all of the entity’s Components. Returns true if the entity is successfully despawned and false if the entity does not exist.

use bevy_ecs::{component::Component, world::World};

#[derive(Component)]
struct Position {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entity = world.spawn(Position { x: 0.0, y: 0.0 }).id();
assert!(world.despawn(entity));
assert!(world.get_entity(entity).is_none());
assert!(world.get::<Position>(entity).is_none());

pub fn clear_trackers(&mut self)

Clears the internal component tracker state.

The world maintains some internal state about changed and removed components. This state is used by RemovedComponents to provide access to the entities that had a specific type of component removed since last tick.

The state is also used for change detection when accessing components and resources outside of a system, for example via World::get_mut() or World::get_resource_mut().

By clearing this internal state, the world “forgets” about those changes, allowing a new round of detection to be recorded.

When using bevy_ecs as part of the full Bevy engine, this method is added as a system to the main app, to run during CoreSet::Last, so you don’t need to call it manually. When using bevy_ecs as a separate standalone crate however, you need to call this manually.

// a whole new world
let mut world = World::new();

// you changed it
let entity = world.spawn(Transform::default()).id();

// change is detected
let transform = world.get_mut::<Transform>(entity).unwrap();
assert!(transform.is_changed());

// update the last change tick
world.clear_trackers();

// change is no longer detected
let transform = world.get_mut::<Transform>(entity).unwrap();
assert!(!transform.is_changed());

pub fn query<Q>(&mut self) -> QueryState<Q>

where Q: WorldQuery,

Returns QueryState for the given [WorldQuery], which is used to efficiently run queries on the World by storing and reusing the QueryState.

use bevy_ecs::{component::Component, entity::Entity, world::World};

#[derive(Component, Debug, PartialEq)]
struct Position {
  x: f32,
  y: f32,
}

#[derive(Component)]
struct Velocity {
  x: f32,
  y: f32,
}

let mut world = World::new();
let entities = world.spawn_batch(vec![
    (Position { x: 0.0, y: 0.0}, Velocity { x: 1.0, y: 0.0 }),
    (Position { x: 0.0, y: 0.0}, Velocity { x: 0.0, y: 1.0 }),
]).collect::<Vec<Entity>>();

let mut query = world.query::<(&mut Position, &Velocity)>();
for (mut position, velocity) in query.iter_mut(&mut world) {
   position.x += velocity.x;
   position.y += velocity.y;
}

assert_eq!(world.get::<Position>(entities[0]).unwrap(), &Position { x: 1.0, y: 0.0 });
assert_eq!(world.get::<Position>(entities[1]).unwrap(), &Position { x: 0.0, y: 1.0 });

To iterate over entities in a deterministic order, sort the results of the query using the desired component as a key. Note that this requires fetching the whole result set from the query and allocation of a Vec to store it.

use bevy_ecs::{component::Component, entity::Entity, world::World};

#[derive(Component, PartialEq, Eq, PartialOrd, Ord, Debug)]
struct Order(i32);
#[derive(Component, PartialEq, Debug)]
struct Label(&'static str);

let mut world = World::new();
let a = world.spawn((Order(2), Label("second"))).id();
let b = world.spawn((Order(3), Label("third"))).id();
let c = world.spawn((Order(1), Label("first"))).id();
let mut entities = world.query::<(Entity, &Order, &Label)>()
    .iter(&world)
    .collect::<Vec<_>>();
// Sort the query results by their `Order` component before comparing
// to expected results. Query iteration order should not be relied on.
entities.sort_by_key(|e| e.1);
assert_eq!(entities, vec![
    (c, &Order(1), &Label("first")),
    (a, &Order(2), &Label("second")),
    (b, &Order(3), &Label("third")),
]);

pub fn query_filtered<Q, F>(&mut self) -> QueryState<Q, F>

where Q: WorldQuery, F: ReadOnlyWorldQuery,

Returns QueryState for the given filtered [WorldQuery], which is used to efficiently run queries on the World by storing and reusing the QueryState.

use bevy_ecs::{component::Component, entity::Entity, world::World, query::With};

#[derive(Component)]
struct A;
#[derive(Component)]
struct B;

let mut world = World::new();
let e1 = world.spawn(A).id();
let e2 = world.spawn((A, B)).id();

let mut query = world.query_filtered::<Entity, With<B>>();
let matching_entities = query.iter(&world).collect::<Vec<Entity>>();

assert_eq!(matching_entities, vec![e2]);

pub fn removed<T>(&self) -> impl Iterator<Item = Entity>

where T: Component,

Returns an iterator of entities that had components of type T removed since the last call to World::clear_trackers.

pub fn removed_with_id( &self, component_id: ComponentId ) -> impl Iterator<Item = Entity>

Returns an iterator of entities that had components with the given component_id removed since the last call to World::clear_trackers.

pub fn init_resource<R>(&mut self) -> ComponentId

where R: Resource + FromWorld,

Initializes a new resource and returns the [ComponentId] created for it.

If the resource already exists, nothing happens.

The value given by the FromWorld::from_world method will be used. Note that any resource with the Default trait automatically implements FromWorld, and those default values will be here instead.

pub fn insert_resource<R>(&mut self, value: R)

where R: Resource,

Inserts a new resource with the given value.

Resources are “unique” data of a given type. If you insert a resource of a type that already exists, you will overwrite any existing data.

pub fn init_non_send_resource<R>(&mut self) -> ComponentId

where R: 'static + FromWorld,

Initializes a new non-send resource and returns the [ComponentId] created for it.

If the resource already exists, nothing happens.

The value given by the FromWorld::from_world method will be used. Note that any resource with the Default trait automatically implements FromWorld, and those default values will be here instead.

Panics

Panics if called from a thread other than the main thread.

pub fn insert_non_send_resource<R>(&mut self, value: R)

where R: 'static,

Inserts a new non-send resource with the given value.

NonSend resources cannot be sent across threads, and do not need the Send + Sync bounds. Systems with NonSend resources are always scheduled on the main thread.

Panics

If a value is already present, this function will panic if called from a different thread than where the original value was inserted from.

pub fn remove_resource<R>(&mut self) -> Option<R>

where R: Resource,

Removes the resource of a given type and returns it, if it exists. Otherwise returns None.

pub fn remove_non_send_resource<R>(&mut self) -> Option<R>

where R: 'static,

Removes a !Send resource from the world and returns it, if present.

NonSend resources cannot be sent across threads, and do not need the Send + Sync bounds. Systems with NonSend resources are always scheduled on the main thread.

Returns None if a value was not previously present.

Panics

If a value is present, this function will panic if called from a different thread than where the value was inserted from.

pub fn contains_resource<R>(&self) -> bool

where R: Resource,

Returns true if a resource of type R exists. Otherwise returns false.

pub fn contains_non_send<R>(&self) -> bool

where R: 'static,

Returns true if a resource of type R exists. Otherwise returns false.

pub fn is_resource_added<R>(&self) -> bool

where R: Resource,

pub fn is_resource_changed<R>(&self) -> bool

where R: Resource,

pub fn resource<R>(&self) -> &R

where R: Resource,

Gets a reference to the resource of the given type

Panics

Panics if the resource does not exist. Use get_resource instead if you want to handle this case.

If you want to instead insert a value if the resource does not exist, use get_resource_or_insert_with.

pub fn resource_mut<R>(&mut self) -> Mut<'_, R>

where R: Resource,

Gets a mutable reference to the resource of the given type

Panics

Panics if the resource does not exist. Use get_resource_mut instead if you want to handle this case.

If you want to instead insert a value if the resource does not exist, use get_resource_or_insert_with.

pub fn get_resource<R>(&self) -> Option<&R>

where R: Resource,

Gets a reference to the resource of the given type if it exists

pub fn get_resource_mut<R>(&mut self) -> Option<Mut<'_, R>>

where R: Resource,

Gets a mutable reference to the resource of the given type if it exists

pub fn get_resource_or_insert_with<R>( &mut self, func: impl FnOnce() -> R ) -> Mut<'_, R>

where R: Resource,

Gets a mutable reference to the resource of type T if it exists, otherwise inserts the resource using the result of calling func.

pub fn non_send_resource<R>(&self) -> &R

where R: 'static,

Gets an immutable reference to the non-send resource of the given type, if it exists.

Panics

Panics if the resource does not exist. Use get_non_send_resource instead if you want to handle this case.

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn non_send_resource_mut<R>(&mut self) -> Mut<'_, R>

where R: 'static,

Gets a mutable reference to the non-send resource of the given type, if it exists.

Panics

Panics if the resource does not exist. Use get_non_send_resource_mut instead if you want to handle this case.

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn get_non_send_resource<R>(&self) -> Option<&R>

where R: 'static,

Gets a reference to the non-send resource of the given type, if it exists. Otherwise returns None.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn get_non_send_resource_mut<R>(&mut self) -> Option<Mut<'_, R>>

where R: 'static,

Gets a mutable reference to the non-send resource of the given type, if it exists. Otherwise returns None

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn insert_or_spawn_batch<I, B>( &mut self, iter: I ) -> Result<(), Vec<Entity>>

where I: IntoIterator, <I as IntoIterator>::IntoIter: Iterator<Item = (Entity, B)>, B: Bundle,

For a given batch of (Entity, Bundle) pairs, either spawns each Entity with the given bundle (if the entity does not exist), or inserts the Bundle (if the entity already exists). This is faster than doing equivalent operations one-by-one. Returns Ok if all entities were successfully inserted into or spawned. Otherwise it returns an Err with a list of entities that could not be spawned or inserted into. A “spawn or insert” operation can only fail if an Entity is passed in with an “invalid generation” that conflicts with an existing Entity.

Note

Spawning a specific entity value is rarely the right choice. Most apps should use World::spawn_batch. This method should generally only be used for sharing entities across apps, and only when they have a scheme worked out to share an ID space (which doesn’t happen by default).

use bevy_ecs::{entity::Entity, world::World, component::Component};
#[derive(Component)]
struct A(&'static str);
#[derive(Component, PartialEq, Debug)]
struct B(f32);

let mut world = World::new();
let e0 = world.spawn_empty().id();
let e1 = world.spawn_empty().id();
world.insert_or_spawn_batch(vec![
  (e0, (A("a"), B(0.0))), // the first entity
  (e1, (A("b"), B(1.0))), // the second entity
]);

assert_eq!(world.get::<B>(e0), Some(&B(0.0)));

pub fn resource_scope<R, U>( &mut self, f: impl FnOnce(&mut World, Mut<'_, R>) -> U ) -> U

where R: Resource,

Temporarily removes the requested resource from this World, then re-adds it before returning.

This enables safe simultaneous mutable access to both a resource and the rest of the World. For more complex access patterns, consider using SystemState.

Example

use bevy_ecs::prelude::*;
#[derive(Resource)]
struct A(u32);
#[derive(Component)]
struct B(u32);
let mut world = World::new();
world.insert_resource(A(1));
let entity = world.spawn(B(1)).id();

world.resource_scope(|world, mut a: Mut<A>| {
    let b = world.get_mut::<B>(entity).unwrap();
    a.0 += b.0;
});
assert_eq!(world.get_resource::<A>().unwrap().0, 2);

pub fn send_event<E>(&mut self, event: E)

where E: Event,

Sends an Event.

pub fn send_event_default<E>(&mut self)

where E: Event + Default,

Sends the default value of the Event of type E.

pub fn send_event_batch<E>(&mut self, events: impl IntoIterator<Item = E>)

where E: Event,

Sends a batch of Events from an iterator.

pub unsafe fn insert_resource_by_id( &mut self, component_id: ComponentId, value: OwningPtr<'_> )

Inserts a new resource with the given value. Will replace the value if it already existed.

You should prefer to use the typed API World::insert_resource where possible and only use this in cases where the actual types are not known at compile time.

Safety

The value referenced by value must be valid for the given [ComponentId] of this world.

pub unsafe fn insert_non_send_by_id( &mut self, component_id: ComponentId, value: OwningPtr<'_> )

Inserts a new !Send resource with the given value. Will replace the value if it already existed.

You should prefer to use the typed API World::insert_non_send_resource where possible and only use this in cases where the actual types are not known at compile time.

Panics

If a value is already present, this function will panic if not called from the same thread that the original value was inserted from.

Safety

The value referenced by value must be valid for the given [ComponentId] of this world.

pub fn increment_change_tick(&self) -> u32

pub fn read_change_tick(&self) -> u32

Reads the current change tick of this world.

If you have exclusive (&mut) access to the world, consider using change_tick(), which is more efficient since it does not require atomic synchronization.

pub fn change_tick(&mut self) -> u32

Reads the current change tick of this world.

This does the same thing as read_change_tick(), only this method is more efficient since it does not require atomic synchronization.

pub fn last_change_tick(&self) -> u32

pub fn check_change_ticks(&mut self)

Iterates all component change ticks and clamps any older than MAX_CHANGE_AGE. This prevents overflow and thus prevents false positives.

Note: Does nothing if the World counter has not been incremented at least CHECK_TICK_THRESHOLD times since the previous pass.

pub fn clear_all(&mut self)

Runs both clear_entities and clear_resources, invalidating all Entity and resource fetches such as Res, ResMut

pub fn clear_entities(&mut self)

Despawns all entities in this World.

pub fn clear_resources(&mut self)

Clears all resources in this World.

Note: Any resource fetch to this World will fail unless they are re-initialized, including engine-internal resources that are only initialized on app/world construction.

This can easily cause systems expecting certain resources to immediately start panicking. Use with caution.

impl World

pub fn get_resource_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>

Gets a pointer to the resource with the id [ComponentId] if it exists. The returned pointer must not be used to modify the resource, and must not be dereferenced after the immutable borrow of the World ends.

You should prefer to use the typed API World::get_resource where possible and only use this in cases where the actual types are not known at compile time.

pub fn get_resource_mut_by_id( &mut self, component_id: ComponentId ) -> Option<MutUntyped<'_>>

Gets a pointer to the resource with the id [ComponentId] if it exists. The returned pointer may be used to modify the resource, as long as the mutable borrow of the World is still valid.

You should prefer to use the typed API World::get_resource_mut where possible and only use this in cases where the actual types are not known at compile time.

pub fn get_non_send_by_id(&self, component_id: ComponentId) -> Option<Ptr<'_>>

Gets a !Send resource to the resource with the id [ComponentId] if it exists. The returned pointer must not be used to modify the resource, and must not be dereferenced after the immutable borrow of the World ends.

You should prefer to use the typed API World::get_resource where possible and only use this in cases where the actual types are not known at compile time.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn get_non_send_mut_by_id( &mut self, component_id: ComponentId ) -> Option<MutUntyped<'_>>

Gets a !Send resource to the resource with the id [ComponentId] if it exists. The returned pointer may be used to modify the resource, as long as the mutable borrow of the World is still valid.

You should prefer to use the typed API World::get_resource_mut where possible and only use this in cases where the actual types are not known at compile time.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn remove_resource_by_id(&mut self, component_id: ComponentId) -> Option<()>

Removes the resource of a given type, if it exists. Otherwise returns None.

You should prefer to use the typed API World::remove_resource where possible and only use this in cases where the actual types are not known at compile time.

pub fn remove_non_send_by_id(&mut self, component_id: ComponentId) -> Option<()>

Removes the resource of a given type, if it exists. Otherwise returns None.

You should prefer to use the typed API World::remove_resource where possible and only use this in cases where the actual types are not known at compile time.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn get_by_id( &self, entity: Entity, component_id: ComponentId ) -> Option<Ptr<'_>>

Retrieves an immutable untyped reference to the given entity’s Component of the given [ComponentId]. Returns None if the entity does not have a Component of the given type.

You should prefer to use the typed API World::get_mut where possible and only use this in cases where the actual types are not known at compile time.

Panics

This function will panic if it isn’t called from the same thread that the resource was inserted from.

pub fn get_mut_by_id( &mut self, entity: Entity, component_id: ComponentId ) -> Option<MutUntyped<'_>>

Retrieves a mutable untyped reference to the given entity’s Component of the given [ComponentId]. Returns None if the entity does not have a Component of the given type.

You should prefer to use the typed API World::get_mut where possible and only use this in cases where the actual types are not known at compile time.

impl World

pub fn add_schedule(&mut self, schedule: Schedule, label: impl ScheduleLabel)

Runs the Schedule associated with the label a single time.

The Schedule is fetched from the

pub fn run_schedule(&mut self, label: impl ScheduleLabel)

Runs the Schedule associated with the label a single time.

The Schedule is fetched from the Schedules resource of the world by its label, and system state is cached.

For simple testing use cases, call Schedule::run(&mut world) instead.

Panics

Panics if the requested schedule does not exist, or the Schedules resource was not added.

pub fn run_schedule_ref(&mut self, label: &(dyn ScheduleLabel + 'static))

Runs the Schedule associated with the label a single time.

Unlike the run_schedule method, this method takes the label by reference, which can save a clone.

The Schedule is fetched from the Schedules resource of the world by its label, and system state is cached.

For simple testing use cases, call Schedule::run(&mut world) instead.

Panics

Panics if the requested schedule does not exist, or the Schedules resource was not added.

Trait Implementations

impl Debug for World

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for World

fn default() -> World

Returns the “default value” for a type.

impl SystemParam for &World

type State = ()

Used to store data which persists across invocations of a system.

type Item<'w, 's> = &'w World

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state( _world: &mut World, system_meta: &mut SystemMeta ) -> <&World as SystemParam>::State

Registers any World access used by this [SystemParam] and creates a new instance of this param’s State.

unsafe fn get_param<'w, 's>( _state: &'s mut <&World as SystemParam>::State, _system_meta: &SystemMeta, world: &'w World, _change_tick: u32 ) -> <&World as SystemParam>::Item<'w, 's>

Safety

fn new_archetype( _state: &mut Self::State, _archetype: &Archetype, _system_meta: &mut SystemMeta )

For the specified [Archetype], registers the components accessed by this [SystemParam] (if applicable).

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this [SystemParam]’s state. This is used to apply Commands during apply_system_buffers.

impl<'w> ReadOnlySystemParam for &'w World

SAFETY: only reads world

impl Send for World

impl Sync for World