Struct WorldRef 

pub struct WorldRef { /* private fields */ }

A reference to a World with erased lifetime for ergonomic entity traversal.

This is the single unsafe boundary in the crate. All EntityPtr instances created from a WorldRef will borrow from the original World.

Size

8 bytes (&'static World)

Safety

The caller must ensure:

1. The World outlives all EntityPtr instances created from this 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.

For stale reference handling across mutations, use EntityHandle instead.

Thread Safety

NOT Send, NOT Sync - must stay on the creating thread within a single system.

Implementations

impl WorldRef

pub unsafe fn new(world: &World) -> Self

Creates a new WorldRef by transmuting the lifetime to ’static.

Safety

The caller must ensure that:

• The World reference outlives all EntityPtr instances created from this WorldRef
• The World is NOT mutated while any EntityPtr from this WorldRef exists
• Typically this means the WorldRef is created at system entry and discarded at system exit

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

Gets an EntityPtr for the given entity.

Returns an EntityPtr regardless of whether the entity exists. Use EntityPtr::is_alive() to check validity.

pub fn entity_opt(&self, entity: Entity) -> Option<EntityPtr>

Gets an EntityPtr only if the entity exists.

Returns None if the entity has been despawned.

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

Creates an EntityPtr from an EntityHandle.

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

Gets a component directly from an entity.

Convenience method for one-off component access without creating an EntityPtr.

pub fn world(&self) -> &World

Returns the underlying World reference.

This can be used to access World methods directly when needed.

Trait Implementations

impl Debug for WorldRef

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

Formats the value using the given formatter.