Terrain3DRegion

Inherits: Resource

Description

This resource stores all map data for Terrain3D. See Controlmap Format and Data Format Changelog.

Properties

Image

color_map

Image

control_map

bool

deleted

bool

edited

Image

height_map

Vector2

height_range

Vector2(0, 0)

Dictionary

instances

{}

Vector2i

location

bool

modified

int

region_size

0

float

version

0.8

float

vertex_spacing

1.0

Methods

void

calc_height_range()

Terrain3DRegion

duplicate(deep: bool = false)

Dictionary

get_data() const

Image

get_map(map_type: MapType) const

Array[Image]

get_maps() const

Image

sanitize_map(map_type: MapType, map: Image) const

void

sanitize_maps()

Error

save(path: String = “”, 16-bit: bool = false)

void

set_data(data: Dictionary)

void

set_map(map_type: MapType, map: Image)

void

set_maps(maps: Array[Image])

void

update_height(height: float)

void

update_heights(low_high: Vector2)

bool

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

Image color_map 🔗

  • void set_color_map(value: Image)

  • Image get_color_map()

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.

Image control_map 🔗

  • void set_control_map(value: Image)

  • Image get_control_map()

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.

bool deleted 🔗

  • void set_deleted(value: bool)

  • bool is_deleted()

This region is marked for deletion. It won’t be rendered once Terrain3DData.update_maps() rebuilds the map index. The file will be deleted from disk on save().

bool edited 🔗

  • void set_edited(value: bool)

  • bool is_edited()

This region is marked for updating by Terrain3DData.update_maps() and for undo/redo tracking when set between Terrain3DEditor.start_operation() and Terrain3DEditor.stop_operation(). The latter method clears the edited flag. This flag serves a different purpose than modified.

Image height_map 🔗

  • void set_height_map(value: Image)

  • Image get_height_map()

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 Terrain3D.save_16_bit.

Vector2 height_range = Vector2(0, 0) 🔗

  • void set_height_range(value: Vector2)

  • Vector2 get_height_range()

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 Terrain3DInstancer.update_mmis() to rebuild the MMIs.

Vector2i location 🔗

  • void set_location(value: Vector2i)

  • Vector2i get_location()

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.

bool modified 🔗

  • void set_modified(value: bool)

  • bool is_modified()

This region has been modified and will be saved to disk upon save(). This serves a different purpose than the temporary edited setting.

int region_size = 0 🔗

  • void set_region_size(value: int)

  • int get_region_size()

The current region size for this region, calculated from the dimensions of the first loaded map. It should match Terrain3D.region_size.

float version = 0.8 🔗

  • void set_version(value: float)

  • float get_version()

The data file version. This is independent of the Terrain3D version, though they often align.

float vertex_spacing = 1.0 🔗

  • void set_vertex_spacing(value: float)

  • float get_vertex_spacing()

Stored instancer transforms are laterally scaled by this value. This value is manage by the instancer on loading or when Terrain3D.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.

Terrain3DRegion duplicate(deep: bool = false) 🔗

Returns a duplicate copy of this node, with references to the same image maps and multimeshes.

  • deep - Also make complete duplicates of the maps and multimeshes.

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 = “”, 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.