Utility Scripts · Body Penetration

Relationships and Snapshots

Read actual depth, state and geometry for one Tip–target connection.

JoltPenetrationRelationship is created automatically and has no public method for forced capture or termination. Remove the owning Tip or destroy the relevant body to end it explicitly. A snapshot is a copy at the time of reading; editing it does not control the solver.

Method	Meaning
rel.is_valid()	Bool: the relationship still exists in the current world.
rel.get_depth()	Real in metres, max(0, signed_depth). Check validity before reading.
rel.get_snapshot()	Struct or undefined; GML resolves a target wrapper from target_handle.

var rel = tip.get_relationship();
if (is_struct(rel) && rel.is_valid()) {
    var snapshot = rel.get_snapshot();
    if (is_struct(snapshot) && snapshot.has_entered) {
        show_debug_message("Depth: " + string(snapshot.depth) + " m");
        show_debug_message("Progress: " + string(snapshot.depth_percent) + "%");
    }
}

Snapshot fields#

Fields	Type / units	Meaning
schema	1	Data-structure version.
handle / tip_handle / penetrator_handle / target_handle	Handles	Identities of the relationship, Tip and both bodies.
target	JoltBody / undefined	Managed target wrapper added by get_snapshot(). Not added to native event snapshots.
state / phase	Integer	Public JoltPenetrationState and low-level phase: 1 Engaging, 2 Engaged, 3 Releasing. Do not mix these enums.
has_entered	Bool	The relationship has reached actual entry. It does not revert to false during later extraction.
signed_depth / depth / max_depth	m	Depth along the axis from entry; signed_depth may be negative and depth is nonnegative. max_depth is the effective limit.
depth_percent	% / 0–100	Depth relative to the limit, clamped to 0–100. Inspect signed_depth rather than this percentage for overshoot.
axial_speed	m/s	Relative Tip speed: positive inward, negative outward.
tip_position / entry / axis	{x,y,z}	Current world-space Tip point, entry point and normalized channel axis. The frame moves with a Dynamic target.
lateral_error	m	Tip displacement away from the channel axis.
angle_error	rad	Deviation from the captured relative orientation; not the impact angle in degrees.
embedded / at_limit	Bool	Derived resting state inside material / reaching the depth-limit region.
suppressed / clearance	Bool	Owned pair-collision suppression / geometric clearance result.
forward_force / backward_force	N	Resistance captured for this relationship.
motor_lambda / limit_lambda / sample_valid	Solver sample	Impulse quantities of the last solver sample and its validity. They are not automatically forces in N and may be invalid while sleeping.
capture_source	0–4	0 original, 1 query, 2 contact-assisted, 3 support with current intent, 4 support with earlier valid evidence.
step_serial / revision	Integer	Simulation step and snapshot revision. Model 2 can produce multiple revisions within one outer step.

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
JoltPenetrationRelationship.get_depth	JoltPenetrationRelationship.get_depth()	Nonnegative depth in m; native failure can yield 0, check is_valid and error.
JoltPenetrationRelationship.get_snapshot	JoltPenetrationRelationship.get_snapshot()	Detached schema snapshot with managed target added, or undefined. The relationship does not own the target body.
JoltPenetrationRelationship.is_valid	JoltPenetrationRelationship.is_valid()	Boolean relationship existence in the current world.