Crate hecs_schedule
source ·Expand description
Hecs-schedule
hecs-schedule is a framework for hecs that provides system abstractions for paralell execution.
SubWorld
SubWorld provides the ability to split the world into smaller parts which can only access a subset of components. This allows
Commandbuffer
CommandBuffer provides deferred world modification by means of component insertion, removal, entity spawning and despawning, as well as arbitrary world modification by closures, which will be executed at a later time.
The commandbuffer extends the already existing hecs::CommandBuffer and provides more functionality.
System and Schedule
A system represents a unit of work which can access any resource. Systems are implemented for any function and closure with any number of arguments (well, up to a sane limit due to tuple size and compile time).
A system may access a subworld and safely access the declared components. It can also access any other value by type with Read and Write wrappers.
This value will be pulled from the provided Context which is provided to Schedule::execute as a mutable reference. This means that systems can access local variable and struct members from outside the ECS. If a value of the type was not provided, the system will exit cleanly with an error.
Systems can either return nothing or an empty result, which will be properly boxed and propogated
The schedule is a collection of ordered system executions.
When a schedule is executed, a tuple of references for the contained systems will be provided.
Usage
use hecs_schedule::*;
use hecs::*;
let mut world = World::default();
#[derive(Debug)]
struct App {
name: &'static str,
}
let mut app = App {
name: "hecs-schedule"
};
// Spawn some entities
let a = world.spawn(("a", 42));
world.spawn(("b", 0));
world.spawn(("c", 7));
// Create a simple system to print the entities
let print_system = | w: SubWorld<(& &'static str, &i32)> | {
w.query::<(&&'static str, &i32)>().iter().for_each(|(e, val)| {
println!("Entity {:?}: {:?}", e, val);
})
};
// Get a component from a specific entity, failing gracefully if the entity
// didn't exist or the subworld did not support the component. The result
// will propogate to the schedule execution.
let get_system = move | w: SubWorld<&i32> | -> anyhow::Result<()> {
let val = w.get::<i32>(a)?;
// Prints the answer to life, the universe, and everything.
// Welp, maybe not how to please the borrow checker, but almost
// everything.
println!("Got: {}", *val);
Ok(())
};
// Declare a system which borrows the app and prints it.
// This requires that a reference to app was provided to execute.
// Otherwise, the system fails and returns an error, which propogates to the
// schedule and stops execution.
// It is also possible to modify the app via `mut Write<App>`
let print_app = |app: Read<App>| {
println!("App: {:?}", app);
};
// Note: the `hecs_schedule::CommandBuffer` is a superset of `hecs::CommandBuffer` and is
// accesible as a shared resource from systems.
let spawn_system = |mut cmd: Write<hecs_schedule::CommandBuffer>| {
cmd.spawn(("c", 5));
};
// Construct a schedule
let mut schedule = Schedule::builder()
.add_system(spawn_system)
.add_system(print_system)
.add_system(print_app)
.add_system(get_system)
.build();
// Execute the schedule's systems and provide the world and app. This will parallelize as much
// as possible.
schedule.execute((&mut world, &mut app)).expect("Failed to execute schedule");
Re-exports
pub use borrow::Read;
pub use borrow::Write;
pub use error::Error;
pub use context::*;
pub use system::*;
Modules
- This module provides traits for borrowing values and the relationship between references and owned values, as well as ref cells.
- This module provides types and traits associated to accessing of borrowed values.
- This module provides the error type and result type aliases for hecs-schedule.
- Provides system which are an abstraction for anything that can be executed against a Context.
- Defines common traits
Macros
- Return size of tuple
- Expands a tuple
- Execute macro for each kind of tuple
- Execute macro for each kind of tuple
- Macro for implementing lifetime eliding IntoBorrow
Structs
- Describes how a type is accessed.
- Marker type for a subworld which has access to the whole world
- Represents a unit of work with compatible borrows.
- Holds information regarding batches
- Extends the built in hecs::CommandBuffer.
- Wraps the bulting QueryOne with a Result containing the entity and component instead of option
- A shedule represents a collections of system which will run with effects in a determined order.
- Builder for incrementally constructing a schedule.
- Represents a borrow of the world which can only access a subset of components (unless
AllAccess
is used).
Traits
- Helper trait for types which do not implement clone, but has a clone wrapper
- Trait for allowing function to work on both World and SubWorld
- Convert a type into the correspodning access.
- Declare subset relations between tuples
Type Aliases
- An empty subworld, can not access any components
- Type alias for a subworld referencing the world by an atomic_refcell::AtomicRef. Most common for schedules
- Type alias for a subworld referencing the world by a reference
- Type alias for a subworld referencing the world by a std::cell::Ref