WorldScape3DData

Image[] color_maps = []

An ArrayImage containing references to all of the color maps in all regions. See WorldScape3DRegion.color_map.

Image[] control_maps = []

An ArrayImage containing references to all of the control maps in all regions. See WorldScape3DRegion.control_map.

Image[] height_maps = []

An ArrayImage containing references to all of the height maps in all regions. See WorldScape3DRegion.height_map.

Vector2i[] region_locations = []

The array of all active region locations; those not marked for deletion.

int add_region(WorldScape3DRegion region, bool update = 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 WorldScape3D.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().

WorldScape3DRegion add_region_blank(Vector2i region_location, bool update = true)

Creates and adds a blank region at the specified location. See add_region().

WorldScape3DRegion add_region_blankp(Vector3 global_position, bool update = true)

Creates and adds a blank region at a region location encompassing the specified global position. See add_region().

void calc_height_range(bool recursive = 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 WorldScape3DRegion.calc_height_range().

void change_region_size(int region_size)

Reslices terrain data to fit the new region size. This is a destructive process for which there is no undo. However Redot 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(Rect2i area, Callable callback)

Calls the callback function for every region within the given area. If using vertex_spacing, area values should be descaled. The callable receives: source WorldScape3DRegion, 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 WorldScape3DRegion, 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.

int export_image(String file_name, int map_type) 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 Redot's native data format.

Color get_color(Vector3 global_position) const

Returns the associated pixel on the color map at the requested position. Returns [code skip-lint]Color(NAN, NAN, NAN, NAN)[/code] 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(Vector3 global_position) const

Returns the associated pixel on the control map at the requested position. Returns [code skip-lint]4,294,967,295[/code] aka [code skip-lint]UINT32_MAX[/code] if the position is outside of defined regions.

float get_control_angle(Vector3 global_position) 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 [code skip-lint]NAN[/code] if the position is outside of defined regions.

bool get_control_auto(Vector3 global_position) const

Returns whether the autoshader is enabled on the control map at the requested position. Returns [code skip-lint]false[/code] if the position is outside of defined regions.

int get_control_base_id(Vector3 global_position) 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 [code skip-lint]4,294,967,295[/code] aka [code skip-lint]UINT32_MAX[/code] if the position is outside of defined regions.

float get_control_blend(Vector3 global_position) 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 [code skip-lint]NAN[/code] if the position is outside of defined regions.

bool get_control_hole(Vector3 global_position) const

Returns whether there is a hole on the control map at the requested position. Returns [code skip-lint]false[/code] 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.

bool get_control_navigation(Vector3 global_position) const

Returns whether navigation is enabled on the control map at the requested position. Returns [code skip-lint]false[/code] if the position is outside of defined regions.

int get_control_overlay_id(Vector3 global_position) 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 [code skip-lint]4,294,967,295[/code] aka [code skip-lint]UINT32_MAX[/code] if the position is outside of defined regions.

float get_control_scale(Vector3 global_position) 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 [code skip-lint]NAN[/code] if the position is outside of defined regions.

float get_height(Vector3 global_position) 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 [code skip-lint]NAN[/code] 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 WorldScape3DMaterial.world_background used that extends the mesh outside of this range will not change this variable. You need to set WorldScape3D.cull_margin or the renderer will clip meshes.

Image[] get_maps(int map_type) const

Returns an Array of Images from all regions of the specified map type.

Vector3 get_mesh_vertex(int lod, int filter, Vector3 global_position) 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 [code skip-lint]NAN[/code] in the vector's Y coordinate. [code skip-lint]lod[/code] - Determines how many heights around the given global position will be sampled. Range 0 - 8. [code skip-lint]filter[/code] - Specifies how samples are filtered. See HeightFilter. [code skip-lint]global_position[/code] - X and Z coordinates of the vertex. Heights will be sampled around these coordinates.

Vector3 get_normal(Vector3 global_position) const

Returns the terrain normal at the specified position. This function uses get_height(). Returns [code skip-lint]Vector3(NAN, NAN, NAN)[/code] if the requested position is a hole or outside of defined regions.

Color get_pixel(int map_type, Vector3 global_position) const

Returns the pixel for the map type associated with the specified position. Returns [code skip-lint]Color(NAN, NAN, NAN, NAN)[/code] if the position is outside of defined regions.

WorldScape3DRegion get_region(Vector2i region_location) const

Return the WorldScape3DRegion at the specified location. This will return inactive regions marked for deletion. Check with WorldScape3DRegion.deleted.

int get_region_count() const

Returns the number of active regions; those not marked for deletion.

int get_region_id(Vector2i region_location) 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(Vector3 global_position) const

Returns the region id at a global position. See get_region_id().

Vector2i get_region_location(Vector3 global_position) 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 existence.

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. See get_region_map_index().

int get_region_map_index(Vector2i region_location) 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.

WorldScape3DRegion get_regionp(Vector3 global_position) const

Returns the region at the specified global position. This will return inactive regions marked for deletion. Check with WorldScape3DRegion.deleted.

WorldScape3DRegion[] get_regions_active(bool copy = false, bool deep = false) const

Returns an array of active regions not marked for deletion. Each region knows its own location. See WorldScape3DRegion.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(Vector3 global_position) const

Returns the roughness modifier (wetness) on the color map alpha channel associated with the specified position. Returns [code skip-lint]Color(NAN, NAN, NAN, NAN)[/code] if the position is outside of defined regions.

Vector3 get_texture_id(Vector3 global_position) const

Returns [code skip-lint]Vector3(base texture id, overlay id, blend value)[/code]. Returns [code skip-lint]Vector3(NAN, NAN, NAN)[/code] 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 WorldScape3DMaterial.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(Vector2i region_location) const

Returns true if the specified region location has an active region.

bool has_regionp(Vector3 global_position) const

Returns true if the specified global position has an active region.

void import_images(Image[] images, Vector3 global_position = Vector3(0, 0, 0), float offset = 0.0, float scale = 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. [code skip-lint]images[/code] - MapType.TYPE_MAX sized array of Images for Height, Control, Color. Images can be blank or null. [code skip-lint]global_position[/code] - X,0,Z position on the region map. Valid range is WorldScape3D.vertex_spacing * WorldScape3D.region_size * (+/-16, +/-16). [code skip-lint]offset[/code] - Add this factor to all height values, can be negative. [code skip-lint]scale[/code] - Scale all height values by this factor (applied after offset).

bool is_in_slope(Vector3 global_position, Vector2 slope_range, bool invert = 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(Vector2i region_location) const

Returns true if the region at the location exists and is marked as deleted. Syntactic sugar for WorldScape3DRegion.deleted.

bool is_region_modified(Vector2i region_location) const

Returns true if the region at the location exists and is marked as modified. Syntactic sugar for WorldScape3DRegion.modified.

Image layered_to_image(int map_type) 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(String directory)

Loads all of the WorldScape3DRegion files found in the specified directory. Then it rebuilds all map arrays.

void load_region(Vector2i region_location, String directory, bool update = true)

Loads the specified region location file. - update - rebuild maps if true.

void remove_region(WorldScape3DRegion region, bool update = 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(Vector2i region_location, bool update = true)

Removes the region at the specified location. See remove_region().

void remove_regionp(Vector3 global_position, bool update = true)

Removes the region at the specified global_position. See remove_region().

void save_directory(String directory)

This saves all active regions into the specified directory.

void save_region(Vector2i region_location, String directory, bool save_16_bit = false)

Saves the specified active region to the directory. See WorldScape3DRegion.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(Vector3 global_position, Color color)

Sets the color on the color map pixel associated with the specified position. See set_pixel() for important information.

void set_control(Vector3 global_position, int control)

Sets the value on the control map pixel associated with the specified position. See set_pixel() for important information.

void set_control_angle(Vector3 global_position, float degrees)

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(Vector3 global_position, bool enable)

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(Vector3 global_position, int texture_id)

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(Vector3 global_position, float blend_value)

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(Vector3 global_position, bool enable)

Sets if a hole should be rendered on the control map at the requested position. See set_pixel() for important information.

void set_control_navigation(Vector3 global_position, bool enable)

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(Vector3 global_position, int texture_id)

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(Vector3 global_position, float percentage_modifier)

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(Vector3 global_position, float height)

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(int map_type, Vector3 global_position, Color pixel)

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 WorldScape3DRegion.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(Vector2i region_location, bool deleted)

Marks a region as deleted. It will stop displaying when maps are updated. The file will be removed on save.

void set_region_modified(Vector2i region_location, bool modified)

Sets the region as modified. It will be written to disk when saved. Syntactic sugar for WorldScape3DRegion.modified.

void set_roughness(Vector3 global_position, float roughness)

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(int map_type = 3, bool all_regions = true, bool generate_mipmaps = 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 WorldScape3DRegion.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 [code skip-lint]region.get_color_map().generate_mipmaps()[/code]. 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:WorldScape3DRegion = terrain.data.get_regionp(global_position)
				region.set_edited(true)
				terrain.data.update_maps(WorldScape3DRegion.TYPE_HEIGHT, false)
				region.set_edited(false)
				

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(AABB edited_area)

This signal is emitted whenever the editor 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.

HEIGHT_FILTER_NEAREST = 0

Enum: HeightFilter

Samples the height map at the exact coordinates given.

HEIGHT_FILTER_MINIMUM = 1

Enum: HeightFilter

Samples (1 << lod) * 2 heights around the given coordinates and returns the lowest.

REGION_MAP_SIZE = 32

Hard coded number of regions on a side. The total number of regions is this squared.