Struct evenio::world::World

source ·

pub struct World { /* private fields */ }

Expand description

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

Implementations§

source §

impl World

source

pub fn new() -> Self

Creates a new, empty world.

§Examples

use evenio::prelude::*;

let mut world = World::new();

source

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

Broadcast an event to all systems in this world.

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

§Examples

use evenio::prelude::*;

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

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

let mut world = World::new();

world.add_system(my_system);
world.send(MyEvent(123));

Output:

got event: 123

source

pub fn send_many<F, R>(&mut self, f: F) -> R
where F: FnOnce(Sender<'_>) -> R,

Enqueue an arbitrary number of events and send them all at once.

The closure f is passed a Sender used to add events to a queue. Once the closure returns, all enqueued events are broadcasted as described by send.

§Examples

world.send_many(|mut sender| {
    sender.send(A);
    sender.send(B);
});

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 is not 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: Component>(&mut self, entity: EntityId, component: C)

Sends the Insert event.

This is equivalent to:

world.send(Insert::new(entity, component));

source

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

Sends the Remove event.

This is equivalent to:

world.send(Remove::<C>::new(entity));

source

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

Sends the Despawn event.

This is equivalent to:

world.send(Despawn(entity));

source

pub fn get_component<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_component::<MyComponent>(e),
    Some(&MyComponent(123))
);

source

pub fn get_component_mut<C: Component>( &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_component_mut::<MyComponent>(e),
    Some(&mut MyComponent(123))
);

source

pub fn add_system<S: IntoSystem<M>, M>(&mut self, system: S) -> SystemId

Adds a new system to the world, returns its SystemId, and sends the AddSystem event to signal its creation.

If the system already exists (as determined by System::type_id) then the SystemId of the existing system is returned and no event is sent.

§Panics

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

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

§Examples

use evenio::prelude::*;

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

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

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

source

pub fn remove_system(&mut self, system: SystemId) -> Option<SystemInfo>

Removes a system from the world, returns its SystemInfo, and sends the RemoveSystem event. If the system ID is invalid, then None is returned and no event is sent.

§Example

use evenio::prelude::*;

let mut world = World::new();

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

let info = world.remove_system(system_id).unwrap();

assert_eq!(info.id(), system_id);
assert!(!world.systems().contains(system_id));

source

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

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 systems 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 system = world.add_system(|_: Receiver<E>, _: Fetcher<&C>| {});

assert!(world.components().contains(component));
assert!(world.systems().contains(system));

world.remove_component(component);

assert!(!world.components().contains(component));
// System was also removed because it references `C` in its `Fetcher`.
assert!(!world.systems().contains(system));

source

pub fn add_event<E: Event>(&mut self) -> EventId

Adds the event E to the world, returns its EventId, and sends the AddEvent event to signal its creation.

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

§Examples

use evenio::prelude::*;

#[derive(Event)]
struct MyEvent;

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

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

source

pub unsafe fn add_event_with_descriptor( &mut self, desc: EventDescriptor ) -> EventId

Adds an event described by a given EventDescriptor.

Like add_event, an AddEvent event is sent if the event is newly added. If the TypeId of the event matches an existing event, then the existing event’s EventId 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’s documentation for more information.

source

pub fn remove_event(&mut self, event: EventId) -> Option<EventInfo>

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

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

The RemoveEvent event is sent.
All systems that send or receive the event are removed.

§Examples

use evenio::prelude::*;

#[derive(Event)]
struct MyEvent;

let mut world = World::new();

let id = world.add_event::<MyEvent>();
world.remove_event(id);

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

source