freecs 4.8.0

A high-performance, archetype-based Entity Component System (ECS) written in Rust.
Documentation

freECS

A high-performance, archetype-based Entity Component System (ECS) for Rust

Used as the foundation of Nightshade, a data-oriented game engine in Rust.

Key Features:

  • Zero-cost abstractions with static dispatch
  • Multi-threaded parallel processing using Rayon (automatically enabled on non-WASM platforms)
  • Sparse set tags with deterministic iteration that don't fragment archetypes
  • Command buffers for deferred structural changes
  • Change detection for incremental updates, opt-in per dynamic world so worlds that never diff by tick don't pay for it
  • Sequence-numbered event channels with exactly-once cursor consumption
  • Structural change log covering spawns, despawns, component moves, and tag flips, opt-in on the same terms
  • Multi-world support for >64 component types with shared entity allocator
  • Two entry points over the same storage. The ecs! macro fixes the component set at compile time and generates named accessors, while dynamic worlds (dynamic feature) register components at runtime with bundle spawns, typed queries, and marker tags, with the same guarantees
  • Plain public data all the way down: tables, allocator, tag sets, and logs are inspectable structs and vecs

The ecs! macro generates the entire ECS at compile time using only plain data structures, functions, and zero unsafe code.

Table of Contents

How it works (build it from scratch)

If you want to understand the data layout under the macro, there is a three-part series that builds the same kernel by hand in around 1500 lines of Rust, motivating each design choice.

freecs is what you get when you put a declarative macro on top of that kernel.

Quick Start

Add this to your Cargo.toml:

[dependencies]

freecs = "3"

freecs has two entry points over the same archetype storage. Reach for the dynamic world by default. Typed tuple queries with change and added filters, ergonomic Res/ResMut/Query system functions, cross-world joins, prepared queries, hierarchies, exactly-once events, snapshots and deltas, and the whole grouped multi-world substrate live there, its typed queries compile to the same slice loops the macro emits, and new surface lands on the dynamic side first. The ecs! macro is the compile-time tier. It fixes a small component set up front and generates a named accessor for everything over full static dispatch and no runtime registration, which keeps it the fastest path to a tiny fixed-schema game, the most explicit API, and the executable specification the dynamic implementation is tested against. Both run side by side when you want them to.

Dynamic: DynWorld

Enable the feature:

[dependencies]

freecs = { version = "3", features = ["dynamic"] }

Runtime registration, no macro and no masks. Types register lazily on first use, tuples spawn as bundles, and systems are plain functions whose arguments are Res, ResMut, and Query:

use freecs::Schedule;
use freecs::dynamic::DynWorld;
use freecs::system_param::{Query, Res, ResMut, ScheduleExt};

#[derive(Default, Clone, Debug)]
struct Position { x: f32, y: f32 }

#[derive(Default, Clone, Debug)]
struct Velocity { x: f32, y: f32 }

#[derive(Default, Clone, Debug)]
struct Health { value: f32 }

struct Player;

struct DeltaTime(f32);
struct Score(u32);

// A system is a function. Resources come first (`Res` reads, `ResMut`
// writes), then a `Query` that takes its mutability from the tuple.
fn movement(dt: Res<DeltaTime>, query: Query<(&mut Position, &Velocity)>) {
    query.for_each(|_entity, (position, velocity)| {
        position.x += velocity.x * dt.0;
        position.y += velocity.y * dt.0;
    });
}

// A single-component query skips the tuple, and its closure the nesting.
fn decay(mut score: ResMut<Score>, query: Query<&mut Health>) {
    query.for_each(|_entity, health| health.value *= 0.98);
    score.0 += 1;
}

fn main() {
    let mut world = DynWorld::new();
    world.insert_resources((DeltaTime(0.016), Score(0)));

    let player = world.spawn((
        Position { x: 0.0, y: 0.0 },
        Velocity { x: 1.0, y: 2.0 },
        Health { value: 100.0 },
    ));
    world.add_tag_type::<Player>(player);

    // One tuple registers every system; each is named after its function.
    let mut schedule = Schedule::new();
    schedule.add_systems((movement, decay));
    schedule.run(&mut world);

    // Read-only queries on &world are real iterators. A single element can
    // skip the tuple, so `&Position` yields `(entity, &Position)` directly.
    let player_positions: Vec<_> = world
        .query_ref::<&Position>()
        .with_tag_type::<Player>()
        .iter()
        .map(|(entity, position)| (entity, position.x, position.y))
        .collect();
    println!("{player_positions:?}");

    world.step();
}

Everything else in this README's static sections has a dynamic counterpart. The Dynamic Worlds section covers the full API, the three access tiers, and measured performance against the macro path. The repository ships the same complete tower defense game written both ways (examples/tower-defense.rs and examples/tower-defense-dynamic.rs).

Static: the ecs! macro

use freecs::{ecs, Entity};

ecs! {
    World {
        position: Position => POSITION,
        velocity: Velocity => VELOCITY,
        health: Health => HEALTH,
    }
    Tags {
        player => PLAYER,
        enemy => ENEMY,
    }
    Events {
        collision: CollisionEvent,
    }
    Resources {
        delta_time: f32
    }
}

pub fn main() {
    let mut world = World::default();

    // Spawn entities with components
    let _entity = world.spawn_entities(POSITION | VELOCITY, 1)[0];

    // Or use the entity builder
    let entity = EntityBuilder::new()
        .with_position(Position { x: 1.0, y: 2.0 })
        .spawn(&mut world, 1)[0];

    // Read components using the generated methods
    let position = world.get_position(entity);
    println!("Position: {:?}", position);

    // Set components (adds if not present)
    world.set_position(entity, Position { x: 1.0, y: 2.0 });

    // Mutate a component
    if let Some(position) = world.get_position_mut(entity) {
        position.x += 1.0;
    }

    // Get an entity's component mask
    let _component_mask = world.component_mask(entity).unwrap();

    // Add a new component to an entity
    world.add_components(entity, HEALTH);

    // Or use the generated add method
    world.add_health(entity);

    // Query all entities
    let _entities = world.get_all_entities();

    // Query all entities with a specific set of components
    let _players: Vec<Entity> = world.query_entities(POSITION | VELOCITY | HEALTH).collect();

    // Query the first entity with a specific component,
    // returning early instead of checking remaining entities
    let _first_player_entity = world.query_first_entity(POSITION | VELOCITY | HEALTH);

    // Remove a component from an entity
    world.remove_components(entity, HEALTH);

    // Or use the generated remove method
    world.remove_health(entity);

    // Check if entity has components
    if world.entity_has_position(entity) {
        println!("Entity has position component");
    }

    // Add tags to entities (lightweight markers)
    world.add_player(entity);

    // Check if entity has a tag
    if world.has_player(entity) {
        println!("Entity is a player");
    }

    // Remove tags
    world.remove_player(entity);

    // Send events
    world.send_collision(CollisionEvent {
        entity_a: entity,
        entity_b: entity,
    });

    // Systems are functions that transform component data
    systems::run_systems(&mut world);

    // Despawn entities, freeing their table slots for reuse
    world.despawn_entities(&[entity]);
}

use components::*;
mod components {
    #[derive(Default, Debug, Clone, Copy)]
    pub struct Position {
        pub x: f32,
        pub y: f32,
    }

    #[derive(Default, Debug, Clone, Copy)]
    pub struct Velocity {
        pub x: f32,
        pub y: f32,
    }

    #[derive(Default, Debug, Clone, Copy)]
    pub struct Health {
        pub value: f32,
    }
}

use events::*;
mod events {
    use super::*;

    #[derive(Debug, Clone)]
    pub struct CollisionEvent {
        pub entity_a: Entity,
        pub entity_b: Entity,
    }
}

mod systems {
    use super::*;

    pub fn run_systems(world: &mut World) {
        example_system(world);
        update_positions_system(world);
        collision_handler_system(world);
        health_system(world);
    }

    fn example_system(world: &mut World) {
        world.query_position_mut(VELOCITY, |_entity, position| {
            position.x += 1.0;
        });
    }

    fn update_positions_system(world: &mut World) {
        let dt = world.resources.delta_time;

        world.for_each_mut(POSITION | VELOCITY, 0, |_entity, table, idx| {
            table.position[idx].x += table.velocity[idx].x * dt;
            table.position[idx].y += table.velocity[idx].y * dt;
        });
    }

