The terrain is represented by two raster grids - type grid and height grid.

The materials used to texture the terrain are in the TerrainTextures table. Each material consists of several PBR textures similar to other materials in the game - base color, normal map, roughness / metallic, etc.

The layout of these materials on the terrain is controlled by the terrain type grid, which describes what material to use for each grid tile. Each tile can reference only one material. However, materials are blended along type pixel boundaries with a fairly wide blending border, to avoid obvious pixelation.The values in the pixels are 8 - bit indices in the TerrainTextures table.

The geometry of the terrain is described by a dense heightfield, with the same density as the type grid. Each grid value indicates the height in this point, as a 16 - bit number. That number is then scaled to obtain the final height in game units (i.e.centimeters). The height grid samples are located at the type grid tile corners, i.e. the height grid is 1 pixel bigger than the type grid.

Checks if there is enough connected passable tiles at a given location (forming a connected area).

bool terrain.AreaPassable(point pos, int area, [int pfclass = 0, bool bUseTunnels = false])

bool terrain.AreaPassable(int x, int y, int z, int area, [int pfclass = 0, bool bUseTunnels = false])

bool terrain.AreaPassable(object obj, int area, [bool bUseTunnels = false]) point pos : position to check.

int x, y, z : position to check.

object obj : position and pfclass to check.

int area : number of connected passable tiles.

int pfclass : pfclass to use (optional, default 0).

bool bAvoidTunnels : ignore connectivity through tunnels (optional, default false).

Modifies all values in the height grid by given value

void terrain.ChangeHeight(diff) int diff : value to add.

Checks if a circle area with given radius is passable.

Usefull to verify if there is enough space to fit safely something at a given position.

bool terrain.CirclePassable(point pos, int radius, [int pfclass = 0])

bool terrain.CirclePassable(int x, int y, int z, int radius, [int pfclass = 0])

bool terrain.CirclePassable(object obj, int radius) point pos : position to check.

int x, y, z : position to check.

object obj : position and pfclass to check.

int radius : radius to check.

int pfclass : pfclass to use (optional, default 0).

Clamp a box with the map bounding box.

box terrain.ClampBox(box, border) box box : box to clamp

int border : optional, if specified the function will shrink the map boundaries by this amount for the purpose of the clamp.

Clamp a position with the map bounding box.

point terrain.ClampPoint(pos, border) point pos : position to clamp

int border : optional, if specified the function will shrink the map boundaries by this amount for the purpose of the clamp.

Clamp a vector with the map bounding box.

point, point terrain.ClampVector(ptFrom, ptTo) point ptFrom : vector begin point to clamp

point ptTo : vector end point to clamp

Clears all water from the map.

void terrain.ClearWater()

Counts the passable tiles in a circle area with given radius.

Usefull to estimate how passable is a given area compared to another.

int terrain.CountPassable(point pos, int radius, [int pfclass = 0])

int terrain.CountPassable(int x, int y, int z, int radius, [int pfclass = 0])

int terrain.CountPassable(object obj, int radius) point pos : position to check.

int x, y, z : position to check.

object obj : position and pfclass to check.

int radius : radius to check.

int pfclass : pfclass to use (optional, default 0).

Search a position with enough connected passable tiles (forming a connected area) starting from a given position.

Different passability levels could be considered when tunnels are allowed only.

bool terrain.FindAreaPassable(point pos, int area, int radius, [int pfclass = 0, bool bUseTunnels = false, function filter = false, ...])

bool terrain.FindAreaPassable(int x, int y, int z, int area, int radius, [int pfclass = 0, bool bUseTunnels = false, function filter = false, ...])

bool terrain.FindAreaPassable(object unit, int area, int radius, [bool bUseTunnels = false, bool bCanDestlock = false, function filter = false, ...]) point pos : position to check.

int x, y, z : position to check.

object unit : unit at position and pfclass to check.

int area : number of connected passable tiles.

int radius : search radius around the position to check.

int pfclass : pfclass to use (optional, default 0).

bool bAvoidTunnels : restrict search in a single level and ignore connectivity through tunnels (optional, default false).

bool bCanDestlock : if an unit is provided, check for destlockable positions only.

function filter : if provided, each position (x, y, z) will be tested with. All remaing parameters are forwarded.

Search for the nearest passable tile around a center position, according to certain criteria, specified by flags.

The initial position is tested without tile alignment, to handle the trivial case where the center position is passable.

The function is faster than terrain.FindPassable.

