Ammo.js Character Controller Step Height Guide

This article explains how the step height parameter influences stairs traversal for a kinematic character controller in the ammo.js physics library. It covers the underlying physics mechanics of step detection, the consequences of misconfiguring this value, and practical tips for achieving smooth vertical movement over obstacles and staircases.

Understanding the Step Height Parameter

In ammo.js (a JavaScript port of the Bullet physics engine), the btKinematicCharacterController relies on a specific parameter called stepHeight to handle vertical obstacles. This parameter defines the maximum vertical height of an obstacle, such as a stair riser or a curb, that the character can automatically step over without jumping or losing forward momentum.

When a character moves forward and collides with an object, the character controller performs a series of collision sweeps. If the vertical distance from the character’s feet to the top of the colliding surface is less than or equal to the configured stepHeight, the controller temporarily lifts the character up to the top of the obstacle and allows forward movement to continue.

How Step Height Affects Stair Traversal

1. Step Height is Too Low

If the stepHeight is set to a value smaller than the height of the individual stair risers in your 3D environment, the character controller will treat each step as a solid wall. The collision sweep will fail to find a valid path over the step, causing the character to get stuck at the base of the staircase or require a jump force to proceed.

2. Step Height is Too High

Setting the stepHeight too high allows characters to effortlessly glide over massive obstacles, such as crates, low walls, or steep ledges that should normally block passage. Additionally, excessively high values can cause the character to “teleport” or snap violently to the top of structures, leading to an unrealistic and jarring visual experience for the player.

3. Smooth Step-Up and Step-Down Mechanics

Stair traversal requires a balance of stepping up and stepping down: * Stepping Up: The controller detects the step within the stepHeight limit and offsets the character upward. * Stepping Down: While step height handles upward movement, moving down stairs requires proper gravity or step-down logic. If the character moves forward off a step, they may float temporarily before gravity pulls them down unless the controller is configured to snap to the ground.

Best Practices for Configuration

To achieve smooth stairs traversal in your ammo.js project, implement the following practices:

• Match Step Height to Asset Metrics: Measure the exact height of the stairs in your 3D modeling software (e.g., Blender) and set the stepHeight parameter slightly higher than the height of a single step riser to account for floating-point inaccuracies.
• Adjust Character Margin: Ensure the collision margin of your character’s shape (usually a capsule) is properly tuned. A margin that is too large can interfere with the precision of the step detection sweep.
• Complement with Max Slope Angle: Use the setMaxSlope method in conjunction with step height. While step height handles vertical cliffs (stairs), the max slope angle prevents the character from walking up excessively steep ramps.