Struct World 

pub struct World { /* private fields */ }

ECS World containing all entities, components and tags

Tag System

Tags are lightweight string labels stored as bitmasks (u128).

• Up to 128 unique tags globally
• O(1) tag filtering in queries
• Tags are not components (no storage overhead per entity)

Deferred Operations

Use world.defer() to queue operations that modify the World during iteration. Applied via apply_deferred() at frame end.

Example

let mut world = World::new();

// Create entity with components and tags
let player = world.spawn()
    .insert(Position { x: 0.0, y: 0.0 })
    .insert(Velocity { x: 1.0, y: 0.0 })
    .tag("player")
    .tag("friendly")
    .id();

// Immutable query
world.select::<(Position, Velocity)>()
    .tagged("player")
    .each(|entity, (pos, vel)| {
        println!("{}: {:?}", entity, pos);
    });

// Mutable query
world.select_mut::<(Position, Velocity)>()
    .not_tagged("frozen")
    .each(|entity, (pos, vel)| {
        pos.x += vel.x;
        pos.y += vel.y;
    });

Implementations

impl World

pub fn new() -> World

Creates a new empty World

pub fn spawn(&mut self) -> EntityBuilder<'_>

Starts building a new entity

Returns an EntityBuilder for fluent API chaining. Entity IDs are reused from a free list after destruction.

pub fn is_alive(&self, entity: Entity) -> bool

Checks if an entity is alive and matches the given generation

Returns false if:

• Entity ID not in alive set
• Generation mismatch (entity was destroyed and ID reused)

pub fn destroy(&mut self, entity: Entity) -> bool

Destroys an entity and removes all its components and tags

The entity ID is added to a free list for reuse. The generation counter is increased to invalidate old references.

Returns true if the entity was alive, false otherwise.

pub fn insert<C>(&mut self, entity: Entity, component: C)

where C: Component,

Inserts a component into an entity

If the entity already has this component type, it will be replaced. Does nothing if the entity is not alive.

pub fn remove<C>(&mut self, entity: Entity) -> bool

where C: Component,

Removes a component from an entity

Returns true if the component was removed, false if not found.

pub fn get<C>(&self, entity: Entity) -> Option<&C>

where C: Component,

Gets an immutable reference to a component

Returns None if:

• Entity is not alive
• Entity doesn’t have this component type

pub fn get_mut<C>(&mut self, entity: Entity) -> Option<&mut C>

where C: Component,

Gets a mutable reference to a component

Returns None if:

• Entity is not alive
• Entity doesn’t have this component type

pub fn has<C>(&self, entity: Entity) -> bool

where C: Component,

Checks if an entity has a component of the given type

pub fn has_tag(&self, entity: Entity, tag: &str) -> bool

Checks if an entity has a specific tag

This is O(1) after the tag name lookup.

pub fn tag(&mut self, entity: Entity, tag: &str)

Attaches a tag to an entity

Tags are stored as bitmasks for fast filtering in queries. Does nothing if the entity is not alive.

Panics

Panics if more than 128 unique tags are created globally.

pub fn untag(&mut self, entity: Entity, tag: &str)

Removes a tag from an entity by clearing its bit in the bitmask

pub fn get_entity_tags(&self, entity_id: u32) -> Vec<String>

Returns all tag names associated with an entity

Primarily used for debugging and inspection.

pub fn select<T>(&self) -> Query<'_, T>

where T: for<'w> QueryTuple<'w>,

Starts an immutable query

Example

world.select::<(Position, Velocity)>()
    .tagged("player")
    .each(|entity, (pos, vel)| {
        println!("{:?}", pos);
    });

pub fn select_mut<T>(&mut self) -> QueryMut<'_, T>

where T: for<'w> QueryTupleMut<'w>,

Starts a mutable query

Example

world.select_mut::<(Position, Velocity)>()
    .not_tagged("frozen")
    .each(|entity, (pos, vel)| {
        pos.x += vel.x;
    });

pub fn defer<F>(&mut self, f: F)

where F: FnOnce(&mut World) + Send + Sync + 'static,

Queues an operation to be executed later via apply_deferred()

Useful for spawning/destroying entities during query iteration.

Example

world.select::<(Health,)>().each(|entity, (health,)| {
    if health.0 <= 0 {
        world.defer(move |w| {
            w.destroy(entity);
        });
    }
});
world.apply_deferred();

pub fn apply_deferred(&mut self)

Executes all queued deferred operations

Called automatically each frame by apply_deferred_system.

pub fn entity_count(&self) -> usize

Returns the number of alive entities

pub fn dump_all_memory(&self)

Prints physical memory layout of all component storages (debug only)

Shows memory addresses and byte offsets to verify:

• Components are stored contiguously
• Cache-friendly memory access patterns

Only enabled in debug builds to avoid I/O overhead.

pub fn inspect(&self)

Prints a formatted table of all entities and their components (debug only)

Shows:

• Entity IDs and generations
• Attached tags
• Component values

Useful for debugging game state and verifying entity configurations. Only enabled in debug builds to avoid string formatting overhead.

Trait Implementations

impl Default for World

fn default() -> World

Returns the “default value” for a type.