Struct EntityPtr 

pub struct EntityPtr { /* private fields */ }

An ergonomic smart pointer to an entity with embedded World reference.

Created from WorldRef::entity(). Provides fluent method chaining without repeatedly passing &World.

Size

16 bytes (Entity + &'static World)

Thread Safety

NOT Send, NOT Sync - must stay on the creating thread.

Implementations

impl EntityPtr

pub const fn entity(self) -> Entity

Returns the underlying Entity.

pub const fn handle(self) -> EntityHandle

Returns an EntityHandle for storage in components.

Examples found in repository

examples/mixed_usage.rs (line 146)

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

    println!("=== Mixed Usage Example ===\n");

    // Build a linked list: a -> b -> c -> d
    println!("Building linked list: a -> b -> c -> d\n");

    let d = world.spawn((Name("d"), LinkedList { next: None })).id();
    let c = world
        .spawn((
            Name("c"),
            LinkedList {
                next: Some(EntityHandle::new(d)),
            },
        ))
        .id();
    let b = world
        .spawn((
            Name("b"),
            LinkedList {
                next: Some(EntityHandle::new(c)),
            },
        ))
        .id();
    let a = world
        .spawn((
            Name("a"),
            LinkedList {
                next: Some(EntityHandle::new(b)),
            },
        ))
        .id();

    // Store handle for later use (EntityHandle is Send + Sync)
    let a_handle = EntityHandle::new(a);

    // === BoundEntity approach ===
    println!("--- BoundEntity Approach (explicit &World) ---");

    let bound = a_handle.bind(&world);
    let length = count_chain_length_bound(bound);
    println!("Chain length from 'a': {}", length);
    assert_eq!(length, 4);

    // Get component with explicit world
    let name = a_handle.get::<Name>(&world).unwrap().0;
    println!("Starting node name: {}", name);

    // === EntityPtr approach ===
    println!("\n--- EntityPtr Approach (ergonomic) ---");

    // No unsafe needed! WorldExt provides ergonomic access
    let ptr = world.entity_ptr(a_handle.entity()); // Convert handle to ptr

    let length = count_chain_length_ptr(ptr);
    println!("Chain length from 'a': {}", length);
    assert_eq!(length, 4);

    // Convert back to handle
    let back_to_handle = ptr.handle();
    assert_eq!(back_to_handle.entity(), a_handle.entity());
    println!("Round-trip handle conversion: OK");

    // === Team example ===
    println!("\n--- Team Example ---");

    // Create team members
    let alice = world.spawn((Name("Alice"), Health(100))).id();
    let bob = world.spawn((Name("Bob"), Health(80))).id();
    let charlie = world.spawn((Name("Charlie"), Health(120))).id();

    // Create team leader with team
    let leader = world
        .spawn((
            Name("Leader"),
            Health(150),
            Team(vec![
                EntityHandle::new(alice),
                EntityHandle::new(bob),
                EntityHandle::new(charlie),
            ]),
        ))
        .id();

    // Calculate total team health using EntityPtr
    let leader_ptr = world.entity_ptr(leader);
    let total = team_health(leader_ptr);
    println!("Total team health: {}", total);
    println!("  Expected: 150 + 100 + 80 + 120 = 450");
    assert_eq!(total, 450);

    // Find team member using BoundEntity
    let leader_bound = EntityHandle::new(leader).bind(&world);
    let bob_bound = find_team_member(leader_bound, "Bob").unwrap();
    let bob_health = bob_bound.get::<Health>().unwrap().0;
    println!("Bob's health: {}", bob_health);
    assert_eq!(bob_health, 80);

    // === Stale Reference Handling ===
    println!("\n--- Stale Reference Handling ---");

    let temp = world.spawn((Name("Temporary"), Health(50))).id();
    let temp_handle = EntityHandle::new(temp);

    // Check it's alive
    println!("Before despawn:");
    println!("  is_alive: {}", temp_handle.is_alive(&world));
    println!("  name: {:?}", temp_handle.get::<Name>(&world).map(|n| n.0));
    assert!(temp_handle.is_alive(&world));

    // Despawn the entity
    world.despawn(temp);

    // Handle gracefully returns None
    println!("After despawn:");
    println!("  is_alive: {}", temp_handle.is_alive(&world));
    println!("  name: {:?}", temp_handle.get::<Name>(&world).map(|n| n.0));
    assert!(!temp_handle.is_alive(&world));
    assert!(temp_handle.get::<Name>(&world).is_none());

    // === Mixing approaches in computation ===
    println!("\n--- Mixing Approaches ---");

    // Start with a stored handle
    let leader_handle = EntityHandle::new(leader);

    // Use BoundEntity for one part of the computation
    let bound = leader_handle.bind(&world);
    let leader_name = bound.get::<Name>().unwrap().0;

    // Switch to EntityPtr for another part
    let ptr = world.entity_ptr(leader_handle.entity());
    let total_health = team_health(ptr);

    println!(
        "{}'s team has total health of {}",
        leader_name, total_health
    );

    // Can also convert EntityPtr back to BoundEntity's handle
    let ptr_handle = ptr.handle();
    let rebound = ptr_handle.bind(&world);
    assert_eq!(rebound.get::<Name>().unwrap().0, leader_name);
    println!("Seamless conversion between approaches: OK");

    println!("\nAll assertions passed!");
}

