Capture, Angles and Motion

A valid hit must satisfy surface, axis, angle, motion and filtering requirements together.

Model 2 uses the collision shape's leading support to measure surface proximity and the Tip axis separately to find the logical entry point. A tilted Box corner can touch before a Tip at the centre of its face. This is ordinary geometry, not automatically a side hit.

What impact angle means#

0° means the Tip axis points straight into the surface. max_angle=40 allows a current axis up to approximately 40° when other requirements pass. This is not the body's angle to world Z: target orientation and the actual surface normal also matter. A rotating body may start at 35° and be beyond the limit at impact.

Inward motion#

Relative Tip-point velocity must have positive components along the axis and into the surface. Model 2 accepts directions between the Tip axis and inward normal. Residual velocity outside this cone is limited to max(0.25, min(axial_speed, inward_speed) * tan(min(max_angle, 80°))) m/s. A fast knife's modest ballistic drop is therefore not rejected solely by a fixed lateral speed threshold; outward motion and parallel sliding are still rejected.

Authored relative angular velocity is limited to 0.5 rad/s. Short-lived incoming-motion evidence helps distinguish collision-generated rotation; it never authorizes capture by itself. Current surface, motion, angle and other conditions are revalidated. External transform, velocity or applied-force changes invalidate that evidence.

Capture at 60 Hz#

Current model 2 may split one gameplay physics step into shorter segments near impact and rerun admission between them. The surface no longer has to happen to land in a single snapshot. Keep your normal game update; do not add extra jolt_update calls or enlarge capture_overlap to compensate for drop speed.

The surface must be real#

• Both the axis ray and support projection must confirm the same finite target and compatible surface normals.
• The hit must be in the penetrator's front region. Back, side and parallel hits are rejected.
• Another blocking body in the capture region can prevent a relationship.
• Normal agreement is conservative on curved targets; a supported shape does not make every hit valid.

Choosing a model#

Strict Predictive: actual tip entry#

tip.set_capture_model(JOLT_PENETRATION_CAPTURE_STRICT_PREDICTIVE);
tip.set_max_angle(70);
// Configure the local position at the collision apex and the inward axis
// before calling tip.set_enabled(true).

Model 3 follows actual point motion, including tool rotation and target movement. Prediction may shorten a physics segment but cannot pull the body or suppress collisions. A relationship requires fresh validation of the finite surface, same SubShape, normal, current angle, inward movement and blockers. A longer probe_length does not permit passing a wall.

For a knife use one Dynamic Compound: a handle Box, a recessed blade shape and a pointed/tapered Convex tip. The Tip is a local apex point and insertion axis, not another rigid Body. A broad Box face can hit before its central Tip; bouncing or sliding is correct in this mode. Collision geometry, rather than the rendered mesh, determines this behavior.

Strict uses a fixed 0.00001 m numerical tolerance and at most 0.002 m initial depth; deeper missed entries are rejected. The Tip must lie on the actual leading surface within 0.00001 m. capture_gap, capture_overlap and tip_surface_tolerance do not enlarge these strict bounds. max_angle=70 permits a current deviation from the normal up to 70° (roughly 20–160° on a protractor), not guaranteed entry after bouncing or rotating. Neither default model nor default max_angle changes.

Search is bounded: at most 32 candidates, a horizon up to 50 ms, reach up to 4 m and at most eight prediction pieces. Budget overflow and unverifiable crossings fail closed. Adjacent Compound children remain conservative: SubShape identity is not bypassed. After an observed blocker, retreat the tip; reacquiring a candidate behind it must not bypass the rejection.