What Penetration Does
Let a body's tip physically enter another body, remain embedded and be pulled out again.
Penetration connects a Dynamic penetrator to an enabled target. A valid hit creates a guided channel: the body can slide inward and outward along its entry axis while a physics constraint holds lateral displacement and relative rotation. Forces, mass and gravity still determine motion.
Three concepts to understand#
| Concept | What it represents |
|---|---|
| Target | An ordinary Static or Dynamic body enabled through jolt_penetration_target(). It defines resistance and a depth limit. |
| Tip | An authored point on the penetrator's front surface and its local axis. It is not another collider or a new body. |
| Relationship | A temporary connection between one Tip and one target. It stores entry position, depth and state, and is created automatically. |
Interaction sequence#
Free motion → candidate near a surface → Captured → actual entry / Start → insertion or Embedded → extraction → full clearance → rearm → another hit. Several states can occur within one gameplay step.
Where it fits#
Use it for a dart, nail, spike or fork that should remain in a physical target. The target can move and receives physical reaction. Penetration does not cut a mesh hole, deform material or subtract health; your project implements visual marks and gameplay responses using snapshots and events.
Learning path#
- Start with First Working Scene and verify a simple Box against a Static Box.
- Then adjust target resistance, Tip placement and max_angle in the configuration chapters.
- Use the Tip, relationship and event references when integrating your game. For rejected hits, use the diagnostic table.
Penetration updates inside the normal jolt_update(). Do not add another penetration step or call jolt_update for every Tip.