Struct evenio::world::World

pub struct World { /* private fields */ }

A container for all data in the ECS. This includes entities, components, handlers, and events.

Implementations

impl World

pub fn new() -> Self

Creates a new, empty world.

Examples

use evenio::prelude::*;

let mut world = World::new();

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

Broadcast a global event to all handlers in this world. All handlers which listen for this event

Any events sent by handlers will also broadcast. This process continues recursively until all events have finished broadcasting.

See also World::send_to to send a TargetedEvent.

Examples

use evenio::prelude::*;

#[derive(GlobalEvent)]
struct MyEvent(i32);

fn my_handler(r: Receiver<MyEvent>) {
    println!("got event: {}", r.event.0);
}

let mut world = World::new();

world.add_handler(my_handler);
world.send(MyEvent(123));

Output:

got event: 123

pub fn send_to<E: TargetedEvent>(&mut self, target: EntityId, event: E)

Broadcast a targeted event to all handlers in this world.

Any events sent by handlers will also broadcast. This process continues recursively until all events have finished broadcasting.

See also World::send to send a GlobalEvent.

Examples

use evenio::prelude::*;

#[derive(TargetedEvent)]
struct MyEvent(i32);

fn my_handler(r: Receiver<MyEvent, EntityId>) {
    println!("target of received event is {:?}", r.query);
}

let mut world = World::new();

world.add_handler(my_handler);

let target = world.spawn();

// Send my event to `target` entity.
world.send_to(target, MyEvent(123));

pub fn spawn(&mut self) -> EntityId

Creates a new entity, returns its EntityId, and sends the Spawn event to signal its creation.

The new entity is spawned without any components attached. The returned EntityId will not have been used by any previous entities in this world.

Examples

use evenio::prelude::*;

let mut world = World::new();
let id = world.spawn();

assert!(world.entities().contains(id));

pub fn insert<C: Component>(&mut self, entity: EntityId, component: C)

Sends the Insert event.

This is equivalent to:

world.send_to(entity, Insert(component));

pub fn remove<C: Component>(&mut self, entity: EntityId)

Sends the Remove event.

This is equivalent to:

world.send_to(entity, Remove::<C>);

pub fn despawn(&mut self, entity: EntityId)

Sends the Despawn event.

This is equivalent to:

world.send_to(entity, Despawn);

pub fn get<C: Component>(&self, entity: EntityId) -> Option<&C>

Gets an immutable reference to component C on entity. Returns None if entity doesn’t exist or doesn’t have the requested component.

Examples

use evenio::prelude::*;

#[derive(Component, PartialEq, Debug)]
struct MyComponent(i32);

let mut world = World::new();

let e = world.spawn();
world.insert(e, MyComponent(123));

assert_eq!(world.get::<MyComponent>(e), Some(&MyComponent(123)));

pub fn get_mut<C: Component<Mutability = Mutable>>( &mut self, entity: EntityId ) -> Option<&mut C>

Gets a mutable reference to component C on entity. Returns None if entity doesn’t exist or doesn’t have the requested component.

Examples

use evenio::prelude::*;

#[derive(Component, PartialEq, Debug)]
struct MyComponent(i32);

let mut world = World::new();

let e = world.spawn();
world.insert(e, MyComponent(123));

assert_eq!(world.get_mut::<MyComponent>(e), Some(&mut MyComponent(123)));

pub fn add_handler<H: IntoHandler<M>, M>(&mut self, handler: H) -> HandlerId

Adds a new handler to the world, returns its HandlerId, and sends the AddHandler event to signal its creation.

If the handler already exists (as determined by Handler::type_id) then the HandlerId of the existing handler is returned and no event is sent.

Panics

Panics if the configuration of the handler is invalid. This can occur when, for instance, the handler does not specify an event to receive.

world.add_handler(|| {}); // Panics

Examples

use evenio::prelude::*;

fn my_handler(_: Receiver<MyEvent>) {};

let mut world = World::new();
let id = world.add_handler(my_handler);

assert!(world.handlers().contains(id));

pub fn remove_handler(&mut self, handler: HandlerId) -> Option<HandlerInfo>

Removes a handler from the world, returns its HandlerInfo, and sends the RemoveHandler event. If the handler ID is invalid, then None is returned and no event is sent.

Example

use evenio::prelude::*;

let mut world = World::new();

let handler_id = world.add_handler(|_: Receiver<MyEvent>| {});

let info = world.remove_handler(handler_id).unwrap();

assert_eq!(info.id(), handler_id);
assert!(!world.handlers().contains(handler_id));

pub fn add_component<C: Component>(&mut self) -> ComponentId

Adds the component C to the world, returns its ComponentId, and sends the AddComponent event to signal its creation.

If the component already exists, then the ComponentId of the existing component is returned and no event is sent.

Examples

use evenio::prelude::*;

#[derive(Component)]
struct MyComponent;

let mut world = World::new();
let id = world.add_component::<MyComponent>();

assert_eq!(id, world.add_component::<MyComponent>());

pub unsafe fn add_component_with_descriptor( &mut self, desc: ComponentDescriptor ) -> ComponentId

Adds a component described by a given ComponentDescriptor.

Like add_component, an AddComponent event is sent if the component is newly added. If the TypeId of the component matches an existing component, then the existing component’s ComponentId is returned and no event is sent.

Safety

