Struct World

pub struct World { /* private fields */ }

The World struct holds all the data of a world.

Implementations

impl World

pub fn new() -> World

pub fn add_resource( &mut self, resource_data: impl SendSync, ) -> Result<(), ResourceError>

This adds a resource to the World’s Resources. Resources are like global components and can be used for things like frametime and other things systems should have access to.

Errors

If there is already a resource of the provided resource’s type present, an error variant is returned.

Example

    world.add_resource(String::from("This is an example resource!"))?;

pub fn remove_resource<T>(&mut self)

where T: SendSync,

Removes the requested resource from the World’s Resources if it exists, otherwise does nothing.

Example

    world.add_resource(String::from("This is an example resource!"))?;
    world.remove_resource::<String>();

pub fn get_resource<T>( &self, ) -> Result<MappedRwLockReadGuard<'_, RawRwLock, T>, ResourceError>

where T: SendSync,

Gets a resource as readable.

Errors

If the resource doesn’t exist, an error variant is returned.

Example

    world.add_resource(20_u32)?;

    // In this example we print our resource
    println!("{}", world.get_resource::<u32>()?);

pub fn get_resource_mut<T>( &self, ) -> Result<MappedRwLockWriteGuard<'_, RawRwLock, T>, ResourceError>

where T: SendSync,

Gets a resource as writable.

Errors

If the resource doesn’t exist, an error variant is returned.

Example

    world.add_resource(20_u32);

    // resource plus one
    *world.get_resource_mut::<u32>().unwrap() += 1;

pub fn register_component<T>(&mut self)

where T: SendSync,

Register a component.

pub fn create_entity( &self, components: impl ComponentSet, ) -> Result<Entity, EntityError>

Spawn an entity with components. The maximum size for tuples provided to this method is 10.

Errors

Returns an error variant if a provided component is not registered in the world.

Example

    // spawn entity
    world.create_entity((30_u32, 60.0_f32))?;

    // You can also bind the entity to access it later on.
    let entity = world.create_entity((20_u32, 30.0_f32))?;

    // When only adding one component, put a comma after it for rust to recognise it as a tuple.
    world.create_entity((20_u32,))?;

pub fn delete_entity(&self, entity: Entity) -> Result<(), EntityError>

Delete an Entity from the world. See QueryEntity::delete if you are using a query, which is the recommended way to do this.

Errors

Can only delete entities if they exist. Otherwise an error variant is returned.

Example

    let entity = world.create_entity((10_u32,))?;

    // delete the entity
    world.delete_entity(entity)?;

pub fn assign_components( &self, components: impl ComponentSet, entity: Entity, ) -> Result<(), EntityError>

Assign components to an Entity. See QueryEntity::assign_components if you are using a query, which is the recommended way to do this.

Errors

This can fail when either the entity doesn’t exist, or one of the components is not registered. Then aan error variant will be returned.

Example

    let entity = world.create_entity((5_u32,))?;

    // assign more components
    world.assign_components((30.0_f32, String::from("hello world")), entity)?;

pub fn delete_component<C>(&self, entity: Entity) -> Result<(), EntityError>

where C: SendSync,

Delete components from an Entity if it exists. See QueryEntity::delete_component if you are using a query, which is the recommended way to do this.

Errors

This fails if the component is not registered in the world, in which case an error variant is returned.

Example

fn main() -> Result<(), magma_ecs::error::EntityError> {
    let entity = world.create_entity((5_u32, 10.0_f32))?;

    // delete a component
    world.delete_component::<u32>(entity)?;

pub fn get_component<C>( &self, entity: Entity, ) -> Result<MappedRwLockReadGuard<'_, RawRwLock, C>, EntityError>

where C: SendSync,

Get a component as readable from an Entity.

Errors

If the requested component is either not registered on the World or the entity doesn’t have that component, an error variant is returned.

Example

    // create an entity with u32
    let entity = world.create_entity((30_u32,))?;

    // get the component as readable
    world.get_component::<u32>(entity)?;

pub fn get_component_mut<C>( &self, entity: Entity, ) -> Result<MappedRwLockWriteGuard<'_, RawRwLock, C>, EntityError>

where C: SendSync,

Get a component as writable from an Entity.

Errors

If the requested component is either not registered on the World or the entity doesn’t have that component, an error variant is returned.

Example

    // create an entity with u32
    let entity = world.create_entity((30_u32,))?;

    // get the component as writable and add 1
    *world.get_component_mut::<u32>(entity)? += 1;

pub fn query<Q>(&self) -> Result<Vec<QueryEntity<'_>>, EntityError>

where Q: ComponentSet,

Query for entities with specified components. Also see the methods of QueryEntity.

Errors

If any provided component is not registered in the world, an error variant is returned.

Example

    world.create_entity((30_u32, 20.0_f32))?;
    world.create_entity((20_u32,))?;

    // Only the first entity will be in our query, because we searched for (u32, f32).
    let query = world.query::<(u32, f32)>()?;

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.