Crate flax

Expand description

Flax is a performant and ergonomic Entity Component System.

The world is organized by simple identifiers known as an Entity, which can have any number of components attached to them.

Systems operate on the world’s entities and provide the application logic.

Consider reading the User Guide

§Features

§Live Demo

See a live demo of asteroids using wasm here.

Source

§Example Usage

  // Declare static components
  use flax::*;

  component! {
    health: f32,
    regen: f32,
    pos: (f32, f32),
    player: (),
    items: Vec<String>,
  }

  let mut world = World::new();

  // Spawn an entity
  let p = EntityBuilder::new()
      .set(health(), 50.0)
      .tag(player())
      .set(pos(), (0.0, 0.0))
      .set(regen(), 1.0)
      .set_default(items())
      .spawn(&mut world);

  let mut query = Query::new((health().as_mut(), regen()));

  // Apply health regeneration for all matched entites
  for (health, regen) in &mut query.borrow(&world) {
      *health = (*health + regen).min(100.0);
  }

§Systems

Queries with logic can be abstracted into a system, and multiple systems can be collected into a schedule.

let regen_system = System::builder()
    .with_query(Query::new((health().as_mut(), regen())))
    .for_each(|(health, regen)| {
        *health = (*health + regen).min(100.0);
    })
    .boxed();

let despawn_system = System::builder()
    .with_query(Query::new(entity_ids()).filter(health().le(0.0)))
    .with_cmd_mut()
    .build(|mut q: QueryBorrow<EntityIds, _>, cmd: &mut CommandBuffer| {
        for id in &mut q {
            cmd.despawn(id);
        }
    })
    .boxed();

let mut schedule = Schedule::from([regen_system, despawn_system]);

schedule.execute_par(&mut world)?;

§Relations

Flax provides first class many-many relations between entities, which is useful for tree scene hierarchies, graphs, and physics joints between entities.

Relations can be both state-less or have associated data, like spring or joint strengths.

Relations are cache friendly and querying children of does not require random access. In addition, relations are cleaned up on despawns and are stable during serialization, even if the entity ids migrate due to collisions.

See the guide for more details.

component! {
    child_of(parent): () => [ Debuggable ],
}

let mut world = World::new();

let parent = Entity::builder()
    .set(name(), "Parent".into())
    .spawn(&mut world);

let child1 = Entity::builder()
    .set(name(), "Child1".into())
    .set_default(child_of(parent))
    .spawn(&mut world);

§Comparison to other ECS

Compared to other ECS implementations, a component is simply another Entity identifier to which data is attached. This means the same “type” can be added to an entity multiple times.

A limitation of existing implementations such as specs, planck, or hecs is that newtype wrappers need to be created to allow components of the same inner type to coexist.

This leads to having to forward all trait implementations trough e.g derive-more or dereferencing the newtypes during usage.

By making components separate from the type the components can work together without deref or newtype construction.

component! {
    velocity: Vec3,
    position: Vec3,
}

let vel = world.get(entity, velocity())?;
let mut pos = world.get_mut(entity, position())?;
let dt = 0.1;

*pos += *vel * dt;

On a further note, since the components have to be declared beforehand, it limits the amount of types which can be inserted as components. This fixes subtle bugs which come by having the type dictate the component, such as using an Arc<Type> instead of just Type, which leads to subsequent systems not finding the Type on the entity.

Using statically declared components makes the rust type system disallow these cases and catches these bugs earlier.

§Motivation

During development of a game in school I used the hecs ECS. It is an awesome library, and the author Ralith has been wonderful in accepting contributions and inquiries.

Despite this, I often made subtle bugs with similar types. The game engine was cluttered with gigantic newtypes for Velocity, Position with many deref coercions in order to coexist.

§Unsafe

This library makes use of unsafe for type erasure and the allocation in storage of ComponentBuffers and Archetypes.

Re-exports§

pub use archetype::BatchSpawn;
pub use archetype::RefMut;
pub use commands::CommandBuffer;
pub use component::Component;
pub use entity::entity_ids;
pub use entity::Entity;
pub use entity::EntityBuilder;
pub use error::Error;
pub use fetch::relations_like;
pub use fetch::EntityIds;
pub use fetch::Fetch;
pub use fetch::FetchExt;
pub use fetch::FetchItem;
pub use fetch::Mutable;
pub use fetch::Opt;
pub use fetch::OptOr;
pub use fetch::Relations;
pub use metadata::Debuggable;
pub use metadata::Exclusive;
pub use query::Children;
pub use query::Dfs;
pub use query::DfsBorrow;
pub use query::DfsIter;
pub use query::EntityBorrow;
pub use query::EntityQuery;
pub use query::Planar;
pub use query::Query;
pub use query::QueryBorrow;
pub use query::QueryIter;
pub use query::Topo;
pub use relation::RelationExt;
pub use schedule::Schedule;
pub use schedule::ScheduleBuilder;
pub use schedule::SystemInfo;
pub use system::BoxedSystem;
pub use system::SharedResource;
pub use system::System;
pub use system::SystemBuilder;
pub use world::World;

Modules§

archetype: Structured component storage
buffer: Provides a buffer for holding multiple types simultaneously
commands: Contains a commandbuffer
component: Low level component construction
components: This module contains standard components that different libraries can agree on, though they don’t have to.
entity: Provides entity identifiers
error: Defines the single error type and result alias
events: Subscribe to changes in the world
fetch: Traits for fetching multiple component values simultaneously
filter: Filter items yielded queries
format: Formatting utilities
metadata: Component metadata used for reflection
query: Query the world
relation: Low level relation construction
schedule: System execution
serializeserde: Allows for efficient serialization and deserialization of the world and the entities therein
sink: Provides a sink trait for sending events
system: System execution
vtable: vtable implementation for dynamic dispatching
world: Contains the main ecs world

Macros§

component: Declarative component generation
component_vtable: Helper macro for creating a vtable for custom components

Structs§

EntityRef: Borrow all the components of an entity at once.
EntityRefMut: Borrow all the components of an entity at once.
OccupiedEntry: A view into an occupied component entry
VacantEntry: A view into a vacant component entry

Enums§

Entry: Entry like api for an entity’s component

Derive Macros§

Fetchderive

Crate flaxCopy item path