Struct Access 

pub struct Access { /* 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 Access

pub const fn new() -> Access

Creates an empty Access collection.

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

Adds access to the component given by index.

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

Adds exclusive access to the component given by index.

pub fn remove_read(&mut self, index: ComponentId)

Removes read access to the component given by index.

This also removes write access, since if you can’t even read a component, you also can’t write to it.

Because this method corresponds to the set difference operator ∖, it can create complicated logical formulas that you should verify correctness of. For example, A ∪ (B ∖ A) isn’t equivalent to (A ∪ B) ∖ A, so you can’t replace a call to Self::remove_read followed by a call to Self::extend with a call to Self::extend followed by a call to Self::remove_read.

pub fn remove_write(&mut self, index: ComponentId)

Removes write access to the component given by index.

Unlike Self::remove_read, this method only removes write access, since it’s reasonable to “downgrade” write access to only read access.

Because this method corresponds to the set difference operator ∖, it can create complicated logical formulas that you should verify correctness of. For example, A ∪ (B ∖ A) isn’t equivalent to (A ∪ B) ∖ A, so you can’t replace a call to remove_write followed by a call to extend with a call to extend followed by a call to remove_write.

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

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

This is for components 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> and Allow<T>.

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

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

pub fn has_any_read(&self) -> bool

Returns true if this can access any component.

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

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

pub fn has_any_write(&self) -> bool

Returns true if this accesses any component mutably.

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

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

This is a component 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 components (i.e. EntityRef and &World).

pub fn write_all(&mut self)

Sets this as having mutable access to all components (i.e. EntityMut and &mut World).

pub fn has_read_all(&self) -> bool

Returns true if this has access to all components (i.e. EntityRef and &World).

pub fn has_write_all(&self) -> bool

Returns true if this has write access to all components (i.e. EntityMut and &mut World).

pub fn clear_writes(&mut self)

Removes all writes.

pub fn clear(&mut self)

Removes all accesses.

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

Adds all access from other.

pub fn remove_conflicting_access(&mut self, other: &Access)

Removes any access from self that would conflict with other. This removes any reads and writes for any component written by other, and removes any writes for any component read by other.

pub fn is_compatible(&self, other: &Access) -> 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) -> 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) -> AccessConflicts

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

pub fn archetypal(&self) -> &ComponentIdSet

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

These are components 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 try_reads_and_writes( &self, ) -> Result<&ComponentIdSet, UnboundedAccessError>

👎Deprecated since 0.20.0:

use `reads_and_writes().as_finite_set()

Returns the set of components with read access, or an error if the access is unbounded.

This includes components with write access, since write access also allows you to read the component.

pub fn reads(&self) -> &InvertibleComponentIdSet

Returns the set of components with read or write access.

This includes components with write access, since write access also allows you to read the component.

pub fn try_writes(&self) -> Result<&ComponentIdSet, UnboundedAccessError>

👎Deprecated since 0.20.0:

use `writes().as_finite_set()

Returns the set of components with write access, or an error if the access is unbounded.

pub fn writes(&self) -> &InvertibleComponentIdSet

Returns the set of components with write access.

pub fn try_iter_access( &self, ) -> Result<impl Iterator<Item = ComponentAccessKind>, UnboundedAccessError>

Returns an iterator over the component IDs and their ComponentAccessKind.

Returns Err(UnboundedAccess) if the access is unbounded. This typically occurs when an Access is marked as accessing all components, and then adding exceptions.

Examples

let mut access = Access::default();

access.add_read(ComponentId::new(1));
access.add_write(ComponentId::new(2));
access.add_archetypal(ComponentId::new(3));

let result = access
    .try_iter_access()
    .map(Iterator::collect::<Vec<_>>);

assert_eq!(
    result,
    Ok(vec![
        ComponentAccessKind::Shared(ComponentId::new(1)),
        ComponentAccessKind::Exclusive(ComponentId::new(2)),
        ComponentAccessKind::Archetypal(ComponentId::new(3)),
    ]),
);

Examples found in repository

examples/ecs/dynamic.rs (line 183)

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();
    let mut event_names = HashMap::<String, EventKey>::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}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_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(str::parse) {
                        Some(Ok(size)) => size,
                        _ => 0,
                    };
                    // Register our new component to the world with a layout specified by its size
                    // SAFETY: [u64] is Send + Sync
                    let id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            name.to_string(),
                            StorageType::Table,
                            Layout::array::<u64>(size).unwrap(),
                            None,
                            true,
                            false,
                            ComponentCloneBehavior::Default,
                            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 {name} does not exist");
                        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() / 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
                        .access()
                        .try_iter_access()
                        .unwrap()
                        .map(|component_access| {
                            let id = *component_access.index();
                            let ptr = filtered_entity.get_by_id(id).unwrap();
                            let info = component_info.get(&id).unwrap();
                            let len = info.layout().size() / 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 matches!(component_access, ComponentAccessKind::Exclusive(_)) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

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

                    println!("{}: {}", filtered_entity.id(), terms);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

Trait Implementations

impl Clone for Access

fn clone(&self) -> Access

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Access

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

Formats the value using the given formatter.

impl Default for Access

fn default() -> Access

Returns the “default value” for a type.

impl Eq for Access

impl PartialEq for Access

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Access