HeightfieldCollider (component)

A regular grid of heights, which is the shape terrain collides with. Testing against it costs a cell lookup rather than a walk down a triangle tree, so a large landscape collides at a cost that stays flat as it grows.

The grid

rows and cols are the grid's dimensions, extent its world span as { x = width, y = heightScale, z = depth }, and heights the row-major grid itself, indexed heights[r * cols + c + 1]. The grid is centred on the entity.

rows maps to the entity's local Z and cols to its local X.

entity.find("terrain").component.add("HeightfieldCollider", {
    rows = 64, cols = 64,
    extent = { x = 300, y = 1, z = 300 },
    heights = grid,
})

Use setGrid(rows, cols, heights) to replace the grid and the dimensions describing it together, so the two are never out of step.

Replication

heights is NoSync. It is large, and every peer can rebuild it from its own copy of the terrain, so replicating it would send a whole landscape over the wire to reproduce something each peer already has.

Fields

Field	Meaning
rows / cols	Grid dimensions.
extent	World span, with y scaling the heights.
heights	Row-major height grid. Not replicated.
isTrigger	Report overlaps without blocking.
friction	Surface friction.
restitution	Bounciness.
rollingResistance	How strongly the surface resists a body rolling on it: a rolling body slows at this many times gravity on level ground, so a ball rolled at v stops after v^2 / (2 * rollingResistance * 9.81). 0 rolls on.
spinningResistance	The same for a body spinning on the surface about the contact normal. 0 spins on.
surface	The surface the collider is made of, by name: one Physics.defineSurface defined gives it its friction, restitution and resistances in place of the fields above, and contacts, contact events and ray and shape casts report the name either way. Empty names none.
surfaceLayers	The surfaces the height samples name, by name: each painted layer of a terrain collides as its own surface.
surfaceMap	Per height sample, row-major as heights, the one-based index into surfaceLayers of the surface it names (0 for surface). A contact or cast on the field names the layer of the sample nearest the point and collides with that surface's coefficients.
oneWay	The direction, in the collider's own frame, bodies pass through it along: a body moving that way goes through, and a body meeting it from the side the direction points to stands on it (a jump-through platform is {0, 1, 0}). Physics.passThrough(entity) drops a standing body through. Unset blocks from every side.
surfaceVelocity	The velocity, m/s in the collider's own frame, its surface moves at along itself while the collider stays put: friction carries what rests on it (a conveyor belt, a treadmill, an escalator). Write it at runtime to change the speed or direction. Unset holds the surface still.
contactTag	The tag the world's contact filter reads this collider by: Physics.setContactFilter(tagA, tagB, mode) makes two tags pass through each other ("ignore"), report contacts and push nothing ("sensor") or collide ("solid"). Empty names none.