Struct fyrox::scene::navmesh::NavigationalMesh

pub struct NavigationalMesh { /* private fields */ }

Navigational mesh (navmesh for short) is a surface which can be used for path finding. Unlike A* Pathfinder, it can build arbitrary paths on a surface of large polygons, making a path from point A to point B linear (standard pathfinder builds path only from vertex to vertex). Navmeshes should be used when you have an arbitrary “walkable” surface, for example, a game level with rooms, hallways, multiple floors and so on. A* pathfinder should be used for strategies or any other types of games with uniform pathfinding grid.

How to create

You should prefer using the navmesh editor to create navigational meshes, however if it is not possible, you can create it manually. Use NavigationalMeshBuilder to create new instance and add it to your scene graph. Keep in mind, that this node is just a convenient wrapper around Navmesh, so you should also read its docs to get better understanding how it works.

fn create_navmesh(graph: &mut Graph) -> Handle<Node> {
    // A simple navmesh with four vertices and two triangles.
    let navmesh = Navmesh::new(
        vec![TriangleDefinition([0, 1, 2]), TriangleDefinition([0, 2, 3])],
        vec![
            Vector3::new(-1.0, 0.0, 1.0),
            Vector3::new(1.0, 0.0, 1.0),
            Vector3::new(1.0, 0.0, -1.0),
            Vector3::new(-1.0, 0.0, -1.0),
        ],
    );
    NavigationalMeshBuilder::new(BaseBuilder::new())
        .with_navmesh(navmesh)
        .build(graph)
}

Agents

Navigational mesh agent helps you to build paths along the surface of a navigational mesh and follow it. Agents can be used to drive the motion of your game characters. Every agent knows about its target and automatically rebuilds the path if the target has moved. Navmesh agents are able to move along the path, providing you with their current position, so you can use it to perform an actual motion of your game characters. Agents work together with navigational meshes, you need to update their state every frame, so they can recalculate path if needed. A simple example could something like this:

// Add this to your script
agent: NavmeshAgent

After that, you need to update the agent every frame to make sure it will follow the target:

fn update_agent(
    agent: &mut NavmeshAgent,
    target: Vector3<f32>,
    dt: f32,
    navmesh: &NavigationalMesh,
) {
    // Set the target to follow and the speed.
    agent.set_target(target);
    agent.set_speed(1.0);

    // Update the agent.
    agent.update(dt, &navmesh.navmesh_ref()).unwrap();

    // Print its position - you can use this position as target point of your game character.
    println!("{}", agent.position());
}

This method should be called in on_update of your script. It accepts four parameters: a reference to the agent, a target which it will follow, a time step (context.dt), and a reference to navigational mesh node. You can fetch navigational mesh from the scene graph by its name:

fn find_navmesh<'a>(scene: &'a mut Scene, name: &str) -> &'a mut NavigationalMesh {
    let handle = scene.graph.find_by_name_from_root(name).unwrap().0;
    scene.graph[handle].as_navigational_mesh_mut()
}

Implementations

impl NavigationalMesh

pub const BASE: &'static str = "base"

pub const NAVMESH: &'static str = "navmesh"

impl NavigationalMesh

pub fn navmesh_ref(&self) -> RwLockReadGuard<'_, RawRwLock, Navmesh>

Returns a reference to the inner navigational mesh.

pub fn navmesh_mut(&mut self) -> RwLockWriteGuard<'_, RawRwLock, Navmesh>

Returns a reference to the inner navigational mesh.

pub fn navmesh(&self) -> Arc<RwLock<RawRwLock, Navmesh>>

Returns a shared reference to the inner navigational mesh. It could be used to perform off-thread path calculations.

Methods from Deref<Target = Base>

pub const NAME: &'static str = "name"

pub const LOCAL_TRANSFORM: &'static str = "local_transform"

pub const VISIBILITY: &'static str = "visibility"

pub const LIFETIME: &'static str = "lifetime"

pub const DEPTH_OFFSET: &'static str = "depth_offset"

pub const LOD_GROUP: &'static str = "lod_group"

pub const MOBILITY: &'static str = "mobility"

pub const TAG: &'static str = "tag"

