Character

Ground Detection

Reads the CharacterVirtual support state, surface data, and landing transitions.

The controller updates its ground support every native step. Read the state after jolt_update() so it describes the latest completed simulation.

Ground states#

Constant	Value	Meaning
JOLT_CHARACTER_GROUND_ON_GROUND	0	Supported by a walkable surface.
JOLT_CHARACTER_GROUND_ON_STEEP	1	Touching support that exceeds max_slope.
JOLT_CHARACTER_GROUND_NOT_SUPPORTED	2	Contact exists, but it does not currently support the character.
JOLT_CHARACTER_GROUND_IN_AIR	3	No supporting contact.

State checks#

var state = player.get_ground_state();
if (player.is_grounded()) {
    // On a walkable surface.
} else if (player.is_on_steep_ground()) {
    // Touching a slope that cannot be climbed.
} else if (player.is_in_air()) {
    // Fully airborne.
}

Surface information#

var normal = player.get_ground_normal();
var point = player.get_ground_position();
var velocity = player.get_ground_velocity();
var body = player.get_ground_body();
var entity = player.get_ground_entity();

Method	Result
get_ground_normal()	Supporting surface normal.
get_ground_position()	World-space contact position.
get_ground_velocity()	Velocity of the supporting surface at the contact.
get_ground_body()	Managed JoltBody or undefined when unavailable.
get_ground_entity()	That body's user_data, commonly a bound instance.

Transition events#

if (player.just_landed()) {
    effect_create_above(ef_smoke, x, y, 0, c_white);
}

if (player.just_left_ground()) {
    // Start falling animation.
}

Both flags cover the complete jolt_update() call, even when it performs multiple fixed steps.

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_ground_body	JoltCharacter.get_ground_body()	Managed support JoltBody or its user_data; undefined if no matching live wrapper or on error.
JoltCharacter.get_ground_entity	JoltCharacter.get_ground_entity()	Managed support JoltBody or its user_data; undefined if no matching live wrapper or on error.
JoltCharacter.get_ground_normal	JoltCharacter.get_ground_normal()	Support normal: world {x, y, z}, jednotkový vektor / unit vector; undefined on error. Read support data together with ground_state.
JoltCharacter.get_ground_position	JoltCharacter.get_ground_position()	Support position: world {x, y, z}, m; undefined on error. Read support data together with ground_state.
JoltCharacter.get_ground_state	JoltCharacter.get_ground_state()	JOLT_CHARACTER_GROUND_* enum, undefined on error; latest solver state.
JoltCharacter.get_ground_velocity	JoltCharacter.get_ground_velocity()	Support velocity: world {x, y, z}, m/s; undefined on error. Read support data together with ground_state.
JoltCharacter.is_grounded	JoltCharacter.is_grounded()	Boolean derived from ground_state; is_in_air includes IN_AIR and NOT_SUPPORTED. A read error yields false, not proof of ground support.
JoltCharacter.is_in_air	JoltCharacter.is_in_air()	Boolean derived from ground_state; is_in_air includes IN_AIR and NOT_SUPPORTED. A read error yields false, not proof of ground support.
JoltCharacter.is_on_steep_ground	JoltCharacter.is_on_steep_ground()	Boolean derived from ground_state; is_in_air includes IN_AIR and NOT_SUPPORTED. A read error yields false, not proof of ground support.
JoltCharacter.just_landed	JoltCharacter.just_landed()	Boolean event for the managed frame; read after jolt_update. The next managed frame begin clears it. Not persistent state (e.g. just_landed is not is_grounded).
JoltCharacter.just_left_ground	JoltCharacter.just_left_ground()	Boolean event for the managed frame; read after jolt_update. The next managed frame begin clears it. Not persistent state (e.g. just_landed is not is_grounded).