Struct Terrain 

pub struct Terrain { /* private fields */ }

Terrain is a height field where each point has fixed coordinates in XZ plane, but variable Y coordinate. It can be used to create landscapes. It supports multiple layers, where each layer has its own material and mask.

Chunking

Terrain itself does not define any geometry or rendering data, instead it uses one or more chunks for that purpose. Each chunk could be considered as a “sub-terrain”. You can “stack” any amount of chunks from any side of the terrain. To do that, you define a range of chunks along each axes. This is very useful if you need to extend your terrain in a particular direction. Imagine that you’ve created a terrain with just one chunk (0..1 range on both axes), but suddenly you found that you need to extend the terrain to add some new game locations. In this case you can change the range of chunks at the desired axis. For instance, if you want to add a new location to the right from your single chunk, then you should change width_chunks range to 0..2 and leave length_chunks as is (0..1). This way terrain will be extended and you can start shaping the new location.

Layers

Layer is a material with a blending mask. Layers helps you to build a terrain with wide variety of details. For example, you can have a terrain with 3 layers: grass, rock, snow. This combination can be used to create a terrain with grassy plateaus, rocky mountains with snowy tops. Each chunk (see above) can have its own set of materials for each layer, however the overall layer count is defined by the terrain itself. An ability to have different set of materials for different chunks is very useful to support various biomes.

Level of detail (LOD)

Terrain has automatic LOD system, which means that the closest portions of it will be rendered with highest possible quality (defined by the resolution of height map and masks), while the furthest portions will be rendered with lowest quality. This effectively balances GPU load and allows you to render huge terrains with low overhead.

The main parameter that affects LOD system is block_size (Terrain::set_block_size), which defines size of the patch that will be used for rendering. It is used to divide the size of the height map into a fixed set of blocks using quad-tree algorithm.

Current implementation uses modified version of CDLOD algorithm without patch morphing. Apparently it is not needed, since bilinear filtration in vertex shader prevents seams to occur.

Painting

Painting involves constructing a BrushStroke and calling its BrushStroke::accept_messages method with a channel receiver, and sending a series of pixel messages into that channel. The BrushStroke will translate those messages into modifications to the Terrain’s textures.

Ray casting

You have two options to perform a ray casting:

1. By using ray casting feature of the physics engine. In this case you need to create a Heighfield collider and use standard crate::scene::graph::physics::PhysicsWorld::cast_ray method.
2. By using Terrain::raycast - this method could provide you more information about intersection point, than physics-based.

Physics

As usual, to have collisions working you need to create a rigid body and add an appropriate collider to it. In case of terrains you need to create a collider with Heightfield shape and specify your terrain as a geometry source.

Coordinate Spaces

Terrains operate in several systems of coordinates depending upon which aspect of the terrain is being measured.

• Local: These are the 3D f32 coordinates of the Terrain node that are transformed to world space by the Base::global_transform. It is measured in meters.
• Local 2D: These are the 2D f32 coordinates formed by taking the (x,y,z) of local coordinates and turning them into (x,z), with y removed and z becoming the new y. The size of chunks in these coordinates is set by Terrain::chunk_size.
• Grid Position: These are the 2D i32 coordinates that represent a chunk’s position within the regular grid of chunks that make up a terrain. The local 2D position of a chunk can be calculated from its grid position by multiplying its x and y coordinates by the x and y of Terrain::chunk_size.
• Height Pixel Position: These are the 2D coordinates that measure position across the x and z axes of the terrain using pixels in the height data of each chunk. (0,0) is the position of the Terrain node. The height pixel position of a chunk can be calculated from its grid position by multiplying its x and y coordinates by (x - 3) and (y - 3) of Terrain::height_map_size. Subtracting 1 from each dimension is necessary because the height map data of chunks overlaps by one pixel on each edge, so the distance between the origins of two adjacent chunks is one less than height_map_size.
• Mask Pixel Position: These are the 2D coordinates that measure position across the x and z axes of the terrain using pixels of the mask data of each chunk. (0,0) is the position of the (0,0) pixel of the mask texture of the (0,0) chunk. This means that (0,0) is offset from the position of the Terrain node by a half-pixel in the x direction and a half-pixel in the z direction. The size of each pixel is determined by Terrain::chunk_size and Terrain::mask_size.