pub fn get<T: Component>(self) -> Option<&'static T>

Gets a component from this entity.

Returns None if the entity doesn’t exist or doesn’t have the component.

Lifetime Note

The returned reference has a 'static lifetime because EntityPtr carries a 'static world reference. This is safe as long as the WorldRef safety contract is upheld (world outlives all EntityPtrs). However, this means the borrow checker cannot prevent use-after-free if the world is dropped while references are held. Always ensure EntityPtr usage is scoped within a single system execution.

Examples found in repository

examples/tree_traversal.rs (line 31)

fn sum_tree(node: EntityPtr) -> i32 {
    let my_value = node.get::<Value>().map(|v| v.0).unwrap_or(0);

    let children_sum: i32 = node
        .get::<Children>()
        .map(|c| c.0.iter().map(|h| sum_tree(node.follow_handle(*h))).sum())
        .unwrap_or(0);

    my_value + children_sum
}

// Recursive function to find the root by traversing parent links
fn find_root(node: EntityPtr) -> EntityPtr {
    match node.follow::<Parent, _>(|p| p.0) {
        Some(parent) => find_root(parent),
        None => node,
    }
}

// Recursive function to compute tree depth
fn tree_depth(node: EntityPtr) -> usize {
    node.get::<Children>()
        .map(|c| {
            c.0.iter()
                .map(|h| tree_depth(node.follow_handle(*h)))
                .max()
                .unwrap_or(0)
                + 1
        })
        .unwrap_or(0)
}

