Struct Node

pub struct Node(/* private fields */);

Node is the basic building block for 3D scenes. It has multiple variants, but all of them share some common functionality:

• Local and global transform
• Info about connections with other nodes in scene
• Visibility state - local and global
• Name and tags
• Level of details
• Physics binding mode

The exact functionality depends on variant of the node, check the respective docs for a variant you interested in.

Hierarchy

Nodes can be connected with other nodes, so a child node will be moved/rotate/scaled together with parent node. This has some analogy in real world - imagine a pen with a cap. The pen will be the parent node in the hierarchy and the cap will be child node. When you moving the pen, the cap moves with it only if it attached to the pen. The same principle works with scene nodes.

Transform

The node has two kinds of transform - local and global. Local transform defines where the node is located (translation) relative to origin, how much it is scaled (in percent) and rotated (around any arbitrary axis). Global transform is almost the same, but it also includes the whole chain of transforms of parent nodes. In the previous example with the pen, the cap has its own local transform which tells how much it should be moved from origin to be exactly on top of the pen. But global transform of the cap includes transform of the pen. So if you move the pen, the local transform of the cap will remain the same, but global transform will include the transform of the pen.

Name and tag

The node can have arbitrary name and tag. Both could be used to search the node in the graph. Unlike the name, tag could be used to store some gameplay information about the node. For example you can place a Mesh node that represents health pack model and it will have a name “HealthPack”, in the tag you could put additional info like “MediumPack”, “SmallPack”, etc. So 3D model will not have “garbage” in its name, it will be stored inside tag.

Visibility

The now has two kinds of visibility - local and global. As with transform, everything here is pretty similar. Local visibility defines if the node is visible as if it would be rendered alone, global visibility includes the combined visibility of entire chain of parent nodes.

Please keep in mind that “visibility” here means some sort of a “switch” that tells the renderer whether to draw the node or not.

Level of details

The node could control which children nodes should be drawn based on the distance to a camera, this is so called level of detail functionality. There is a separate article about LODs, it can be found here.

Property inheritance

Property inheritance is used to propagate changes of unmodified properties from a prefab to its instances. For example, you can change scale of a node in a prefab and its instances will have the same scale too, unless the scale is set explicitly in an instance. Such feature allows you to tweak instances, add some unique details to them, but take general properties from parent prefabs.

Important notes

Property inheritance uses variable::InheritableVariable to wrap actual property value, such wrapper stores a tiny bitfield for flags that can tell whether or not the property was modified. Property inheritance system is then uses reflection to “walk” over each property in the node and respective parent resource (from which the node was instantiated from, if any) and checks if the property was modified. If it was modified, its value remains the same, otherwise the value from the respective property in a “parent” node in the parent resource is copied to the property of the node. Such process is then repeated for all levels of inheritance, starting from the root and going down to children in inheritance hierarchy.

The most important thing is that variable::InheritableVariable will save (serialize) its value only if it was marked as modified (we don’t need to save anything if it can be fetched from parent). This saves a lot of disk space for inherited assets (in some extreme cases memory consumption can be reduced by 90%, if there’s only few properties modified). This fact requires “root” (nodes that are not instances) nodes to have all inheritable properties to be marked as modified, otherwise their values won’t be saved, which is indeed wrong.

When a node is instantiated from some model resource, all its properties become non-modified. Which allows the inheritance system to correctly handle redundant information.

Such implementation of property inheritance has its drawbacks, major one is: each instance still holds its own copy of of every field, even those inheritable variables which are non-modified. Which means that there’s no benefits of RAM consumption, only disk space usage is reduced.

Implementations

impl Node

pub fn new<T: NodeTrait>(node: T) -> Self

Creates a new node instance from any type that implements NodeTrait.

pub fn cast<T: NodeTrait>(&self) -> Option<&T>

Performs downcasting to a particular type.

Example

fn node_as_mesh_ref(node: &Node) -> &Mesh {
    node.cast::<Mesh>().expect("Expected to be an instance of Mesh")
}

