Utility Scripts · Body Penetration

Tip Placement and Configuration

Place the Tip on the actual front surface and point its axis along the intended insertion direction.

jolt_penetrator_tip(body) prepares an inactive model 2 JoltPenetrator. Set position/axis with set_local_position/set_local_axis, then activate with set_enabled(true). The (body, config) overload still creates immediately and retains default model 1. The penetrator must be a Dynamic non-sensor body with a supported solid shape. Supply position and axis in body-local space, not world space; body rotation then transforms them into the world.

tip = jolt_penetrator_tip(penetrator, {
    local_position: { x: 0, y: 0, z: -0.4 },
    local_axis: { x: 0, y: 0, z: -1 },
    capture_model: 2,
    max_angle: 40,
    max_insertion: 0.2,
    mask: 1
});

Core configuration#

Name	Default / range	Meaning
enabled	false / legacy config: true	Enables admission for this Tip.
local_position	{x:0,y:0,z:0}	Finite local point on the collision shape's front surface.
local_axis	{x:0,y:0,z:1}	Finite nonzero vector. It is normalized; its positive direction means insertion.
mask	4294967295 / uint32	Allowed target category_bits; at least one bit must overlap.
max_angle	20° / 0 ≤ angle < 90°	Maximum current angle between the axis and the target's inward normal.
max_insertion	0.5 m / > 0	Tip insertion limit relative to the entry point.
max_simultaneous_penetrations	1 / integer 1–32	Maximum simultaneous relationships on one Tip; world capacity also applies.
max_capture_axial_speed	0 m/s / ≥ 0	0 disables this speed cap. A positive value caps relative axial speed at admission, not subsequent movement.
capture_model	2 setters / 1 legacy config; 0, 1, 2, 3	A newly prepared setter object uses model 2. The config-struct overload retains default model 1. Opt into model 3 with JOLT_PENETRATION_CAPTURE_STRICT_PREDICTIVE.

Capture model 2 parameters#

Name	Default / range	Meaning
probe_length	0.05 m / 0 < x ≤ 1	Axis-surface search length. Support geometry can justify a longer ray; this setting does not authorize capture across a larger gap.
probe_radius	0 m / 0 ≤ x ≤ 0.1	Expands candidate search around the axis. It is not another collider or permission for a side hit.
capture_gap	0.001 m / 0 < x ≤ 0.005	Maximum positive gap of the leading support in front of the verified surface.
capture_overlap	0.02 m / 0 < x ≤ 0.03	Maximum initial authored-Tip intrusion measured along the surface normal. This is not the final max_depth.
tip_surface_tolerance	0.001 m / 0 < x ≤ 0.002	Tolerance for registering the Tip on the front surface.
rearm_separation	0.01 m / 0 < x ≤ 1	Clearance needed to rearm after extraction; the body is checked as well as the Tip point.
contact_assisted	true	Retained model 1 setting. It does not change model 2 decisions or toggle segmentation or support geometry.
contact_tolerance	0.02 m / 0 < x ≤ 0.1	Original tolerance; modern models also use an explicitly supplied value as a fallback for probe_length and rearm_separation at creation. Prefer the dedicated parameters.

configure() first loads the full current configuration. Changing contact_tolerance alone therefore does not replace the existing probe_length or rearm_separation. Numbers must be finite; out-of-range values are rejected. Unknown keys are not public settings and have no guaranteed effect.

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
jolt_penetrator_tip	jolt_penetrator_tip(body,config=undefined)	Live Body; without config returns a pending inactive JoltPenetrator (handle 0), with config activates according to enabled (default true). undefined on failure. Note capture_model defaults differ: builder 2, direct options omitting the field 1. Explicitly select JOLT_PENETRATION_CAPTURE_STRICT_PREDICTIVE (3) for Strict Predictive.