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 purge_entity(&self, entity: Entity) -> Result<(), EntityError>

Delete an Entity clearing the underlying component storage. This method of deletion is slower, but may be desired sometimes when it is nessesary to drop the component data. See QueryEntity::purge if you are using a query, which is the recommended way to do this.

Errors

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

Example

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

    // purge the entity
    world.purge_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 purge_component<C>(&self, entity: Entity) -> Result<(), EntityError>

where C: SendSync,

Delete a component from an Entity clearing the underlying component storage. This method of deletion is slower, but may sometimes be desired when the component data should be dropped. See QueryEntity::purge_component if you are using a query, which is the recommended way to do this.

Errors

Returns an error variant if the component type is not registered in the World.

Example

    // create entity with u32 and f32
    let entity = world.create_entity((30_u32, 20.0_f32))?;

    // purge u32 component from entity
    world.purge_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)>()?;

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

where Q: ComponentSet,

Query for entities with specified components that have just been added. This only returns entities whose components have been added since the last time they where queried. 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_added::<(u32, f32)>()?;

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

where Q: ComponentSet,

Query for entities with specified components that have just been removed. This returns entities who, or whose components, have been removed since the last time they where queried. Also see the methods of QueryEntity.

Errors

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

Example

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

    world.delete_entity(entity).unwrap();

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

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

where Q: ComponentSet,

Query for entities with specified components that have just been changed. This returns entities whose components have been assigned or mutably borrowed since the last time they where queried. 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_changed::<(u32, f32)>()?;

pub fn register_event<T>(&mut self)

where T: SendSync + Clone,

Register an event type.

pub fn send_event<T>(&self, event: T) -> Result<(), EventError>

where T: SendSync + Clone,

Send an event

Errors

This function will return an error if the event type is not registered.

pub fn get_pending_events(&self) -> Vec<TypeId>

Returns the TypeIds of pending events.

pub fn poll_events<T>(&self) -> Result<Vec<T>, EventError>

where T: SendSync + Clone,

Returns the pending events of type T as a Vec<T>.

Errors

This function will return an error if the event type is not registered.

pub fn clear_events(&self)

Clears pending events.

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.