Struct bevy::ecs::query::Access

pub struct Access<T>
where
    T: SparseSetIndex,
{ /* private fields */ }

Tracks read and write access to specific elements in a collection.

Used internally to ensure soundness during system initialization and execution. See the is_compatible and get_conflicts functions.

Implementations

impl<T> Access<T>

where T: SparseSetIndex,

pub const fn new() -> Access<T>

Creates an empty Access collection.

pub fn add_read(&mut self, index: T)

Adds access to the element given by index.

pub fn add_write(&mut self, index: T)

Adds exclusive access to the element given by index.

pub fn add_archetypal(&mut self, index: T)

Adds an archetypal (indirect) access to the element given by index.

This is for elements whose values are not accessed (and thus will never cause conflicts), but whose presence in an archetype may affect query results.

Currently, this is only used for Has<T>.

pub fn has_read(&self, index: T) -> bool

Returns true if this can access the element given by index.

pub fn has_any_read(&self) -> bool

Returns true if this can access anything.

pub fn has_write(&self, index: T) -> bool

Returns true if this can exclusively access the element given by index.

Examples found in repository

examples/ecs/dynamic.rs (line 171)

fn main() {
    let mut world = World::new();
    let mut lines = std::io::stdin().lines();
    let mut component_names = HashMap::<String, ComponentId>::new();
    let mut component_info = HashMap::<ComponentId, ComponentInfo>::new();

    println!("{}", PROMPT);
    loop {
        print!("\n> ");
        let _ = std::io::stdout().flush();
        let Some(Ok(line)) = lines.next() else {
            return;
        };

        if line.is_empty() {
            return;
        };

        let Some((first, rest)) = line.trim().split_once(|c: char| c.is_whitespace()) else {
            match &line.chars().next() {
                Some('c') => println!("{}", COMPONENT_PROMPT),
                Some('s') => println!("{}", ENTITY_PROMPT),
                Some('q') => println!("{}", QUERY_PROMPT),
                _ => println!("{}", PROMPT),
            }
            continue;
        };

        match &first[0..1] {
            "c" => {
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };
                    let size = match component.next().map(|s| s.parse::<usize>()) {
                        Some(Ok(size)) => size,
                        _ => 0,
                    };
                    // Register our new component to the world with a layout specified by it's size
                    // SAFETY: [u64] is Send + Sync
                    let id = world.init_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            name.to_string(),
                            StorageType::Table,
                            Layout::array::<u64>(size).unwrap(),
                            None,
                        )
                    });
                    let Some(info) = world.components().get_info(id) else {
                        return;
                    };
                    component_names.insert(name.to_string(), id);
                    component_info.insert(id, info.clone());
                    println!("Component {} created with id: {:?}", name, id.index());
                });
            }
            "s" => {
                let mut to_insert_ids = Vec::new();
                let mut to_insert_data = Vec::new();
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };

                    // Get the id for the component with the given name
                    let Some(&id) = component_names.get(name) else {
                        println!("Component {} does not exist", name);
                        return;
                    };

                    // Calculate the length for the array based on the layout created for this component id
                    let info = world.components().get_info(id).unwrap();
                    let len = info.layout().size() / std::mem::size_of::<u64>();
                    let mut values: Vec<u64> = component
                        .take(len)
                        .filter_map(|value| value.parse::<u64>().ok())
                        .collect();
                    values.resize(len, 0);

                    // Collect the id and array to be inserted onto our entity
                    to_insert_ids.push(id);
                    to_insert_data.push(values);
                });

                let mut entity = world.spawn_empty();

                // Construct an `OwningPtr` for each component in `to_insert_data`
                let to_insert_ptr = to_owning_ptrs(&mut to_insert_data);

                // SAFETY:
                // - Component ids have been taken from the same world
                // - Each array is created to the layout specified in the world
                unsafe {
                    entity.insert_by_ids(&to_insert_ids, to_insert_ptr.into_iter());
                }

                println!("Entity spawned with id: {:?}", entity.id());
            }
            "q" => {
                let mut builder = QueryBuilder::<FilteredEntityMut>::new(&mut world);
                parse_query(rest, &mut builder, &component_names);
                let mut query = builder.build();

                query.iter_mut(&mut world).for_each(|filtered_entity| {
                    let terms = filtered_entity
                        .components()
                        .map(|id| {
                            let ptr = filtered_entity.get_by_id(id).unwrap();
                            let info = component_info.get(&id).unwrap();
                            let len = info.layout().size() / std::mem::size_of::<u64>();

                            // SAFETY:
                            // - All components are created with layout [u64]
                            // - len is calculated from the component descriptor
                            let data = unsafe {
                                std::slice::from_raw_parts_mut(
                                    ptr.assert_unique().as_ptr().cast::<u64>(),
                                    len,
                                )
                            };

                            // If we have write access, increment each value once
                            if filtered_entity.access().has_write(id) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

                            format!("{}: {:?}", info.name(), data[0..len].to_vec())
                        })
                        .collect::<Vec<_>>()
                        .join(", ");

                    println!("{:?}: {}", filtered_entity.id(), terms);
                });
            }
            _ => continue,
        }
    }
}