point terrain.FindPassableTile(obj, tfp_flags, ...)

point terrain.FindPassableTile(pos, tfp_flags, ...)

point terrain.FindPassableTile(x, y, z, tfp_flags, ...) CObject obj : search center. The pass class and pass flags are deduced from it, in case there is a path component.

point pos : search center.

int x, y, z : search center.

int tfp_flags : Flag based number defining different modifications to the default behavior. If some of the behaviors require aditional params, they should follow in the correct order. The available flags are:

-- const.tfpLimitDist

Limits the search between min/max distance.

Additional param: max_dist, min_dist (int)

-- const.tfpPassClass

Specifies a pass class, overriding the pass class in obj param, if any. Exepcts a pf class index or an object.

Additional param: pfclass (int/object)

-- const.tfpCanDestlock

Searches for destlockable positions only. Exepcts a deslocking radius, an object or a boolean too indicate to use the one found in obj.

Additional params: destlock_radius (int/object/bool)

-- const.tfpVoxelCenters

Restricts the search to voxel centers only.

-- const.tfpReturnXYZ

Forces the result to be the point coordinates instead.

-- const.tfpCollectList

Forces the result to be a list of all pass positions in a list, instead of the first one. Exepcts max results count, or a boolean.

Requires const.tfpLimitDist. Incompatible with const.tfpReturnXYZ.

Additional params: max_results (int,bool)

-- const.tfpLuaFilter

A Lua filter expecting as parameters coordinates: x, y, z

Any additional parameters passed after the filter are passsed back to it when called, after the coordinates.

Additional params: filter (function)

returns point pass_pos : a passable position if found (or its coordinates if const.tfpReturnXYZ is specified, or a list with all positions matching the criteria if const.tfpReturnList is specified).

Example:

	local nsp_flags = const.tfpLimitDist | const.tfpLuaFilter
	local max_dist, min_dist = 16*guim, 2*guim
	local danger_pos, danger_dist = self:FindDangerAround()
	local pos = terrain.FindPassableTile(self, nsp_flags, max_dist, min_dist, function(x, y, z, danger_pos, danger_dist)
		return not danger_pos or not IsCloser(danger_pos, x, y, z, danger_dist)
	end, danger_pos, danger_dist)

Returns the closest passable Z in the specified range.

void terrain.FindPassableZ(pt, pfclass, max_below, max_above)

void terrain.FindPassableZ(x, y, z, pfclass, max_below, max_above)

void terrain.FindPassableZ(obj, max_below, max_above) point pt : map position.

int x, y, z : map position as coordinates.

Object obj : game object to use as position and pf class.

int pfclass : pf class to check (0 by default)

int max_below, max_above : search range (unlimited by default).

returns : int pass_z : the pass Z if found or nil.

Search for a reachable passable position around a given start position (or unit), according to a set of rules.

Supports several rules for filtering, weighting and randomizing the results.

The search is 3D but wont change passability levels unless via a tunnel. Thus providing a starting point on impassable would search around within the provided limits, ignoring passable positions on adjacent layers.

The only case where the starting layer is changed, is for positions with valid Z exactly on the terrain, resulting from providing visual position of units.

point terrain.FindReachable(obj, rule, ..., [rule2, ...], ..., [ruleN, ...])

point terrain.FindReachable(start_pos, pf_class, rule, ..., [rule2, ...], ..., [ruleN, ...]) CObject obj : object to be used as starting position, applying its pf class

point start_pos : starting search position

int pf_class : pathfinding class

int rule : operation rule. Each rule have different input parameters expected after its declaration:

-- const.tfrResCount, count

count results are expected (1 by default). Unlimited results can be specified by providing -1.

-- const.tfrResCollect, results, start_idx

Pushes the results into the given table results instead into the stack. If no table is providied (false), then such table is created and pushed into the stack. Always pushes the collected count into the stack as well. If start_idx is false then the results are pushed at the end of the table.

-- const.tfrRandom, seed

The result(s) are randomized based on the given seed

-- const.tfrDir, angle

Sets the orientation to angle (used by some of the operation rules)

-- const.tfrLimitDist, max_dist, min_dist

The result(s) are located between min_dist and max_dist traversed distance from the start.

-- const.tfrLimitDir, max_angle, min_angle

The result(s) are located between min_angle and max_angle absolute deviation form the given orientation (the object*s angle by default).

-- const.tfrBoxFilter, filter_box

The result(s) are accepted only if inside the provided box (2D).