The size of blocks and the size of quad tree nodes is measured in height pixel coordinates, and these measurements count the number of pixels needed to render the vertices of that part of the terrain, which means that they overlap with their neighbors just as chunks overlap. Two adjacent blocks share vertices along their edge, so they also share pixels in the height map data.

Implementations

impl Terrain

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

pub const HOLES_ENABLED: &'static str = "holes_enabled"

pub const LAYERS: &'static str = "layers"

pub const CHUNK_SIZE: &'static str = "chunk_size"

pub const WIDTH_CHUNKS: &'static str = "width_chunks"

pub const LENGTH_CHUNKS: &'static str = "length_chunks"

pub const HEIGHT_MAP_SIZE: &'static str = "height_map_size"

pub const BLOCK_SIZE: &'static str = "block_size"

pub const MASK_SIZE: &'static str = "mask_size"

pub const CHUNKS: &'static str = "chunks"

impl Terrain

pub fn align_chunk_margins(&mut self, grid_position: Vector2<i32>)

The height map of a chunk must have one-pixel margins around the edges which do not correspond to vertices in the terrain of that chunk, but are still needed for calculating the normal of the edge vertices. The normal for each vertex is derived from the heights of the four neighbor vertices, which means that every vertex must have four neighbors, even edge vertices. The one-pixel margin guarantees this.

This method modifies the margin of the chunk at the given position so that it matches the data in the eight neighboring chunks.

pub fn align_chunk_edges(&mut self, grid_position: Vector2<i32>)

The height map of a chunk must duplicate the height data of neighboring chunks along each edge. Otherwise the terrain would split apart at chunk boundaries. This method modifies all eight neighboring chunks surrounding the chunk at the given position to force them to align with the edge data of the chunk at the given position.

pub fn chunk_size(&self) -> Vector2<f32>

Returns chunk size in meters. This is equivalent to Chunk::physical_size.

pub fn set_chunk_size(&mut self, chunk_size: Vector2<f32>) -> Vector2<f32>

Sets new chunk size of the terrain (in meters). All chunks in the terrain will be repositioned according to their positions on the grid. Return the previous chunk size.

pub fn height_map_size(&self) -> Vector2<u32>

Returns height map dimensions along each axis. This is measured in pixels and gives the size of each chunk, including the 1 pixel overlap that each chunk shares with its neighbors.

pub fn hole_mask_size(&self) -> Vector2<u32>

Returns hole mask dimensions along each axis. This is measured in pixels and gives the size of each chunk by counting the faces between height map vertices. Holes are cut into terrain by removing faces, so each pixel represents one face.

pub fn set_height_map_size( &mut self, height_map_size: Vector2<u32>, ) -> Vector2<u32>

Sets new size of the height map for every chunk. Heightmaps in every chunk will be resampled which may cause precision loss if the size was decreased. Warning: This method is very heavy and should not be used at every frame!

pub fn set_block_size(&mut self, block_size: Vector2<u32>) -> Vector2<u32>

Sets the new block size, measured in height map pixels. Block size defines “granularity” of the terrain; the minimal terrain patch that will be used for rendering. It directly affects level-of-detail system of the terrain. Warning: This method is very heavy and should not be used at every frame!

pub fn block_size(&self) -> Vector2<u32>

Returns current block size of the terrain as measured by counting vertices along each axis of the block mesh.

pub fn set_holes_enabled(&mut self, enabled: bool) -> bool

Add or remove the hole masks from the chunks of this terrain.

pub fn holes_enabled(&self) -> bool

True if hole masks have been added to chunks.

pub fn mask_size(&self) -> Vector2<u32>

Returns the number of pixels along each axis of the layer blending mask.

pub fn set_mask_size(&mut self, mask_size: Vector2<u32>) -> Vector2<u32>

Sets new size of the layer blending mask in pixels. Every layer mask will be resampled which may cause precision loss if the size was decreased.

pub fn width_chunks(&self) -> Range<i32>

Returns a numeric range along width axis which defines start and end chunk indices on a chunks grid.

pub fn set_width_chunks(&mut self, chunks: Range<i32>) -> Range<i32>

Sets amount of chunks along width axis.

pub fn length_chunks(&self) -> Range<i32>

Returns a numeric range along length axis which defines start and end chunk indices on a chunks grid.

pub fn set_length_chunks(&mut self, chunks: Range<i32>) -> Range<i32>

Sets amount of chunks along length axis.

