Terrain3DInstancer

Inherits: Object

Description

This class places mesh instances defined in the Terrain3D asset dock into MultiMeshInstance3Ds on the ground.

Data is currently stored in Terrain3DRegion.instances and loaded into MultiMeshInstances, which are attached to the scene tree and managed by this class.

The methods available for adding instances are:

add_transforms() - Accepts your list of transforms and parses them by region and cell location and stores in our data storage. Recommended for general API instancing.
add_multimesh() - Pulls the transforms out of your MultiMesh and calls add_transforms.
add_instances() - A feature rich function designed for hand editing via Terrain3DEditor.
Creating your own instance data and inserting it directly into Terrain3DRegion.instances. It’s not difficult to do this in GDScript, but a thorough understanding of the C++ code in this class is recommended.

The methods available for removing instances are:

remove_instances() - Like add_instances, this is can be used procedurally but is designed for hand editing.
clear_by_mesh(), clear_by_location() - To erase large sections of instances
Editing Terrain3DRegion.instances directly.

After modifying region data, run update_mmis() to rebuild the MultiMeshInstance3Ds.

Read More:

Tutorial: Foliage Instancing
Godot Reference: MultiMesh

Methods

void	add_instances(global_position: `Vector3`, params: `Dictionary`)
void	add_multimesh(mesh_id: `int`, multimesh: `MultiMesh`, transform: `Transform3D` = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0), update: `bool` = true)
void	add_transforms(mesh_id: `int`, transforms: Array[`Transform3D`], colors: `PackedColorArray` = PackedColorArray(), update: `bool` = true)
void	append_location(region_location: `Vector2i`, mesh_id: `int`, transforms: Array[`Transform3D`], colors: `PackedColorArray`, update: `bool` = true)
void	append_region(region: Terrain3DRegion, mesh_id: `int`, transforms: Array[`Transform3D`], colors: `PackedColorArray`, update: `bool` = true)
void	clear_by_location(region_location: `Vector2i`, mesh_id: `int`)
void	clear_by_mesh(mesh_id: `int`)
void	clear_by_region(region: Terrain3DRegion, mesh_id: `int`)
void	dump_data()
void	dump_mmis()
void	remove_instances(global_position: `Vector3`, params: `Dictionary`)
void	swap_ids(src_id: `int`, dest_id: `int`)
void	update_mmis(rebuild: `bool` = false)
void	update_transforms(aabb: `AABB`)

Method Descriptions

void add_instances(global_position: Vector3, params: Dictionary) 🔗

Used by Terrain3DEditor to place instances given many brush parameters. In addition to the brush position, it also uses the following parameters: asset_id, size, strength, fixed_scale, random_scale, fixed_spin, random_spin, fixed_tilt, random_tilt, align_to_normal, height_offset, random_height, vertex_color, random_hue, random_darken. All of these settings are set in the editor through tool_settings.gd.

void add_multimesh(mesh_id: int, multimesh: MultiMesh, transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0), update: bool = true) 🔗

Allows procedural placement of meshes, or importing from another MultiMeshInstancer placement tool. The specified mesh_id should already be setup as a Terrain3DMeshAsset in the asset dock. This function extracts the instance transforms and colors from a multimesh and passes it to add_transforms().

Update will regenerate the MultiMeshInstances. Disable for bulk adding, then call at the end.

void add_transforms(mesh_id: int, transforms: Array[Transform3D], colors: PackedColorArray = PackedColorArray(), update: bool = true) 🔗

Allows procedural placement of meshes. The mesh_id should already be setup as a Terrain3DMeshAsset in the asset dock. You provide the array of Transform3Ds and optional Colors, which will be parsed into our data storage.

This function adds the Terrain3DMeshAsset.height_offset to the transform along its local Y axis.

Update will regenerate the MultiMeshInstances. Disable for bulk adding, then call at the end.

void append_location(region_location: Vector2i, mesh_id: int, transforms: Array[Transform3D], colors: PackedColorArray, update: bool = true) 🔗

Appends new transforms to the existing data within a region location. The mesh_id should already be setup as a Terrain3DMeshAsset in the asset dock.

Update will regenerate the MultiMeshInstances. Disable for bulk adding, then call at the end.

void append_region(region: Terrain3DRegion, mesh_id: int, transforms: Array[Transform3D], colors: PackedColorArray, update: bool = true) 🔗

Appends new transforms to the existing data within a region location. The mesh_id should already be setup as a Terrain3DMeshAsset in the asset dock.

Update will regenerate the MultiMeshInstances. Disable for bulk adding, then call at the end.

void clear_by_location(region_location: Vector2i, mesh_id: int) 🔗

Removes all instancer data and MultiMeshInstance nodes attached to the tree for the specified region location and mesh id.

void clear_by_mesh(mesh_id: int) 🔗

Removes all instancer data and MultiMeshInstance nodes attached to the tree for all regions for the specified mesh id.

void clear_by_region(region: Terrain3DRegion, mesh_id: int) 🔗

Removes all instancer data and MultiMeshInstance nodes attached to the tree for the specified region and mesh id.

void dump_data() 🔗

Dumps the instancer data arrays and dictionaries for all regions.

void dump_mmis() 🔗

Dumps the MultiMeshInstance3Ds attached to the tree and information about the nodes for all regions.

void remove_instances(global_position: Vector3, params: Dictionary) 🔗

Uses parameters asset_id, size, strength, fixed_scale, random_scale, slope (Vector2), to randomly remove instances within the indicated brush position and size.

void swap_ids(src_id: int, dest_id: int) 🔗

Swaps the ID of two meshes without changing the mesh instances on the ground.

void update_mmis(rebuild: bool = false) 🔗

Rebuilds the MMIs in cells that have been modified or are missing. See Terrain3DRegion.instances.

rebuild - Destroys all MMIs first then rebuilds all of them from scratch.

void update_transforms(aabb: AABB) 🔗

Reviews all existing instance transforms within an AABB and adjusts their heights to match the terrain.