Penetration history
Records of actual entries live on the target body without changing physics.
target_body.set_penetration_history_capacity(32);
var records = target_body.get_penetration_records();
var count = target_body.get_penetration_record_count();Capacity is an integer from 0 to 4096; default 0 disables recording. The limit applies to completed records; protected active records may take the total above capacity. Shrinking retains the newest completed records. Enabling does not reconstruct arbitrary past penetrations.
Record#
| Field | Meaning |
|---|---|
| id, active | Record identity and active penetration state. |
| entry_step, end_step, end_reason | Physics step serials and numeric termination reason. |
| source_body, source_tip | Source identifiers, not guarantees of live wrappers. |
| local_position, local_axis, local_normal, local_rotation | Target-local values; XYZW rotation. |
| max_depth_reached, current_depth, final_depth | Depths in metres; final_depth is null while active. |
get_penetration_record(index) uses zero-based indexing and returns undefined out of range. get_penetration_records() returns a snapshot copy. clear_penetration_history() clears only completed records, preserving active relationships. Capacity 0 removes active history records too, but does not remove physical relationships.
Debug#
jolt_debug_enable(true);
jolt_debug_set(JOLT_DEBUG_PENETRATION, true);
jolt_debug_set_penetration_history(true);Debug shows at most the newest five stored records per target. History does not create damage, mesh holes or permanent deformation.
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 |
|---|---|---|
| JoltBody.get_penetration_history_capacity | JoltBody.get_penetration_history_capacity() | Numeric capacity / current record count; 0 on error. Count can exceed the completed-record capacity due to protected active records. |
| JoltBody.get_penetration_record_count | JoltBody.get_penetration_record_count() | Numeric capacity / current record count; 0 on error. Count can exceed the completed-record capacity due to protected active records. |
| JoltBody.get_penetration_records | JoltBody.get_penetration_records() | Detached snapshots, oldest entry ID first; error returns []. Not references to live relationships. |
Complete API declarations#
Declarations match the production GML sources. A value after = marks an optional argument. This is a signature inventory; the guide sections describe meaning, units and limitations. The type before a dot identifies the method owner, not a global function.