    fn collision_handler_system(world: &mut World) {
        for event in world.collect_collision() {
            println!("Collision detected between {:?} and {:?}", event.entity_a, event.entity_b);
        }
    }

    fn health_system(world: &mut World) {
        world.query_health_mut(0, |_entity, health| {
            health.value *= 0.98;
        });
    }
}

Generated API

The ecs! macro generates type-safe methods for each component:

// For each component, you get:
world.get_position(entity)          // -> Option<&Position>
world.get_position_mut(entity)      // -> Option<&mut Position>
world.modify_position(entity, f)    // -> Option<R> - mutate via closure, returns closure result
world.set_position(entity, pos)     // Sets or adds the component
world.add_position(entity)          // Adds with default value
world.remove_position(entity)       // Removes the component
world.entity_has_position(entity)   // Checks if entity has component
world.query_position()              // Iterator over &Position across all tables
world.query_position_mut(mask, f)   // Visit (Entity, &mut Position) for entities matching mask
world.iter_position(f)              // Visit (Entity, &Position)
world.iter_position_mut(f)          // Visit (Entity, &mut Position)
world.for_each_position_mut(f)      // Visit &mut Position only, fastest typed path, no change stamping
world.par_for_each_position_mut(f)  // Parallel &mut Position (non-WASM)
world.iter_position_slices()        // Iterator over &[Position], one slice per table
world.iter_position_slices_mut()    // Iterator over &mut [Position]

Closure-Based Mutation

The modify_<component> methods allow you to mutate a component via a closure, which automatically releases the borrow when done. This is useful when you need to mutate a component and then immediately access the world again:

// Instead of this pattern (requires explicit drop):
let player = world.get_player_mut(entity).unwrap();
player.stamina -= 10.0;
let _ = player;  // Must drop to release borrow
let pos = world.get_position(entity);

// Use modify for cleaner code:
world.modify_player(entity, |p| p.stamina -= 10.0);
let pos = world.get_position(entity);  // No drop needed

// The closure can return values:
let old_health = world.modify_health(entity, |h| {
    let old = h.value;
    h.value = 100.0;
    old
});

Systems

Systems are functions that query entities and transform their components:

pub fn update_global_transforms_system(world: &mut World) {
    let entities: Vec<Entity> = world
        .query_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM)
        .collect();
    for entity in entities {
        // The entities we queried for are guaranteed to have
        // a local transform and global transform here
        let new_global_transform = query_global_transform(world, entity);
        let global_transform = world.get_global_transform_mut(entity).unwrap();
        *global_transform = GlobalTransform(new_global_transform);
    }
}

pub fn query_global_transform(world: &World, entity: Entity) -> nalgebra_glm::Mat4 {
    let Some(local_transform) = world.get_local_transform(entity) else {
        return nalgebra_glm::Mat4::identity();
    };
    if let Some(Parent(parent)) = world.get_parent(entity) {
        query_global_transform(world, *parent) * local_transform
    } else {
        local_transform
    }
}

Events

Events are stored in sequence-numbered channels, the same cursor scheme the structural change log uses.

The default consumption style is consume_<event>: each consumer owns one u64 cursor, and every call yields the events sent since that consumer last looked, advancing the cursor past them. Calling it every frame delivers each event exactly once, two consumers never steal from or double-process each other, and a consumer that skips a frame catches up:

struct RenderSync {
    collision_cursor: u64,
}

fn render_sync_system(world: &mut World, sync: &mut RenderSync) {
    for event in world.consume_collision(&mut sync.collision_cursor) {
        // Seen exactly once by this consumer
    }
}

The buffer-reading forms, read_<event>() and collect_<event>(), return everything still buffered. Events stay buffered for two frames before world.step() expires them, so a per-frame handler using these sees each event twice. They are for debugging, one-shot inspection, or frame setups you manage yourself. When in doubt, use consume_.

