Struct bevy::ecs::world::World

pub struct World { /* private fields */ }
Expand description

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

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

Retrieves this World’s unique ID

Retrieves this world’s Entities collection

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

Retrieves this world’s Archetypes collection

Retrieves this world’s Components collection

Retrieves this world’s Storages collection

Retrieves this world’s Bundles collection

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

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

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.

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())

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);

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;

Returns the components of an Entity through ComponentInfo.

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).

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);

Returns an Entity iterator of current entities.

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

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;

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);

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);

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);

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);

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;

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());

Clears component tracker state

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")),
]);

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]);

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

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

Inserts a new resource with standard starting values.

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.

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.

Inserts a new non-send resource with standard starting values.

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.

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

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

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

Safety

Only remove NonSend resources from the main thread as they cannot be sent across threads

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

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.

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.

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

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

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

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

Safety

This will allow aliased mutable access to the given resource type. The caller must ensure that there is either only one mutable access or multiple immutable accesses at a time.

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.

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.

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

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

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

Safety

This will allow aliased mutable access to the given non-send resource type. The caller must ensure that there is either only one mutable access or multiple immutable accesses at a time.

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)));

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);

Sends an Event.

Sends the default value of the Event of type E.

Sends a batch of Events from an iterator.

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 component_id must exist in this World

Gets a 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.

Gets a 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.

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.

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.

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.

Trait Implementations

Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait. Read more
Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait. Read more
Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more
Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s. Read more
Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait. Read more

Returns the argument unchanged.

Creates Self using data from the given World
Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more