-- const.tfrCenterRadius, max_radius, min_radius, center_pos

The result(s) are located between min_radius and max_radius linear distance around the center_pos (the object's pos by default).

This rule can co-exists with const.tfrLimitDist to make it possible to apply constraints by 2 different positions (e.g. Roam behavior).

The start_pos can be outside the allowed max_radius around center_pos, but in that case the results are not guaranteed to be the best possible.

-- const.tfrWeightDir, max_angle_weight, min_angle_weight, angle_weight_distrib

Apply weights to the results according to how close/far they are to a given orientation (the object's angle by default). The weight distribution law can be linear (1), quadratic (2), etc.

-- const.tfrWeightDist, max_dist_weight, min_dist_weight, dist_weight_distrib

Apply weights to the results according to how close/far they are to the start position (according to the traversed distance). The weight distribution law can be linear (1), quadratic (2), etc.

-- const.tfrWeightRadius, max_radius_weight, min_radius_weight, radius_weight_distrib

Apply weights to the results according to how close/far they are to the center position (according to the linear 2D distance). The weight distribution law can be linear (1), quadratic (2), etc.

-- const.tfrPassCost, max_cost, min_cost

Filter the result(s) by pathfinding cost.

-- const.tfrPassLOS

Restrict the results to have passable LOS to the start position. Tunnels are therefore ignored in this rule.

-- const.tfrPassClass, pfclass

Specify a pf class.

-- const.tfrVoxelCenters

Results will be confined to voxel centers only.

-- const.tfrPassBorder, pass_border

Limit the result(s) to those located at a minimum distance pass_border to impassable.

-- const.tfrCanDestlock, destlock_radius

Restrict the results to be destlockable positions.

You can set a custom destlock_radius (-1 sets it to to the given unit's destlock radius).

If a point is given, in stead of a unit, destlock_radius is necessary

-- const.tfrDbgStats

Debug only: print statistics.

-- const.tfrDbgMap

Debug only: return point to weight map as first result

-- const.tfrLuaFilter, filter, [filter_params]

Call a Lua filter for each result.

The function is called with the coordinates x, y and z, followed by all filter_params.

This should be the last rule in the parameters as everything after it is considered as filter parameters.

returns point pos1, pos2, ... : Number of results specified by rule const.tfrResCount (1 by default)

Multiple rules can be requested in the same call by providing them in succession.

Example:

	local pos = terrain.FindReachable(self,
		const.tfrRandom, seed,
		const.tfrLimitDist, max_dist, min_dist,
		const.tfrCenterRadius, max_radius, min_radius, center_pos,
		const.tfrWeightDir, max_angle_weight, min_angle_weight, angle_weight_distrib,
		const.tfrPassCost, max_cost, min_cost,
		const.tfrLuaFilter, filter, ...)

Fix any discontinuities at the height border, as some operation are not applied there.

void terrain.FixHeightBorder()

Returns the average height of the specified circle area. If no parameters are specified, then the average for the whole map is computed.

int terrain.GetAreaHeight(pos, radius) point pos : optional, center of the circle area.

int radius : optional, radius of the circle area.

Returns the grass density at given position.

int terrain.GetGrassDensity(pos) point pos : position to check.

Returns the terrain height at given position.

int terrain.GetHeight(pos) point pos : position to check.

Returns the map height/sizey.

int terrain.GetMapHeight()

Returns the size of the map (terrain) rectangle as two integers (sizex and sizey).

int, int terrain.GetMapSize()

Returns the map width/sizex.

int terrain.GetMapWidth()

Returns the min & max terrain height in a given box. The box bounderies are rounded up to the height grid alignment.

int, int terrain.GetMinMaxHeight(bbox)

Returns an unique number defining the passability state of the terrain.

Different pass ID-s can denote the same passability state, but the same ID cannot denote two different passability states.

int terrain.GetPassId()

Returns the orientation angle of the terrain normal projection at the given position.

int terrain.GetSlopeOrientation(pos) point pos : position to check.

Returns the max surface height at given position (e.g. water).

int terrain.GetSurfaceHeight(pos) point pos : position to check.

Returns the normal to the terrain surface, with all components multiplied by 100.

point terrain.GetSurfaceNormal(pos) point pos : position to check.

Returns the normal to the terrain, with all components multiplied by 100.

point terrain.GetTerrainNormal(pos) point pos : position to check.

Returns the slope angle of the terrain at the given position, as determined by the terrain normal.

int terrain.GetTerrainSlope(pos) point pos : position to check.

Returns the terrain type at the given map position.

int terrain.GetTerrainType(pos) point pos : position to check.

Returns the number of available terrain types.

int terrain.GetTerrainsCount()

Returns the water height at given position.

int terrain.GetWaterHeight(pos) point pos : position to check.

Returns the x and y sizes of the heightmap grid.

int, int terrain.HeightMapSize()

Returns the intersection point of a ray with the terrain.

point terrain.IntersectRay(pt1, pt2) point pt1 : start point of the ray.

point pt2 : end point of the ray.

Returns the intersection point of a segment with the terrain.

point terrain.IntersectSegment(pt1, pt2) point pt1 : start point of the segment.

point pt2 : end point of the segment.

Forces a recalculation of the typemap in the specified area or the entire map.

void terrain.InvalidateType(area) box area : optional, area to recalculate.

Forces a recalculation of the height values in the specified area or the entire map.

void terrain.InvlidateHeight(area) box area : optional, area to recalculate.

Checks if a box is the same or bigger than the map bounding box.

bool terrain.IsMapBox(box) box box : box to check

Returns true if the specified point is inside the terrain boundaries.

bool terrain.IsPointInBounds(pos, [border]) point pos : position to check.

int border : optional, if specified the function will shrink the map boundaries by this amount for the purpose of the check.

Returns true if the specified point is s considered vertical terrain depending on the terrain normal.

bool terrain.IsVerticalTerrain(pos) point pos : position to check.

Returns whether water is present at given position.

int terrain.IsWater(pos) point pos : position to check.

Checks for water/land in a given radius.

bool terrain.IsWaterNearby(pos, radius) point pos : position to check.

int radius : check radius.

Replaced the terrain type in a circle area.

void terrain.ReplaceTypeCircle(ptCenter, nRadius, hTypeOld, vType) point ptCenter : center of the circle area to change.

int nRadius : radius of the circle area to change.

int hTypeOld : terrain type to be replaced.

int hTypeNew : terrain type to apply.

int vType : optional, alternative terrain type to apply on vertical terrain areas.

Scales all values in the height grid by given nominator and denominator.

void terrain.ScaleHeight(mul, div) int mul : nominator value to apply.

int div : denominator value to apply.

Sets the terrain height at the given position to the specified value.

void terrain.SetHeight(pos, height) point pos : the position to alter.

int height : the new height to set.

Calculates the average height in the given circle, then modifies it by the given value

void terrain.SetHeightCircle(pt, nInnerRadius, nOuterRadius, nHeightDiff) point pt : the center of the circle area to alter.

int nInnerRadius : radius of the inner circle, where the desired height will be set without smoothing.

int nOuterRadius : radius of the outer ring, where the new height will be smoothed toward the current values.

int nHeightDiff : value to add to the computed average height.

Sets the height values in the given circle, smoothing the height in the outer ring toward the existing values

void terrain.SetHeightCircle(pt, nInnerRadius, nOuterRadius, nHeight, mode) point pt : the center of the circle area to alter.

int nInnerRadius : radius of the inner circle, where the desired height will be set without smoothing.

int nOuterRadius : radius of the outer ring, where the new height will be smoothed toward the current values.

int nHeight : new height to set.

int mode : optional, can be const.hsDefault (default, set target values directly), const.hsMin (new_height = Min(new_height, current)) or const.hsMax (new_height = Max(new_height, current)).

Sets the terrain type at the given position.

void terrain.SetTerrainType(pos, type) point pos : position to change.

int type : new terrain type.

Sets the terrain type in a rectangular area.

void terrain.SetTypeBox(box, type) box b : the area to change.

int nType : terrain type to apply.

Sets the terrain type in a circle area.

void terrain.SetTypeCircle(ptCenter, nRadius, hType, vType) point ptCenter : center of the circle area to change.

int nRadius : radius of the circle area to change.

int hType : terrain type to apply.

int vType : optional, alternative terrain type to apply on vertical terrain areas.

Smooths the terrain height in the given circle.

void terrain.SmoothHeightCircle(pt, radius) point pt : the center of the circle area to smooth.

int radius : the radius of circle area to smooth.

string mode : (optional) you can specify "min" or "max" to be used when setting the terrain height at each point.

Returns the x and y sizes of the typemap grid.

int, int terrain.TypeMapSize()

Sets the water height from the position of a given object.

void terrain.UpdateWaterGridFromObject(obj) object obj : object to use (or it's position).

(insert footer.md.html here)