VoxelInstanceGenerator¶
Inherits: Resource
Decides where to spawn instances on top of a voxel surface.
Description:¶
Generates the necessary information to spawn instances on top of a voxel surface. This may be used by a VoxelInstancer.
Note: to generate voxels, see VoxelGenerator.
Properties:¶
Methods:¶
| Return | Signature |
|---|---|
| int | get_voxel_texture_filter_mask ( ) const |
| void | set_voxel_texture_filter_mask ( int mask ) |
Enumerations:¶
enum EmitMode:
- EMIT_FROM_VERTICES = 0 --- Use vertices of the mesh to spawn instances. This is the fasted option, but can produce noticeable patterns.
- EMIT_FROM_FACES_FAST = 1 --- Uses faces of the mesh to spawn instances. It is a balanced option with some shortcuts taken, without causing too noticeable patterns.
- EMIT_FROM_FACES = 2 --- Uses faces of the mesh to spawn instances. This is the slowest option, but should produce no noticeable patterns.
- EMIT_ONE_PER_TRIANGLE = 3 --- Uses faces of the mesh to spawn instances (where faces are triangles). Only one instance is spawned per triangle. By default, it spawns in the middle of triangles. Randomness can be added to this position with jitter.
- EMIT_MODE_COUNT = 4
enum Distribution:
- DISTRIBUTION_LINEAR = 0 --- Uniform distribution.
- DISTRIBUTION_QUADRATIC = 1 --- Distribution with more small items, and fewer big ones.
- DISTRIBUTION_CUBIC = 2 --- Distribution with even more small items, and even fewer big ones.
- DISTRIBUTION_QUINTIC = 3
- DISTRIBUTION_COUNT = 4
enum Dimension:
- DIMENSION_2D = 0
- DIMENSION_3D = 1
- DIMENSION_COUNT = 2
Property Descriptions¶
float density = 0.1¶
Controls how many instances are generated. Might give different results depending on the type of emission chosen.
EmitMode emit_mode = EMIT_FROM_VERTICES (0)¶
In which way instances are primarily emitted.
float jitter = 1.0¶
Controls randomness of spawning position when emit_mode is set to EMIT_ONE_PER_TRIANGLE.
float max_height = 3.4028235e+38¶
Instances will not be created above this height.
This also depends on the chosen VoxelInstancer.up_mode.
float max_height_falloff = 0.0¶
Distance over which density will fade, when below max_height.
float max_scale = 1.0¶
Minimum scale instances will be randomized with.
float max_slope_degrees = 180.0¶
Instances will not spawn if the ground has a slope higher than this angle.
This also depends on the chosen VoxelInstancer.up_mode.
float max_slope_falloff_degrees = 0.0¶
Angular distance over which density will fade, when below max_slope_degrees.
float min_height = 1.1754944e-38¶
Instances will not be created below this height. This also depends on the chosen VoxelInstancer.up_mode.
float min_height_falloff = 0.0¶
Distance over which density will fade, when above min_height.
float min_scale = 1.0¶
Maximum scale instances will be randomized with.
float min_slope_degrees = 0.0¶
Instances will not spawn if the ground has a slope lower than this angle.
This also depends on the chosen VoxelInstancer.up_mode.
float min_slope_falloff_degrees = 0.0¶
Angular distance over which density will fade, when above min_slope_degrees.
Noise noise¶
Noise used to filter out spawned instances, so that they may spawn in patterns described by the noise.
Dimension noise_dimension = DIMENSION_3D (1)¶
Which dimension should be used when evaluating noise and noise_graph.
float noise_falloff = 0.0¶
Noise range over which density will fade. For example if falloff is 0.3, then density will fade when noise values are between 0 and 0.3.
VoxelGraphFunction noise_graph¶
Graph function used to filter out spawned instances, similar to noise, but allows more custom noise computations.
The graph must have 2 inputs (X and Z) if noise_dimension is 2D, and 3 inputs (X, Y and Z) if 3D. There must be one SDF output.
float noise_on_scale = 0.0¶
How much noise also affects the scale of instances.
float noise_threshold = 0.0¶
Expands or shrink noise filtering. Higher values expand the areas where instances will spawn, lower values shrinks them.
float offset_along_normal = 0.0¶
Offsets spawned instances along the normal of the ground.
The normal depends on VoxelInstancer.up_mode and is also affected by vertical_alignment.
bool random_rotation = true¶
When enbabled, instances will be given a random rotation. If not, they will use a consistent rotation depending on the ground slope.
bool random_vertical_flip = false¶
When enabled, instances will randomly be flipped upside down. This can be useful with small rocks to create illusion of more variety.
Distribution scale_distribution = DISTRIBUTION_QUADRATIC (1)¶
Sets how random scales are distributed.
bool snap_to_generator_sdf_enabled = false¶
Enables snapping to generator SDF. The generator's SDF values will be queried to move instances along their normal to be closerr to ground. Can help reduce the occurrence of "floating" or "buried" instances when moving close to them. This requires the terrain's generator to support series generation. Side-effects: instances might become floating or buried when seen from far away; spawning might become less even.
int snap_to_generator_sdf_sample_count = 2¶
How many samples per instance will be taken from the generator in order to approach the snapping position. More samples increases precision, but is more expensive.
float snap_to_generator_sdf_search_distance = 1.0¶
Distance up and down across which snapping will search for ground location.
float triangle_area_threshold = 0.0¶
If set greater than zero, triangles of the ground with an area lower than this threshold will be ignored.
Some meshing algorithms can often produce thin or small triangles that can affect distribution quality of spawned instances. If this happens, use this property to filter them out.
Note: this property is relative to LOD0. The generator will scale it when spawning instances on meshes of different LOD index.
float vertical_alignment = 1.0¶
Sets how much instances will align with the ground.
If 0, they will completely align with the ground.
If 1, they will completely align with whichever direction is considered "up".
This depends on VoxelInstancer.up_mode.
PackedInt32Array voxel_texture_filter_array = PackedInt32Array(0)¶
Specifies which voxel texture indices on top of which instances may spawn.
This only works when voxel_texture_filter_enabled is enabled, and VoxelMesherTransvoxel is used with VoxelMesherTransvoxel.texturing_mode set to VoxelMesherTransvoxel.TEXTURES_MIXEL4_S4 or VoxelMesherTransvoxel.TEXTURES_SINGLE_S4. Indices are currently limited between 0 and 31 included.
bool voxel_texture_filter_enabled = false¶
When true, enables filtering of instances based on voxel texture indices. See voxel_texture_filter_array.
float voxel_texture_filter_threshold = 0.5¶
When voxel_texture_filter_enabled is active, controls how much of filtered texture has to be present for instances to spawn. The value must be betweem 0 and 1.
Method Descriptions¶
int get_voxel_texture_filter_mask( )¶
(This method has no documentation)
void set_voxel_texture_filter_mask( int mask )¶
(This method has no documentation)
Generated on Jan 26, 2026