Render3D. HeightMap

HeightMap - Terrain from a grid of heights: an object that draws itself, and that objects with collideLevel stand on

  • heights is a 2D array [row][column] of 0 to 1 values
  • Row 0 is the far edge at -Z and column 0 is the left edge at -X
  • It can be an image instead, where the red channel is the height
  • colors is an optional 2D array of Colors or an image, sampled per vertex
  • images are read through a canvas, so they must be same origin or loaded with crossOrigin set
  • pos3D is the center of the map, its grid spans mapSize on X and Z around it, and a full value is height above it
  • getHeight, getNormal, getColor and raycast are in world space, with the map's position taken off
  • It stays upright and unscaled, its lookups do not turn with it

Constructor

new HeightMap(heights, mapSizeopt, heightopt, colorsopt, pos3Dopt, smoothopt)

Create a height map from an array or an image, it draws itself and joins the level's collision

Parameters:
NameTypeAttributesDefaultDescription
heightsArray.<Array.<number>> | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | TextureInfo
mapSizeVector2<optional>

World size along X and Z

heightnumber<optional>
1

World height of a full value

colorsArray.<Array.<Color>> | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | TextureInfo<optional>
pos3DVector3<optional>

Center of the map

smoothboolean<optional>

Defaults to render3D.smoothShading

Source
Example
const terrain = new HeightMap(heightImage, vec2(100, 100), 10, colorImage);
const y = terrain.getHeight(x, z); // stand things on it, or give them collideLevel

Extends

  • EngineObject3D

Members

colors :Array.<Array.<Color>>|undefined

Type:
  • Array.<Array.<Color>> | undefined
Properties
TypeDescription
Array.<Array.<Color>> | undefined

Vertex colors as [row][column], undefined for white

Source

columns

Number of columns, along X

Source

height

Properties
TypeDescription
number

World height of a full value

Source

heights

Properties
TypeDescription
Array.<Array.<number>>

Heights 0-1 as [row][column], rows along Z, rebuild() after changing them

Source

mapSize

Properties
TypeDescription
Vector2

World size along X and Z

Source

rows

Number of rows, along Z

Source

smooth

Properties
TypeDescription
boolean

Smooth shading, rebuild() after changing it

Source

Methods

buildMesh(smoothopt) → {Mesh}

Build the terrain mesh, one vertex per sample, centered on the map's own origin

Parameters:
NameTypeAttributesDescription
smoothboolean<optional>

Defaults to render3D.smoothShading

Source
Returns:
Type: 
Mesh

destroy(immediateopt)

Destroy the map, it leaves the level's collision

Parameters:
NameTypeAttributesDescription
immediateboolean<optional>
Source

getColor(x, zopt) → {Color}

Color of the nearest sample to a position, white when there are no colors

Parameters:
NameTypeAttributesDescription
xnumber | Vector3

X, or a position to take X and Z from

znumber<optional>
Source
Returns:
Type: 
Color

getHeight(x, zopt) → {number}

World height at a position, exactly the height of the mesh buildMesh draws there, clamped at the edges

Parameters:
NameTypeAttributesDescription
xnumber | Vector3

X, or a position to take X and Z from

znumber<optional>
Source
Returns:
Type: 
number

getNormal(x, zopt) → {Vector3}

Surface normal at a position, from the slope across a sample

Parameters:
NameTypeAttributesDescription
xnumber | Vector3

X, or a position to take X and Z from

znumber<optional>
Source
Returns:
Type: 
Vector3

raycast(ray) → {number|undefined}

Distance along a ray to where it crosses the terrain surface, or undefined for a miss

  • Exact: the ground is flat inside each triangle, so the ray is checked between each grid line and cell diagonal it crosses, and a hill it only grazes is still hit
  • A ray that starts under the ground crosses on its way out, so the hit is still on the surface
Parameters:
NameTypeDescription
rayRay3D

From screenToRay, or any ray

Source
Returns:
Type: 
number | undefined

rebuild()

Make the mesh again from the heights and colors, after changing them or smooth

Source

update()

Keeps an eye on its placement, called automatically each frame

Source