[Lengthy] Box3D Technical Feedback + Questions For Erin

[coreysaintpierre]

Hi Erin,

We've been doing a fairly deep integration and validation pass with Box3D for a deterministic game simulation. I wanted to share a few observations and questions that came out of that work because they may be useful feedback for Box3D itself.

I'm intentionally keeping the application details abstract, but the relevant simulation shape is straightforward: one fast dynamic sphere interacting with a dense static field of convex/static objects, with an application-owned fixed logical tick and a requirement to identify exact collision boundaries while still allowing Box3D to own the actual contact graph and rigid-body response.

We're currently pinned to Box3D commit:

954cf879e717334eb96da9a5c255788fdc9f5f87

We have not modified Box3D source.

What we've liked

The overall experience with Box3D has been very positive.

In particular:

• The collision/query API has been extremely useful for building deterministic application-side diagnostics without replacing the solver.
• The engine source has been readable enough that we could trace behavior causally rather than treating the simulation as a black box.
• Contact recycling, speculative contacts, fast-body classification, CCD and solver staging have all behaved consistently once we understood their interaction.
• Native multi-contact solving is something we increasingly want to preserve rather than reproduce ourselves.
• The public tuning/control surface has been unusually useful for advanced investigation: body safety factor, contact recycling controls, public collision queries, contact events, material controls, counters, etc.
• Performance has been excellent. In one release-mode target-hardware test using 1,000 static spheres, five static walls and one dynamic sphere, a full contact-refresh operation of the type described below measured only tens of microseconds.

The biggest takeaway from our investigation is that the engine has given us enough control to solve an unusual scheduling requirement through public APIs. We have not found a technical justification for maintaining a Box3D fork.

We can provide minimized standalone repros, measurements or source-level traces for anything below if useful.

1. Is a zero-time world step an intentional public contract?

This is our most important question.

We've experimentally found that:

b3World_Step(world, 0.0f, subStepCount)

performs the broad-phase/contact update and narrow-phase refresh without positive-time solver integration.

That behavior is extremely useful for us.

Our application sometimes establishes an additional collision boundary inside one logical gameplay tick. At that boundary we need Box3D to recompute the native contact graph from the body's current transform without advancing simulation time.

A zero-dt step has given us exactly that operation.

Our question is:

Is b3World_Step(world, 0, ...) intentionally supported as a contact-refresh operation that applications can rely on long-term?

If yes, simply documenting that guarantee would be very useful.

If not, what public mechanism would you recommend for:

Update broad-phase/contact state and recompute current contact manifolds without advancing simulation time?

An explicit operation conceptually similar to:

b3World_RefreshContacts(world)

would map very cleanly to our use case.

We would much rather depend on an intentional Box3D contract than on behavior that merely happens to follow from the current implementation.

2. Scoped contact-recycling override during refresh

We found a specific interaction between externally partitioned world steps and contact recycling.

A simplified case is:

1. A non-touching contact object already exists.
2. The application advances the world through a very short positive-time segment.
3. During that segment the geometry becomes manifold-valid.
4. The body's motion during this new shortened outer step is below its fast-body threshold.
5. At the next contact update, cached non-touching contact state can be recycled instead of recomputed.

The geometry can therefore be valid while the cached contact still reports non-touching.

We isolated this against the b3_isFast path and contact-recycle distance.

The cleanest public workaround we've measured is:

float oldDistance = b3World_GetContactRecycleDistance(world);

b3World_SetContactRecycleDistance(world, 0.0f);
b3World_Step(world, 0.0f, 1);
b3World_SetContactRecycleDistance(world, oldDistance);

This forces the boundary refresh to recompute existing cached contacts, after which normal recycling immediately resumes.

We've tested this fairly aggressively:

• natural contact populations;
• sphere/sphere contacts;
• hull/sphere contacts;
• mixed sphere + hull scenes;
• simultaneous wall/corner contacts;
• populated scenes;
• a 1,000-static-sphere scale fixture.

In the 1,000-sphere release test, the pulse recovered the intentionally stale target while producing zero observed non-target touching/begin/end/hit changes across the other 999 spheres plus five walls.

Total pulse cost on the target machine was:

• p50: 22.473 us
• p95: 36.353 us

For comparison, one 120 Hz logical tick is approximately 8333 us.

The public workaround is therefore both effective and inexpensive for our workload.

Still, conceptually we're changing persistent world state in order to request behavior for one refresh operation.

Would something like a scoped refresh option make sense?

Conceptually:

