BabylonJS/Babylon.js · error

Missing required heightfield parameters

Error message

Missing required heightfield parameters

What it means

A HEIGHTFIELD PhysicsShape requires explicit ground/height data (groundMesh plus heightfield parameters such as dimensions/subdivisions) in the options. When those required parameters are absent, HavokPlugin cannot compute the height sampler for the Havok collider and throws. Heightfields are data-driven shapes and cannot be inferred from arbitrary meshes.

Source

Thrown at packages/dev/core/src/Physics/v2/Plugins/havokPlugin.ts:1876

                            for (let z = 0; z < options.numHeightFieldSamplesZ; z++) {
                                const hkBufferIndex = z * options.numHeightFieldSamplesX + x;
                                const bjsBufferIndex = (options.numHeightFieldSamplesX - 1 - x) * options.numHeightFieldSamplesZ + z;
                                heightBuffer[hkBufferIndex] = options.heightFieldData[bjsBufferIndex];
                            }
                        }

                        const scaleX = options.heightFieldSizeX / (options.numHeightFieldSamplesX - 1);
                        const scaleZ = options.heightFieldSizeZ / (options.numHeightFieldSamplesZ - 1);
                        shape._pluginData = this._hknp.HP_Shape_CreateHeightField(
                            options.numHeightFieldSamplesX,
                            options.numHeightFieldSamplesZ,
                            [scaleX, 1, scaleZ],
                            bufferBegin
                        )[1];

                        this._hknp._free(bufferBegin);
                    } else {
                        throw new Error("Missing required heightfield parameters");
                    }
                }
                break;
            default:
                throw new Error("Unsupported Shape Type.");
                break;
        }

        this._shapes.set(shape._pluginData[0], shape);
    }

    /**
     * Sets the shape filter membership mask of a body
     * @param shape - The physics body to set the shape filter membership mask for.
     * @param membershipMask - The shape filter membership mask to set.
     */
    public setShapeFilterMembershipMask(shape: PhysicsShape, membershipMask: number): void {
        const collideWith = this._hknp.HP_Shape_GetFilterInfo(shape._pluginData)[1][1];

View on GitHub (pinned to 0592b347b8)

Solutions

1. Provide all required heightfield options, including groundMesh, when constructing PhysicsShapeHeightfield / {type: PhysicsShapeType.HEIGHTFIELD}.
2. Check the PhysicsShapeHeightfield constructor docs for the exact required parameter set and fill each field.
3. If you just want collision from an arbitrary terrain mesh, use PhysicsShapeType.MESH instead of HEIGHTFIELD.

Example fix

// before
const shape = new PhysicsShape({ type: PhysicsShapeType.HEIGHTFIELD }, scene);
// after
const shape = new PhysicsShapeHeightfield(parent, {
  groundMesh: terrain,
  pointCount: { x: 64, z: 64 },
  size: { x: 100, z: 100 },
  minHeight: 0,
  maxHeight: 10
}, scene);

if (!options.groundMesh) {
  throw new Error("HEIGHTFIELD shape requires options.groundMesh and heightfield parameters");
}

When it happens

Trigger: Creating a shape with type PhysicsShapeType.HEIGHTFIELD without options.groundMesh (or without the required heightfield parameters like pointCount/size/scale), hitting the else branch at havokPlugin.ts:1876.

Common situations: Passing a regular mesh as ground without the heightfield-specific options; using PhysicsShapeHeightfield with an options object missing minHeight/maxHeight or dimension fields; copy-pasting a MESH shape config and only changing the type.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• No mesh provided to create physics shape.
• Unknown motion type: ${type}
• Unsupported Shape Type.
• Unsupported Constraint Type.
• Unsupported Physics plugin version.

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/aae745b09d8acf27. Report an issue: GitHub.