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

A Resource container, which provides methods to insert, access and manage the contained resources.

Many methods take &self which works because everything is stored with interior mutability. In case you violate the borrowing rules of Rust (multiple reads xor one write), you will get a panic.

Use with Specs

If you’re using this from the Specs ECS library, there are two things to be aware of:

  1. There are many utility methods Specs provides. To use them, you need to import specs::WorldExt.
  2. You should not use World::empty, but rather specs::WorldExt::new. The latter can simply be called using World::new(), as long as WorldExt is imported.

Resource Ids

Resources are identified by ResourceIds, which consist of a TypeId.

Implementations

Creates a new, empty resource container.

Note that if you’re using Specs, you should use WorldExt::new instead.

Inserts a resource into this container. If the resource existed before, it will be overwritten.

Examples

Every type satisfying Any + Send + Sync automatically implements Resource, thus can be added:

struct MyRes(i32);

When you have a resource, simply insert it like this:

use shred::World;

let mut world = World::empty();
world.insert(MyRes(5));

Removes a resource of type R from the World and returns its ownership to the caller. In case there is no such resource in this World, None will be returned.

Use this method with caution; other functions and systems might assume this resource still exists. Thus, only use this if you’re sure no system will try to access this resource after you removed it (or else you will get a panic).

Returns true if the specified resource type R exists in self.

Returns true if the specified resource type exists in self.

Returns an entry for the resource with type R.

Gets SystemData T from the World. This can be used to retrieve data just like in Systems.

This will not setup the system data, i.e. resources fetched here must exist already.

Examples

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();
world.insert(Timer);
world.insert(AnotherResource);
let system_data: (Read<Timer>, Read<AnotherResource>) = world.system_data();
Panics
  • Panics if T is already borrowed in an incompatible way.

Sets up system data T for fetching afterwards.

Most SystemData implementations will insert a sensible default value, by implementing SystemData::setup. However, it is not guaranteed to do that; if there is no sensible default, setup might not do anything.

Examples
use shred::{Read, World};

#[derive(Default)]
struct MyCounter(u32);

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();
assert!(!world.has_value::<MyCounter>());

// `Read<MyCounter>` requires a `Default` implementation, and uses
// that to initialize the resource
world.setup::<Read<MyCounter>>();
assert!(world.has_value::<MyCounter>());

Here’s another example, showing the case where no resource gets initialized:

use shred::{ReadExpect, World};

struct MyCounter(u32);

// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();

world.setup::<ReadExpect<MyCounter>>();

Executes f once, right now and with the specified system data.

This sets up the system data f expects, fetches it and then executes f. This is essentially like a one-time System.

This is especially useful if you either need a lot of system data or, with Specs, if you want to build an entity and for that you need to access resources first - just fetching the resources and building the entity would cause a double borrow.

Calling this method is equivalent to:

{
    // note the extra scope
    world.setup::<MySystemData>();
    let my_data: MySystemData = world.system_data();
    my_data.do_something();
}
Examples
// NOTE: If you use Specs, use `World::new` instead.
let mut world = World::empty();

#[derive(Default)]
struct MyRes {
    field: i32,
}

world.exec(|(mut my_res,): (Write<MyRes>,)| {
    assert_eq!(my_res.field, 0);
    my_res.field = 5;
});

assert_eq!(world.fetch::<MyRes>().field, 5);

Fetches the resource with the specified type T or panics if it doesn’t exist.

Panics

Panics if the resource doesn’t exist. Panics if the resource is being accessed mutably.

Like fetch, but returns an Option instead of inserting a default value in case the resource does not exist.

Like try_fetch, but fetches the resource by its ResourceId which allows using a dynamic ID.

This is usually not what you need; please read the type-level documentation of ResourceId.

Panics

This method panics if id refers to a different type ID than T.

Fetches the resource with the specified type T mutably.

Please see fetch for details.

Panics

Panics if the resource doesn’t exist. Panics if the resource is already being accessed.

Like fetch_mut, but returns an Option instead of inserting a default value in case the resource does not exist.

Like try_fetch_mut, but fetches the resource by its ResourceId which allows using a dynamic ID.

This is usually not what you need; please read the type-level documentation of ResourceId.

Panics

This method panics if id refers to a different type ID than T.

Internal function for inserting resources, should only be used if you know what you’re doing.

This is useful for inserting resources with a custom ResourceId.

Panics

This method panics if id refers to a different type ID than R.

Internal function for removing resources, should only be used if you know what you’re doing.

This is useful for removing resources with a custom ResourceId.

Panics

This method panics if id refers to a different type ID than R.

Internal function for fetching resources, should only be used if you know what you’re doing.

Retrieves a resource without fetching, which is cheaper, but only available with &mut self.

Retrieves a resource without fetching, which is cheaper, but only available with &mut self.

Trait Implementations

Returns the “default value” for a type. Read more

Constructs a new World instance.

Registers a new component, adding the component storage. Read more

Registers a new component with a given storage. Read more

👎 Deprecated since 0.15.0:

use World::insert instead

Adds a resource to the world. Read more

Fetches a component storage for reading. Read more

Fetches a component storage for writing. Read more

Fetches a resource for reading. Read more

Fetches a resource for writing. Read more

Convenience method for fetching entities. Read more

Convenience method for fetching entities.

Allows building an entity with its components. Read more

Allows building an entity with its components. Read more

Returns an iterator for entity creation. This makes it easy to create a whole collection of them. Read more

Deletes an entity and its components.

Deletes the specified entities and their components.

Deletes all entities and their components.

Checks if an entity is alive. Please note that atomically created or deleted entities (the ones created / deleted with the Entities struct) are not handled by this method. Therefore, you should have called maintain() before using this method. Read more

Merges in the appendix, recording all the dynamically created and deleted entities into the persistent generations vector. Also removes all the abandoned components. Read more

Fetches a component storage for reading. Read more

Fetches a component storage for writing. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Tries to create the default.

Calls try_default and panics on an error case.

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.