HeightField

Creates a regular height grid for Static terrain.

Each sample defines public Z at a point on a regular XY grid. The wrapper converts Jolt's internal orientation to Z-up and reverses rows so public Y grows in input-row order.

Syntax#

jolt_heightfield_create_static(heights, width, height, cell_size,
                 x=0, y=0, z=0, options=undefined)

heights format#

heights[row * width + column]
heights[row][column]

The flat array has width*height values; the nested form has exactly height rows of width values. Every sample is a finite local Z and may be positive or negative.

Resolution, dimensions, and orientation#

• width and height are sample counts, not world dimensions.
• The grid must be square: width == height.
• Resolution is 4..512 samples per side.
• cell_size is positive X spacing; options.cell_size_y controls Y and defaults to cell_size.
• World span is (width-1)*cell_size by (height-1)*cell_size_y.
• x,y,z is the first sample origin: [0][0] is at (x,y,z+heights[0][0]), not the terrain centre.

cell_size_y is the only shape-specific field in shared options. After construction, __jolt_high_apply_options() ignores it.

Validation and return#

The creator rejects non-square or out-of-range grids, wrong sample counts, uneven rows, NaN/Infinity, and non-positive cell sizes. It returns a Static JoltBody or undefined. Relevant options are rotation, rotation_euler, friction, restitution, layer, and sensor; motion-only options fail. Contacts, filtering, sensors, and raycasts are supported. Debug draw strides large grids to roughly 128 samples per axis.

Reusable JoltShape#

var shape = jolt_shape_heightfield(heights, width, height, cell_size,
                       cache_key=undefined, cell_size_y=undefined);
var terrain = shape.create_static(x, y, z, options);

The resource creator has a different optional-argument order. create_dynamic() and create_kinematic() are unavailable. jolt_shape_load() supports HeightField .jcol.

Low-Level / Advanced API#

No ergonomic array creator exists. jolt_world_geometry_create(world,payload) expects an internal base64 payload and Static motion; use jolt_heightfield_create_static() or jolt_shape_heightfield().

Example#

var size = 8;
var heights = array_create(size * size, 0);
for (var yy = 0; yy < size; ++yy) {
    for (var xx = 0; xx < size; ++xx) {
        var dx = xx - 3.5;
        var dy = yy - 3.5;
        heights[yy * size + xx] = 0.08 * (dx*dx + dy*dy);
    }
}
var terrain = jolt_heightfield_create_static(heights, size, size, 1,
    -3.5, -3.5, 0, {friction:0.9, cell_size_y:1});

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.