Struct WorldAccessGuard 

pub struct WorldAccessGuard<'w> { /* private fields */ }

Provides safe access to the world via [WorldAccess] permissions, which enforce aliasing rules at runtime in multi-thread environments

Implementations

impl WorldAccessGuard<'_>

pub fn query( &self, query: ScriptQueryBuilder, ) -> Result<VecDeque<ScriptQueryResult>, InteropError>

Queries the world for entities that match the given query.

impl WorldAccessGuard<'_>

Impls to do with dynamically querying systems and schedules

pub fn scope_schedule<O, F: FnOnce(&mut World, &mut Schedule) -> O>( &self, label: &ReflectSchedule, f: F, ) -> Result<O, InteropError>

Temporarilly removes the given schedule from the world, and calls the given function on it, then re-inserts it.

Useful for initializing schedules, or modifying systems

pub fn systems( &self, schedule: &ReflectSchedule, ) -> Result<Vec<ReflectSystem>, InteropError>

Retrieves all the systems in a schedule

impl WorldAccessGuard<'_>

pub fn register_script_component( &self, component_name: String, ) -> Result<ScriptComponentRegistration, InteropError>

Registers a dynamic script component, and returns a reference to its registration

impl WorldAccessGuard<'_>

pub fn id(&self) -> WorldId

Returns the id of the world this guard provides access to

impl<'w> WorldAccessGuard<'w>

pub fn invalidate(&self)

Invalidates the world access guard, making it and any guards derived from this one unusable.

pub fn with_static_guard<O>( world: &'w mut World, f: impl FnOnce(WorldGuard<'static>) -> O, ) -> O

Safely allows access to the world for the duration of the closure via a static WorldAccessGuard.

The guard is invalidated at the end of the closure, meaning the world cannot be accessed at all after the closure ends.

pub fn with_existing_static_guard<O>( guard: WorldAccessGuard<'w>, f: impl FnOnce(WorldGuard<'static>) -> O, ) -> O

Safely allows access to the world for the duration of the closure via a static WorldAccessGuard using a previously lifetimed world guard. Will invalidate the static guard at the end but not the original.

