Terrain3DData
Inherits: Object
Description
Terrain3D divides all data into regions which fit on a grid in the world. These coordinates are called region locations. The map data are stored in instances of Terrain3DRegion, which are saved to individual files. This class manages region loading, unloading, data retreival and manipulation.
Properties
Array[ |
|
|
Array[ |
|
|
Array[ |
|
|
Array[ |
|
Methods
Error |
add_region(region: Terrain3DRegion, update: |
add_region_blank(region_location: |
|
add_region_blankp(global_position: |
|
void |
calc_height_range(recursive: |
void |
change_region_size(region_size: |
void |
do_for_regions(area: |
Error |
export_image(file_name: |
|
get_color(global_position: |
|
get_color_maps_rid() const |
|
get_control(global_position: |
|
get_control_angle(global_position: |
|
get_control_auto(global_position: |
|
get_control_base_id(global_position: |
|
get_control_blend(global_position: |
|
get_control_hole(global_position: |
|
get_control_maps_rid() const |
|
get_control_navigation(global_position: |
|
get_control_overlay_id(global_position: |
|
get_control_scale(global_position: |
|
get_height(global_position: |
|
get_height_maps_rid() const |
|
get_height_range() const |
Array[ |
|
|
get_mesh_vertex(lod: |
|
get_normal(global_position: |
|
get_pixel(map_type: MapType, global_position: |
get_region(region_location: |
|
|
get_region_count() const |
|
get_region_id(region_location: |
|
get_region_idp(global_position: |
|
get_region_location(global_position: |
|
get_region_map() const |
|
get_region_map_index(region_location: |
get_regionp(global_position: |
|
Array[Terrain3DRegion] |
get_regions_active(copy: |
|
get_regions_all() const |
|
get_roughness(global_position: |
|
get_texture_id(global_position: |
|
has_region(region_location: |
|
has_regionp(global_position: |
void |
import_images(images: Array[ |
|
is_in_slope(global_position: |
|
is_region_deleted(region_location: |
|
is_region_modified(region_location: |
|
layered_to_image(map_type: MapType) const |
void |
load_directory(directory: |
void |
load_region(region_location: |
void |
remove_region(region: Terrain3DRegion, update: |
void |
remove_regionl(region_location: |
void |
remove_regionp(global_position: |
void |
save_directory(directory: |
void |
save_region(region_location: |
void |
set_color(global_position: |
void |
set_control(global_position: |
void |
set_control_angle(global_position: |
void |
set_control_auto(global_position: |
void |
set_control_base_id(global_position: |
void |
set_control_blend(global_position: |
void |
set_control_hole(global_position: |
void |
set_control_navigation(global_position: |
void |
set_control_overlay_id(global_position: |
void |
set_control_scale(global_position: |
void |
set_height(global_position: |
void |
set_pixel(map_type: MapType, global_position: |
void |
set_region_deleted(region_location: |
void |
set_region_modified(region_location: |
void |
set_roughness(global_position: |
void |
update_maps(map_type: MapType = 3, all_maps : |
Signals
color_maps_changed() 🔗
Emitted when the color maps array is regenerated.
control_maps_changed() 🔗
Emitted when the control maps array is regenerated.
height_maps_changed() 🔗
Emitted when the height maps array is regenerated.
maps_changed() 🔗
Emitted when the region map or any map array has been regenerated.
maps_edited(edited_area: AABB) 🔗
This signal is emitted whenever the editor (Terrain3DEditor) is used to:
add or remove a region
alter a region map with a brush tool
undo or redo any of the above operations
The parameter contains the axis-aligned bounding box of the area edited.
region_map_changed() 🔗
Emitted when the region map is regenerated.
Enumerations
enum HeightFilter: 🔗
HeightFilter HEIGHT_FILTER_NEAREST = 0
Samples the height map at the exact coordinates given.
HeightFilter HEIGHT_FILTER_MINIMUM = 1
Samples (1 << lod) * 2 heights around the given coordinates and returns the lowest.
Constants
REGION_MAP_SIZE = 32 🔗
Hard coded number of regions on a side. The total number of regions is this squared.
Property Descriptions
Array[Image] color_maps = [] 🔗
Array[
Image] get_color_maps()
An ArrayImage containing references to all of the color maps in all regions. See Terrain3DRegion.color_map.
Array[Image] control_maps = [] 🔗
Array[
Image] get_control_maps()
An ArrayImage containing references to all of the control maps in all regions. See Terrain3DRegion.control_map.
Array[Image] height_maps = [] 🔗
Array[
Image] get_height_maps()
An ArrayImage containing references to all of the height maps in all regions. See Terrain3DRegion.height_map.
Array[Vector2i] region_locations = [] 🔗
void set_region_locations(value: Array[
Vector2i])Array[
Vector2i] get_region_locations()
The array of all active region locations; those not marked for deletion.
Method Descriptions
Error add_region(region: Terrain3DRegion, update: bool = true) 🔗
Adds a region for sculpting and painting.
The region should already be configured with the desired location and maps before sending to this function.
Upon saving, this region will be written to a data file stored in Terrain3D.data_directory.
update - regenerates the texture arrays if true. Set to false if bulk adding many regions, then true on the last one or use update_maps().
Terrain3DRegion add_region_blank(region_location: Vector2i, update: bool = true) 🔗
Creates and adds a blank region at the specified location. See add_region().
Terrain3DRegion add_region_blankp(global_position: Vector3, update: bool = true) 🔗
Creates and adds a blank region at a region location encompassing the specified global position. See add_region().
void calc_height_range(recursive: bool = false) 🔗
Recalculates the master height range for the whole terrain by summing the height ranges of all active regions.
Recursive mode does the same, but has each region recalculate heights from each heightmap pixel. See Terrain3DRegion.calc_height_range().
void change_region_size(region_size: int) 🔗
Reslices terrain data to fit the new region size. This is a destructive process for which there is no undo. However Godot does make an undo entry, which will reslice in reverse. Files on disk are not added or removed until the scene is saved.
void do_for_regions(area: Rect2i, callback: Callable) 🔗
Calls the callback function for every region within the given area. If using vertex_spacing, area values should be descaled.
The callable receives: source Terrain3DRegion, source Rect2i, dest Rect2i, (bindings)
You may wish to append .bind() to the callback to pass along variables. For instance internally this function is called when changing region size. We bind the destination Terrain3DRegion, then use do_for_regions to copy segments of source regions to segments of destination regions. See the code for change_region_size() for more.
Error export_image(file_name: String, map_type: MapType) const 🔗
Exports the specified map type as one of r16/raw, exr, jpg, png, webp, res, tres.
R16 or exr are recommended for roundtrip external editing.
R16 can be edited by Krita, however you must know the dimensions and min/max before reimporting. This information is printed to the console.
Res/tres stores in Godot’s native data format.
Color get_color(global_position: Vector3) const 🔗
Returns the associated pixel on the color map at the requested position.
Returns Color(NAN, NAN, NAN, NAN) if the position is outside of defined regions.
RID get_color_maps_rid() const 🔗
Returns the resource ID of the generated height map Texture Array sent to the shader. You can use this RID with the RenderingServer to set it as a shader parameter for a sampler2DArray uniform in your own shader. See Tips for an example.
int get_control(global_position: Vector3) const 🔗
Returns the associated pixel on the control map at the requested position.
Returns 4,294,967,295 aka UINT32_MAX if the position is outside of defined regions.
float get_control_angle(global_position: Vector3) const 🔗
Returns the angle, aka uv rotation, on the control map at the requested position. Values are fixed to 22.5 degree intervals, for a maximum of 16 angles. 360 / 16 = 22.5.
Returns NAN if the position is outside of defined regions.
bool get_control_auto(global_position: Vector3) const 🔗
Returns whether the autoshader is enabled on the control map at the requested position.
Returns false if the position is outside of defined regions.
int get_control_base_id(global_position: Vector3) const 🔗
Returns the base texture ID on the control map at the requested position. Values are 0 - 31, which matches the ID of the texture asset in the asset dock.
Returns 4,294,967,295 aka UINT32_MAX if the position is outside of defined regions.
float get_control_blend(global_position: Vector3) const 🔗
Returns the blend value between the base texture ID and the overlay texture ID. The value is clamped between 0.0 - 1.0 where 0.0 shows only the base texture, and 1.0 shows only the overlay texture.
Returns NAN if the position is outside of defined regions.
bool get_control_hole(global_position: Vector3) const 🔗
Returns whether there is a hole on the control map at the requested position.
Returns false if the position is outside of defined regions.
RID get_control_maps_rid() const 🔗
Returns the resource ID of the generated control map Texture Array sent to the shader. You can use this RID with the RenderingServer to set it as a shader parameter for a sampler2DArray uniform in your own shader. See Tips for an example.
Returns whether navigation is enabled on the control map at the requested position.
Returns false if the position is outside of defined regions.
int get_control_overlay_id(global_position: Vector3) const 🔗
Returns the overlay texture ID on the control map at the requested position. Values are 0 - 31, which matches the ID of the texture asset in the asset dock.
Returns 4,294,967,295 aka UINT32_MAX if the position is outside of defined regions.
float get_control_scale(global_position: Vector3) const 🔗
Returns the uv scale on the control map at the requested position. The value is rounded to the nearest 20% difference from 100%, ranging between -60% to +80%. Eg. +20% or -40%.
Returns NAN if the position is outside of defined regions.
float get_height(global_position: Vector3) const 🔗
Returns the height at the requested position. If the position is close to a vertex, the pixel height on the heightmap is returned. Otherwise the value is interpolated from the 4 vertices surrounding the position.
Returns NAN if the requested position is a hole or outside of defined regions.
RID get_height_maps_rid() const 🔗
Returns the resource ID of the generated height map texture array sent to the shader. You can use this RID with the RenderingServer to set it as a shader parameter for a sampler2DArray uniform in your own shader. See Tips for an example.
Vector2 get_height_range() const 🔗
Returns the highest and lowest heights for the sculpted terrain used to set the world AABB. See calc_height_range().
Any Terrain3DMaterial.world_background used that extends the mesh outside of this range will not change this variable. You need to set Terrain3D.cull_margin or the renderer will clip meshes.
Array[Image] get_maps(map_type: MapType) const 🔗
Returns an Array of Images from all regions of the specified map type.
Vector3 get_mesh_vertex(lod: int, filter: HeightFilter, global_position: Vector3) const 🔗
Returns the position of a terrain vertex at a certain LOD. If the position is outside of defined regions or there is a hole, it returns NAN in the vector’s Y coordinate.
lod - Determines how many heights around the given global position will be sampled. Range 0 - 8.
filter - Specifies how samples are filtered. See HeightFilter.
global_position - X and Z coordinates of the vertex. Heights will be sampled around these coordinates.
Vector3 get_normal(global_position: Vector3) const 🔗
Returns the terrain normal at the specified position. This function uses get_height().
Returns Vector3(NAN, NAN, NAN) if the requested position is a hole or outside of defined regions.
Color get_pixel(map_type: MapType, global_position: Vector3) const 🔗
Returns the pixel for the map type associated with the specified position.
Returns Color(NAN, NAN, NAN, NAN) if the position is outside of defined regions.
Terrain3DRegion get_region(region_location: Vector2i) const 🔗
Return the Terrain3DRegion at the specified location. This will return inactive regions marked for deletion. Check with Terrain3DRegion.deleted.
int get_region_count() const 🔗
Returns the number of active regions; those not marked for deletion.
int get_region_id(region_location: Vector2i) const 🔗
Returns -1 if no region or out of bounds at the given location, otherwise returns the current region id.
The region_id is the index into the TextureArrays sent to the shader, and can change at any time. Gamedevs should generally index regions by location. However, this function is useful to determine if the location is a valid region.
int get_region_idp(global_position: Vector3) const 🔗
Returns the region id at a global position. See get_region_id().
Vector2i get_region_location(global_position: Vector3) const 🔗
Returns the calculated region location for the given global position. This is just a calculation and does no bounds checking or verification that a region exists. See get_region_map_index() for bounds checking, or has_region() for checking existance.
PackedInt32Array get_region_map() const 🔗
Returns a fully populated 32 x 32 array. The array location contains the region id + 1, or 0, which means no region.
int get_region_map_index(region_location: Vector2i) static 🔗
Given a region location, returns the index into the region map array. See get_region_map().
You can use this function to quickly determine if a location is within the greater world bounds (-16,-16) to (15, 15). It returns -1 if not.
Terrain3DRegion get_regionp(global_position: Vector3) const 🔗
Returns the region at the specified global position. This will return inactive regions marked for deletion. Check with Terrain3DRegion.deleted.
Array[Terrain3DRegion] get_regions_active(copy: bool = false, deep: bool = false) const 🔗
Returns an array of active regions not marked for deletion. Each region knows its own location. See Terrain3DRegion.location.
copy - returns a shallow copy of the regions; region map references are copied.
deep - returns a deep copy of the regions; region maps are full duplicates.
Dictionary get_regions_all() const 🔗
Returns all regions in a dictionary indexed by region location. Some regions may be marked for deletion.
float get_roughness(global_position: Vector3) const 🔗
Returns the roughness modifier (wetness) on the color map alpha channel associated with the specified position.
Returns Color(NAN, NAN, NAN, NAN) if the position is outside of defined regions.
Vector3 get_texture_id(global_position: Vector3) const 🔗
Returns Vector3(base texture id, overlay id, blend value).
Returns Vector3(NAN, NAN, NAN) if the position is a hole or outside of defined regions.
This is often used for playing sounds on footsteps. It’s up to the gamedev to determine which is visually apparent based on shader settings.
Due to blending, it won’t be pixel perfect. Try having your player controller print this value while walking around to see how the blending values look. Perhaps you’ll find that the overlay texture is visible starting at a blend value of .3 to .5, otherwise the base is visible. You can also observe the control blend debug view with Terrain3DMaterial.show_control_blend.
Observing how this is done in The Witcher 3, there are only about 6 sounds used (snow, foliage, dirt, gravel, rock, wood), and except for wood, they are not pixel perfect. Wood is easy to do by detecting if the player is walking on wood meshes. The other 5 sounds are played when the player is in an area where the textures are blending. So it might play rock while over a dirt area. This shows pixel perfect accuracy is not important. It will still provide a seamless audio visual experience.
bool has_region(region_location: Vector2i) const 🔗
Returns true if the specified region location has an active region.
bool has_regionp(global_position: Vector3) const 🔗
Returns true if the specified global position has an active region.
void import_images(images: Array[Image], global_position: Vector3 = Vector3(0, 0, 0), offset: float = 0.0, scale: float = 1.0) 🔗
Imports an Image set (Height, Control, Color) into this resource. It does NOT normalize values to 0-1. You must do that using get_min_max() and adjusting scale and offset.
images - MapType.TYPE_MAX sized array of Images for Height, Control, Color. Images can be blank or null.
global_position - X,0,Z position on the region map. Valid range is Terrain3D.vertex_spacing * Terrain3D.region_size * (+/-16, +/-16).
offset - Add this factor to all height values, can be negative.
scale - Scale all height values by this factor (applied after offset).
bool is_in_slope(global_position: Vector3, slope_range: Vector2, invert: bool = false) const 🔗
Returns true if the slope of the terrain at the given position is within the slope range. If invert is true, it returns true if the position is outside the given range.
bool is_region_deleted(region_location: Vector2i) const 🔗
Returns true if the region at the location exists and is marked as deleted. Syntactic sugar for Terrain3DRegion.deleted.
bool is_region_modified(region_location: Vector2i) const 🔗
Returns true if the region at the location exists and is marked as modified. Syntactic sugar for Terrain3DRegion.modified.
Image layered_to_image(map_type: MapType) const 🔗
Returns an Image of the given map type that contains all regions in one large image. If the world has multiple islands, this function will return an image large enough to encompass all used regions, with black areas in between the islands.
void load_directory(directory: String) 🔗
Loads all of the Terrain3DRegion files found in the specified directory. Then it rebuilds all map arrays.
void load_region(region_location: Vector2i, directory: String, update: bool = true) 🔗
Loads the specified region location file.
update - rebuild maps if true.
void remove_region(region: Terrain3DRegion, update: bool = true) 🔗
Marks the specified region as deleted. This deactivates it so it won’t render it on screen once maps are updated, unless marked not deleted. The file will be deleted from disk upon saving.
void remove_regionl(region_location: Vector2i, update: bool = true) 🔗
Removes the region at the specified location. See remove_region().
void remove_regionp(global_position: Vector3, update: bool = true) 🔗
Removes the region at the specified global_position. See remove_region().
void save_directory(directory: String) 🔗
This saves all active regions into the specified directory.
void save_region(region_location: Vector2i, directory: String, 16_bit: bool = false) 🔗
Saves the specified active region to the directory. See Terrain3DRegion.save().
region_location - the region to save.
16_bit - converts the edited 32-bit heightmap to 16-bit. This is a lossy operation.
void set_color(global_position: Vector3, color: Color) 🔗
Sets the color on the color map pixel associated with the specified position. See set_pixel() for important information.
void set_control(global_position: Vector3, control: int) 🔗
Sets the value on the control map pixel associated with the specified position. See set_pixel() for important information.
void set_control_angle(global_position: Vector3, degrees: float) 🔗
Sets the angle, aka uv rotation, on the control map at the requested position. Values are rounded to the nearest 22.5 degree interval, for a maximum of 16 angles. 360 / 16 = 22.5.
See set_pixel() for important information.
void set_control_auto(global_position: Vector3, enable: bool) 🔗
Sets if the material should render the autoshader or manual texturing on the control map at the requested position.
See set_pixel() for important information.
void set_control_base_id(global_position: Vector3, texture_id: int) 🔗
Sets the base texture ID on the control map at the requested position. Values are clamped to 0 - 31, matching the ID of the texture asset in the asset dock.
See set_pixel() for important information.
void set_control_blend(global_position: Vector3, blend_value: float) 🔗
Sets the blend value between the base texture ID, and the overlay texture ID. The value is clamped between 0.0 - 1.0 where 0.0 shows only the base texture, and 1.0 shows only the overlay texture.
See set_pixel() for important information.
void set_control_hole(global_position: Vector3, enable: bool) 🔗
Sets if a hole should be rendered on the control map at the requested position. See set_pixel() for important information.
Sets if navigation generation is enabled on the control map at the requested position. See set_pixel() for important information.
void set_control_overlay_id(global_position: Vector3, texture_id: int) 🔗
Sets the overlay texture ID on the control map at the requested position. Values are clamped to 0 - 31, matching the ID of the texture asset in the asset dock.
See set_pixel() for important information.
void set_control_scale(global_position: Vector3, percentage_modifier: float) 🔗
Sets the uv scale on the control map at the requested position. The value is rounded to the nearest 20% difference from 100%, ranging between -60% to +80%.
See set_pixel() for important information.
void set_height(global_position: Vector3, height: float) 🔗
Sets the height value on the heightmap pixel associated with the specified position. See set_pixel() for important information.
Unlike get_height(), which interpolates between vertices, this function does not and will set the pixel at floored coordinates.
void set_pixel(map_type: MapType, global_position: Vector3, pixel: Color) 🔗
Sets the pixel for the map type associated with the specified position. This method is fine for setting a few pixels, but if you wish to modify thousands of pixels quickly, you should get the region and use Terrain3DRegion.get_map(), then edit the images directly.
After setting pixels you need to call update_maps(). You may also need to regenerate collision if you don’t have dynamic collision enabled.
void set_region_deleted(region_location: Vector2i, deleted: bool) 🔗
Marks a region as deleted. It will stop displaying when maps are updated. The file will be removed on save.
void set_region_modified(region_location: Vector2i, modified: bool) 🔗
Sets the region as modified. It will be written to disk when saved. Syntactic sugar for Terrain3DRegion.modified.
void set_roughness(global_position: Vector3, roughness: float) 🔗
Sets the roughness modifier (wetness) on the color map alpha channel associated with the specified position. See set_pixel() for important information.
void update_maps(map_type: MapType = 3, all_maps : bool = true, generate_mipmaps: bool = false) 🔗
Regenerates the region map and the TextureArrays that combine the requested map types. This function needs to be called after editing any of the maps.
By default, this function rebuilds all maps for all regions.
map_type - Regenerate only maps of this type.
all_regions - Regenerate all regions if true, otherwise only those marked with Terrain3DRegion.edited.
generate_mipmaps - Regenerate mipmaps if map_type is color or all (max), for the regions specified above. This can also be done on individual regions before calling this function with
region.get_color_map().generate_mipmaps().
For frequent editing, rather than enabling all_regions, it is more optimal to only update changed regions as follows:
terrain.data.set_height(global_position, 10.0)
var region:Terrain3DRegion = terrain.data.get_regionp(global_position)
region.set_edited(true)
terrain.data.update_maps(Terrain3DRegion.TYPE_HEIGHT, false)
region.set_edited(false)