// Recursive function to collect all node names in pre-order
fn collect_names(node: EntityPtr, names: &mut Vec<&'static str>) {
    if let Some(name) = node.get::<Name>() {
        names.push(name.0);
    }

    if let Some(children) = node.get::<Children>() {
        for child_handle in &children.0 {
            collect_names(node.follow_handle(*child_handle), names);
        }
    }
}

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

    // Build a tree:
    //
    //           root (10)
    //          /    \
    //       a (5)   b (3)
    //         |
    //       c (2)
    //         |
    //       d (7)
    //
    println!("Building tree structure...\n");

    let d = world.spawn((Name("d"), Value(7))).id();
    let c = world
        .spawn((Name("c"), Value(2), Children(vec![EntityHandle::new(d)])))
        .id();
    // Add parent link to d
    world.entity_mut(d).insert(Parent(EntityHandle::new(c)));

    let a = world
        .spawn((Name("a"), Value(5), Children(vec![EntityHandle::new(c)])))
        .id();
    world.entity_mut(c).insert(Parent(EntityHandle::new(a)));

    let b = world.spawn((Name("b"), Value(3))).id();

    let root = world
        .spawn((
            Name("root"),
            Value(10),
            Children(vec![EntityHandle::new(a), EntityHandle::new(b)]),
        ))
        .id();
    world.entity_mut(a).insert(Parent(EntityHandle::new(root)));
    world.entity_mut(b).insert(Parent(EntityHandle::new(root)));

    // No unsafe needed! WorldExt provides ergonomic access
    // Demonstrate tree operations
    let root_ptr = world.entity_ptr(root);

    // 1. Sum all values
    let total = sum_tree(root_ptr);
    println!("Sum of all values in tree: {}", total);
    println!("  Expected: 10 + 5 + 2 + 7 + 3 = 27");
    assert_eq!(total, 27);

    // 2. Find root from any node
    let d_ptr = world.entity_ptr(d);
    let found_root = find_root(d_ptr);
    let root_name = found_root.get::<Name>().unwrap().0;
    println!("\nFinding root from node 'd': {}", root_name);
    assert_eq!(root_name, "root");

    let b_ptr = world.entity_ptr(b);
    let found_root = find_root(b_ptr);
    let root_name = found_root.get::<Name>().unwrap().0;
    println!("Finding root from node 'b': {}", root_name);
    assert_eq!(root_name, "root");

    // 3. Compute tree depth (number of edges on longest path)
    let depth = tree_depth(root_ptr);
    println!("\nTree depth from root: {}", depth);
    println!("  Expected: 3 (root->a, a->c, c->d = 3 edges)");
    assert_eq!(depth, 3);

    let a_ptr = world.entity_ptr(a);
    let a_depth = tree_depth(a_ptr);
    println!("Subtree depth from 'a': {}", a_depth);
    assert_eq!(a_depth, 2);

    // 4. Collect all names in pre-order traversal
    let mut names = Vec::new();
    collect_names(root_ptr, &mut names);
    println!("\nPre-order traversal: {:?}", names);
    assert_eq!(names, vec!["root", "a", "c", "d", "b"]);

    println!("\nAll assertions passed!");
}

examples/concurrent_systems.rs (line 46)

fn sum_health(node: EntityPtr) -> i32 {
    let my_health = node.get::<Health>().map(|h| h.0).unwrap_or(0);

    let children_health: i32 = node
        .get::<Children>()
        .map(|c| c.0.iter().map(|h| sum_health(node.follow_handle(*h))).sum())
        .unwrap_or(0);

    my_health + children_health
}

// Recursive helper: sum armor across a hierarchy
fn sum_armor(node: EntityPtr) -> i32 {
    let my_armor = node.get::<Armor>().map(|a| a.0).unwrap_or(0);

    let children_armor: i32 = node
        .get::<Children>()
        .map(|c| c.0.iter().map(|h| sum_armor(node.follow_handle(*h))).sum())
        .unwrap_or(0);

    my_armor + children_armor
}

examples/entity_graph.rs (line 49)

fn total_weight(character: EntityPtr) -> f32 {
    character
        .get::<Inventory>()
        .map(|inv| {
            inv.0
                .iter()
                .filter_map(|h| character.follow_handle(*h).get::<Weight>())
                .map(|w| w.0)
                .sum()
        })
        .unwrap_or(0.0)
}

// Get equipped weapon damage (if any)
fn equipped_damage(character: EntityPtr) -> Option<i32> {
    character
        .get::<Equipped>()
        .and_then(|e| e.weapon)
        .and_then(|h| character.follow_handle(h).get::<Damage>())
        .map(|d| d.0)
}

// Get equipped armor defense (if any)
fn equipped_defense(character: EntityPtr) -> Option<i32> {
    character
        .get::<Equipped>()
        .and_then(|e| e.armor)
        .and_then(|h| character.follow_handle(h).get::<Defense>())
        .map(|d| d.0)
}

// Get target's name and health (if targeting someone)
fn target_info(character: EntityPtr) -> Option<(&'static str, i32)> {
    character
        .follow_opt::<Target, _>(|t| t.0)
        .and_then(|target| {
            let name = target.get::<Name>()?.0;
            let health = target.get::<Health>()?.0;
            Some((name, health))
        })
}