pub unsafe fn new_non_exclusive( world: UnsafeWorldCell<'w>, subset: impl IntoIterator<Item = ReflectAccessId>, type_registry: AppTypeRegistry, allocator: AppReflectAllocator, function_registry: AppScriptFunctionRegistry, schedule_registry: AppScheduleRegistry, script_component_registry: AppScriptComponentRegistry, ) -> Self

Creates a new WorldAccessGuard from a possibly non-exclusive access to the world.

It requires specyfing the exact accesses that are allowed to be given out by the guard. Those accesses need to be safe to be given out to the script, as the guard will assume that it is safe to give them out in any way.

Safety

• The caller must ensure that the accesses in subset are not aliased by any other access
• If an access is allowed in this subset, but alised by someone else, either by being converted to mutable or non mutable reference, this guard will be unsafe.

pub fn new_exclusive(world: &'w mut World) -> Self

Creates a new WorldAccessGuard for the given mutable borrow of the world.

Creating a guard requires that some resources exist in the world, namely:

• AppTypeRegistry
• AppReflectAllocator
• AppScriptFunctionRegistry

If these resources do not exist, they will be initialized.

pub fn list_accesses(&self) -> Vec<(ReflectAccessId, AccessCount)>

Purely debugging utility to list all accesses currently held.

pub unsafe fn release_all_accesses(&self)

Should only really be used for testing purposes

pub fn access_len(&self) -> usize

Returns the number of accesses currently held.

pub fn as_unsafe_world_cell(&self) -> Result<UnsafeWorldCell<'w>, InteropError>

Retrieves the underlying unsafe world cell, with no additional guarantees of safety proceed with caution and only use this if you understand what you’re doing

pub fn as_unsafe_world_cell_readonly( &self, ) -> Result<UnsafeWorldCell<'w>, InteropError>

Retrieves the underlying read only unsafe world cell, with no additional guarantees of safety proceed with caution and only use this if you understand what you’re doing

pub fn get_component_id( &self, id: TypeId, ) -> Result<Option<ComponentId>, InteropError>

Gets the component id of the given component or resource

pub fn get_resource_id( &self, id: TypeId, ) -> Result<Option<ComponentId>, InteropError>

Gets the resource id of the given component or resource

pub fn with_read_access<T: Into<ReflectAccessId>, O, F: FnOnce(&Self) -> O>( &self, id: T, closure: F, ) -> Result<O, ()>

A utility for running a closure with scoped read access to the given id

pub fn with_write_access<T: Into<ReflectAccessId>, O, F: FnOnce(&Self) -> O>( &self, id: T, closure: F, ) -> Result<O, ()>

A utility for running a closure with scoped write access to the given id

pub fn get_access_location( &self, raid: ReflectAccessId, ) -> Option<Location<'static>>

Get the location of the given access

pub fn claim_read_access(&self, raid: ReflectAccessId) -> bool

Claims read access to the given type.

pub fn claim_write_access(&self, raid: ReflectAccessId) -> bool

Claims write access to the given type.

pub unsafe fn release_access(&self, raid: ReflectAccessId)

Releases read or write access to the given type.

Safety

• This can only be called safely after all references to the type created using the access have been dropped
• You can only call this if you previously called one of: WorldAccessGuard::claim_read_access or WorldAccessGuard::claim_write_access
• The number of claim and release calls for the same id must always match

pub fn claim_global_access(&self) -> bool

Claims global access to the world

pub unsafe fn release_global_access(&self)

Releases global access to the world

Safety

• This can only be called safely after all references created using the access have been dropped

pub fn type_registry(&self) -> TypeRegistryArc

Returns the type registry for the world

pub fn schedule_registry(&self) -> AppScheduleRegistry

Returns the schedule registry for the world

pub fn component_registry(&self) -> AppScriptComponentRegistry

Returns the component registry for the world

pub fn allocator(&self) -> AppReflectAllocator

Returns the script allocator for the world

pub fn script_function_registry(&self) -> AppScriptFunctionRegistry

Returns the function registry for the world

pub fn with_global_access<F: FnOnce(&mut World) -> O, O>( &self, f: F, ) -> Result<O, InteropError>

Claims access to the world for the duration of the closure, allowing for global access to the world.

pub fn with_resource<F, R, O>(&self, f: F) -> Result<O, InteropError>

where R: Resource, F: FnOnce(&R) -> O,

Safely accesses the resource by claiming and releasing access to it.

Panics

• if the resource does not exist

pub fn with_resource_mut<F, R, O>(&self, f: F) -> Result<O, InteropError>

where R: Resource, F: FnOnce(Mut<'_, R>) -> O,

Safely accesses the resource by claiming and releasing access to it.

Panics

• if the resource does not exist

pub fn with_component<F, T, O>( &self, entity: Entity, f: F, ) -> Result<O, InteropError>

where T: Component, F: FnOnce(Option<&T>) -> O,

Safely accesses the component by claiming and releasing access to it.

pub fn with_component_mut<F, T, O>( &self, entity: Entity, f: F, ) -> Result<O, InteropError>

where T: Component<Mutability = Mutable>, F: FnOnce(Option<Mut<'_, T>>) -> O,

Safely accesses the component by claiming and releasing access to it.

pub fn with_or_insert_component_mut<F, T, O>( &self, entity: Entity, f: F, ) -> Result<O, InteropError>

where T: Component<Mutability = Mutable> + Default, F: FnOnce(&mut T) -> O,

Safey modify or insert a component by claiming and releasing global access.

pub fn lookup_function( &self, type_ids: impl IntoIterator<Item = TypeId>, name: impl Into<Cow<'static, str>>, ) -> Result<DynamicScriptFunction, Cow<'static, str>>

Try to lookup a function with the given name on the given type id’s namespaces.

Returns the function if found, otherwise returns the name of the function that was not found.

pub fn get_functions_on_type( &self, type_id: TypeId, ) -> Vec<(Cow<'static, str>, DynamicScriptFunction)>

Iterates over all available functions on the type id’s namespace + those available on any reference if any exist.

pub fn is_valid_entity(&self, entity: Entity) -> Result<bool, InteropError>

checks if a given entity exists and is valid

pub fn try_call_overloads( &self, type_id: TypeId, name: impl Into<Cow<'static, str>>, args: Vec<ScriptValue>, context: FunctionCallContext, ) -> Result<ScriptValue, InteropError>

Tries to call a fitting overload of the function with the given name and in the type id’s namespace based on the arguments provided. Currently does this by repeatedly trying each overload until one succeeds or all fail.

impl WorldAccessGuard<'_>

Impl block for higher level world methods

pub fn construct( &self, type_: ScriptTypeRegistration, payload: HashMap<String, ScriptValue>, one_indexed: bool, ) -> Result<Box<dyn PartialReflect>, InteropError>

An arbitrary type constructor utility.

Allows the construction of arbitrary types (within limits dictated by the API) from the script directly

pub fn load_script_asset( &self, asset_path: &str, ) -> Result<Handle<ScriptAsset>, InteropError>

Loads a script from the given asset path with default settings.

pub fn get_script_asset_load_state( &self, script: Handle<ScriptAsset>, ) -> Result<LoadState, InteropError>

Checks the load state of a script asset.

pub fn spawn(&self) -> Result<Entity, InteropError>

Spawns a new entity in the world

pub fn get_type_by_name( &self, type_name: &str, ) -> Option<ScriptTypeRegistration>

get a type registration for the type, without checking if it’s a component or resource

pub fn get_type_registration_by_name( &self, type_name: String, ) -> Result<Option<Union<ScriptTypeRegistration, Union<ScriptComponentRegistration, ScriptResourceRegistration>>>, InteropError>

Similar to Self::get_type_by_name but returns a type erased ScriptTypeRegistration, ScriptComponentRegistration or ScriptResourceRegistration depending on the underlying type and state of the world.

pub fn get_schedule_by_name( &self, schedule_name: String, ) -> Option<ReflectSchedule>

get a schedule by name

pub fn get_component_type( &self, registration: ScriptTypeRegistration, ) -> Result<Result<ScriptComponentRegistration, ScriptTypeRegistration>, InteropError>

get a component type registration for the type

pub fn get_resource_type( &self, registration: ScriptTypeRegistration, ) -> Result<Result<ScriptResourceRegistration, ScriptTypeRegistration>, InteropError>

get a resource type registration for the type

pub fn add_default_component( &self, entity: Entity, registration: ScriptComponentRegistration, ) -> Result<(), InteropError>

add a default component to an entity

pub fn insert_component( &self, entity: Entity, registration: ScriptComponentRegistration, value: ReflectReference, ) -> Result<(), InteropError>

insert the component into the entity

pub fn get_component( &self, entity: Entity, component_registration: ScriptComponentRegistration, ) -> Result<Option<ReflectReference>, InteropError>

get the component from the entity

pub fn has_component( &self, entity: Entity, component_id: ComponentId, ) -> Result<bool, InteropError>

check if the entity has the component

pub fn remove_component( &self, entity: Entity, registration: ScriptComponentRegistration, ) -> Result<(), InteropError>

remove the component from the entity

pub fn get_resource( &self, resource_id: ComponentId, ) -> Result<Option<ReflectReference>, InteropError>

get the given resource

pub fn remove_resource( &self, registration: ScriptResourceRegistration, ) -> Result<(), InteropError>

remove the given resource

pub fn has_resource( &self, resource_id: ComponentId, ) -> Result<bool, InteropError>

check if the entity has the resource

pub fn has_entity(&self, entity: Entity) -> Result<bool, InteropError>

check the given entity exists

pub fn get_children(&self, entity: Entity) -> Result<Vec<Entity>, InteropError>

get the children of the given entity

pub fn get_parent(&self, entity: Entity) -> Result<Option<Entity>, InteropError>

get the parent of the given entity

pub fn push_children( &self, parent: Entity, children: &[Entity], ) -> Result<(), InteropError>

insert children into the given entity

pub fn remove_children( &self, parent: Entity, children: &[Entity], ) -> Result<(), InteropError>

remove children from the given entity

pub fn insert_children( &self, parent: Entity, index: usize, children: &[Entity], ) -> Result<(), InteropError>

insert children into the given entity at the given index

pub fn despawn_recursive(&self, parent: Entity) -> Result<(), InteropError>

despawn this and all children of the given entity recursively

pub fn despawn(&self, entity: Entity) -> Result<(), InteropError>

despawn the given entity

pub fn despawn_descendants(&self, parent: Entity) -> Result<(), InteropError>

despawn all children of the given entity recursively

pub fn exit(&self) -> Result<(), InteropError>

Sends AppExit event to the world with success status

Trait Implementations

impl<'w> Clone for WorldAccessGuard<'w>

fn clone(&self) -> WorldAccessGuard<'w>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'w> Debug for WorldAccessGuard<'w>

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

Formats the value using the given formatter.