pub const CAST_SHADOWS: &'static str = "cast_shadows"

pub const PROPERTIES: &'static str = "properties"

pub const FRUSTUM_CULLING: &'static str = "frustum_culling"

pub const IS_RESOURCE_INSTANCE_ROOT: &'static str = "is_resource_instance_root"

pub const RESOURCE: &'static str = "resource"

pub const SCRIPTS: &'static str = "scripts"

pub const ENABLED: &'static str = "enabled"

pub fn set_name<N>(&mut self, name: N)

where N: AsRef<str>,

Sets name of node. Can be useful to mark a node to be able to find it later on.

pub fn name(&self) -> &str

Returns name of node.

pub fn name_owned(&self) -> String

Returns owned name of node.

pub fn local_transform(&self) -> &Transform

Returns shared reference to local transform of a node, can be used to fetch some local spatial properties, such as position, rotation, scale, etc.

pub fn local_transform_mut(&mut self) -> &mut Transform

Returns mutable reference to local transform of a node, can be used to set some local spatial properties, such as position, rotation, scale, etc.

pub fn set_local_transform(&mut self, transform: Transform)

Sets new local transform of a node.

pub fn find_properties_ref<'a>( &'a self, name: &'a str ) -> impl Iterator<Item = &'a Property>

Tries to find properties by the name. The method returns an iterator because it possible to have multiple properties with the same name.

pub fn find_first_property_ref(&self, name: &str) -> Option<&Property>

Tries to find a first property with the given name.

pub fn set_properties(&mut self, properties: Vec<Property>) -> Vec<Property>

Sets a new set of properties of the node.

pub fn set_lifetime(&mut self, time_seconds: Option<f32>) -> &mut Base

Sets lifetime of node in seconds, lifetime is useful for temporary objects. Example - you firing a gun, it produces two particle systems for each shot: one for gunpowder fumes and one when bullet hits some surface. These particle systems won’t last very long - usually they will disappear in 1-2 seconds but nodes will still be in scene consuming precious CPU clocks. This is where lifetimes become handy - you just set appropriate lifetime for a particle system node and it will be removed from scene when time will end. This is efficient algorithm because scene holds every object in pool and allocation or deallocation of node takes very little amount of time.

pub fn lifetime(&self) -> Option<f32>

Returns current lifetime of a node. Will be None if node has undefined lifetime. For more info about lifetimes see set_lifetime.

pub fn parent(&self) -> Handle<Node>

Returns handle of parent node.

pub fn children(&self) -> &[Handle<Node>]

Returns slice of handles to children nodes. This can be used, for example, to traverse tree starting from some node.

pub fn global_transform( &self ) -> Matrix<f32, Const<4>, Const<4>, ArrayStorage<f32, 4, 4>>

Returns global transform matrix, such matrix contains combined transformation of transforms of parent nodes. This is the final matrix that describes real location of object in the world.

pub fn inv_bind_pose_transform( &self ) -> Matrix<f32, Const<4>, Const<4>, ArrayStorage<f32, 4, 4>>

Returns inverse of bind pose matrix. Bind pose matrix - is special matrix for bone nodes, it stores initial transform of bone node at the moment of “binding” vertices to bones.

pub fn is_resource_instance_root(&self) -> bool

Returns true if this node is model resource instance root node.

pub fn resource(&self) -> Option<Resource<Model>>

Returns resource from which this node was instantiated from.

pub fn set_visibility(&mut self, visibility: bool) -> bool

Sets local visibility of a node.

pub fn visibility(&self) -> bool

Returns local visibility of a node.

pub fn local_bounding_box(&self) -> AxisAlignedBoundingBox

Returns current local-space bounding box. Keep in mind that this value is just a placeholder, because there is not information to calculate actual bounding box.

pub fn world_bounding_box(&self) -> AxisAlignedBoundingBox

Returns current world-space bounding box.

pub fn set_mobility(&mut self, mobility: Mobility) -> Mobility

Set new mobility for the node. See Mobility docs for more info.

pub fn mobility(&self) -> Mobility

Return current mobility of the node.

pub fn global_visibility(&self) -> bool

