Limits and Performance
Design interactions around supported geometry and capacity, rather than treating this as a general material-destruction simulator.
Penetration implements guided entry and axial movement of rigid bodies. The corrected 60 Hz capture path supports ordinary gravity hits in the tested range, but it is not unlimited CCD, mesh cutting or an automatic material-energy model.
Fixed capacities#
| Resource | Limit |
|---|---|
| Tips in one world | 128 |
| Relationships in one world | 32 |
| Relationships per Tip | 1–32; max_simultaneous_penetrations |
| Event queue | 256 |
| Candidate buffer per search | 32 |
More Tips do not increase world relationship capacity. One hundred Tips therefore cannot create one hundred simultaneous connections. Overflow rejects creation safely; inspect CapacityFull and candidate_drops. Dense surroundings can exhaust the candidate buffer even with few active relationships.
Runtime cost#
Cost grows with free Tips, nearby bodies, geometry queries and active constraints. Model 2 can add internal physics/admission segments near impact or a depth limit; this segments the shared world, not an isolated tip. Segment count is bounded and is not a public tuning parameter.
- Disable unused tips with set_enabled(false) and clean up removed tools.
- Configure once or when settings actually change, not every Step.
- Read the snapshots you need and drain the event queue once. Disable debug rendering when unnecessary.
- Do not disable collision pairs for performance if they should be penetrable; admission requires a valid collision policy.
The depth limit is not an absolute geometric clamp#
max_depth limits a physics slider. Solver tolerance and brief transient overshoot remain possible, especially with fast or multiply connected bodies. If gameplay depends on reaching the limit, inspect at_limit and signed_depth; depth_percent does not prove geometry never exceeded the maximum.
What to verify in your scene#
- The exact collider and local tip, not just the rendered model's appearance.
- Rotating or strongly accelerating Dynamic targets, boundary angles and simultaneous hits on many bodies.
- Interactions with other constraints; incompatible channels and user constraints may block admission.
- Very thin obstacles and extreme speeds. Checking blockers in the capture region does not replace global CCD for all preceding motion.