pub fn resize(&mut self, width_chunks: Range<i32>, length_chunks: Range<i32>)

Sets new chunks ranges for each axis of the terrain. This function automatically adds new chunks if you’re increasing size of the terrain and removes existing if you shrink the terrain.

pub fn chunks_ref(&self) -> &[Chunk]

Returns a reference to chunks of the terrain.

pub fn chunks_mut(&mut self) -> &mut [Chunk]

Returns a mutable reference to chunks of the terrain.

pub fn find_chunk(&self, grid_position: Vector2<i32>) -> Option<&Chunk>

Return the chunk with the matching Chunk::grid_position.

pub fn find_chunk_mut( &mut self, grid_position: Vector2<i32>, ) -> Option<&mut Chunk>

Return the chunk with the matching Chunk::grid_position.

pub fn update_quad_trees(&mut self)

Create new quad trees for every chunk in the terrain.

pub fn project(&self, p: Vector3<f32>) -> Option<Vector2<f32>>

Projects given 3D point on the surface of terrain and returns 2D vector expressed in local 2D coordinate system of terrain.

pub fn local_to_height_pixel(&self, p: Vector2<f32>) -> Vector2<f32>

Convert from local 2D to height pixel position.

pub fn local_to_mask_pixel(&self, p: Vector2<f32>) -> Vector2<f32>

Convert from local 2D to mask pixel position.

pub fn local_to_hole_pixel(&self, p: Vector2<f32>) -> Vector2<f32>

Convert from local 2D to hole pixel position.

pub fn height_grid_scale(&self) -> Vector2<f32>

The size of each cell of the height grid in local 2D units.

pub fn hole_grid_scale(&self) -> Vector2<f32>

The size of each cell of the height grid in local 2D units.

pub fn mask_grid_scale(&self) -> Vector2<f32>

The size of each cell of the mask grid in local 2D units.

pub fn get_height_grid_square(&self, position: Vector2<f32>) -> TerrainRect

Calculate which cell of the height grid contains the given local 2D position.

pub fn get_mask_grid_square(&self, position: Vector2<f32>) -> TerrainRect

Calculate which cell of the mask grid contains the given local 2D position. Mask grid cells are shifted by a half-pixel in each dimension, so that the origin of the (0,0) cell is at (0.5,0.5) as measured in pixels.

pub fn get_hole_grid_square(&self, position: Vector2<f32>) -> TerrainRect

Calculate which cell of the hole grid contains the given local 2D position. Mask grid cells are shifted by a half-pixel in each dimension, so that the origin of the (0,0) cell is at (0.5,0.5) as measured in pixels.

pub fn get_layer_mask(&self, position: Vector2<i32>, layer: usize) -> Option<u8>

Return the value of the layer mask at the given mask pixel position.

pub fn get_hole_mask(&self, position: Vector2<i32>) -> Option<u8>

Return the value of the layer mask at the given mask pixel position.

pub fn get_height(&self, position: Vector2<i32>) -> Option<f32>

Return the value of the height map at the given height pixel position.

pub fn interpolate_value( &self, position: Vector2<f32>, target: BrushTarget, ) -> f32

Return an interpolation of that the value should be for the given brush target at the given local 2D position. For height target, it returns the height. For mask targets, it returns 0.0 for transparent and 1.0 for opaque.

pub fn height_pos_to_local(&self, position: Vector2<i32>) -> Vector2<f32>

Convert height pixel position into local 2D position.

pub fn mask_pos_to_local(&self, position: Vector2<i32>) -> Vector2<f32>

Convert mask pixel position into local 2D position.

pub fn chunk_containing_height_pos( &self, position: Vector2<i32>, ) -> Vector2<i32>

Determines the chunk containing the given height pixel coordinate. Be aware that the edges of chunks overlap by two pixels because the vertices along each edge of a chunk have the same height as the corresponding vertices of the next chunk in that direction. Due to this, if position.x is on the x-axis origin of the chunk returned by this method, then the position is also contained in the chunk at x - 1. Similarly, if position.y is on the y-axis origin, then the position is also in the y - 1 chunk. If position is on the origin in both the x and y axes, then the position is actually contained in 4 chunks.

pub fn chunk_contains_height_pos( &self, chunk_grid_position: Vector2<i32>, pixel_position: Vector2<i32>, ) -> bool

Given the grid position of some chunk and a height pixel position, return true if the chunk at that position would include data for the height at that position.