pub fn has_any_write(&self) -> bool

Returns true if this accesses anything mutably.

pub fn has_archetypal(&self, index: T) -> bool

Returns true if this has an archetypal (indirect) access to the element given by index.

This is an element whose value is not accessed (and thus will never cause conflicts), but whose presence in an archetype may affect query results.

Currently, this is only used for Has<T>.

pub fn read_all(&mut self)

Sets this as having access to all indexed elements (i.e. &World).

pub fn write_all(&mut self)

Sets this as having mutable access to all indexed elements (i.e. EntityMut).

pub fn has_read_all(&self) -> bool

Returns true if this has access to all indexed elements (i.e. &World).

pub fn has_write_all(&self) -> bool

Returns true if this has write access to all indexed elements (i.e. EntityMut).

pub fn clear_writes(&mut self)

Removes all writes.

pub fn clear(&mut self)

Removes all accesses.

pub fn extend(&mut self, other: &Access<T>)

Adds all access from other.

pub fn is_compatible(&self, other: &Access<T>) -> bool

Returns true if the access and other can be active at the same time.

Access instances are incompatible if one can write an element that the other can read or write.

pub fn is_subset(&self, other: &Access<T>) -> bool

Returns true if the set is a subset of another, i.e. other contains at least all the values in self.

pub fn get_conflicts(&self, other: &Access<T>) -> Vec<T>

Returns a vector of elements that the access and other cannot access at the same time.

pub fn reads_and_writes(&self) -> impl Iterator<Item = T>

Returns the indices of the elements this has access to.

pub fn reads(&self) -> impl Iterator<Item = T>

Returns the indices of the elements this has non-exclusive access to.

pub fn writes(&self) -> impl Iterator<Item = T>

Returns the indices of the elements this has exclusive access to.

pub fn archetypal(&self) -> impl Iterator<Item = T>

Returns the indices of the elements that this has an archetypal access to.

These are elements whose values are not accessed (and thus will never cause conflicts), but whose presence in an archetype may affect query results.

Currently, this is only used for Has<T>.

Trait Implementations

impl<T> Clone for Access<T>

where T: Clone + SparseSetIndex,

fn clone(&self) -> Access<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Access<T>

where T: SparseSetIndex + Debug,

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

Formats the value using the given formatter.

impl<T> Default for Access<T>

where T: SparseSetIndex,

fn default() -> Access<T>

Returns the “default value” for a type.

impl<T> PartialEq for Access<T>

where T: PartialEq + SparseSetIndex,

fn eq(&self, other: &Access<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T> Eq for Access<T>

where T: Eq + SparseSetIndex,

impl<T> StructuralPartialEq for Access<T>

where T: SparseSetIndex,