• If the component is given a TypeId, then the layout and drop function must be compatible with the Rust type identified by the type ID.
• Drop function must be safe to call with a pointer to the component as described by DropFn’s documentation.

pub fn remove_component( &mut self, component: ComponentId ) -> Option<ComponentInfo>

Removes a component from the world and returns its ComponentInfo. If the component ID is invalid, then None is returned and the function has no effect.

Removing a component has the following effects in the order listed:

1. The RemoveComponent event is sent.
2. All entities with the component are despawned.
3. All handlers that reference the component are removed.
4. The corresponding Insert events for the component are removed.
5. The corresponding Remove events for the component are removed.

Examples

let component = world.add_component::<C>();
let handler = world.add_handler(|_: Receiver<E>, _: Fetcher<&C>| {});

assert!(world.components().contains(component));
assert!(world.handlers().contains(handler));

world.remove_component(component);

assert!(!world.components().contains(component));
// Handler was also removed because it references `C` in its `Fetcher`.
assert!(!world.handlers().contains(handler));

pub fn add_global_event<E: GlobalEvent>(&mut self) -> GlobalEventId

Adds the global event E to the world, returns its GlobalEventId, and sends the AddGlobalEvent event to signal its creation.

If the event already exists, then the GlobalEventId of the existing event is returned and no event is sent.

Examples

use evenio::prelude::*;

#[derive(GlobalEvent)]
struct MyEvent;

let mut world = World::new();
let id = world.add_global_event::<MyEvent>();

assert_eq!(id, world.add_global_event::<MyEvent>());

pub fn add_targeted_event<E: TargetedEvent>(&mut self) -> TargetedEventId

Adds the targeted event E to the world, returns its TargetedEventId, and sends the AddTargetedEvent event to signal its creation.

If the event already exists, then the TargetedEventId of the existing event is returned and no event is sent.

Examples

use evenio::prelude::*;

#[derive(TargetedEvent)]
struct MyEvent;

let mut world = World::new();
let id = world.add_targeted_event::<MyEvent>();

assert_eq!(id, world.add_targeted_event::<MyEvent>());

pub unsafe fn add_global_event_with_descriptor( &mut self, desc: EventDescriptor ) -> GlobalEventId

Adds a global event described by a given EventDescriptor.

Like add_global_event, an AddGlobalEvent event is sent if the event is newly added. If the TypeId of the event matches an existing global event, then the existing event’s GlobalEventId is returned and no event is sent.

Safety

• If the event is given a TypeId, then the layout and drop function must be compatible with the Rust type identified by the type ID.
• Drop function must be safe to call with a pointer to the event as described by DropFn’s documentation.
• The event’s kind must be correct for the descriptor. See EventKind for more information.

pub unsafe fn add_targeted_event_with_descriptor( &mut self, desc: EventDescriptor ) -> TargetedEventId

Adds a targeted event described by a given EventDescriptor.

Like add_targeted_event, an AddTargetedEvent event is sent if the event is newly added. If the TypeId of the event matches an existing targeted event, then the existing event’s GlobalEventId is returned and no event is sent.

Safety

• If the event is given a TypeId, then the layout and drop function must be compatible with the Rust type identified by the type ID.
• Drop function must be safe to call with a pointer to the event as described by DropFn’s documentation.
• The event’s kind must be correct for the descriptor. See EventKind for more information.

pub fn remove_global_event( &mut self, event: GlobalEventId ) -> Option<GlobalEventInfo>

Removes a global event from the world and returns its GlobalEventInfo. If the event ID is invalid, then None is returned and the function has no effect.

Removing an event has the following additional effects in the order listed:

1. The RemoveTargetedEvent event is sent.
2. All handlers that send or receive the event are removed.

Examples

use evenio::prelude::*;

#[derive(GlobalEvent)]
struct MyEvent;

let mut world = World::new();

let id = world.add_global_event::<MyEvent>();
world.remove_global_event(id);

assert!(!world.global_events().contains(id));

pub fn remove_targeted_event( &mut self, event: TargetedEventId ) -> Option<TargetedEventInfo>

Removes a targeted event from the world and returns its TargetedEventInfo. If the event ID is invalid, then None is returned and the function has no effect.

Removing an event has the following additional effects in the order listed:

1. The RemoveTargetedEvent event is sent.
2. All handlers that send or receive the event are removed.

Examples

use evenio::prelude::*;

#[derive(TargetedEvent)]
struct MyEvent;

let mut world = World::new();

let id = world.add_targeted_event::<MyEvent>();
world.remove_targeted_event(id);

assert!(!world.targeted_events().contains(id));

pub fn entities(&self) -> &Entities

Returns the Entities for this world.

pub fn components(&self) -> &Components

Returns the Components for this world.

pub fn handlers(&self) -> &Handlers

Returns the Handlers for this world.

pub fn archetypes(&self) -> &Archetypes

Returns the Archetypes for this world.

pub fn global_events(&self) -> &GlobalEvents

Returns the GlobalEvents for this world.

pub fn targeted_events(&self) -> &TargetedEvents

Returns the TargetedEvents for this world.

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

Returns a new UnsafeWorldCell with permission to read all data in this world.

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

Returns a new UnsafeWorldCell with permission to read and write all data in this world.

Trait Implementations

impl Debug for World

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

Formats the value using the given formatter.

impl Default for World

fn default() -> Self

Returns the “default value” for a type.