pub fn chunks_containing_height_pos_iter( &self, pixel_position: Vector2<i32>, ) -> impl Iterator<Item = &Chunk>

Iterate through all the chunks that contain the given height pixel position.

pub fn chunk_height_pos_origin( &self, chunk_grid_position: Vector2<i32>, ) -> Vector2<i32>

Determines the position of the (0,0) coordinate of the given chunk as measured in height pixel coordinates.

pub fn chunk_containing_mask_pos(&self, position: Vector2<i32>) -> Vector2<i32>

Determines the chunk containing the given mask pixel coordinate. This method makes no guarantee that there is actually a chunk at the returned coordinates. It returns the grid_position that the chunk would have if it existed.

pub fn chunk_containing_hole_pos(&self, position: Vector2<i32>) -> Vector2<i32>

Determines the chunk containing the given hole pixel coordinate. This method makes no guarantee that there is actually a chunk at the returned coordinates. It returns the grid_position that the chunk would have if it existed.

pub fn chunk_mask_pos_origin( &self, chunk_grid_position: Vector2<i32>, ) -> Vector2<i32>

Determines the position of the (0,0) coordinate of the given chunk as measured in mask pixel coordinates.

pub fn chunk_hole_pos_origin( &self, chunk_grid_position: Vector2<i32>, ) -> Vector2<i32>

Determines the position of the (0,0) coordinate of the given chunk as measured in hole pixel coordinates.

pub fn update_mask_pixel<F>( &mut self, position: Vector2<i32>, layer: usize, func: F, )

where F: FnOnce(u8) -> u8,

Applies the given function to the value at the given position in mask pixel coordinates. This method calls the given function with the mask value of that pixel. If no chunk contains the given position, then the function is not called.

pub fn for_each_height_map_pixel<F>(&mut self, func: F)

where F: FnMut(&mut f32, Vector2<f32>),

Applies the given function to each pixel of the height map.

pub fn raycast<const DIM: usize>( &self, ray: Ray, results: &mut ArrayVec<TerrainRayCastResult, DIM>, sort_results: bool, ) -> bool

Casts a ray and looks for intersections with the terrain. This method collects all results in given array with optional sorting by the time-of-impact.

Performance

This method isn’t well optimized, it could be optimized 2-5x times. This is a TODO for now.

pub fn set_layers(&mut self, layers: Vec<Layer>) -> Vec<Layer>

Sets new terrain layers.

pub fn layers(&self) -> &[Layer]

Returns a reference to a slice with layers of the terrain.

pub fn layers_mut(&mut self) -> &mut [Layer]

Returns a mutable reference to a slice with layers of the terrain.

pub fn add_layer(&mut self, layer: Layer, masks: Vec<TextureResource>)

Adds new layer to the chunk. It is possible to have different layer count per chunk in the same terrain, however it seems to not have practical usage, so try to keep equal layer count per each chunk in your terrains.

pub fn remove_layer( &mut self, layer_index: usize, ) -> (Layer, Vec<TextureResource>)

Removes a layer at the given index together with its respective blending masks from each chunk.

pub fn pop_layer(&mut self) -> Option<(Layer, Vec<TextureResource>)>

Removes last terrain layer together with its respective blending masks from each chunk.

pub fn insert_layer( &mut self, layer: Layer, masks: Vec<TextureResource>, index: usize, )

Inserts the layer at the given index together with its blending masks for each chunk.

pub fn geometry(&self) -> &TerrainGeometry

Returns data for rendering (vertex and index buffers).

pub fn texture_data(&self, target: BrushTarget) -> TerrainTextureData

Create an object that specifies which TextureResources are being used by this terrain to hold the data for the given BrushTarget. Panics if target is HoleMask and a chunk is missing its hole mask texture.

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 ENABLED: &'static str = "enabled"

pub const RENDER_MASK: &'static str = "render_mask"

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

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

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 GLOBAL_VISIBILITY: &'static str = "global_visibility"

pub const GLOBAL_TRANSFORM: &'static str = "global_transform"

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

pub const INSTANCE_ID: &'static str = "instance_id"

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

pub const GLOBAL_ENABLED: &'static str = "global_enabled"

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

Returns handle of the node. A node has valid handle only after it was inserted in a graph!

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

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. To set global position and rotation, use super::Graph::set_global_position and super::Graph::set_global_rotation methods respectively.

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