Returns combined visibility of an node. This is the final visibility of a node. Global visibility calculated using visibility of all parent nodes until root one, so if some parent node upper on tree is invisible then all its children will be invisible. It defines if object will be rendered. It is not the same as real visibility from point of view of a camera. Use frustum-box intersection test instead.

pub fn original_handle_in_resource(&self) -> Handle<Node>

Handle to node in scene of model resource from which this node was instantiated from.

Notes

This handle is extensively used to fetch information about the state of node in the resource to sync properties of instance with its original in the resource.

pub fn global_position( &self ) -> Matrix<f32, Const<3>, Const<1>, ArrayStorage<f32, 3, 1>>

Returns position of the node in absolute coordinates.

pub fn look_vector( &self ) -> Matrix<f32, Const<3>, Const<1>, ArrayStorage<f32, 3, 1>>

Returns “look” vector of global transform basis, in most cases return vector will be non-normalized.

pub fn side_vector( &self ) -> Matrix<f32, Const<3>, Const<1>, ArrayStorage<f32, 3, 1>>

Returns “side” vector of global transform basis, in most cases return vector will be non-normalized.

pub fn up_vector( &self ) -> Matrix<f32, Const<3>, Const<1>, ArrayStorage<f32, 3, 1>>

Returns “up” vector of global transform basis, in most cases return vector will be non-normalized.

pub fn set_depth_offset_factor(&mut self, factor: f32) -> f32

Sets depth range offset factor. It allows you to move depth range by given value. This can be used to draw weapons on top of other stuff in scene.

Details

This value is used to modify projection matrix before render node. Element m[4][3] of projection matrix usually set to -1 to which makes w coordinate of in homogeneous space to be -z_fragment for further perspective divide. We can abuse this to shift z of fragment by some value.

pub fn depth_offset_factor(&self) -> f32

Returns depth offset factor.

pub fn set_lod_group(&mut self, lod_group: Option<LodGroup>) -> Option<LodGroup>

Sets new lod group.

pub fn take_lod_group(&mut self) -> Option<LodGroup>

Extracts lod group, leaving None in the node.

pub fn lod_group(&self) -> Option<&LodGroup>

Returns shared reference to current lod group.

pub fn lod_group_mut(&mut self) -> Option<&mut LodGroup>

Returns mutable reference to current lod group.

pub fn tag(&self) -> &str

Returns node tag.

pub fn tag_owned(&self) -> String

Returns a copy of node tag.

pub fn set_tag(&mut self, tag: String) -> String

Sets new tag.

pub fn frustum_culling(&self) -> bool

Return the frustum_culling flag

pub fn set_frustum_culling(&mut self, frustum_culling: bool) -> bool

Sets whether to use frustum culling or not

pub fn cast_shadows(&self) -> bool

Returns true if the node should cast shadows, false - otherwise.

pub fn set_cast_shadows(&mut self, cast_shadows: bool) -> bool

Sets whether the mesh should cast shadows or not.

pub fn instance_id(&self) -> SceneNodeId

Returns current instance id.

pub fn remove_script(&mut self, index: usize)

Removes a script with the given index from the scene node. The script will be destroyed in either the current update tick (if it was removed from some other script) or in the next update tick of the parent graph.

pub fn remove_all_scripts(&mut self)

Removes all assigned scripts from the scene node. The scripts will be removed from first-to-last order an their actual destruction will happen either on the current update tick of the parent graph (if it was removed from some other script) or in the next update tick.

pub fn replace_script(&mut self, index: usize, script: Option<Script>)

Sets a new script for the scene node by index. Previous script will be removed (see Self::remove_script docs for more info).

pub fn add_script<T>(&mut self, script: T)

where T: ScriptTrait,

Adds a new script to the scene node. The new script will be initialized either in the current update tick (if the script was added in one of the ScriptTrait methods) or on the next update tick.

pub fn has_script<T>(&self) -> bool

where T: ScriptTrait,

Checks if the node has a script of a particular type. Returns false if there is no such script.

pub fn has_scripts_assigned(&self) -> bool

Checks if the node has any scripts assigned.

pub fn try_get_script<T>(&self) -> Option<&T>