// Find all characters targeting a specific entity
fn find_attackers(world: &World, target_entity: Entity) -> Vec<EntityPtr> {
    world
        .iter_entities()
        .filter_map(|entity_ref| {
            let entity = entity_ref.id();
            let ptr = world.entity_ptr(entity);

            // Check if this entity has a Target component pointing to our target
            ptr.get::<Target>().and_then(|t| {
                t.0.filter(|h| h.entity() == target_entity)
                    .map(|_| world.entity_ptr(entity))
            })
        })
        .collect()
}

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

    println!("Setting up game entities...\n");

    // Create some items
    let sword = world
        .spawn((Name("Iron Sword"), Weight(5.0), Damage(15)))
        .id();
    let shield = world
        .spawn((Name("Wooden Shield"), Weight(8.0), Defense(10)))
        .id();
    let potion = world.spawn((Name("Health Potion"), Weight(0.5))).id();
    let gold = world.spawn((Name("Gold Coins"), Weight(1.0))).id();
    let bow = world
        .spawn((Name("Short Bow"), Weight(3.0), Damage(10)))
        .id();

    // Create the hero
    let hero = world
        .spawn((
            Name("Hero"),
            Health(100),
            Target(None), // Not targeting anyone yet
            Inventory(vec![
                EntityHandle::new(sword),
                EntityHandle::new(shield),
                EntityHandle::new(potion),
                EntityHandle::new(gold),
            ]),
            Equipped {
                weapon: Some(EntityHandle::new(sword)),
                armor: Some(EntityHandle::new(shield)),
            },
        ))
        .id();

    // Create an enemy targeting the hero
    let goblin = world
        .spawn((
            Name("Goblin"),
            Health(30),
            Target(Some(EntityHandle::new(hero))),
            Inventory(vec![EntityHandle::new(bow)]),
            Equipped {
                weapon: Some(EntityHandle::new(bow)),
                armor: None,
            },
        ))
        .id();

    // Create another enemy also targeting the hero
    let _orc = world
        .spawn((
            Name("Orc"),
            Health(50),
            Target(Some(EntityHandle::new(hero))),
        ))
        .id();

    // Demonstrate entity graph queries
    let hero_ptr = world.entity_ptr(hero);
    let goblin_ptr = world.entity_ptr(goblin);

    // 1. Calculate inventory weight
    let weight = total_weight(hero_ptr);
    println!("Hero's inventory weight: {} lbs", weight);
    println!("  Expected: 5.0 + 8.0 + 0.5 + 1.0 = 14.5");
    assert!((weight - 14.5).abs() < 0.01);

    // 2. Check equipped items
    let damage = equipped_damage(hero_ptr);
    println!("\nHero's equipped weapon damage: {:?}", damage);
    assert_eq!(damage, Some(15));

    let defense = equipped_defense(hero_ptr);
    println!("Hero's equipped armor defense: {:?}", defense);
    assert_eq!(defense, Some(10));

    // 3. Goblin's equipment
    let goblin_damage = equipped_damage(goblin_ptr);
    println!("\nGoblin's equipped weapon damage: {:?}", goblin_damage);
    assert_eq!(goblin_damage, Some(10));

    let goblin_defense = equipped_defense(goblin_ptr);
    println!("Goblin's equipped armor defense: {:?}", goblin_defense);
    assert_eq!(goblin_defense, None); // No armor equipped

    // 4. Check targeting
    let hero_target = target_info(hero_ptr);
    println!("\nHero's target: {:?}", hero_target);
    assert_eq!(hero_target, None);

    let goblin_target = target_info(goblin_ptr);
    println!("Goblin's target: {:?}", goblin_target);
    assert_eq!(goblin_target, Some(("Hero", 100)));

    // 5. Find all entities targeting the hero
    let attackers = find_attackers(&world, hero);
    let attacker_names: Vec<_> = attackers
        .iter()
        .filter_map(|p| p.get::<Name>())
        .map(|n| n.0)
        .collect();
    println!("\nEntities targeting the hero: {:?}", attacker_names);
    assert_eq!(attacker_names.len(), 2);
    assert!(attacker_names.contains(&"Goblin"));
    assert!(attacker_names.contains(&"Orc"));

    // 6. Update hero's target to the goblin
    world
        .entity_mut(hero)
        .insert(Target(Some(EntityHandle::new(goblin))));

    // Re-query with fresh EntityPtr
    let hero_ptr = world.entity_ptr(hero);

    let hero_target = target_info(hero_ptr);
    println!("\nAfter targeting goblin:");
    println!("Hero's target: {:?}", hero_target);
    assert_eq!(hero_target, Some(("Goblin", 30)));

    println!("\nAll assertions passed!");
}

