freecs 3.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
  • Sequence-numbered event channels with exactly-once cursor consumption
  • Structural change log covering spawns, despawns, component moves, and tag flips
  • Multi-world support for >64 component types with shared entity allocator
  • Two first-class entry points: 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, over the same storage and 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 first-class entry points over the same archetype storage. The ecs! macro fixes your component set at compile time and generates a named accessor for everything, which is the fastest path to a working game. The dynamic world registers component types at runtime for programs that cannot know their schema up front, editors, plugin hosts, data-driven prefabs, and its typed queries compile to the same slice loops. Pick whichever fits, or run both side by side.

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;
        });
    }
}

Dynamic: DynWorld

Enable the feature:

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

The same game shape with runtime registration, no macro and no masks:

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 }

struct Player;

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

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

    // Types register lazily on first use; tuples spawn as bundles.
    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);

    // Typed queries take mutability from the tuple; Option elements match
    // entities with or without the component.
    world.resources_scope(|world, (delta_time, score): &mut (DeltaTime, Score)| {
        world
            .query::<(&mut Position, &Velocity, Option<&mut Health>)>()
            .for_each(|_entity, (position, velocity, health)| {
                position.x += velocity.x * delta_time.0;
                position.y += velocity.y * delta_time.0;
                if let Some(health) = health {
                    health.value *= 0.98;
                }
            });
        score.0 += 1;
    });

    // Read-only queries on &world are real iterators.
    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).

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 exactly why per-frame handlers must consume through cursors: the two-frame buffer means read_/collect_ deliver the same event on both frames, and consume_ is what 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: 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;
    });
}

Parallelism granularity: 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.

Note: Parallel methods are only available when targeting non-WASM platforms. On WASM targets, use the regular 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 are perfect 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; 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.

Fixed cost: change tracking stores one u32 per component per entity plus a tick stamp on every accessor write, whether or not you consume it. That is the price of the feature always being available.

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.

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:

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; marks 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.

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, structural log, 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.

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();

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

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

// Components and tags share 64 bits per world; 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; 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(),));

// The workhorse: 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;
        }
    });

// Filters: with/without by type, mask, or tag, and changed/added windows.
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() is the exactly-one-match read, the get-the-player call.
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);
}

Writing systems

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

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();

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.

Resources

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

// Fallible and infallible reads; expect_* panics with the type name.
assert!(world.resource::<Score>().is_none());
let delta_time = world.expect_resource::<DeltaTime>().0;
world.insert_resource(Score(0));
world.expect_resource_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>());

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

Mutable typed-query elements and the typed/keyed accessors stamp change ticks; added ticks stamp when a component arrives and survive table migrations. Incremental consumers diff by tick, structural consumers read the log by cursor:

let mut world = DynWorld::new();
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; opt in explicitly when tick diffing
// matters (see Change Detection above for the static twin).
world.mark_changed(entity, position.mask);

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);
}

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, 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>() / expect_resource::<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 the dynamic fast paths are not merely competitive, at scale they are ahead. The costs live elsewhere and are 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:

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.

Named accessors over the keyed tier

Heavy users who miss the macro's generated names (get_position, set_velocity) can have them back in about ten lines: wrap the world with a Keys struct resolved once at construction, and map names to the keyed tier with a local macro. The keyed accessors stamp change ticks identically to the macro's and skip the TypeId hash, so the wrappers run at keyed speed:

use freecs::dynamic::{ComponentKey, DynWorld};

struct Keys {
    position: ComponentKey<Position>,
    velocity: ComponentKey<Velocity>,
}

struct GameWorld {
    world: DynWorld,
    keys: Keys,
}

macro_rules! named_accessors {
    ($($name:ident: $type:ty),+ $(,)?) => {
        freecs::paste::paste! {
            impl GameWorld {
                $(
                    pub fn [<get_ $name>](&self, entity: freecs::Entity) -> Option<&$type> {
                        self.world.get_keyed(self.keys.$name, entity)
                    }

                    pub fn [<get_ $name _mut>](&mut self, entity: freecs::Entity) -> Option<&mut $type> {
                        self.world.get_mut_keyed(self.keys.$name, entity)
                    }

                    pub fn [<set_ $name>](&mut self, entity: freecs::Entity, value: $type) {
                        self.world.set_keyed(self.keys.$name, entity, value);
                    }
                )+
            }
        }
    };
}

named_accessors!(position: Position, velocity: Velocity);

The registration function that builds Keys becomes the single source of truth for the component set: define the type, add one line there and one to the macro invocation. The correctness story is the same suite the macro worlds earned: unit coverage, the three-oracle property tests, and a differential oracle that drives a macro world and a DynWorld with one seeded op stream and requires identical observable state at every step.

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; 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: per-world query masks contain only that world's component bits, so tags cannot appear in per-world masks (this is 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.