where T: ScriptTrait,

Tries to find a first script of the given type T, returns None if there’s no such script.

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

where T: ScriptTrait,

Returns an iterator that yields references to the scripts of the given type T.

pub fn try_get_script_mut<T>(&mut self) -> Option<&mut T>

where T: ScriptTrait,

Tries to find a first script of the given type T, returns None if there’s no such script.

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

where T: ScriptTrait,

Returns an iterator that yields references to the scripts of the given type T.

pub fn try_get_script_component<C>(&self) -> Option<&C>

where C: Any,

Tries find a component of the given type C across all available scripts of the node. If you want to search a component C in a particular script, then use Self::try_get_script and then search for component in it.

pub fn try_get_script_component_mut<C>(&mut self) -> Option<&mut C>

where C: Any,

Tries find a component of the given type C across all available scripts of the node. If you want to search a component C in a particular script, then use Self::try_get_script and then search for component in it.

pub fn script_count(&self) -> usize

Returns total count of scripts assigned to the node.

pub fn script(&self, index: usize) -> Option<&Script>

Returns a shared reference to a script instance with the given index. This method will return None if the index is out of bounds or the script is temporarily not available. This could happen if this method was called from some method of a ScriptTrait. It happens because of borrowing rules - you cannot take another reference to a script that is already mutably borrowed.

pub fn scripts(&self) -> impl Iterator<Item = &Script>

Returns an iterator that yields all assigned scripts.

pub fn script_mut(&mut self, index: usize) -> Option<&mut Script>

Returns a mutable reference to a script instance with the given index. This method will return None if the index is out of bounds or the script is temporarily not available. This could happen if this method was called from some method of a ScriptTrait. It happens because of borrowing rules - you cannot take another reference to a script that is already mutably borrowed.

Important notes

Do not replace script instance using mutable reference given to you by this method. This will prevent correct script de-initialization! Use Self::replace_script if you need to replace the script.

pub fn scripts_mut(&mut self) -> impl Iterator<Item = &mut Script>

Returns an iterator that yields all assigned scripts.

pub fn set_enabled(&mut self, enabled: bool)

Enables or disables scene node. Disabled scene nodes won’t be updated (including scripts) or rendered.

Important notes

Enabled/disabled state will affect children nodes. It means that if you have a node with children nodes, and you disable the node, all children nodes will be disabled too even if their Self::is_enabled method returns true.

pub fn is_enabled(&self) -> bool

Returns true if the node is enabled, false - otherwise. The return value does not include the state of parent nodes. It should be considered as “local” enabled flag. To get actual enabled state, that includes the state of parent nodes, use Self::is_globally_enabled method.

pub fn is_globally_enabled(&self) -> bool

Returns true if the node and every parent up in hierarchy is enabled, false - otherwise. This method returns “true” enabled flag. Its value could be different from the value returned by Self::is_enabled.

pub fn root_resource(&self) -> Option<Resource<Model>>

Returns a root resource of the scene node. This method crawls up on dependency tree until it finds that the ancestor node does not have any dependencies and returns this resource as the root resource. For example, in case of simple scene node instance, this method will return the resource from which the node was instantiated from. In case of 2 or more levels of dependency, it will always return the “top” dependency in the dependency graph.

Trait Implementations

impl Clone for NavigationalMesh

fn clone(&self) -> NavigationalMesh

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for NavigationalMesh

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

Formats the value using the given formatter.

impl Default for NavigationalMesh

fn default() -> NavigationalMesh

Returns the “default value” for a type.

impl Deref for NavigationalMesh

type Target = Base

The resulting type after dereferencing.

fn deref(&self) -> &<NavigationalMesh as Deref>::Target

Dereferences the value.

impl DerefMut for NavigationalMesh

fn deref_mut(&mut self) -> &mut <NavigationalMesh as Deref>::Target

Mutably dereferences the value.

impl NodeTrait for NavigationalMesh

