Skip to main content

Class: TerrainShape

Defined in: physics/shapes/terrain-shape.ts:73

A static, non-convex 2D ground collider defined by a heightmap: a chain of surface points, ordered left to right, closed off into a solid slab by a flat bottom edge depth units below the lowest surface point.

Unlike PolygonShape, TerrainShape does not re-center its vertices around their centroid - points are used exactly as authored, in the shape's own local space, with the owning RigidBody's position acting as a simple translation offset (typically Vector2.zero, with the terrain authored directly in world coordinates). This matches how heightmap terrain is normally authored, and keeps a terrain's points meaningful on their own without also tracking a separately-computed centroid offset.

Narrow-phase collision against a TerrainShape (see detectCircleTerrainCollision/detectPolygonTerrainCollision) is resolved per-segment: each pair of consecutive surface points, plus the flat bottom edge, forms a convex quadrilateral (segments), and the existing circle/polygon narrow-phase routines run against whichever segments overlap the other body's local x-range.

Terrain is intended to always be static (see RigidBodyOptions.isStatic)

  • a heightmap has no meaningful mass distribution to simulate as a moving body. getArea/getMomentOfInertia are still implemented correctly (for a hypothetical dynamic use), but are never called for a static body.

Implements​

Constructors​

Constructor​

new TerrainShape(points, depth): TerrainShape

Defined in: physics/shapes/terrain-shape.ts:101

Creates a new TerrainShape instance.

Parameters​

points​

readonly Vector2[]

The local-space surface points of the terrain, ordered by strictly increasing x. Must contain at least 2 points.

depth​

number

The thickness of the terrain slab below its lowest point. Must be positive.

Returns​

TerrainShape

Throws​

An error if fewer than 2 points are provided, the points are not ordered by strictly increasing x, or depth is not positive.

Properties​

bottomY​

readonly bottomY: number

Defined in: physics/shapes/terrain-shape.ts:84

The flat bottom edge's y-coordinate, in local space: depth units below the lowest of points.

depth​

readonly depth: number

Defined in: physics/shapes/terrain-shape.ts:78

points​

readonly points: readonly Vector2[]

Defined in: physics/shapes/terrain-shape.ts:76

segments​

readonly segments: readonly TerrainSegment[]

Defined in: physics/shapes/terrain-shape.ts:90

The convex quadrilaterals narrow-phase collision detection tests against, one per consecutive pair of points.

type​

readonly type: "terrain" = 'terrain'

Defined in: physics/shapes/terrain-shape.ts:74

The kind of shape this is, used to dispatch collision detection.

Implementation of​

ShapeBase.type

Methods​

getArea()​

getArea(): number

Defined in: physics/shapes/terrain-shape.ts:133

Calculates the area of the terrain's full silhouette (its surface points, closed off by the flat bottom edge).

Returns​

number

The area of the terrain.

Implementation of​

ShapeBase.getArea

getBoundingRadius()​

getBoundingRadius(): number

Defined in: physics/shapes/terrain-shape.ts:159

Calculates the radius of the smallest circle, centered on the shape's local origin (not its centroid - see the class documentation), that fully contains the terrain.

Returns​

number

The bounding radius of the terrain.

Implementation of​

ShapeBase.getBoundingRadius

getMomentOfInertia()​

getMomentOfInertia(mass): number

Defined in: physics/shapes/terrain-shape.ts:143

Calculates the moment of inertia of the terrain's full silhouette for a given mass, about its own center of mass.

Parameters​

mass​

number

The mass of the body the shape belongs to.

Returns​

number

The moment of inertia of the terrain.

Implementation of​

ShapeBase.getMomentOfInertia