Trait EcsEntry

pub trait EcsEntry {
    // Required methods
    fn add_system<T, Sys>(
        &mut self,
        desc: T,
    ) -> WithResult<&mut Self, SystemId, EcsError<SystemDesc<Sys>>>
       where T: Into<SystemDesc<Sys>>,
             Sys: System;
    fn add_once_system<T, Req, F>(
        &mut self,
        sys: T,
    ) -> WithResult<&mut Self, SystemId, EcsError<SystemDesc<FnOnceSystem<Req, F>>>>
       where T: Into<FnOnceSystem<Req, F>>,
             FnOnceSystem<Req, F>: System;
    fn unregister_system(
        &mut self,
        sid: SystemId,
    ) -> WithResult<&mut Self, (), EcsError>;
    fn activate_system(
        &mut self,
        target: SystemId,
        at: InsertPos,
        live: Tick,
    ) -> WithResult<&mut Self, (), EcsError>;
    fn inactivate_system(
        &mut self,
        sid: SystemId,
    ) -> WithResult<&mut Self, (), EcsError>;
    fn register_entity(
        &mut self,
        desc: EntityReg,
    ) -> WithResult<&mut Self, EntityIndex, EcsError>;
    fn unregister_entity<C>(
        &mut self,
    ) -> WithResult<&mut Self, Box<dyn ContainEntity>, EcsError>
       where C: Components;
    fn add_entity<E>(
        &mut self,
        ei: EntityIndex,
        value: E,
    ) -> WithResult<&mut Self, EntityId, EcsError<E>>
       where E: Entity;
    fn remove_entity(
        &mut self,
        eid: EntityId,
    ) -> WithResult<&mut Self, (), EcsError>;
    fn add_resource<T>(
        &mut self,
        desc: T,
    ) -> WithResult<&mut Self, ResourceIndex, EcsError<ResourceDesc>>
       where T: Into<ResourceDesc>;
    fn remove_resource<R>(
        &mut self,
    ) -> WithResult<&mut Self, Option<R>, EcsError>
       where R: Resource;
    fn get_resource<R>(&self) -> Option<&R>
       where R: Resource;
    fn get_resource_mut<R>(&mut self) -> Option<&mut R>
       where R: Resource;
    fn get_resource_index<R>(&self) -> Option<ResourceIndex>
       where R: Resource;
    fn execute_commands<T>(
        &mut self,
        cmds: T,
    ) -> WithResult<&mut Self, (), Box<dyn Error + Send + Sync + 'static>>
       where T: HelpExecuteManyCommands;
    fn execute_command<F, R>(
        &mut self,
        f: F,
    ) -> WithResult<&mut Self, (), Box<dyn Error + Send + Sync + 'static>>
       where F: FnOnce(Commander<'_>) -> R,
             R: Command;
    fn errors(&mut self) -> Vec<Box<dyn Error + Send + Sync + 'static>>;

    // Provided methods
    fn add_systems<T, Systems>(
        &mut self,
        descs: T,
    ) -> WithResult<&mut Self, (), EcsError>
       where T: HelpAddManySystems<Systems> { ... }
    fn add_once_systems<T, Once>(
        &mut self,
        descs: T,
    ) -> WithResult<&mut Self, (), EcsError>
       where T: HelpAddManyOnce<Once> { ... }
    fn register_entity_of<T>(
        &mut self,
    ) -> WithResult<&mut Self, EntityIndex, EcsError>
       where T: AsEntityReg { ... }
    fn add_resources<T>(
        &mut self,
        descs: T,
    ) -> WithResult<&mut Self, (), EcsError>
       where T: HelpAddManyResources { ... }
}

Common interafaces that ECS instance should provide to clients.

ECS instance should provide some methods for adding/removing entities, resources, and systems. Of cource compoenets are included in entities. Moreover, ECS insance is required to be able to execute commands without wrapping them in systems.

Required Methods

fn add_system<T, Sys>( &mut self, desc: T, ) -> WithResult<&mut Self, SystemId, EcsError<SystemDesc<Sys>>>

where T: Into<SystemDesc<Sys>>, Sys: System,

Adds the given system.

Examples

use my_ecs::prelude::*;

fn system() { /* ... */ }

Ecs::default(WorkerPool::new(), [])
    .add_system(system)
    .unwrap();

fn add_once_system<T, Req, F>( &mut self, sys: T, ) -> WithResult<&mut Self, SystemId, EcsError<SystemDesc<FnOnceSystem<Req, F>>>>

where T: Into<FnOnceSystem<Req, F>>, FnOnceSystem<Req, F>: System,

Adds the given FnOnce system.

Examples

use my_ecs::prelude::*;

let s = "string0".to_owned();
let system = move || { drop(s); };

Ecs::default(WorkerPool::new(), [])
    .add_once_system(system)
    .unwrap();

fn unregister_system( &mut self, sid: SystemId, ) -> WithResult<&mut Self, (), EcsError>

Unregisters an inactive system for the given system id.

Examples

use my_ecs::prelude::*;

let mut ecs = Ecs::default(WorkerPool::new(), []);

// Adds an inactive empty system.
let desc = SystemDesc::new().with_activation(0, InsertPos::Back);
let sid = ecs.add_system(desc).unwrap();

let res = ecs.unregister_system(sid);
assert!(res.is_ok());

fn activate_system( &mut self, target: SystemId, at: InsertPos, live: Tick, ) -> WithResult<&mut Self, (), EcsError>

Activates a system for the given system id if it’s not active.

If the system is already active, returns error.

Examples

use my_ecs::prelude::*;

let mut ecs = Ecs::default(WorkerPool::new(), []);

// Active system cannot be activated again.
let sid = ecs.add_system(|| { /* ... */ }).unwrap();
let res = ecs.activate_system(sid, InsertPos::Back, 2);
assert!(res.is_err());

// Adds an inactive empty system.
let desc = SystemDesc::new().with_activation(0, InsertPos::Back);
let sid = ecs.add_system(desc).unwrap();
let res = ecs.activate_system(sid, InsertPos::Back, 2);
assert!(res.is_ok());

fn inactivate_system( &mut self, sid: SystemId, ) -> WithResult<&mut Self, (), EcsError>

Inactivates a system for the given system id.

If the system is already inactive, nothing takes place and returns Ok.

Examples

use my_ecs::prelude::*;

let mut ecs = Ecs::default(WorkerPool::new(), []);

// Inactivates an inactive system takes no effect.
let desc = SystemDesc::new().with_activation(0, InsertPos::Back);
let sid = ecs.add_system(desc).unwrap();
let res = ecs.inactivate_system(sid);
assert!(res.is_ok());

// Inactivates an active system.
let sid = ecs.add_system(|| { /* ... */ }).unwrap();
let res = ecs.inactivate_system(sid);
assert!(res.is_ok());

fn register_entity( &mut self, desc: EntityReg, ) -> WithResult<&mut Self, EntityIndex, EcsError>

Registers an entity type from the given descriptor.

Examples

use my_ecs::prelude::*;

#[derive(Component)] struct C;

let mut desc = EntityReg::new(
    Some(EntityName::new("my-entity".into())),
    Box::new(SparseSet::<std::hash::RandomState>::new()),
);
desc.add_component_of::<C>();

Ecs::default(WorkerPool::new(), [])
    .register_entity(desc)
    .unwrap();

fn unregister_entity<C>( &mut self, ) -> WithResult<&mut Self, Box<dyn ContainEntity>, EcsError>

where C: Components,

Unregisters an entity type.

Examples

use my_ecs::prelude::*;

#[derive(Entity)] struct E { a: Ca, b: Cb }
#[derive(Component)] struct Ca;
#[derive(Component)] struct Cb;

let mut ecs = Ecs::default(WorkerPool::new(), []);

// You can unregister an entity type using entity type itself.
let res = ecs
    .register_entity_of::<E>()
    .unregister_entity::<E>()
    .take();
assert!(res.is_ok());

// Entity can be also identified by a combination of component types.
let res = ecs
    .register_entity_of::<E>()
    .unregister_entity::<(Ca, Cb)>()
    .take();
assert!(res.is_ok());

fn add_entity<E>( &mut self, ei: EntityIndex, value: E, ) -> WithResult<&mut Self, EntityId, EcsError<E>>

where E: Entity,

Adds an entity.

Examples

use my_ecs::prelude::*;

#[derive(Entity)] struct E { c: C }
#[derive(Component)] struct C;

let mut ecs = Ecs::default(WorkerPool::new(), []);
let ei = ecs.register_entity_of::<E>().unwrap();
ecs.add_entity(ei, E { c: C }).unwrap();

fn remove_entity( &mut self, eid: EntityId, ) -> WithResult<&mut Self, (), EcsError>

Removes an entity.

Example

use my_ecs::prelude::*;

#[derive(Entity)] struct E { c: C }
#[derive(Component)] struct C;

let mut ecs = Ecs::default(WorkerPool::new(), []);
let ei = ecs.register_entity_of::<E>().unwrap();
let eid = ecs.add_entity(ei, E { c: C }).unwrap();
let res = ecs.remove_entity(eid);
assert!(res.is_ok());

fn add_resource<T>( &mut self, desc: T, ) -> WithResult<&mut Self, ResourceIndex, EcsError<ResourceDesc>>

where T: Into<ResourceDesc>,

Adds the given resource.

If the same resource type was already added, returns error.

Examples

use my_ecs::prelude::*;

#[derive(Resource)] struct Ra;
#[derive(Resource)] struct Rb(i32);

let mut ecs = Ecs::default(WorkerPool::new(), []);

// Adds an owned resource.
let res = ecs.add_resource(Ra);
assert!(res.is_ok());

// You cannot register the same resource type.
let res = ecs.add_resource(Ra);
assert!(res.is_err());

// Adds a not owned resource.
let mut r = Rb(0);
let ptr = &mut r as *mut Rb;
let desc = unsafe { ResourceDesc::new().with_ptr(ptr) };
let res = ecs.add_resource(desc);
assert!(res.is_ok());

fn remove_resource<R>(&mut self) -> WithResult<&mut Self, Option<R>, EcsError>

where R: Resource,

Removes a resource from the given resource type.

Examples

use my_ecs::prelude::*;

#[derive(Resource, Debug, PartialEq)]
struct R(i32);

let mut ecs = Ecs::default(WorkerPool::new(), []);

let res = ecs
    .add_resource(R(42))
    .remove_resource::<R>()
    .unwrap();
assert_eq!(res, Some(R(42)));

fn get_resource<R>(&self) -> Option<&R>

where R: Resource,

Retrieves shared reference to a resource for the given resource type.

Examples

use my_ecs::prelude::*;

#[derive(Resource)] struct R(i32);

let mut ecs = Ecs::default(WorkerPool::new(), []);

ecs.add_resource(R(42)).unwrap();
let r = ecs.get_resource::<R>().unwrap();
assert_eq!(r.0, 42);

fn get_resource_mut<R>(&mut self) -> Option<&mut R>

where R: Resource,

Retrieves mutable reference to a resource for the given resource type.

Examples

use my_ecs::prelude::*;

#[derive(Resource)] struct R(i32);

let mut ecs = Ecs::default(WorkerPool::new(), []);

ecs.add_resource(R(42)).unwrap();
let r = ecs.get_resource_mut::<R>().unwrap();
r.0 = 43;

let r = ecs.get_resource_mut::<R>().unwrap();
assert_eq!(r.0, 43);

fn get_resource_index<R>(&self) -> Option<ResourceIndex>

where R: Resource,

Returns resource index for the given resource type.

Examples

use my_ecs::prelude::*;

#[derive(Resource)] struct R;

let mut ecs = Ecs::default(WorkerPool::new(), []);

let ei = ecs.add_resource(R).unwrap();
let found = ecs.get_resource_index::<R>().unwrap();
assert_eq!(found, ei);

fn execute_commands<T>( &mut self, cmds: T, ) -> WithResult<&mut Self, (), Box<dyn Error + Send + Sync + 'static>>

where T: HelpExecuteManyCommands,

Executes the given commands in order.

Examples

use my_ecs::prelude::*;

let cmd0 = |ecs: Ecs| -> DynResult<()> { /* ... */ Ok(()) };
let cmd1 = |ecs: Ecs| -> DynResult<()> { /* ... */ Ok(()) };

Ecs::default(WorkerPool::new(), [])
    .execute_commands((cmd0, cmd1))
    .unwrap();

fn execute_command<F, R>( &mut self, f: F, ) -> WithResult<&mut Self, (), Box<dyn Error + Send + Sync + 'static>>

where F: FnOnce(Commander<'_>) -> R, R: Command,

Execute the given command.

Example

use my_ecs::prelude::*;

#[derive(Entity)] struct E { a: Ca }
#[derive(Component)] struct Ca;
#[derive(Component)] struct Cb;

let mut ecs = Ecs::default(WorkerPool::new(), []);
let ei = ecs.register_entity_of::<E>().unwrap();
let eid = ecs.add_entity(ei, E { a: Ca }).unwrap();

// Attaches `Cb` to `E` so that it's now (Ca, Cb);
ecs.execute_command(move |cmdr| cmdr.change_entity(eid).attach(Cb).finish())
    .unwrap();

// We can unregister (Ca, Cb).
let res = ecs.unregister_entity::<(Ca, Cb)>();
assert!(res.is_ok());

fn errors(&mut self) -> Vec<Box<dyn Error + Send + Sync + 'static>>

Returns errors generated from commands or futures.

Commands and futures don’t cause panic. Instead, errors are collected in a vector. Clients can retrieve the vector using this method.

Provided Methods

fn add_systems<T, Systems>( &mut self, descs: T, ) -> WithResult<&mut Self, (), EcsError>

where T: HelpAddManySystems<Systems>,

Adds the given systems.

Examples

use my_ecs::prelude::*;

fn system0() { /* ... */ }
fn system1() { /* ... */ }

Ecs::default(WorkerPool::new(), [])
    .add_systems((system0, system1))
    .unwrap();

fn add_once_systems<T, Once>( &mut self, descs: T, ) -> WithResult<&mut Self, (), EcsError>

where T: HelpAddManyOnce<Once>,

Adds the given FnOnce systems.

Examples

use my_ecs::prelude::*;

let s = "string0".to_owned();
let system0 = move || { drop(s); };
let s = "string1".to_owned();
let system1 = move || { drop(s); };

Ecs::default(WorkerPool::new(), [])
    .add_once_systems((system0, system1))
    .unwrap();

fn register_entity_of<T>( &mut self, ) -> WithResult<&mut Self, EntityIndex, EcsError>

where T: AsEntityReg,

Registers an entity type.

Examples

use my_ecs::prelude::*;

#[derive(Entity)] struct E { c: C }
#[derive(Component)] struct C;

Ecs::default(WorkerPool::new(), [])
    .register_entity_of::<E>()
    .unwrap();

fn add_resources<T>(&mut self, descs: T) -> WithResult<&mut Self, (), EcsError>

where T: HelpAddManyResources,

Adds the given resources.

Examples

use my_ecs::prelude::*;

#[derive(Resource)] struct Ra(i32);
#[derive(Resource)] struct Rb(i32);

Ecs::default(WorkerPool::new(), [])
    .add_resources((Ra(0), Rb(1)))
    .unwrap();

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl EcsEntry for Ecs<'_>

impl EcsEntry for EcsExt<'_>

impl<W, S> EcsEntry for EcsApp<W, S>

where W: Work + 'static, S: BuildHasher + Default + 'static,