pub fn cast_mut<T: NodeTrait>(&mut self) -> Option<&mut T>

Performs downcasting to a particular type.

Example

fn node_as_mesh_mut(node: &mut Node) -> &mut Mesh {
    node.cast_mut::<Mesh>().expect("Expected to be an instance of Mesh")
}

pub fn is_mesh(&self) -> bool

Returns true if node is instance of given type.

pub fn as_mesh(&self) -> &Mesh

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_mesh_mut(&mut self) -> &mut Mesh

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_pivot(&self) -> bool

Returns true if node is instance of given type.

pub fn as_pivot(&self) -> &Pivot

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_pivot_mut(&mut self) -> &mut Pivot

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_camera(&self) -> bool

Returns true if node is instance of given type.

pub fn as_camera(&self) -> &Camera

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_camera_mut(&mut self) -> &mut Camera

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_spot_light(&self) -> bool

Returns true if node is instance of given type.

pub fn as_spot_light(&self) -> &SpotLight

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_spot_light_mut(&mut self) -> &mut SpotLight

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_point_light(&self) -> bool

Returns true if node is instance of given type.

pub fn as_point_light(&self) -> &PointLight

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_point_light_mut(&mut self) -> &mut PointLight

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_directional_light(&self) -> bool

Returns true if node is instance of given type.

pub fn as_directional_light(&self) -> &DirectionalLight

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_directional_light_mut(&mut self) -> &mut DirectionalLight

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_particle_system(&self) -> bool

Returns true if node is instance of given type.

pub fn as_particle_system(&self) -> &ParticleSystem

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_particle_system_mut(&mut self) -> &mut ParticleSystem

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_sprite(&self) -> bool

Returns true if node is instance of given type.

pub fn as_sprite(&self) -> &Sprite

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_sprite_mut(&mut self) -> &mut Sprite

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_terrain(&self) -> bool

Returns true if node is instance of given type.

pub fn as_terrain(&self) -> &Terrain

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_terrain_mut(&mut self) -> &mut Terrain

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_decal(&self) -> bool

Returns true if node is instance of given type.

pub fn as_decal(&self) -> &Decal

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_decal_mut(&mut self) -> &mut Decal

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_rectangle(&self) -> bool

Returns true if node is instance of given type.

pub fn as_rectangle(&self) -> &Rectangle

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_rectangle_mut(&mut self) -> &mut Rectangle

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_rigid_body(&self) -> bool

Returns true if node is instance of given type.

pub fn as_rigid_body(&self) -> &RigidBody

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_rigid_body_mut(&mut self) -> &mut RigidBody

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_collider(&self) -> bool

Returns true if node is instance of given type.

pub fn as_collider(&self) -> &Collider

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_collider_mut(&mut self) -> &mut Collider

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_joint(&self) -> bool

Returns true if node is instance of given type.

pub fn as_joint(&self) -> &Joint

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_joint_mut(&mut self) -> &mut Joint

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_rigid_body2d(&self) -> bool

Returns true if node is instance of given type.

pub fn as_rigid_body2d(&self) -> &RigidBody

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_rigid_body2d_mut(&mut self) -> &mut RigidBody

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_collider2d(&self) -> bool

Returns true if node is instance of given type.

pub fn as_collider2d(&self) -> &Collider

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_collider2d_mut(&mut self) -> &mut Collider

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_joint2d(&self) -> bool

Returns true if node is instance of given type.

pub fn as_joint2d(&self) -> &Joint

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_joint2d_mut(&mut self) -> &mut Joint

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_sound(&self) -> bool

Returns true if node is instance of given type.

pub fn as_sound(&self) -> &Sound

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_sound_mut(&mut self) -> &mut Sound

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_listener(&self) -> bool

Returns true if node is instance of given type.

pub fn as_listener(&self) -> &Listener

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_listener_mut(&mut self) -> &mut Listener

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_navigational_mesh(&self) -> bool

