land

land provides terrain-related queries, such as elevation lookups and surface type detection, for a given point on the map.

Functions

land.getHeight(point)

Returns the terrain elevation, in meters, at the given {x, y} point.

Parameters:

point (table) – A {x, y} map coordinate.

Returns:

Terrain elevation, in meters.

Return type:

number

Example:

local elevation = land.getHeight({x = 1000, y = 2000})

land.getSurfaceHeightWithSeabed(point)

Returns the terrain elevation at the given point, taking seabed depth into account for underwater areas.

Parameters:

point (table) – A {x, y} map coordinate.

Returns:

Terrain (or seabed) elevation, in meters.

Return type:

number

Example:

local seabedElevation = land.getSurfaceHeightWithSeabed({x = 1000, y = 2000})

land.getSurfaceType(point)

Returns an enumerator (see Surface type enumerator below) describing the surface type at the given point.

Parameters:

point (table) – A {x, y} map coordinate.

Returns:

Surface type enumerator value.

Return type:

number

Example:

local surfaceType = land.getSurfaceType({x = 1000, y = 2000})
if surfaceType == land.SurfaceType.WATER then
    env.info('Point is over water.')
end

land.isVisible(origin, destination)

Returns whether destination is visible (line-of-sight, terrain-occluded or not) from origin.

Parameters:

• origin (table) – A {x, y, z} point.

• destination (table) – A {x, y, z} point.

Returns:

Whether destination is visible from origin.

Return type:

boolean

Example:

local canSee = land.isVisible({x = 0, y = 500, z = 0}, {x = 1000, y = 500, z = 1000})

land.getIP(origin, direction, distance)

Returns the intersection point of a ray cast from origin in direction for up to distance, or nil if no intersection with terrain is found.

Parameters:

• origin (table) – A {x, y, z} point.

• direction (table) – A normalized {x, y, z} direction vector.

• distance (number) – Maximum ray distance, in meters.

Returns:

Intersection point, or nil.

Return type:

table

Example:

local hit = land.getIP({x = 0, y = 1000, z = 0}, {x = 0, y = -1, z = 0}, 2000)

land.profile(point1, point2)

Returns a table of terrain elevation samples along the line between two points, useful for line-of-sight or terrain-masking calculations.

Parameters:

• point1 (table) – A {x, y, z} point.

• point2 (table) – A {x, y, z} point.

Returns:

A table of sampled elevation points.

Return type:

table

Example:

local samples = land.profile({x = 0, y = 0, z = 0}, {x = 5000, y = 0, z = 5000})

land.getClosestPointOnRoads(roadType, x, y)

Returns the nearest point on a road network of the given type (see Road type enumerator below) to the specified coordinates.

Parameters:

• roadType (string) – Road network type.

• x (number) – Map x coordinate.

• y (number) – Map y coordinate.

Returns:

The nearest road x/y coordinates.

Return type:

number, number

Example:

local roadX, roadY = land.getClosestPointOnRoads('roads', 1000, 2000)

land.findPathOnRoads(roadType, startX, startY, endX, endY)

Returns a path of waypoints following the road network of the given type (see Road type enumerator below) between two points.

Parameters:

• roadType (string) – Road network type.

• startX (number) – Start x coordinate.

• startY (number) – Start y coordinate.

• endX (number) – End x coordinate.

• endY (number) – End y coordinate.

Returns:

A table of {x, y} waypoints following the road network.

Return type:

table

Example:

local path = land.findPathOnRoads('roads', 0, 0, 5000, 5000)

Enumerators

land.SurfaceType identifies the terrain type returned by getSurfaceType():

Value	Meaning
land.SurfaceType.LAND	Dry land.
land.SurfaceType.SHALLOW_WATER	Shallow water (e.g. near shore).
land.SurfaceType.WATER	Deep water.
land.SurfaceType.ROAD	Paved road.
land.SurfaceType.RUNWAY	Airbase runway or taxiway.

roadType (used by getClosestPointOnRoads() and findPathOnRoads()) accepts one of the following string values:

Value	Meaning
"roads"	Standard road network.
"railroads"	Railway network.

Footnotes

• Points are generally expressed in the flat map coordinate system (x, y), not latitude/longitude; use coord (see coord) to convert as needed.