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...
WorldScape3DRegion
Inherits: Resource < RefCounted < Object
Description
This resource stores all map data for WorldScape3D.
Properties
|
||
|
||
|
||
|
||
|
Methods
void |
|
get_data() const |
|
get_maps() const |
|
sanitize_map(map_type: MapType, map: Image) const |
|
void |
|
void |
set_data(data: Dictionary) |
void |
|
void |
|
void |
update_height(height: float) |
void |
update_heights(low_high: Vector2) |
validate_map_size(map: Image) const |
Enumerations
enum MapType: 🔗
MapType TYPE_HEIGHT = 0
Height map - real values, eg. 10m, 44.5m.
MapType TYPE_CONTROL = 1
Control map - defines where textures and holes are placed.
MapType TYPE_COLOR = 2
Color map - paints color on the terrain
MapType TYPE_MAX = 3
The number of elements in this enum. Often used to specify all map types for functions that request one.
Property Descriptions
This map is used to paint color that blends in to the terrain textures.
Image format: FORMAT_RGBA8, 32-bits per pixel as four 8-bit components.
RGB is used for color, which is multiplied by albedo in the shader. Multiply is a blend mode that only darkens.
A is used for a roughness modifier. A value of 0.5 means no change to the existing texture roughness. Higher than this value increases roughness, lower decreases it.
This map tells the shader which textures to use where, how to blend, where to place holes, etc.
Image format: FORMAT_RF, 32-bit per pixel as full-precision floating-point.
However, we interpret these images as format: RenderingDevice.DATA_FORMAT_R32_UINT aka OpenGL RG32UI 32-bit per pixel as unsigned integer. See Control map format.
This region is marked for deletion. It won't be rendered once WorldScape3DData.update_maps() rebuilds the map index. The file will be deleted from disk on save().
This region is marked for updating by WorldScape3DData.update_maps() and for undo/redo tracking while the terrain is being edited. This flag serves a different purpose than modified.
This map contains the real value heights for the terrain.
Image format: FORMAT_RF, 32-bit per pixel as full-precision floating-point.
Heights sent to the vertex shader on the GPU which modifies the mesh in real-time.
Editing is always done in 32-bit. We do provide an option to save as 16-bit, see WorldScape3D.save_16_bit.
Vector2 height_range = Vector2(0, 0) 🔗
The current minimum and maximum height range for this region, used to calculate the AABB of the terrain. Update it with update_height(), and recalculate it with calc_height_range().
Dictionary instances = {} 🔗
void set_instances(value: Dictionary)
Dictionary get_instances()
A Dictionary that stores the instancer transforms for this region.
The format is instances{mesh_id:int} -> cells{grid_location:Vector2i} -> ( Array:Transform3D, PackedColorArray, modified:bool ). That is:
A Dictionary keyed by mesh_id that returns:
A Dictionary keyed by the grid location of the 32 x 32m cell that returns:
A 3-item Array that contains:
0: An Array of Transform3Ds
1: A PackedColorArray with instance colors, same index as above
2: A bool that tracks if this cell has been modified
After changing this data, call WorldScape3DInstancer.update_mmis() to rebuild the MMIs.
The location in region grid space (world space / region_size) coordinates. e.g. (-1, 1) equates to (-1024, 1024) in world space given a region_size of 1024.
This region has been modified and will be saved to disk upon save(). This serves a different purpose than the temporary edited setting.
The current region size for this region, calculated from the dimensions of the first loaded map. It should match WorldScape3D.region_size.
The data file version. This is independent of the WorldScape3D version, though they often align.
Stored instancer transforms are laterally scaled by this value. This value is manage by the instancer on loading or when WorldScape3D.vertex_spacing is set, and shouldn't be manually adjusted.
Method Descriptions
void calc_height_range() 🔗
Recalculates the height range for this region by looking at every pixel in the heightmap.
Dictionary get_data() const 🔗
Returns all data in this region in a dictionary.
Image get_map(map_type: MapType) const 🔗
Returns the specified image map.
Array[Image] get_maps() const 🔗
Returns an ArrayImage with height, control, and color maps.
Image sanitize_map(map_type: MapType, map: Image) const 🔗
Validates and adjusts the map size and format if possible, or creates a usable blank image in the right size and format.
void sanitize_maps() 🔗
Sanitizes all map types. See sanitize_map().
Error save(path: String = "", save_16_bit: bool = false) 🔗
Saves this region to the current file name.
path - specifies a directory and file name to use from now on.
16-bit - save this region with 16-bit height map instead of 32-bit. This process is lossy. Does not change the bit depth in memory.
void set_data(data: Dictionary) 🔗
Overwrites all local variables with values in the dictionary.
void set_map(map_type: MapType, map: Image) 🔗
Assigns the provided map to the desired map type.
void set_maps(maps: Array[Image]) 🔗
Expects an array with three images in it, and assigns them to the height, control, and color maps.
void update_height(height: float) 🔗
When sculpting, this is called to provide the current height. It may expand the vertical bounds, which is used to calculate the terrain AABB.
void update_heights(low_high: Vector2) 🔗
When sculpting the terrain, this is called to provide both a low and high height. It may expand the vertical bounds, which is used to calculate the terrain AABB.
bool validate_map_size(map: Image) const 🔗
This validates the map size according to previously loaded maps.