Struct Scope 

pub struct Scope<'w> {
    pub(crate) world: &'w World,
    pub(crate) scope: Entity,
}

A read-only scope: one entity and everything below it.

Fields

world: &'w World

scope: Entity

Implementations

impl<'w> Scope<'w>

pub(crate) fn new(world: &'w World, scope: Entity) -> Self

pub fn entity(&self) -> Entity

The entity this scope is rooted at.

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

Whether entity is visible from this scope.

This is the addressability test: the two roots answer true so that their components can be read and written like any other entity’s, even though counting and querying omit them (see Scope::len).

pub fn location(&self, entity: Entity) -> Result<Location, EntityAccessError>

Where a visible entity’s components live.

Answers EntityAccessError::NotAlive for a handle that names no live entity, and EntityAccessError::NotVisible for one that lives outside this scope.

pub fn query<Q: Query>(&self) -> QueryBorrow<'w, Q>

Iterate the visible entities that match Q.

The query is a type, so which components to hand out and which archetypes to visit are written in the turbofish. See crate::query for the items a query is made of.

let mut world = World::new();
world.root_scope_mut().spawn(bundle![1u32]);

for (entity, value) in world.root_scope().query::<(Entity, &u32)>().iter() {
    println!("{entity:?} carries {value}");
}

The answer is a holder: it claims the components the query reaches before anything is handed out, and releases them when it is dropped. A claim that overlaps one already held is reported here, naming where the other was taken, rather than at the row it would have reached.

pub fn query_one<Q: Query>( &self, entity: Entity, ) -> Result<QueryOne<'w, Q>, EntityAccessError>

What Q yields for entity, when it is visible here and its archetype matches.

This is the one-entity form of Scope::query: the row the entity is stored at is looked up directly instead of the archetypes being walked. A lookup that finds nothing says why: the entity is not alive, out of this scope’s reach, or its row does not satisfy the query. The last one covers two cases a caller answers the same way, so it is one error: the archetype does not match Q, or the row sits outside what this scope reaches. A shared row is reachable from every scope, the same by handle as it is through Scope::query.

A lookup by handle does not filter the scaffolding: the root and the shared scope answer like any other entity, which is what lets the resources they carry be read. Iterating and counting go through a scope and leave the pair out; see Scope::len.

let mut world = World::new();
let entity = world.root_scope_mut().spawn(bundle![1u32]);

assert_eq!(*world.root_scope().query_one::<&u32>(entity).unwrap().get(), 1);
assert!(world.root_scope().query_one::<Has<u32>>(entity).unwrap().get());
assert!(!world.root_scope().query_one::<Has<bool>>(entity).unwrap().get());
assert!(world.root_scope().query_one::<&bool>(entity).is_err());

The answer is a holder rather than the item itself: it claims the components the query reaches on that row while it is built, so the claim begins before the item exists and lasts as long as the holder.

pub fn archetype(&self, id: u32) -> Result<&'w Archetype, ArchetypeAccessError>

The archetype with this id, when this scope sees every row of it.

A partially visible archetype is turned down: handing out its entity list would report rows the scope cannot otherwise reach. So is an empty one, which has no row to see. A caller that only wants the shape of an archetype uses Scope::archetype_infos, whose length is the visible one; a caller that has an entity and wants the archetype its row lives in uses Scope::archetype_of, which asks about the row rather than about the whole archetype.

pub fn archetype_of( &self, entity: Entity, ) -> Result<&'w Archetype, EntityAccessError>

The archetype an entity’s row lives in, when the entity is visible here.

This is the counterpart of Scope::location: it answers for one visible row, so it also answers for an archetype Scope::archetype turns down. Two scopes whose entities share a component set share the archetype and each sees only its own rows of it; asking about one row is well defined, while handing out the archetype as a whole is not.

The archetype is the storage, not a view of it: Archetype::entities lists the rows of every scope, the ones this scope cannot see included. Scope::entity_info and Scope::entity_infos are what filter by visibility.

pub fn archetypes(&self) -> impl Iterator<Item = &'w Archetype>

Every archetype this scope sees in full, in id order.

Empty archetypes are skipped: they hold no row, so there is nothing to iterate. The one archetype holding the tree’s scaffolding is included, since its rows do exist; Scope::len is what leaves them out of the count.

pub fn scope(&self, scope: Entity) -> Result<Scope<'w>, EntityAccessError>

The scope of a visible scope.

A scope is an entity like any other, so this is turned down the same way Scope::location is.

pub fn parent_scope(&self, entity: Entity) -> Result<Entity, EntityAccessError>

The parent of a visible entity.

pub fn children(&self, entity: Entity) -> Result<Vec<Entity>, EntityAccessError>

The direct children of a visible entity.

Answers EntityAccessError::NotAlive or EntityAccessError::NotVisible rather than an empty list when the entity is not there to ask about.

pub fn len(&self) -> usize

The number of visible entities, the two roots excluded.

An empty world is empty; the root and the shared scope are scaffolding and are reported by WorldInfo::root and WorldInfo::shared instead of being counted.

pub fn is_empty(&self) -> bool

Whether nothing is visible.

pub fn info(&self) -> WorldInfo

The scope’s shape: visible counts, the component inventory, and the two roots.

pub fn archetype_infos(&self) -> Vec<ArchetypeInfo>

Every archetype with at least one visible row, in id order.

pub fn entity_name( &self, entity: Entity, ) -> Result<&'static str, EntityAccessError>

What a visible entity is called, read from the row that stores it.

A handle rebuilt from bare bits carries no name of its own; the row does. See World::entity_name.

pub fn entity_info( &self, entity: Entity, ) -> Result<EntityInfo, EntityAccessError>

A visible entity’s location and component names.

The handle reported, and the name beside it, both come from the row that stores the entity, so a handle that arrived as bare bits is answered with the label its spawn site gave it.

pub fn entity_infos(&self, limit: usize) -> Vec<EntityInfo>

At most limit visible entities’ information, in storage order.

pub fn queue(self) -> Commands<'w>

A queue of structural changes, all of them in this scope.

Takes the scope by value, so the queue outlives it: the scope is a copy of a reference, and a queue that borrowed the temporary would be unusable in the position it is most wanted.

fn archetype_visible(&self, archetype: &Archetype) -> bool

Whether an archetype has any row this scope can see.

fn fully_visible(&self, archetype: &Archetype) -> bool

Whether every row of archetype is visible from this scope.

fn row_visible(&self, archetype: &Archetype, row: usize) -> bool

Whether row row of archetype is visible.

fn visible_len(&self, index: u32, archetype: &Archetype) -> usize

The number of rows of archetype this scope can see, its own content only: the scaffolding is never counted.

Trait Implementations

impl<'w> Clone for Scope<'w>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'w> Copy for Scope<'w>

impl Debug for Scope<'_>

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

Formats the value using the given formatter.