Sets new local transform of a node. If you need to modify existing local transformation, use Self::local_transform_mut.

pub fn set_position(&mut self, position: Vector3<f32>)

Sets the new position of the node in the parent’s node coordinate system.

pub fn set_position_xyz(&mut self, x: f32, y: f32, z: f32)

Sets the new position of the node in the parent’s node coordinate system.

pub fn set_rotation(&mut self, rotation: UnitQuaternion<f32>)

Sets the new rotation of the node in the parent’s node coordinate system.

pub fn set_rotation_angles(&mut self, roll: f32, pitch: f32, yaw: f32)

Sets the new rotation of the node in the parent’s node coordinate system.

pub fn set_rotation_x(&mut self, angle: f32)

Sets the new rotation of the node around X axis in the parent’s node coordinate system.

pub fn set_rotation_y(&mut self, angle: f32)

Sets the new rotation of the node around Y axis in the parent’s node coordinate system.

pub fn set_rotation_z(&mut self, angle: f32)

Sets the new rotation of the node around Z axis in the parent’s node coordinate system.

pub fn set_scale(&mut self, scale: Vector3<f32>)

Sets the new scale of the node in the parent’s node coordinate system.

pub fn set_scale_xyz(&mut self, x: f32, y: f32, z: f32)

Sets the new scale of the node in the parent’s node coordinate system.

pub fn set_uniform_scale(&mut self, scale: f32)

Sets the new scale of the node for all axes at once in the parent’s node coordinate system.

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 Self

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) -> Matrix4<f32>

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 global_transform_without_scaling(&self) -> Matrix4<f32>

Calculates global transform of the node, but discards scaling part of it.

pub fn inv_bind_pose_transform(&self) -> Matrix4<f32>

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<ModelResource>

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 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 has_inheritance_parent(&self) -> bool

Returns true if the node has a parent object in a resource from which it may restore values of its inheritable properties.

pub fn global_position(&self) -> Vector3<f32>

Returns position of the node in absolute coordinates.

pub fn look_vector(&self) -> Vector3<f32>

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

pub fn side_vector(&self) -> Vector3<f32>

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

pub fn up_vector(&self) -> Vector3<f32>

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

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) -> 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<ModelResource>

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 Terrain

fn clone(&self) -> Terrain

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ComponentProvider for Terrain

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 Terrain

fn constructor() -> NodeConstructor

impl Debug for Terrain

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

Formats the value using the given formatter.

impl Default for Terrain

fn default() -> Self

Returns the “default value” for a type.

impl Deref for Terrain

type Target = Base

The resulting type after dereferencing.

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

Dereferences the value.

impl DerefMut for Terrain

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

Mutably dereferences the value.

impl NodeTrait for Terrain

fn local_bounding_box(&self) -> AxisAlignedBoundingBox

Returns pre-cached bounding axis-aligned bounding box of the terrain. Keep in mind that if you’re modified terrain, bounding box will be recalculated and it is not fast.

fn world_bounding_box(&self) -> AxisAlignedBoundingBox

Returns current world-space bounding box.

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 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 debug_draw(&self, ctx: &mut SceneDrawingContext)

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

fn validate(&self, _: &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.

fn summary(&self) -> String

Brief debugging information about this node.

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 on_global_transform_changed( &self, new_global_transform: &Matrix4<f32>, context: &mut SyncContext<'_, '_>, )

Called when node’s global transform changes.

fn on_local_transform_changed(&self, context: &mut SyncContext<'_, '_>)

Called when node’s local transform changed.

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 should_be_rendered( &self, frustum: Option<&Frustum>, render_mask: BitMask, ) -> bool

Checks if the node should be rendered or not. A node should be rendered if it is enabled, visible and (optionally) is inside some viewing frustum.

impl Reflect for Terrain

where Self: 'static,

fn source_path() -> &'static str

fn try_clone_box(&self) -> Option<Box<dyn Reflect>>

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

fn derived_types() -> &'static [TypeId]

fn query_derived_types(&self) -> &'static [TypeId]

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_ref(&self, func: &mut dyn FnMut(&[FieldRef<'_, '_>]))

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

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

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

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

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

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 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 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)>), )

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

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

impl TypeUuidProvider for Terrain

fn type_uuid() -> Uuid

Return type UUID.

impl Visit for Terrain

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.