Attention: Here be dragons (unstable version)

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Redot.

Checking the stable version of the documentation...

WorldScape3DInstancer

Inherits: Object

Description

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

Data is currently stored in WorldScape3DRegion.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.
Creating your own instance data and inserting it directly into WorldScape3DRegion.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 WorldScape3DRegion.instances directly.

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

Read More: 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: WorldScape3DRegion, 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: WorldScape3DRegion, 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 during terrain editing 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 WorldScape3DMeshAsset 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 WorldScape3DMeshAsset 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 WorldScape3DMeshAsset.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 WorldScape3DMeshAsset in the asset dock.

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

void append_region(region: WorldScape3DRegion, 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 WorldScape3DMeshAsset 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: WorldScape3DRegion, 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 WorldScape3DRegion.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.