fn query_component_ref(&self, type_id: TypeId) -> Option<&(dyn Any + 'static)>

Allows a node to provide access to inner components.

fn query_component_mut( &mut self, type_id: TypeId ) -> Option<&mut (dyn Any + 'static)>

Allows a node to provide access to inner components.

fn local_bounding_box(&self) -> AxisAlignedBoundingBox

Returns axis-aligned bounding box in local space of the node.

fn world_bounding_box(&self) -> AxisAlignedBoundingBox

Returns axis-aligned bounding box in world space of the node.

fn id(&self) -> Uuid

Returns actual type id. It will be used for serialization, the type will be saved together with node’s data allowing you to create correct node instance on deserialization.

fn debug_draw(&self, ctx: &mut SceneDrawingContext)

Allows the node to draw simple shapes to visualize internal data structures for debugging purposes.

fn on_removed_from_graph(&mut self, graph: &mut Graph)

Gives an opportunity to perform clean up after the node was extracted from the scene graph (or deleted).

fn on_unlink(&mut self, graph: &mut Graph)

The method is called when the node was detached from its parent node.

fn sync_native( &self, self_handle: Handle<Node>, context: &mut SyncContext<'_, '_> )

Synchronizes internal state of the node with components of scene graph. It has limited usage and mostly allows you to sync the state of backing entity with the state of the node. For example the engine use it to sync native rigid body properties after some property was changed in the crate::scene::rigidbody::RigidBody node.

fn sync_transform( &self, new_global_transform: &Matrix<f32, Const<4>, Const<4>, ArrayStorage<f32, 4, 4>>, _context: &mut SyncContext<'_, '_> )

Called when node’s global transform changes.

fn is_alive(&self) -> bool

The methods is used to manage lifetime of scene nodes, depending on their internal logic.

fn update(&mut self, context: &mut UpdateContext<'_>)

Updates internal state of the node.

fn collect_render_data(&self, ctx: &mut RenderContext<'_>) -> RdcControlFlow

Allows the node to emit a set of render data. This is a high-level rendering method which can only do culling and provide render data. Render data is just a surface (vertex + index buffers) and a material.

fn validate(&self, scene: &Scene) -> Result<(), String>

Validates internal state of a scene node. It can check handles validity, if a handle “points” to a node of particular type, if node’s parameters are in range, etc. It’s main usage is to provide centralized diagnostics for scene graph.

impl Reflect for NavigationalMesh

where NavigationalMesh: 'static, Base: Reflect, InheritableVariable<Container>: Reflect,

fn source_path() -> &'static str

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn assembly_name(&self) -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn type_assembly_name() -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

fn into_any(self: Box<NavigationalMesh>) -> Box<dyn Any>

fn set( &mut self, value: Box<dyn Reflect> ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>

fn as_any(&self, func: &mut dyn FnMut(&(dyn Any + 'static)))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut (dyn Any + 'static)))

fn as_reflect(&self, func: &mut dyn FnMut(&(dyn Reflect + 'static)))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut (dyn Reflect + 'static)))

fn fields(&self, func: &mut dyn FnMut(&[&(dyn Reflect + 'static)]))

fn fields_mut( &mut self, func: &mut dyn FnMut(&mut [&mut (dyn Reflect + 'static)]) )

fn field( &self, name: &str, func: &mut dyn FnMut(Option<&(dyn Reflect + 'static)>) )

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut (dyn Reflect + 'static)>) )

fn set_field( &mut self, field: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>) )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn as_array(&self, func: &mut dyn FnMut(Option<&(dyn ReflectArray + 'static)>))

fn as_array_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectArray + 'static)>) )

fn as_list(&self, func: &mut dyn FnMut(Option<&(dyn ReflectList + 'static)>))

fn as_list_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectList + 'static)>) )

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&(dyn ReflectInheritableVariable + 'static)>) )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectInheritableVariable + 'static)>) )

fn as_hash_map( &self, func: &mut dyn FnMut(Option<&(dyn ReflectHashMap + 'static)>) )

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectHashMap + 'static)>) )

impl TypeUuidProvider for NavigationalMesh

fn type_uuid() -> Uuid

Return type UUID.

impl Visit for NavigationalMesh

where Base: Visit, InheritableVariable<Container>: Visit,

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> Result<(), VisitError>

Read or write this value, depending on whether Visitor::is_reading() is true or false.