Moving Platforms

Follows translating or rotating bodies and optionally makes their local +Z the character's up direction.

Normal ground velocity is already used when a grounded character stands on a moving body. set_reference_frame() adds explicit transform following for rotating frames, vehicles, ships, or local-gravity environments.

Ordinary platform motion#

On walkable ground, the controller starts its velocity from get_ground_velocity(). A translating dynamic or kinematic platform therefore carries the character without requiring a reference frame.

Rotating reference frame#

player.set_reference_frame(platform_body, false);

// Movement input is rotated with the platform.
player.set_move(input_x, input_y);
jolt_update();

• The character position and rotation follow the body's center-of-mass transform delta.
• The current up vector follows the body's local +Z axis.
• Existing character velocity is rotated with the frame.
• Frame linear and angular velocity are removed from the relative contact solve to avoid applying the motion twice.

Local gravity#

player.set_reference_frame(planet_body, true);
player.set_reference_frame_gravity(true);

var up = player.get_up();

With reference-frame gravity enabled, gravity acts opposite the character's current up vector. Otherwise gravity remains global -Z even though movement is rotated by the frame.

Frame information#

var platform = player.get_reference_frame();
var linear = player.get_reference_frame_velocity();
var angular = player.get_reference_frame_angular_velocity();
var desired = player.get_world_move_velocity();

Leaving the frame#

player.clear_reference_frame();

Clearing restores +Z as up, rotates the character back into the world-up orientation, clears cached frame motion, and disables local-gravity mode.

Read the gravity mode#

var uses_local_gravity = player.get_reference_frame_gravity();

get_reference_frame_gravity() reads whether gravity follows the frame's local up direction. It does not return an acceleration vector. For magnitude use get_gravity(); for current orientation use get_up().

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.