Legion
Legion aims to be a feature rich high performance ECS library for Rust game projects with minimal boilerplate.
Benchmarks
Based on the ecs_bench project.
Getting Started
use *;
// Define our entity data types
;
;
// Create a world to store our entities
let universe = new;
let mut world = universe.create_world;
// Create entities with `Position` and `Velocity` data
world.insert;
// Create entities with `Position` data and a shared `Model` data, tagged as `Static`
// Shared data values are shared across many entities,
// and enable further batch processing and filtering use cases
let entities: & = world.insert;
// Create a query which finds all `Position` and `Velocity` components
let query = query;
// Iterate through all entities that match the query in the world
for in query.iter
WASM
Legion runs with parallelism on by default, which is not currently supported by Web Assembly as it runs single-threaded. Therefore, to build for WASM, ensure you set default-features = false
in Cargo.toml:
= { = "*", = false }
Features
Legion aims to be a more feature-complete game-ready ECS than many of its predecessors.
Advanced Query Filters
The query API can do much more than pull entity data out of the world.
Additional data type filters:
// It is possible to specify that entities must contain data beyond that being fetched
let query = query
.filter;
for position in query.iter
Filter boolean operations:
// Filters can be combined with boolean operators
let query = query
.filter;
for position in query.iter
Filter by shared data value:
// Filters can filter by specific shared data values
let query = query
.filter;
for position in query.iter
Change detection:
// Queries can perform coarse-grained change detection, rejecting entities who's data
// has not changed since the last time the query was iterated.
let query = query
.filter;
for in query.iter
Content Streaming
Entities can be loaded and initialized in a background World
on separate threads and then
when ready, merged into the main World
near instantaneously.
let universe = new;
let mut world_a = universe.create_world;
let mut world_b = universe.create_world;
// Move all entities from `world_b` into `world_a`
// Entity IDs are guaranteed to be unique across worlds and will
// remain unchanged across the move.
world_a.move_from;
Chunk Iteration
Entity data is allocated in blocks called "chunks", each approximately containing 64KiB of data. The query API exposes each chunk via iter_chunk
. As all entities in a chunk are guarenteed to contain the same set of entity data and shared data values, it is possible to do batch processing via the chunk API.
let query = query
.filter;
for chunk in query.iter_chunks_mut