Each event type gets these generated methods:

  • send_<event>(event) - Queue an event
  • consume_<event>(&mut cursor) - Events sent since this cursor, advancing it. Exactly-once per consumer, the default
  • read_<event>_since(cursor) - Slice of events sent after cursor, cursor untouched
  • sequence_<event>() - Sequence number of the newest event. Record it as your cursor
  • trim_<event>(up_to_sequence) - Drop consumed events early (pass the minimum cursor across consumers)
  • read_<event>() - Iterator over all buffered events (up to two frames' worth)
  • collect_<event>() - Collect buffered events into a Vec (up to two frames' worth)
  • peek_<event>() - Reference to the oldest buffered event
  • update_<event>() - Expire events older than one frame. step() already calls this per frame, so calling both halves event lifetime
  • clear_<event>() - Immediately drop all buffered events
  • len_<event>() / is_empty_<event>() - Buffered event count

The dynamic world has the same pair: consume_events::<T>(&mut cursor) for exactly-once handling and read_events::<T>() for the raw buffer.

Channels are bounded: a channel nobody consumes drops its oldest half at EVENT_CHANNEL_CAPACITY entries instead of leaking.

Game Loop Integration

Call world.step() at the end of each frame to handle event expiry and the change-detection tick:

loop {
    input_system(&mut world);
    physics_system(&mut world);
    collision_system(&mut world);

    world.step();  // Expires old events and increments the tick counter
}

Event Lifetime

Events sent during frame N remain readable through frame N+1 and are dropped by the step() that ends frame N+1. This preserves the classic double-buffer property: a system scheduled before the sender still sees the event on the next frame. It is also why per-frame handlers must consume through cursors. The two-frame buffer means read_/collect_ deliver the same event on both frames, and consume_ turns the buffer into exactly-once delivery. Cursor consumers are unaffected by expiry as long as they read at least every other frame. A cursor older than the buffer yields everything still buffered.

High-Performance Features

Query Builder API

For maximum performance, use the query builder which provides direct table access:

fn physics_update_system(world: &mut World) {
    let dt = world.resources.delta_time;

    world.query_mut()
        .with(POSITION | VELOCITY)
        .iter(|entity, table, idx| {
            table.position[idx].x += table.velocity[idx].x * dt;
            table.position[idx].y += table.velocity[idx].y * dt;
        });
}

This eliminates per-entity lookups and provides cache-friendly sequential access.

The query builder also supports filtering:

// Exclude entities with specific components
world.query()
    .with(POSITION | VELOCITY)
    .without(PLAYER)
    .iter(|entity, table, idx| {
        // Only processes entities that have position and velocity but NOT player
    });

You can also use the lower-level iteration methods directly:

// Mutable iteration
world.for_each_mut(POSITION | VELOCITY, 0, |entity, table, idx| {
    table.position[idx].x += table.velocity[idx].x;
});

// Read-only iteration
for entity in world.query_entities(POSITION | VELOCITY) {
    let pos = world.get_position(entity).unwrap();
    let vel = world.get_velocity(entity).unwrap();
    println!("Entity {:?} at ({}, {})", entity, pos.x, pos.y);
}

Query iteration allocates nothing per call. Mutable iteration paths maintain a query cache keyed by component mask so repeated queries skip table matching. One asymmetry to know about is that the read-only for_each can consult the cache but cannot populate it (it takes &self), so a mask that has only ever been used read-only falls back to a linear scan over tables. Table counts are small in practice, and any mutable query with the same mask warms the cache for both.

Batch Spawning

Spawn multiple entities efficiently:

// Method 1: spawn_batch with initialization callback
let entities = world.spawn_batch(POSITION | VELOCITY, 1000, |table, idx| {
    table.position[idx] = Position { x: idx as f32, y: 0.0 };
    table.velocity[idx] = Velocity { x: 1.0, y: 0.0 };
});

// Method 2: spawn_entities (uses component defaults)
let entities = world.spawn_entities(POSITION | VELOCITY, 1000);

// Method 3: entity builder for small batches
let entities = EntityBuilder::new()
    .with_position(Position { x: 0.0, y: 0.0 })
    .with_velocity(Velocity { x: 1.0, y: 1.0 })
    .spawn(&mut world, 100);

Single-Component Iteration

Optimized iteration when you only need one component type:

// Entity and component reference
world.iter_position(|entity, position| {
    println!("{entity}: ({}, {})", position.x, position.y);
});

// Mutable, marks the component changed for change detection
world.iter_position_mut(|_entity, position| {
    position.y *= 0.99;
});

// Component-only fast path, no entity, no change stamping
world.for_each_position_mut(|position| {
    position.x += 1.0;
});

Parallel Iteration

Process large entity counts across multiple CPU cores using Rayon. Parallel iteration is automatically available on non-WASM platforms:

fn parallel_physics_system(world: &mut World) {
    let dt = world.resources.delta_time;

    world.par_for_each_mut(POSITION | VELOCITY, 0, |entity, table, idx| {
        table.position[idx].x += table.velocity[idx].x * dt;
        table.position[idx].y += table.velocity[idx].y * dt;
    });
}

par_for_each_mut parallelizes across archetype tables, so a world with two big archetypes gets at most two-way parallelism from it. The single-component variant par_for_each_<component>_mut additionally parallelizes within each table and is the better choice when most matching entities live in one archetype.

Best for 100K+ entities with non-trivial per-entity computation. For smaller entity counts, serial iteration may be more efficient due to parallelization overhead.

Parallel methods are only available when targeting non-WASM platforms. On WASM targets, use the serial iteration methods instead.

Sparse Set Tags

Tags are lightweight markers stored in sparse sets (a dense Vec<Entity> plus a sparse index array), not in archetypes. Adding or removing a tag never migrates the entity, membership checks are O(1) array lookups with no hashing, iteration over a tag is contiguous and deterministic, and membership is generation-checked so a stale handle never matches a reused id:

ecs! {
    World {
        position: Position => POSITION,
        velocity: Velocity => VELOCITY,
    }
    Tags {
        player => PLAYER,
        enemy => ENEMY,
        selected => SELECTED,
    }
}

// Adding tags doesn't move entities between archetypes.
// The entity must be alive. Tags on dead handles are refused.
world.add_player(entity);
world.add_selected(entity);

// Check if entity has a tag
if world.has_player(entity) {
    println!("Entity is a player");
}

// Iterate a tag directly (deterministic order)
for entity in world.query_player() {
    println!("Player entity: {:?}", entity);
}

// Tags participate in query masks alongside components
world.for_each_mut(POSITION | VELOCITY, PLAYER, |entity, table, idx| {
    // Entities with position and velocity that are NOT players
});

// Remove tags
world.remove_player(entity);

Tag masks occupy the top bits of the u64, components fill from the bottom, and the macro asserts at compile time that they fit together. Tag adds and removes are recorded in the structural change log, so incremental consumers see tag flips the same way they see component changes.

Tags work well for:

  • Runtime categorization (player, enemy, npc)
  • Selection/highlighting states
  • Temporary status flags
  • Any marker that changes frequently

Command Buffers

Command buffers allow you to queue structural changes (spawn, despawn, add/remove components) during iteration, then apply them all at once. This avoids borrowing conflicts and archetype invalidation during queries:

fn death_system(world: &mut World) {
    // Queue despawns during iteration
    let entities_to_despawn: Vec<Entity> = world
        .query_entities(HEALTH)
        .filter(|&entity| {
            world.get_health(entity).map_or(false, |h| h.value <= 0.0)
        })
        .collect();

    for entity in entities_to_despawn {
        world.queue_despawn_entity(entity);
    }

    // Apply all queued commands at once
    world.apply_commands();
}

Available command buffer operations:

  • queue_spawn_entities(mask, count) - Queue a batch spawn
  • queue_despawn_entity(entity) / queue_despawn_entities(entities) - Queue despawns
  • queue_add_components(entity, mask) - Queue component addition
  • queue_remove_components(entity, mask) - Queue component removal
  • queue_set_<component>(entity, value) - Queue component set/update
  • queue_add_<tag>(entity) / queue_remove_<tag>(entity) - Queue tag changes
  • apply_commands() - Apply all queued commands
  • command_count() / clear_commands() - Inspect or drop the queue

Mask Hygiene

Component masks and tag masks share the u64 but not the same APIs. Spawn masks, add_components, remove_components, and the mask-only queries (query_entities, query_first_entity, changed queries) take component bits only, while for_each, for_each_mut, their changed and parallel variants, and query_<component>_mut accept tag bits and filter per entity. Passing tag bits where they don't belong is a debug_assert failure rather than a silently empty result, so misuse fails loudly in debug builds and costs nothing in release.

Change Detection

Track which components have been modified since the last frame. Useful for incremental updates, networking, or rendering optimizations:

fn render_system(world: &mut World) {
    // Process only entities whose components changed since last step()
    world.for_each_mut_changed(POSITION, 0, |entity, table, idx| {
        update_sprite_position(&table.position[idx]);
    });
}

// At the end of your game loop
world.step();  // Increments tick counter and expires old events

Mutations through set_*(), get_*_mut(), modify_*(), query_*_mut(), and iter_*_mut() mark the component slot as changed for the current tick, as do spawns and component add/remove migrations. Raw table access (query_mut() closures, slice iterators, for_each_*_mut) does not mark. This matters the moment a downstream consumer diffs by ticks (delta sync, incremental render extraction): a raw-tier write is invisible to it until something else stamps the slot. Route writes through the accessors, or opt in explicitly:

// Per entity, after a raw write:
world.mark_changed(entity, POSITION | VELOCITY);

// Per table, after a whole-column pass:
let current_tick = world.current_tick();
for table in &mut world.tables {
    if table.mask & POSITION == 0 { continue; }
    for position in &mut table.position { position.x += 1.0; }
    table.mark_columns_changed(POSITION, current_tick);
}

mark_changed(entity, mask) stamps the masked components on one entity and returns false when the entity is missing or carries none of them. table.mark_columns_changed(mask, tick) stamps every row of the masked columns at once, so bulk passes stay free of per-row bookkeeping during the write. The dynamic world has the same pair (DynWorld::mark_changed, mark_columns_changed on its tables).

Each table also keeps a per-component high-water tick. Changed queries compare it first and skip whole tables that no write has touched since the last step(), so scanning cost is proportional to tables with activity rather than total entity count. Tick comparisons are wrapping-safe, so detection keeps working after the u32 tick counter overflows.

Multiple independent consumers can track their own change windows with the explicit-cursor variants query_entities_changed_since(mask, since_tick) and for_each_mut_changed_since(include, exclude, since_tick, f). Record current_tick() when you consume, then call increment_tick() to fence, so writes made later in the same tick stamp a newer value and land in your next window.

Change tracking stores one u32 per component per entity plus a tick stamp on every accessor write, whether or not you consume it. On the static ecs! tier that is unconditional, and it is the price of the feature always being available. A dynamic world makes the same tracking opt-in through set_change_detection(true), so worlds that never diff by tick skip the tick columns and their per-row stamping entirely; see Change detection and sync.

Structural Change Log

Change ticks cover component writes. Structural changes are recorded in a per-world log of plain StructuralChange entries: entity, kind, and the mask involved. Kinds cover Spawned, Despawned, ComponentsAdded, ComponentsRemoved, TagsAdded, and TagsRemoved (the full mask for spawns and despawns, the delta for adds and removes, the tag mask for tag flips). Consumers read structural_changes_since(cursor) against a u64 sequence cursor they own and record structural_sequence() after consuming. The owner of the frame loop calls trim_structural_log(up_to_sequence) with the minimum cursor across consumers. A world whose log is never consumed self-clears at STRUCTURAL_LOG_CAPACITY entries, so it stays bounded instead of leaking.

The log is unconditional on the static ecs! tier. On a dynamic world it is opt-in through the structural_logging field, since an unread log costs a push per entity per structural change; DynEcs exposes the same switch for its group-level lifecycle log.

let mut cursor = 0;
// ... spawns, despawns, component and tag changes happen ...
for change in world.structural_changes_since(cursor) {
    match change.kind {
        StructuralChangeKind::Spawned | StructuralChangeKind::ComponentsAdded => { /* mask gained */ }
        StructuralChangeKind::Despawned | StructuralChangeKind::ComponentsRemoved => { /* mask lost */ }
        StructuralChangeKind::TagsAdded | StructuralChangeKind::TagsRemoved => { /* tag mask flipped */ }
    }
}
cursor = world.structural_sequence();
world.trim_structural_log(cursor);

A despawn is logged as a single Despawned entry. The tags an entity held are dropped implicitly rather than logged individually.

System Scheduling

Organize systems into a schedule for automatic execution. For programs assembled from independent parts (engine plugins, feature crates), Stages holds an ordered list of named stages, each its own Schedule: the app declares stage order once, parts push systems into stages by name (stages.stage_mut("simulation").push(...)), stages run in declaration order and systems within a stage in push order, and pushing into an undeclared stage panics with the declared list. Deterministic composition with no labels or constraint graphs.

use freecs::Schedule;

fn main() {
    let mut world = World::default();

    // Create separate schedules for game logic and rendering
    let mut game_schedule = Schedule::new();
    game_schedule
        .push("input", input_system)
        .push("physics", physics_system)
        .push("collision", collision_system);

    let mut render_schedule = Schedule::new();
    render_schedule
        .push_readonly("render_grid", render_grid)
        .push_readonly("render_entities", render_entities);

    // Game loop
    loop {
        game_schedule.run(&mut world);     // Run game logic
        render_schedule.run(&mut world);   // Run rendering
        world.step();
    }
}

Schedule API:

  • push(name, system) / push_readonly(name, system) - Append a mutable or read-only system
  • insert_before(target, name, system) / insert_after(target, name, system) - Positional insertion
  • replace(name, system) - Swap a system in-place, preserving execution order
  • remove(name) - Remove a system by name (returns bool)
  • contains(name) / names() / len() / is_empty() - Introspection

All systems require a unique &'static str name. Duplicates panic at insertion time.

Entity Builder

An entity builder is generated automatically:

let mut world = World::default();

let entities = EntityBuilder::new()
    .with_position(Position { x: 1.0, y: 2.0 })
    .with_velocity(Velocity { x: 0.0, y: 1.0 })
    .spawn(&mut world, 2);

assert_eq!(world.get_position(entities[0]).unwrap().x, 1.0);
assert_eq!(world.get_position(entities[1]).unwrap().y, 2.0);

Entity Liveness

Entity handles are generational, and the allocator is the single source of truth for liveness. Double despawns and despawns through stale handles are refused rather than corrupting the free list, so two live entities can never share an id and generation. world.is_alive(entity) answers liveness directly, and despawn_entities returns the subset of handles that were actually despawned.

Liveness costs one slot record write per singleton spawn. Batch spawns write the slot table with one bulk fill for the contiguous fresh ids, so batch spawning and despawning are both faster than 2.x despite the added guarantee.

Advanced Features

Per-Component Iteration

For iterating over a single component type, specialized methods are generated:

// Read-only iteration with the owning entity
world.iter_position(|entity, position| {
    println!("{entity}: ({}, {})", position.x, position.y);
});

// Mutable iteration (marks changed)
world.iter_position_mut(|_entity, position| {
    position.x += 1.0;
});

// Slice-based iteration (most efficient, no change stamping)
for slice in world.iter_position_slices() {
    for position in slice {
        println!("Position: ({}, {})", position.x, position.y);
    }
}

for slice in world.iter_position_slices_mut() {
    for position in slice {
        position.x *= 2.0;
    }
}

// Iterate component values directly
for position in world.query_position() {
    println!("Position: ({}, {})", position.x, position.y);
}

// Visit a component for entities matching an additional mask (components or tags)
world.query_position_mut(VELOCITY | PLAYER, |entity, position| {
    // Position of every player that also has velocity, marking position changed
});

Low-Level Iteration

For maximum control, use the low-level iteration methods:

// Read-only iteration with include/exclude masks (tags allowed in both)
world.for_each(POSITION | VELOCITY, PLAYER, |entity, table, idx| {
    let pos = &table.position[idx];
    let vel = &table.velocity[idx];
    println!("Non-player entity at ({}, {})", pos.x, pos.y);
});

// Mutable iteration with include/exclude masks
world.for_each_mut(POSITION | VELOCITY, 0, |entity, table, idx| {
    table.position[idx].x += table.velocity[idx].x;
    table.position[idx].y += table.velocity[idx].y;
});

// Check if entity has multiple components
if world.entity_has_components(entity, POSITION | VELOCITY | HEALTH) {
    println!("Entity has all required components");
}

Tick Management

Query the current and previous tick counters for advanced change detection:

let current = world.current_tick();
let previous = world.last_tick();

// Process only entities changed since last frame
world.for_each_mut_changed(POSITION, 0, |entity, table, idx| {
    sync_transform(entity, &table.position[idx]);
});

// Tick is automatically incremented by world.step()
world.step();

Conditional Compilation

Both components and resources support #[cfg(...)] attributes for conditional compilation. This is useful for debug-only components, optional features, or platform-specific functionality:

ecs! {
    World {
        position: Position => POSITION,
        velocity: Velocity => VELOCITY,
        #[cfg(debug_assertions)]
        debug_info: DebugInfo => DEBUG_INFO,
        #[cfg(feature = "physics")]
        rigid_body: RigidBody => RIGID_BODY,
    }
    Resources {
        delta_time: f32,
        #[cfg(feature = "audio")]
        audio_engine: AudioEngine,
    }
}

When a component or resource has a #[cfg(...)] attribute, all related generated code (struct fields, accessor methods, mask constants, enum variants, etc.) is conditionally compiled based on the feature flag or target configuration.

Cargo Features

  • serde (default): derives Serialize/Deserialize on Entity. Disable with default-features = false if you don't need it.
  • dynamic (off by default): the runtime-registered dynamic world entry point. Costs the default build nothing.
  • snapshot (off by default, implies dynamic and serde): serializable snapshots of dynamic worlds and groups, with per-type column codecs registered alongside components.
  • state (off by default, implies dynamic): an optional state machine over the dynamic layer. A current-and-next value per user-supplied state type, transitions that emit an event, and run-condition gating of systems (while_in, while_in_any, run_if, on_enter, on_exit). Costs the default build nothing.
  • raw_storage (off by default, implies dynamic): the maximum-speed backend for the dynamic world. Behind an identical public API it swaps component columns from Box<dyn Any> + Vec<T> to a contiguous byte buffer read through pointer casts (dropping the per-access downcast), recycles freed column allocations through a thread-local buffer pool, walks query rows and migrates columns without bounds checks or the per-component vtable (both sound because storage invariants guarantee the indices and types), and forbids the two pieces of per-entity bookkeeping the safe backend can maintain: per-row change ticks and the structural-change log. The public API is byte-for-byte identical. Observable behavior is identical too, with two deliberate exceptions tied to the dropped bookkeeping: changed::<T>()/added::<T>()/for_each_mut_changed match nothing, and structural_changes_since/structural_sequence return empty/zero, so set_change_detection and structural_logging cannot turn them back on. HierarchyIndex stays correct by rebuilding from a scan. Every unsafe is confined to the RawColumn type and a few index-time fast paths, all verified with miri. Leave it off to keep the crate provably unsafe-free and to keep the option of change and structural tracking; turn it on for maximum throughput when you do not depend on those filters. Note that the bookkeeping is opt-in on the safe backend too, so switching a world that never tracked anything to raw_storage buys you the storage backend and the faster registry hasher, not the removal of tracking you were already skipping.

Verify a build against both backends the way the crate does:

cargo test --features dynamic                 # safe storage (default)

cargo test --features "dynamic raw_storage"   # contiguous raw storage

Dynamic Worlds

The dynamic feature adds a second entry point for programs that cannot fix their component set at compile time, editors, plugin boundaries, data-driven prefab schemas. DynWorld registers component types at runtime and keeps the rest of the design: contiguous Vec<T> columns per archetype, u64 masks, the same change detection and structural log (opt-in here, rather than always on as on the static tier), sparse-set tags, event channels, and liveness guarantees, and zero unsafe. Columns are erased as whole vecs behind Box<dyn Any + Send + Sync>, never as raw bytes, and structural changes dispatch through a per-type record of plain function pointers that is itself public data.

Everything in this section is also one runnable program, examples/tour.rs, with a comment on each block mapping it back to the subsection that explains it. It compiles on every CI run, so it cannot drift from the API:

cargo run --example tour --features dynamic

The examples below share these component types:

use freecs::dynamic::DynWorld;

#[derive(Default, Clone, Debug)]
struct Position { x: f32, y: f32 }

#[derive(Default, Clone, Debug)]
struct Velocity { x: f32, y: f32 }

#[derive(Default, Clone, Debug)]
struct Health { value: f32 }

Component registration

Types register lazily on first use, so most programs never register anything by hand. Register explicitly when you want a ComponentKey for the keyed tier, or to fix mask bits up front (bits are assigned in registration order):

let mut world = DynWorld::new();

// The spawn registers Position and Velocity lazily.
let entity = world.spawn((Position::default(), Velocity::default()));

// Explicit registration returns a copyable key carrying the mask bit.
let health = world.register::<Health>();
assert_eq!(health.mask, 0b100);

// Components and tags share 64 bits per world, so check the budget in a
// startup assertion instead of meeting the panic at registration 65.
assert!(world.remaining_bits() > 32);

For several worlds that must agree on masks, or for snapshots, declare the schema in one place with dynamic_schema!: it generates the mask constants in declaration order, the registration function building a ComponentRegistry in that exact order, and an assertion per component that the two agree. Declare every component on every build configuration and only ever append, so masks stay identical across feature sets and saves stay loadable. Runtime components keep registering after the declared base; the schema is a floor, not a ceiling:

use freecs::dynamic::DynWorld;

freecs::dynamic_schema! {
    pub fn register_components {
        position: Position => POSITION,
        velocity: Velocity => VELOCITY,
        health: Health => HEALTH,
    }
}

let world = DynWorld::from_registry(register_components());
assert_eq!(HEALTH, 0b100);

Prefix the function with serde (dynamic_schema! { serde pub fn ... }) to register every component with a snapshot codec, so the same declaration is the save-format schema.

Spawning and despawning

let mut world = DynWorld::new();

// One entity from a bundle of component values.
let player = world.spawn((Position { x: 1.0, y: 2.0 }, Health { value: 100.0 }));

// Many entities carrying clones of one bundle.
let squad = world.spawn_bundles((Position::default(), Velocity::default()), 32);

// Deferred spawn: the handle comes back immediately, alive with no
// components until apply_commands runs the queued bundle write.
let reserved = world.queue_spawn((Position::default(),));
assert!(world.is_alive(reserved));
world.apply_commands();

// Despawn by handle, in bulk, or by component membership.
world.despawn_entities(&squad);
world.despawn_with_any::<(Health,)>();

For per-entity initialization at batch speed, the keyed spawn_batch(mask, count, |table, index| ...) fills columns directly.

Component access

let mut world = DynWorld::new();
let entity = world.spawn((Position::default(),));

// Typed access pays one TypeId lookup per call. set adds if missing.
world.set(entity, Velocity { x: 1.0, y: 0.0 });
if let Some(position) = world.get_mut::<Position>(entity) {
    position.x += 1.0;
}
assert!(world.has::<Velocity>(entity));
world.remove::<Velocity>(entity);

// Keyed access skips the hash entirely, for per-entity hot paths.
let position = world.register::<Position>();
world.set_keyed(position, entity, Position { x: 5.0, y: 0.0 });
assert_eq!(world.get_keyed(position, entity).unwrap().x, 5.0);

Queries

Borrow mutability comes from the tuple, and mutable elements stamp change ticks per visited entity. Up to eight elements, all component types distinct:

let mut world = DynWorld::new();
world.spawn((Position::default(), Velocity { x: 1.0, y: 0.0 }));
world.spawn((Position::default(),));

// Most systems are a tuple query with a closure.
world
    .query::<(&mut Position, &Velocity)>()
    .for_each(|_entity, (position, velocity)| {
        position.x += velocity.x;
    });

// Single-component queries skip the tuple.
world.query::<&mut Position>().for_each(|_entity, position| {
    position.y = 0.0;
});

// Option elements match entities with or without the component.
world
    .query::<(&mut Position, Option<&Velocity>)>()
    .for_each(|_entity, (position, velocity)| {
        if let Some(velocity) = velocity {
            position.x += velocity.x;
        }
    });

// Filter with/without by type, mask, or tag, plus changed/added windows.
// The changed/added windows need `set_change_detection(true)` on the world;
// without it they match nothing. See "Change detection and sync" below.
struct Frozen;
world
    .query::<&mut Position>()
    .without_tag_type::<Frozen>()
    .changed::<Position>()
    .for_each(|_entity, _position| {});

On a shared borrow, query_ref runs read-only tuples as a real Iterator whose items borrow the world, so results collect and compose with adapters:

let total: f32 = world
    .query_ref::<(&Position, Option<&Velocity>)>()
    .iter()
    .map(|(_entity, (position, velocity))| {
        position.x + velocity.map_or(0.0, |velocity| velocity.x)
    })
    .sum();

// single() returns the match when exactly one entity qualifies.
if let Some((entity, position)) = world.query_ref::<&Position>().single() {
    println!("{entity} at {}", position.x);
}

// iter_combinations() yields each unordered pair once, for pairwise
// logic like collision tests.
for ((entity_a, a), (entity_b, b)) in world.query_ref::<&Position>().iter_combinations() {
    let _ = (entity_a, entity_b, a.x - b.x);
}

In a DynEcs group, tuples whose components live in different member worlds run through ecs.query_join with the same filter vocabulary. See Grouped dynamic worlds.

Hot systems freeze a configured query into a PreparedQuery with .prepare() and rerun it without per-call TypeId resolution (prepared.query(&mut world).for_each(...)). The read form (PreparedQueryRef) does the same for iterators. Prepared masks are plain copyable data.

Heavy passes go parallel with par_for_each. Matching archetypes run concurrently, and an unfiltered query also splits the rows within each archetype across the pool, so one large archetype uses every core. Filtered queries stay archetype-granular. Same filters and stamping:

world
    .query::<(&mut Position, &Velocity)>()
    .par_for_each(|_entity, (position, velocity)| {
        position.x += velocity.x;
    });

Writing systems

Systems are plain functions over &mut DynWorld or &DynWorld, and the borrow checker is the access checker. The take/put scopes give a system a resource and the world as independent borrows:

struct DeltaTime(f32);
struct Score(u32);

fn movement_system(world: &mut DynWorld) {
    world.resource_scope(|world, delta_time: &mut DeltaTime| {
        world
            .query::<(&mut Position, &Velocity)>()
            .for_each(|_entity, (position, velocity)| {
                position.x += velocity.x * delta_time.0;
                position.y += velocity.y * delta_time.0;
            });
    });
}

fn score_system(world: &mut DynWorld) {
    world.resources_scope(|world, (score, delta_time): &mut (Score, DeltaTime)| {
        score.0 += world.query_ref::<&Health>().iter().count() as u32;
        let _ = delta_time;
    });
}

fn render_system(world: &DynWorld) {
    for (_entity, position) in world.query_ref::<&Position>().iter() {
        let _ = position;
    }
}

let mut world = DynWorld::new();
world.insert_resource(DeltaTime(0.016));
world.insert_resource(Score(0));

let mut schedule = freecs::Schedule::new();
schedule
    .push("movement", movement_system)
    .push("score", score_system)
    .push_if(
        "expensive",
        |world: &DynWorld| world.entity_count() > 0,
        |_world| {},
    )
    .push_readonly("render", render_system);

schedule.run(&mut world);
world.step();

To drop the take/put boilerplate, the system_param module turns a plain function whose arguments are Res, ResMut, and Query into a runnable system, so the take/put scope disappears from the call site. add_system on a Schedule<DynWorld> names one system and infers its shape from the signature; add_systems registers a tuple at once, naming each after its function type. add_system_if gates a system on a run condition, the param-system form of Schedule::push_if, so a system can run only when the host is in a given state: pass |world| in_state(world, …) as the condition. The state itself is the host's concern; freecs only checks the condition each pass.

use freecs::system_param::{Query, Res, ResMut, ScheduleExt};

struct DeltaTime(f32);
struct Score(u32);

fn movement(dt: Res<DeltaTime>, mut score: ResMut<Score>, query: Query<(&mut Position, &Velocity)>) {
    query.for_each(|_entity, (position, velocity)| {
        position.x += velocity.x * dt.0;
        position.y += velocity.y * dt.0;
    });
    score.0 += 1;
}

let mut world = DynWorld::new();
world.insert_resources((DeltaTime(0.016), Score(0)));

let mut schedule = freecs::Schedule::new();
schedule.add_systems((movement,));
schedule.run(&mut world);

Resource parameters resolve out of the world's ResourceMap through the same take/put resources_scope uses, so they never alias a query's table borrow. Resource parameters come first, query parameters after. Type-level filters (With, Without, Changed, Added, WithTag, WithoutTag, and tuples of them) narrow a query as Query<(&mut Position,), With<Player>>.

A single query borrows the world directly. Several queries in one system share the world through a cell and each take it only for one for_each, so two queries run in sequence rather than nested, at a cost of one borrow check per call rather than anything per entity:

use freecs::system_param::{Query, ScheduleExt};

fn resolve(positions: Query<&mut Position>, velocities: Query<&Velocity>) {
    let mut sample = (0.0, 0.0);
    velocities.for_each(|_entity, velocity| sample = (velocity.x, velocity.y));
    positions.for_each(|_entity, position| {
        position.x += sample.0;
        position.y += sample.1;
    });
}

ParamSet<(Query<…>, Query<…>)> is the alternative when you would rather name a grouped set and reach its members through p0() and p1().

Resource-only systems and systems ending in a &mut W host argument run over any ResourceHost, not just DynWorld. An engine that wraps DynWorld or DynEcs in its own world type and implements ResourceHost can register fn(Res<Input>, ResMut<Settings>, &mut MyWorld) on its own Schedule<MyWorld>, so resource parameters replace the resource_scope boilerplate while the &mut MyWorld stays free for the wrapper's own queries. A Query parameter resolves against DynWorld, and an unfiltered Query<Q> also resolves against a DynEcs group through query_join, so systems on a Schedule<DynEcs> can take one too. ParamSet, multiple query parameters, and type-level query filters are DynWorld only.

EventReader<T> and EventWriter<T> are the event-facing extract parameters, resolved against the event bus that both DynWorld and DynEcs embed. A writer buffers its sends and flushes them to the bus after the system returns; a reader keeps its own u64 cursor in the runner, so it sees each event once across frames, two readers of the same type advance independently, and a Query in the same system borrows the world alongside it. Events are copied out for the run, so the event type is Clone.

use freecs::system_param::{EventReader, EventWriter, Query, ScheduleExt};

#[derive(Clone)]
struct Collision { entity: u32 }

fn detect(query: Query<&Position>, mut writer: EventWriter<Collision>) {
    query.for_each(|_entity, position| {
        if position.x < 0.0 {
            writer.send(Collision { entity: 0 });
        }
    });
}

fn respond(reader: EventReader<Collision>) {
    for _collision in &reader {
        // handle each collision exactly once
    }
}

let mut schedule = freecs::Schedule::new();
schedule.add_systems((detect, respond));

Events

Events buffer for two frames. The default consumption is consume_events with one u64 cursor per consumer: calling it every frame delivers each event exactly once, and independent consumers never steal from each other. read_events re-reads the whole buffer and is for debugging and one-shot inspection:

#[derive(Clone, Debug)]
struct Damage { amount: f32 }

let mut world = DynWorld::new();
world.send(Damage { amount: 10.0 });

let mut cursor = 0;
for event in world.consume_events::<Damage>(&mut cursor) {
    println!("took {}", event.amount);
}
assert!(world.consume_events::<Damage>(&mut cursor).is_empty());

world.step(); // expires events after their two-frame window

Store cursors wherever the consumer lives, typically a field on a resource struct, one per event type per consumer.

States

The state feature adds an optional state machine for programs that gate systems on a screen or mode. You supply the state type (any Copy + PartialEq value); freecs supplies the current-and-next holder, the transition step, the StateTransition event, and the gating combinators. It combines the ECS layer's run conditions and system parameters with a small state model, kept behind a feature so the default build carries none of it.

insert_state stores the state, add_state_transitions registers the transition step on a schedule, next_state requests a change (applied on the next transition step, so no frame sees a mid-frame flip), and while_in, while_in_any, and run_if gate a system or a whole tuple of systems in one schedule entry. A gated system is either a plain fn(&mut World) world system or a system-parameter function, and a tuple may mix the two. on_enter and on_exit run once per transition by reading the emitted StateTransition event through their own cursor.

use freecs::Schedule;
use freecs::dynamic::DynWorld;
use freecs::system_param::{ResMut, ScheduleExt};
use freecs::state::{StateScheduleExt, insert_state, next_state, while_in, on_enter};

#[derive(Clone, Copy, PartialEq, Eq)]
enum Screen { Title, Playing }

fn tick(mut ticks: ResMut<Ticks>) { ticks.0 += 1; }
fn build_hud(/* ... */) { /* ... */ }

let mut world = DynWorld::new();
insert_state(&mut world, Screen::Title);

let mut schedule = Schedule::new();
schedule.add_state_transitions::<Screen>("screen_transitions");
schedule.push("enter_play", on_enter(Screen::Playing, build_hud));
schedule.push("play", while_in(Screen::Playing, (tick, animate, physics)));

Everything is generic over the host, so it works over DynWorld, a DynEcs group, or any wrapper that implements ResourceHost and EventHost.

Resources

let mut world = DynWorld::new();
world.insert_resource(DeltaTime(0.016));

// Fallible and infallible reads. res/res_mut panic with the type name.
assert!(world.resource::<Score>().is_none());
let delta_time = world.res::<DeltaTime>().0;
world.insert_resource(Score(0));
world.res_mut::<Score>().0 += 1;

// Scopes take resources out for one closure and put them back, even on
// panic. See Writing systems above for the tuple form.
world.resource_scope(|_world, score: &mut Score| score.0 += 1);
let _ = (delta_time, world.remove_resource::<Score>());

The scopes are the intended take/put pattern. Reach for them before hand-rolling remove then reinsert. An engine that wraps DynWorld or DynEcs in its own world type needs the closure to receive that wrapper, which the scope methods cannot do since their closures receive the bare world. Implement ResourceHost on the wrapper (one method returning the wrapped resource map) and import ResourceHostExt for the same scopes as methods on the host, host.resource_scope(...) and host.resources_scope(...). Their closures receive the host itself, with the same take/put semantics and panic reinsertion. The host must return the same map on every call, and debug builds verify the reinserted resource is still reachable, so a misrouted map fails loudly.

Tags

Tags are sparse sets outside the archetype tables: adding or removing one never migrates the entity. Name them by marker type, or hold TagKey values when the tag set itself is dynamic:

struct Boss;

let mut world = DynWorld::new();
let entity = world.spawn((Position::default(),));

world.add_tag_type::<Boss>(entity);
assert!(world.has_tag_type::<Boss>(entity));
assert_eq!(world.query_tag_type::<Boss>().count(), 1);
world
    .query_ref::<&Position>()
    .with_tag_type::<Boss>()
    .iter()
    .count();
world.remove_tag_type::<Boss>(entity);

// The keyed form for runtime-defined tags.
let elite = world.register_tag();
world.add_tag(elite, entity);
assert!(world.has_tag(elite, entity));

Hierarchies

ChildOf is a plain up-pointing link, pull-maintained with no hooks:

use freecs::dynamic::ChildOf;

let mut world = DynWorld::new();
let parent = world.spawn((Position::default(),));
let child = world.spawn((Position::default(), ChildOf(parent)));

assert_eq!(world.children(parent), vec![child]);
world.despawn_recursive(parent); // cycle-tolerant, follows links breadth-first
assert!(!world.is_alive(child));

In a DynEcs group, use ecs.despawn_recursive(root) instead so the cascade despawns through the group.

Hierarchy-heavy consumers keep a HierarchyIndex, a consumer-owned map synced by pull from the structural log and change ticks, so lookups stop scanning and each sync costs what changed:

use freecs::dynamic::{ChildOf, HierarchyIndex};

let mut world = DynWorld::new();
let mut hierarchy = HierarchyIndex::new();

let parent = world.spawn((Position::default(),));
let child = world.spawn((Position::default(), ChildOf(parent)));

hierarchy.sync(&mut world); // once a frame, or before reading
assert_eq!(hierarchy.children(parent), &[child]);
assert_eq!(hierarchy.descendants(parent), vec![child]);
hierarchy.despawn_recursive(&mut world, parent);

Every link write that stamps change ticks is picked up: spawns, set, migrations, and raw-tier writes followed by mark_changed. Reads reflect the last sync.

Deferred commands

Queue structural changes while iterating and apply them at a safe point:

let mut world = DynWorld::new();
let entity = world.spawn((Position::default(), Health { value: 1.0 }));

world.query::<&Health>().for_each(|entity, health| {
    let _ = (entity, health);
});

world.queue_set(entity, Health { value: 50.0 });
world.queue_despawn_entity(entity);
world.queue(|world| {
    let _ = world.spawn((Position::default(),));
});
world.apply_commands();

queue_add_components, queue_remove_components, queue_add_tag_type, and queue_spawn_entities round out the set.

Change detection and sync

Both are opt-in on a dynamic world, because both cost something on every write whether or not anyone reads them: change detection keeps two u32 columns beside each component column and stamps a tick per row on every mutable query, and the structural log pushes an entry per entity per structural change. Turn on what you consume, before the spawns you want to observe:

let mut world = DynWorld::new();
world.set_change_detection(true);
world.structural_logging = true;

let position = world.register::<Position>();
let entity = world.spawn((Position::default(),));

world.step();
world.get_mut::<Position>(entity).unwrap().x = 1.0;

// Which entities changed since the last step?
assert_eq!(world.query_entities_changed(position.mask).count(), 1);

// changed/added as query filters, on both query forms.
world
    .query_ref::<&Position>()
    .added::<Position>()
    .iter()
    .count();

// Structural history: spawns, despawns, component moves, tag flips.
let mut cursor = 0;
for change in world.structural_changes_since(cursor) {
    let _ = (change.entity, change.kind, change.mask);
}
cursor = world.structural_sequence();
world.trim_structural_log(cursor);

// Raw-tier writes skip stamping, so opt in explicitly when tick diffing
// matters (see Change Detection above for the static twin).
world.mark_changed(entity, position.mask);

Leave them off and the feature degrades quietly rather than loudly: changed::<T>(), added::<T>(), and the for_each_mut_changed family match nothing, and structural_changes_since reports that nothing happened, exactly as under raw_storage. HierarchyIndex::sync notices and rebuilds from a scan instead of diffing, so it stays correct either way. DynEcs has the same structural_logging switch for its group-level lifecycle log, and each member world opts in separately. The static ecs! tier is unaffected: its change ticks and structural log are still always on.

Entity inspection

The registry is the schema, and it is queryable, which is what editors and tooling protocols build on:

let mut world = DynWorld::new();
let entity = world.spawn((Position::default(), Health { value: 3.0 }));

for info in world.entity_components(entity) {
    println!("{} on bit {}", info.type_name, info.mask.trailing_zeros());
}

// Add-by-name for a default value works today with public pieces.
let named_mask = world
    .component_by_name(std::any::type_name::<Health>())
    .map(|info| info.mask);
if let Some(mask) = named_mask {
    let other = world.spawn((Position::default(),));
    world.add_components(other, mask);
}

With the snapshot feature, serde-registered components also move as values: set_component_by_name / get_component_by_name exchange one component as codec bytes resolved by type name (grouped worlds route the name to the owning member), so an editor protocol reads and writes any component over the wire with no per-type dispatch. Writes add the component when absent and stamp change ticks like any set.

Three access tiers, from ergonomic to explicit:

  • Typed: spawn(bundle) / spawn_bundles(bundle, count) / queue_spawn(bundle) returning the handle before the command applies, get::<T> / set / remove, query::<(&mut A, &B)>() with Option<&T> elements, up to eight per tuple, and bare single elements (query::<&mut A>()), changed::<T>() and added::<T>() filters on both query forms (after set_change_detection(true)), query_ref iterators on &world with single() and iter_combinations(), marker-type tags (add_tag_type::<T>, with_tag_type::<T>()), despawn_with_any::<(A, B)>(), ChildOf links with children / despawn_recursive, entity inspection (entity_components, component_by_name), resource_scope / resources_scope over tuples, send(event) / consume_events::<T>(&mut cursor), insert_resource / resource::<T>() / res::<T>(). TypeId lookups happen at registration and per typed call, never inside iteration loops.
  • Keyed: register::<T>() returns a copyable ComponentKey<T> carrying the component's mask bit. get_keyed / set_keyed and mask-based for_each / for_each_mut skip the hash entirely.
  • Raw tables: for_each_tables_mut(mask, 0, |table| ...) with table.columns_pair(a, b) hoists concrete slices once per table for the tightest loops, no change stamping, same covenant as the static path.

Measured against the macro world on the same two-component mutation workload (three f32 writes per entity), the typed query runs 0.83 µs per 1k entities versus 1.12 µs for the static for_each_mut closure form, and 75 µs versus 116 µs per 100k. The hoisted table form does 7.3 µs per 10k versus 11.6 µs. The slice-zip loop shapes vectorize better than per-entity index closures, so at scale the dynamic fast paths come out ahead. The costs are elsewhere and bounded. Batch spawning pays function-pointer column fills (16.5 µs versus 12.2 µs per 1k spawns), per-entity typed access pays the TypeId map (16.5 ns versus 6.8 ns keyed), and every column adds one Box indirection per table.

Component types need Send + Sync + Default + 'static, the same effective bounds the macro path relies on (Default because migration moves values with mem::take, Send + Sync for parallel iteration).

Grouped dynamic worlds

DynEcs groups dynamic worlds over one shared entity allocator, the dynamic counterpart of the macro's multi-world form and the escape hatch past 64 components. Each member world carries its own registry and full mask space, one entity can hold rows in any combination of worlds, and despawning retires it everywhere with the same generation broadcast the static multi-world uses, so stale handles are refused in every member. Group tags live outside any world's mask space and filter per-world typed queries by set reference.

The group is also where state and signals that cross member (and plugin) boundaries live: DynEcs carries its own resource map (insert_resource / res / resource_scope / resources_scope, same semantics as the world's) and its own event channels (send / consume_events with per-consumer cursors), and ecs.step() expires group events and steps every member world in one call. World-local resources and events remain on each DynWorld. The two levels are separate channels, not mirrors.

Marker tags exist at the group level too (ecs.add_tag_type::<Selected>, remove_tag_type, has_tag_type, query_tag_type), and they're the right home for entity-scoped markers in a grouped world. They spend no member world's mask bits, need no world index to touch, land in the group structural log, and drop on group despawn. ecs.tag_set_type::<T>() hands the set to any per-world typed query via with_tag_set/without_tag_set. Marker memberships survive snapshots: the group persists each tag's type name and re-binds the marker to its set on first use after a load.

Tuples that span member worlds run through ecs.query_join: one world drives the iteration at full slice speed (the world holding every mutable element), the others resolve their elements per entity at get speed, read-only, skipping entities that lack a required foreign component. Mutable elements in two different worlds panic. Mutate your own state and read theirs, or co-locate the types in one schema when a hot loop needs slice speed for everything (registries compose, so two parts sharing a member world is a declaration choice, not a framework feature). A tuple that resolves to one world degenerates to a plain scan. Joins filter by group marker tags (with_tag_type / without_tag_type) and by driver-world changed / added windows:

ecs.query_join::<(&mut Position, &Burning)>()
    .for_each(|_entity, (position, burning)| {
        position.y += burning.lift;
    });

Joins carry the same surface as the single-world forms. query_join_ref runs the read-only join as a real Iterator on &ecs, and query_join(...).par_for_each(...) walks driver tables in parallel with foreign worlds shared read-only across threads. world.stats() and ecs.stats() return a census of tables, budgets, logs, and caches for editor overlays, and compact() drops empty archetype tables at loading screens.

Declare the members once with dynamic_worlds! (index constants plus the build function, each member asserted at its declared index, and apps extending a built group use add_world_at):

freecs::dynamic_worlds! {
    pub fn build_ecs {
        CORE => register_core_components,
        UI => register_ui_components,
    }
}

Since a component type lives in exactly one member world (enforced when a member is added, and diagnosed with both world indices if a later lazy registration creates a duplicate), the group routes typed access itself: ecs.get::<T>(), set, get_mut, has, remove, query, and query_ref resolve the owning world per type (first member in index order, cached in the public type_routes map), and ecs.spawn_with(bundle) spawns one group entity with each component routed to its world, so bundles span worlds. Routed access never registers types lazily. Where a type lives is a schema decision, so set on an unregistered type panics instead of guessing. Member indexing remains for world-level operations, snapshots, and structural logs:

use freecs::dynamic::{ComponentRegistry, DynEcs};

let mut ecs = DynEcs::new();
let core = ecs.add_world(ComponentRegistry::new());
let render = ecs.add_world(ComponentRegistry::new());
let selected = ecs.register_tag();

let entity = ecs.spawn();
ecs.worlds[core].set(entity, Position { x: 1.0, y: 0.0 });
ecs.worlds[render].set(entity, Sprite { id: 7 });
ecs.add_tag(selected, entity);

let DynEcs { worlds, tags, .. } = &mut ecs;
worlds[core]
    .query::<(&mut Position,)>()
    .with_tag_set(&tags[selected])
    .for_each(|_entity, (position,)| position.x += 1.0);

// The group keeps its own lifecycle log, the same two-log split as the
// macro multi-world: "entity spawned or died anywhere" and group tag flips
// are one cursor-consumed stream on the group, while each member world's
// structural log records that world's row history.
let mut cursor = 0;
for change in ecs.structural_changes_since(cursor) {
    // Spawned / Despawned with mask 0, TagsAdded / TagsRemoved carrying
    // the group tag index in the mask field.
    let _ = (change.entity, change.kind);
}
cursor = ecs.structural_sequence();
ecs.trim_structural_log(cursor);

The lifecycle log is verified against the macro multi-world's by the differential oracle: one seeded op stream drives both forms and requires entry-for-entry identical logs.

ChildOf hierarchies cascade at the group level too: ecs.despawn_recursive(root) follows links across every member world and despawns through the group, so retirement broadcasts everywhere and each death lands in the lifecycle log. In a group, prefer it over the single-world form.

Snapshots

The snapshot feature makes dynamic worlds serializable. Components register with a column codec, register_serde::<T>() uses postcard for the column bytes, or register_codec supplies any byte format, and world.snapshot() produces a plain DynWorldSnapshot you serialize with whatever serde format you like. DynWorld::from_snapshot(registry, &snapshot) rebuilds the world over a registry with the same registration order (appending new components after the snapshot's schema is fine, masks stay stable). Allocator state survives, so despawned ids recycle correctly after a load, stale-handle refusal is reconstructed from allocator liveness even for entities that never had a row, and every restored slot reads as changed so incremental consumers resync. Events, pending commands, and the structural log are transient and not captured. DynEcs snapshots the same way with one registry per member world.

The trust boundary is the registry. Bits are assigned in registration order, so registration is schema: build one ComponentRegistry, clone it into every world that must agree on masks, and register deterministically if masks are ever serialized. Keys carry their registry id and are debug-checked against the world using them. Query tuples must not repeat a component type, and a wrong-type column swapped in by hand panics on the next typed access rather than misbehaving.

Components and tags share each world's 64 mask bits, components from bit 0 up and tags from bit 63 down, and lazy registration spends bits silently, so check world.remaining_bits() in a startup assertion rather than discovering the ceiling when registration 65 panics.

Deltas are the incremental form: world.delta_cursor() starts a stream (fencing the change window), world.delta_since(&cursor) captures everything that changed as a serialized change-set, and replica.apply_delta(&delta) replays it onto a replica seeded from a full snapshot of the same lineage. Structural entries replay in order, changed component values ride the same codecs snapshots use, and a trimmed or overflowed structural log fails the capture loudly so the caller reseeds from a full snapshot instead of silently diverging. DynEcs has the group forms (delta_cursor / delta_since / apply_delta), covering handle lifecycle, group tags, and every member world in one change-set. This is the substrate for network replication and efficient autosave.

Named accessors over the keyed tier

Heavy users who miss the macro world's generated names (get_position, set_velocity, add_boss) get them back from dynamic_accessors!: it generates a keys struct, a resolve constructor registering everything in declaration order, and the named methods on your wrapper type, all over the keyed tier, so they skip the TypeId hash and stamp change ticks exactly like the macro world's accessors:

use freecs::dynamic::DynWorld;

struct Boss;

struct Game {
    world: DynWorld,
    keys: GameKeys,
}

freecs::dynamic_accessors! {
    pub struct GameKeys for Game { world, keys }
    components {
        position: Position,
        velocity: Velocity,
    }
    tags {
        boss: Boss,
    }
}

let mut world = DynWorld::new();
let keys = GameKeys::resolve(&mut world);
let mut game = Game { world, keys };

let entity = game.world.spawn((Position::default(),));
game.set_position(entity, Position { x: 1.0, y: 0.0 });
game.add_boss(entity);
assert!(game.has_boss(entity));

Per component: get_ / get_<name>_mut / set_ / remove_ / has_. Per tag: add_ / remove_ / has_ / query_. Combine with dynamic_schema! when the same declaration also needs mask constants and a shared registry.

Multi-World ECS

For projects exceeding 64 component types, you can split components across multiple independent worlds that share a single entity allocator. Each world retains full u64 bitmask performance (up to 64 components per world).

use freecs::{ecs, Entity, Schedule};

ecs! {
    GameEcs {
        CoreWorld {
            position: Position => POSITION,
            velocity: Velocity => VELOCITY,
        }
        RenderWorld {
            sprite: Sprite => SPRITE,
            color: Color => COLOR,
        }
    }
    Tags { player => PLAYER }
    Events { collision: CollisionEvent }
    GameResources { delta_time: f32 }
}

Entities are spawned from the shared allocator and can have components in any combination of worlds:

let mut ecs = GameEcs::default();

// Spawn an entity and add components across worlds
let entity = ecs.spawn();
ecs.core_world.set_position(entity, Position { x: 0.0, y: 0.0 });
ecs.render_world.set_sprite(entity, Sprite { id: 1 });

// EntityBuilder spans worlds automatically
let entities = EntityBuilder::new()
    .with_position(Position { x: 0.0, y: 0.0 })
    .with_sprite(Sprite { id: 2 })
    .spawn(&mut ecs, 1);

// Per-world queries run at full bitmask speed
ecs.core_world.for_each_mut(POSITION | VELOCITY, 0, |entity, table, idx| {
    table.position[idx].x += table.velocity[idx].x;
});

// Cross-world access via split borrowing
let GameEcs { core_world, render_world, player, .. } = &mut ecs;
core_world.for_each(POSITION, 0, |entity, table, idx| {
    if let Some(sprite) = render_world.get_sprite(entity) {
        // Access components from both worlds
    }
});

// Despawn cascades across all worlds and returns false for stale handles
ecs.despawn(entity);

Despawning is safe against reuse: despawn refuses stale or already-despawned handles (returning false), and stale handles cannot re-add components in any world, including worlds that never stored the entity. That guarantee is paid for in memory. Despawn broadcasts the retired generation into every world's location table, so each world's table grows to cover any despawned id, 16 bytes per id per world. The trust boundary is the shared allocator: a handle forged for an id it never issued can still insert a row, since worlds have no allocator access.

Tags, events, resources, command buffers, and Schedule all work identically in multi-world mode. Structural history is split across two kinds of log, and consumers should pick one oracle per purpose. The ECS keeps a lifecycle log (structural_changes_since on the ECS) recording handle allocation and death (Spawned/Despawned with mask 0) plus tag flips. Each world keeps its own row-level log, where an entity is Spawned with a component mask when its first components arrive in that world and Despawned when its row leaves. An entity that gains components therefore appears as Spawned once in the ECS log and once per world it enters. Sync world contents from world logs, and handle lifetime or tags from the ECS log, rather than merging both.

One asymmetry is that per-world query masks contain only that world's component bits, so tags cannot appear in per-world masks (asserted in debug builds). Tag filtering in multi-world uses the tag-set variants with split borrows:

let GameEcs { core_world, player, .. } = &ecs;
core_world.for_each_with_tags(POSITION, 0, &[player], &[], |entity, table, idx| {
    // Entities with position that carry the player tag
});

Component mask constants (e.g. POSITION, SPRITE) have globally unique names but each world numbers its components independently starting at bit 0, so never mix masks from different worlds in one query.

Single-world syntax remains unchanged. Multi-world is detected by the presence of multiple Ident { ... } blocks inside the first group.

License

This project is licensed under the MIT License - see the LICENSE file for details.