examples/mixed_usage.rs (line 60)

fn team_health(leader: EntityPtr) -> i32 {
    leader
        .get::<Team>()
        .map(|team| {
            team.0
                .iter()
                .filter_map(|h| leader.follow_handle(*h).get::<Health>())
                .map(|h| h.0)
                .sum::<i32>()
        })
        .unwrap_or(0)
        + leader.get::<Health>().map(|h| h.0).unwrap_or(0)
}

pub fn has<T: Component>(self) -> bool

Checks if this entity has a component of type T.

Returns false if the entity doesn’t exist.

pub fn is_alive(self) -> bool

Checks if this entity is still alive.

pub fn follow<T, F>(self, f: F) -> Option<EntityPtr>

where T: Component, F: FnOnce(&T) -> EntityHandle,

Follows a reference component to another entity.

The component must contain an EntityHandle. Use follow_opt for optional references.

Returns None if this entity doesn’t have the component.

Examples found in repository

examples/tree_traversal.rs (line 43)

fn find_root(node: EntityPtr) -> EntityPtr {
    match node.follow::<Parent, _>(|p| p.0) {
        Some(parent) => find_root(parent),
        None => node,
    }
}

pub fn follow_opt<T, F>(self, f: F) -> Option<EntityPtr>

where T: Component, F: FnOnce(&T) -> Option<EntityHandle>,

Follows an optional reference component to another entity.

The extractor function returns Option<EntityHandle>.

Returns None if this entity doesn’t have the component or the reference is None.

Examples found in repository

examples/mixed_usage.rs (line 49)

fn count_chain_length_ptr(start: EntityPtr) -> usize {
    let mut count = 1;
    let mut current = start;

    while let Some(next) = current.follow_opt::<LinkedList, _>(|l| l.next) {
        count += 1;
        current = next;
    }

    count
}

examples/entity_graph.rs (line 81)

fn target_info(character: EntityPtr) -> Option<(&'static str, i32)> {
    character
        .follow_opt::<Target, _>(|t| t.0)
        .and_then(|target| {
            let name = target.get::<Name>()?.0;
            let health = target.get::<Health>()?.0;
            Some((name, health))
        })
}

pub fn follow_handle(self, handle: EntityHandle) -> EntityPtr

Creates an EntityPtr from an EntityHandle using this pointer’s world.

Convenience method for tree traversal when you have stored handles. This enables cleaner recursive patterns without needing access to WorldRef.

Example

fn sum_tree(ptr: EntityPtr) -> i32 {
    let children_sum: i32 = ptr
        .get::<TreeChildren>()
        .map(|c| c.0.iter().map(|h| sum_tree(ptr.follow_handle(*h))).sum())
        .unwrap_or(0);
    ptr.get::<Value>().map(|v| v.0).unwrap_or(0) + children_sum
}

Examples found in repository

examples/tree_traversal.rs (line 35)

fn sum_tree(node: EntityPtr) -> i32 {
    let my_value = node.get::<Value>().map(|v| v.0).unwrap_or(0);

    let children_sum: i32 = node
        .get::<Children>()
        .map(|c| c.0.iter().map(|h| sum_tree(node.follow_handle(*h))).sum())
        .unwrap_or(0);

    my_value + children_sum
}

