bevy_entity_ptr

Ergonomic smart-pointer-like access to Bevy ECS entities with immutable-only semantics.

Overview

This crate provides two complementary approaches for accessing entity data in Bevy:

Design Principles

• Immutable only - No get_mut variants (functional programming style)
• Single unsafe boundary - Only WorldRef::new() is unsafe
• Graceful stale handling - Despawned entities return None, not undefined behavior
• Zero-cost where possible - #[repr(transparent)], #[inline], const fn

Installation

Add to your Cargo.toml:

[dependencies]
bevy_entity_ptr = "0.1"

Quick Start

Safe Approach: EntityHandle + BoundEntity

Use this when you want fully safe code with explicit world parameters:

use bevy_ecs::prelude::*;
use bevy_entity_ptr::{EntityHandle, BoundEntity};

#[derive(Component)]
struct Parent(EntityHandle);

#[derive(Component)]
struct Name(String);

fn find_parent_name(entity: Entity, world: &World) -> Option<String> {
    let handle = EntityHandle::new(entity);
    let bound = handle.bind(world);

    // Follow the Parent component to get the parent entity
    let parent = bound.follow::<Parent, _>(|p| p.0)?;

    // Get the parent's name
    parent.get::<Name>().map(|n| n.0.clone())
}

Ergonomic Approach: WorldRef + EntityPtr

Use this when you want fluent traversal without passing &World everywhere. There is one unsafe point: WorldRef::new().

use bevy_ecs::prelude::*;
use bevy_entity_ptr::{WorldRef, EntityPtr, EntityHandle};

#[derive(Component)]
struct Parent(EntityHandle);

#[derive(Component)]
struct Health(i32);

#[derive(Component)]
struct TreeChildren(Vec<EntityHandle>);

// Recursive tree traversal - no &World parameter needed!
fn sum_tree_health(node: EntityPtr) -> i32 {
    let my_health = node.get::<Health>().map(|h| h.0).unwrap_or(0);

    let children_health: i32 = node
        .get::<TreeChildren>()
        .map(|c| {
            c.0.iter()
                .map(|h| sum_tree_health(node.follow_handle(*h)))
                .sum()
        })
        .unwrap_or(0);

    my_health + children_health
}

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

fn health_system(world: &World) {
    // SAFETY: WorldRef is dropped before system returns
    let w = unsafe { WorldRef::new(world) };

    // Use EntityPtr for ergonomic traversal
    for entity in world.iter_entities() {
        let ptr = w.entity(entity.id());
        let total = sum_tree_health(ptr);
        println!("Subtree health: {}", total);
    }
}

Mixed Usage

Store handles in components, use smart pointers for traversal:

use bevy_ecs::prelude::*;
use bevy_entity_ptr::{EntityHandle, WorldRef, EntityPtr};

// EntityHandle is Send + Sync, safe to store in components
#[derive(Component)]
struct Inventory {
    items: Vec<EntityHandle>,
}

#[derive(Component)]
struct Weight(f32);

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

Navigation Traits (Optional)

Enable the nav-traits feature for parent/child navigation helpers:

[dependencies]
bevy_entity_ptr = { version = "0.1", features = ["nav-traits"] }

use bevy_ecs::prelude::*;
use bevy_entity_ptr::{EntityHandle, WorldRef, HasParent, HasChildren};

#[derive(Component)]
struct ParentRef(Option<Entity>);

impl HasParent for ParentRef {
    fn parent_entity(&self) -> Option<Entity> {
        self.0
    }
}

#[derive(Component)]
struct ChildRefs(Vec<Entity>);

impl HasChildren for ChildRefs {
    fn children_entities(&self) -> &[Entity] {
        &self.0
    }
}

fn navigate_tree(world: &World, entity: Entity) {
    // SAFETY: WorldRef scoped to this function
    let w = unsafe { WorldRef::new(world) };
    let ptr = w.entity(entity);

    // Navigate to parent
    if let Some(parent) = ptr.nav().parent::<ParentRef>() {
        println!("Has parent: {:?}", parent.entity());
    }

    // Navigate to children
    let children = ptr.nav_many().children::<ChildRefs>();
    println!("Has {} children", children.len());
}

Thread Safety

Multi-Threaded Usage Example

Multiple read-only systems can use bevy_entity_ptr concurrently. Each system creates its own WorldRef at entry, and Bevy's scheduler runs them in parallel when all systems only read:

use bevy_ecs::prelude::*;
use bevy_entity_ptr::{EntityHandle, EntityPtr, WorldRef};

#[derive(Component)]
struct Health(i32);

#[derive(Component)]
struct Armor(i32);

#[derive(Component)]
struct Children(Vec<EntityHandle>);

#[derive(Component)]
struct RootMarker;

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
}

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
}

/// System A: Computes total health across hierarchies
fn compute_health_system(world: &World, query: Query<Entity, With<RootMarker>>) {
    // SAFETY: System has &World access, WorldRef dropped before system returns
    let world_ref = unsafe { WorldRef::new(world) };

    for entity in &query {
        let total = sum_health(world_ref.entity(entity));
        println!("Total health: {}", total);
    }
}

/// System B: Runs concurrently with System A
fn compute_armor_system(world: &World, query: Query<Entity, With<RootMarker>>) {
    // SAFETY: System has &World access, WorldRef dropped before system returns
    let world_ref = unsafe { WorldRef::new(world) };

    for entity in &query {
        let total = sum_armor(world_ref.entity(entity));
        println!("Total armor: {}", total);
    }
}

// Bevy's scheduler runs both systems in parallel - both only read
fn setup_app(app: &mut App) {
    app.add_systems(Update, (compute_health_system, compute_armor_system));
}

Why this is safe:

• Each system creates its own WorldRef instance at entry
• WorldRef and EntityPtr are NOT Send/Sync - they cannot be shared between threads
• Bevy's scheduler detects that both systems only have &World access and runs them in parallel
• All operations through EntityPtr are read-only by design

See examples/concurrent_systems.rs for a complete runnable example.

Stale Reference Handling

Both approaches gracefully handle despawned entities:

use bevy_ecs::prelude::*;
use bevy_entity_ptr::EntityHandle;

#[derive(Component)]
struct Name(&'static str);

fn stale_handling_example(world: &mut World) {
    let entity = world.spawn(Name("temporary")).id();
    let handle = EntityHandle::new(entity);

    // Works fine
    assert!(handle.is_alive(world));
    assert_eq!(handle.get::<Name>(world).unwrap().0, "temporary");

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

    // Gracefully returns None - no undefined behavior!
    assert!(!handle.is_alive(world));
    assert!(handle.get::<Name>(world).is_none());
}

Safety

The only unsafe code is WorldRef::new(). The caller must ensure:

1. The World outlives all EntityPtr instances created from the WorldRef
2. The World is NOT mutated while any EntityPtr exists

In Bevy systems, this is naturally satisfied: systems with &World access cannot mutate. Create WorldRef at system entry, use it for reads, and let it drop before the system returns.

What This Crate Does NOT Support (By Design)

• Mutable access - Use Bevy's native APIs for mutations
• Despawning - Use world.despawn() directly
• Component insertion/removal - Use Bevy's native APIs
• Cross-frame storage of EntityPtr - Use EntityHandle or raw Entity for storage

License

MIT OR Apache-2.0