Struct World

Source

pub struct World { /* private fields */ }

Expand description

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

Implementations§

Source §

impl World

Source

pub fn new() -> World

Creates a new, empty world.

§Examples

use evenio::prelude::*;

let mut world = World::new();

Source

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

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

Source

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

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

Source

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

Source

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

Sends the Insert event.

This is equivalent to:

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

Source

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

Sends the Remove event.

This is equivalent to:

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

Source

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

Sends the Despawn event.

This is equivalent to:

world.send_to(entity, Despawn);

Source

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

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

Source

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

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

Source

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

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

Source

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

Source

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

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

Source

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.

Source

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:

The RemoveComponent event is sent.
All entities with the component are despawned.
All handlers that reference the component are removed.
The corresponding Insert events for the component are removed.
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));

Source

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

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

Source

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

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

Source

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.

Source

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.

Source

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:

The RemoveTargetedEvent event is sent.
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));

Source

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:

The RemoveTargetedEvent event is sent.
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));

Source