// Recursive function to find the root by traversing parent links
fn find_root(node: EntityPtr) -> EntityPtr {
    match node.follow::<Parent, _>(|p| p.0) {
        Some(parent) => find_root(parent),
        None => node,
    }
}

// Recursive function to compute tree depth
fn tree_depth(node: EntityPtr) -> usize {
    node.get::<Children>()
        .map(|c| {
            c.0.iter()
                .map(|h| tree_depth(node.follow_handle(*h)))
                .max()
                .unwrap_or(0)
                + 1
        })
        .unwrap_or(0)
}

// Recursive function to collect all node names in pre-order
fn collect_names(node: EntityPtr, names: &mut Vec<&'static str>) {
    if let Some(name) = node.get::<Name>() {
        names.push(name.0);
    }

    if let Some(children) = node.get::<Children>() {
        for child_handle in &children.0 {
            collect_names(node.follow_handle(*child_handle), names);
        }
    }
}

examples/concurrent_systems.rs (line 50)

fn sum_health(node: EntityPtr) -> i32 {
    let my_health = node.get::<Health>().map(|h| h.0).unwrap_or(0);

    let children_health: i32 = node
        .get::<Children>()
        .map(|c| c.0.iter().map(|h| sum_health(node.follow_handle(*h))).sum())
        .unwrap_or(0);

    my_health + children_health
}

// Recursive helper: sum armor across a hierarchy
fn sum_armor(node: EntityPtr) -> i32 {
    let my_armor = node.get::<Armor>().map(|a| a.0).unwrap_or(0);

    let children_armor: i32 = node
        .get::<Children>()
        .map(|c| c.0.iter().map(|h| sum_armor(node.follow_handle(*h))).sum())
        .unwrap_or(0);

    my_armor + children_armor
}

examples/entity_graph.rs (line 53)

fn total_weight(character: EntityPtr) -> f32 {
    character
        .get::<Inventory>()
        .map(|inv| {
            inv.0
                .iter()
                .filter_map(|h| character.follow_handle(*h).get::<Weight>())
                .map(|w| w.0)
                .sum()
        })
        .unwrap_or(0.0)
}

// Get equipped weapon damage (if any)
fn equipped_damage(character: EntityPtr) -> Option<i32> {
    character
        .get::<Equipped>()
        .and_then(|e| e.weapon)
        .and_then(|h| character.follow_handle(h).get::<Damage>())
        .map(|d| d.0)
}

// Get equipped armor defense (if any)
fn equipped_defense(character: EntityPtr) -> Option<i32> {
    character
        .get::<Equipped>()
        .and_then(|e| e.armor)
        .and_then(|h| character.follow_handle(h).get::<Defense>())
        .map(|d| d.0)
}

examples/mixed_usage.rs (line 64)

fn team_health(leader: EntityPtr) -> i32 {
    leader
        .get::<Team>()
        .map(|team| {
            team.0
                .iter()
                .filter_map(|h| leader.follow_handle(*h).get::<Health>())
                .map(|h| h.0)
                .sum::<i32>()
        })
        .unwrap_or(0)
        + leader.get::<Health>().map(|h| h.0).unwrap_or(0)
}

pub const fn nav(self) -> EntityPtrNav

Returns a navigator for this entity, enabling HasParent/HasChildren navigation.

This method is always available but navigation methods require the nav-traits feature.

pub const fn nav_many(self) -> EntityPtrNavMany

Returns an iterator-like navigator for collecting multiple related entities.

Useful for iterating over children or other entity collections.

Trait Implementations

impl Clone for EntityPtr

fn clone(&self) -> EntityPtr

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EntityPtr

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for EntityPtr

fn hash<H: Hasher>(&self, state: &mut H)

Hashes the entity ID only.

This enables use in HashSet and as HashMap keys within a single-world context (the typical usage pattern).

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for EntityPtr

fn eq(&self, other: &Self) -> bool

Compares by entity ID only.

This assumes both EntityPtrs reference the same world, which is the typical usage pattern within a single system.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for EntityPtr

impl Eq for EntityPtr