Returns true if node is instance of given type.

pub fn as_navigational_mesh(&self) -> &NavigationalMesh

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_navigational_mesh_mut(&mut self) -> &mut NavigationalMesh

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_absm(&self) -> bool

Returns true if node is instance of given type.

pub fn as_absm(&self) -> &AnimationBlendingStateMachine

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_absm_mut(&mut self) -> &mut AnimationBlendingStateMachine

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_animation_player(&self) -> bool

Returns true if node is instance of given type.

pub fn as_animation_player(&self) -> &AnimationPlayer

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_animation_player_mut(&mut self) -> &mut AnimationPlayer

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

pub fn is_ragdoll(&self) -> bool

Returns true if node is instance of given type.

pub fn as_ragdoll(&self) -> &Ragdoll

Tries to cast shared reference to a node to given type, panics if cast is not possible.

pub fn as_ragdoll_mut(&mut self) -> &mut Ragdoll

Tries to cast mutable reference to a node to given type, panics if cast is not possible.

Trait Implementations

impl Clone for Node

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ComponentProvider for Node

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

Allows an object to provide access to inner components.

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

Allows an object to provide access to inner components.

impl ConstructorProvider<Node, Graph> for AnimationBlendingStateMachine

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for AnimationPlayer

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Camera

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Collider

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Collider

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Decal

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for DirectionalLight

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Joint

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Joint

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Listener

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Mesh

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for NavigationalMesh

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for ParticleSystem

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Pivot

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for PointLight

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Ragdoll

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Rectangle

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for RigidBody

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for RigidBody

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Sound

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for SpotLight

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Sprite

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for Terrain

fn constructor() -> NodeConstructor

impl ConstructorProvider<Node, Graph> for TileMap

fn constructor() -> NodeConstructor

impl Debug for Node

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

Formats the value using the given formatter.

impl DerefMut for Node

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: NodeTrait> From<T> for Node

fn from(value: T) -> Self

Converts to this type from the input type.

impl NameProvider for Node

fn name(&self) -> &str

Returns a reference to the name of the entity.

impl Reflect for Node

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<Self>) -> Box<dyn Any>

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

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

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

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

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

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 fields(&self, func: &mut dyn FnMut(&[&dyn Reflect]))

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

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

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

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 SceneGraphNode for Node

type Base = Base

type SceneGraph = Graph

type ResourceData = Model

fn base(&self) -> &Self::Base

fn set_base(&mut self, base: Self::Base)

fn is_resource_instance_root(&self) -> bool

fn original_handle_in_resource(&self) -> Handle<Self>

fn set_original_handle_in_resource(&mut self, handle: Handle<Self>)

fn resource(&self) -> Option<Resource<Self::ResourceData>>

fn self_handle(&self) -> Handle<Self>

fn parent(&self) -> Handle<Self>

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

fn children_mut(&mut self) -> &mut [Handle<Self>]

fn swap_child_position( &mut self, child: Handle<Self>, pos: usize, ) -> Option<usize>

Puts the given child handle to the given position pos, by swapping positions.

fn set_child_position( &mut self, child: Handle<Self>, dest_pos: usize, ) -> Option<usize>

fn child_position(&self, child: Handle<Self>) -> Option<usize>

fn has_child(&self, child: Handle<Self>) -> bool

fn revert_inheritable_property( &mut self, path: &str, ) -> Option<Box<dyn Reflect>>

fn component_ref<T>(&self) -> Option<&T>

where T: Any,

Tries to borrow a component of given type.

fn component_mut<T>(&mut self) -> Option<&mut T>

where T: Any,

Tries to borrow a component of given type.

fn has_component<T>(&self) -> bool

where T: Any,

Checks if the node has a component of given type.

impl TypeUuidProvider for Node

fn type_uuid() -> Uuid

Return type UUID.

impl Visit for Node

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> VisitResult

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

impl Deref for Node

type Target = dyn NodeTrait<Target = Base>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.