Character Movement
Controls normalized planar input, direct velocity, and GameMaker-side synchronization.
set_move(x, y) stores persistent planar input. During every fixed physics step the native controller clamps its length to 1, multiplies it by speed, rotates it by the optional reference frame, and cancels movement into overly steep slopes.
Planar movement#
// Step event: input may range from -1 to 1.
var move_x = keyboard_check(ord("D")) - keyboard_check(ord("A"));
var move_y = keyboard_check(ord("W")) - keyboard_check(ord("S"));
player.set_move(move_x, move_y);
jolt_update();
player.sync();Speed#
player.set_speed(6.5);
var speed = player.get_speed();Speed must be finite and non-negative. It is the magnitude of the desired planar movement in world units per second.
Direct velocity#
player.set_velocity(push_x, push_y, push_z);
var velocity = player.get_velocity();Direct velocity is expressed in public world coordinates. The next character step rebuilds horizontal motion from set_move(), while preserving vertical motion relative to the current up vector.
Movement values#
| Method | Meaning |
|---|---|
| get_world_move_velocity() | Desired movement after reference-frame rotation, normalization, speed, and steep-slope cancellation. |
| get_velocity() | Current native linear velocity, including vertical motion and impulses. |
| get_reference_frame_velocity() | Linear velocity of the configured reference body. |
| get_reference_frame_angular_velocity() | Angular velocity of the configured reference body. |
Teleporting#
player.set_position(target_x, target_y, target_z);
var feet = player.get_position();set_position() moves the controller's base point immediately. It does not perform a swept movement test, so use it for spawning or deliberate teleportation rather than ordinary locomotion.
Runtime mass, gravity and pushing#
| API | Contract |
|---|---|
| player.set_mass(value) / get_mass() | Finite mass > 0; affects CharacterVirtual interaction with rigid bodies, not a conversion to JoltBody. |
| player.set_gravity(value) / get_gravity() | Finite nonnegative gravity magnitude in units/s². Default direction is world -Z; reference-frame gravity uses -up. |
| player.set_max_strength(value) / get_max_strength() | Finite nonnegative maximum force for pushing rigid bodies. |
| player.set_max_strength(value) / get_max_push_force() | Aliases of set_max_strength/get_max_strength; not the character-to-character push setting. |
// player is a validated JoltCharacter; submit changes before jolt_update().
if (!player.set_mass(80)) show_debug_message(jolt_get_error_message());
if (!player.set_gravity(9.81)) show_debug_message(jolt_get_error_message());
if (!player.set_max_strength(500)) show_debug_message(jolt_get_error_message());Ground Friction a Air Movement#
Original movement applies with the opt-in modes disabled. Ground Friction and Air Movement change traction and own horizontal velocity. Explosion external impulse has separate state and is not automatically erased by the next set_move. Character has no public add_impulse method; use a supported system such as jolt_explosion with include_characters.
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.
| Symbol / owner | Signature | Operation contract |
|---|---|---|
| JoltCharacter.get_gravity | JoltCharacter.get_gravity() | Gravity magnitude: current numeric value in m/s². Failure: undefined; an invalid object is not a zero measurement. |
| JoltCharacter.get_mass | JoltCharacter.get_mass() | Mass: current numeric value in kg. Failure: undefined; an invalid object is not a zero measurement. |
| JoltCharacter.get_max_strength | JoltCharacter.get_max_strength() | Maximum pushing force: current numeric value in N. Failure: undefined; an invalid object is not a zero measurement. |
| JoltCharacter.get_speed | JoltCharacter.get_speed() | Walking speed: current numeric value in m/s. Failure: undefined; an invalid object is not a zero measurement. |
| JoltCharacter.get_velocity | JoltCharacter.get_velocity() | Current world velocity {x, y, z} in m/s, undefined on error. |
| JoltCharacter.set_gravity | JoltCharacter.set_gravity(value) | Gravity magnitude: finite number ≥0 m/s²; default 9.81. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltCharacter.set_mass | JoltCharacter.set_mass(value) | Mass: finite number >0 kg; default 80. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltCharacter.set_max_strength | JoltCharacter.set_max_strength(value) | Maximum pushing force: finite number ≥0 N; default 100. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltCharacter.set_move | JoltCharacter.set_move(x, y) | Two finite input axes x/y, conventionally -1..1; Boolean. Movement request for subsequent steps, not a teleport or impulse. A reference frame can rotate the direction. |
| JoltCharacter.set_speed | JoltCharacter.set_speed(value) | Walking speed: finite number ≥0 m/s; default 5. Returns true on acceptance, false for an invalid input or object. Updates the live object. |
| JoltCharacter.set_velocity | JoltCharacter.set_velocity(x, y, z) | Finite world x/y/z in m/s; Boolean. Direct velocity assignment clears stored air/ground momentum and external impulse; rejected while attached. |