b3World_RefreshContacts(world, disableRecyclingForThisRefresh);

or an equivalent step option.

That would make the intent clearer and eliminate the need for applications to temporarily mutate and restore the global recycle distance.

3. Targeted refresh/invalidation of existing body contacts

We also looked at the per-body contact-recycling API.

Current documentation correctly notes that changing body contact-recycling state only affects subsequently created contacts; existing contacts keep the recycling state with which they were created.

That makes sense architecturally, but it means it cannot be used to invalidate an already-existing stale contact pair.

A potentially useful advanced API might be something along the lines of:

• refresh existing contacts involving this body;
• invalidate cached manifolds for this body's contacts;
• force narrow-phase recomputation for this body.

We do not need this for performance; the world-level refresh is already very inexpensive in our tests, but such an operation could express the application's intent more narrowly.

Character controllers, externally scheduled projectiles, deterministic gameplay simulations and similar systems might conceivably have related use cases.

4. Outer world-step partitioning versus solver substeps

One of the more interesting things we learned is that splitting one logical interval into multiple calls to b3World_Step is meaningfully different from keeping one outer step and increasing the Box3D substep count.

The outer boundary changes more than integration resolution.

In our experiments it affected:

• when broad-phase/contact creation occurs;
• when narrow phase recomputes manifolds;
• contact begin/end lifecycle;
• contact recycling;
• cached-transform reuse;
• the displacement history relevant to b3_isFast.

For example, a body that would qualify as fast over the complete logical interval can become non-fast when that interval is externally partitioned into a much shorter first world step. That in turn can make an existing non-touching pair eligible for recycling.

This is internally consistent, but it is not necessarily an obvious consequence for users treating substeps and outer partitions as two ways of increasing temporal resolution.

A documentation note along the lines of:

Repeated outer world steps are not equivalent to solver substeps; outer steps create additional collision/contact lifecycle boundaries and can affect CCD/fast-body/contact-recycling behavior.

might save advanced users some investigation.

5. Shape-pair differences in speculative contact behavior

Another useful thing we discovered was how materially different primitive pairs can be with respect to speculative contact construction.

For the cases relevant to us:

• sphere/sphere contact requires actual combined-radius overlap;
• hull/sphere contact can produce a manifold at positive separation inside B3_SPECULATIVE_DISTANCE.

That distinction had major consequences for externally scheduled collision boundaries.

We eventually mapped the hull/sphere transition experimentally at approximately the engine's 20 mm speculative distance and confirmed the source behavior.

The general documentation already explains speculative contacts well, but a more explicit indication of which primitive-pair manifold routines create positive-separation speculative contacts versus requiring actual overlap might be useful for people building precise collision scheduling or debugging contact timing.

We're not suggesting those semantics should change; only that their differences are significant enough to be worth surfacing.

6. Contact events during a contact-only refresh

A related contract question:

During the zero-time refresh described above, we observe begin/end contact state transitions without positive-time integration or a collision impulse. Native hit events then occur on the subsequent positive-time solver step when appropriate.

That distinction is actually useful to us:

• touching/begin describes contact-graph membership;
• hit describes a causal solver interaction.

Is that event behavior under dt == 0 intentional and stable?

If zero-time stepping is intended to be supported, documenting its event semantics would be particularly helpful.

Summary

The questions we'd most value guidance on are:

1. Is zero-dt b3World_Step intentionally supported as a contact-refresh operation?
2. If not, what public operation would you recommend for recomputing the current contact graph without advancing time?
3. Would a scoped no-recycling contact refresh be a useful public API?
4. Is there interest in a targeted existing-contact refresh/invalidation operation for one body?
5. Would you consider documenting the non-equivalence of outer-step partitioning and solver substeps with respect to contact lifecycle / fast-body / recycling behavior?
6. Would more explicit documentation of shape-pair speculative-manifold behavior be useful?
7. If zero-time stepping is supported, are its begin/end contact-event semantics also intended to be part of that contract?

We're treating any application-specific response-law differences as our responsibility rather than as a Box3D change request.

None of these questions are blocking us today; we have a public-API implementation that works extremely well in our measured workload. The main thing we want to avoid is building long-term architecture around an accidental zero-dt stepping contract if that isn't how you intend Box3D to be used.

If any of this is interesting, we're happy to provide small standalone repros rather than application code, including a minimal short-partition stale-contact case, mixed sphere/hull case, corner case, and the 1,000-static-body performance benchmark.

Thanks for building Box3D. We've spent enough time inside it now to appreciate how much difficult machinery it is quietly handling for us.