docs: Point users to NarrowPhaseConfig::prediction_distance

[johanhelsing]

Objective

I tripped up on collisions, because I considered the units as meters, but the default value for prediction distance is 1 (presumably pixels)

Solution

Most of the documentation links to the ContactReportingPlugin when talking about contacts.

So link from there to NarrowPhaseConfig::prediction_distance, so they can follow the trail.

[Jondolf]

The recommended units are currently pixels in 2D and meters in 3D, which applies to the prediction distance as well. Once we add physics scale like pixels_per_meter, 2D can perhaps be handled more conveniently.

I'm a bit unsure if we want to have the part about bodies being considered colliding with the penetration distance in the docs though, because I consider the behavior to be somewhat incorrect. The prediction distance is used just to avoid missing collisions; the narrow phase collects all contacts before the solver starts, and the constraints can later move bodies around into penetrating states, which would only be detected during the next frame without the extra margin. It only causes a collision response if the bodies are actually penetrating though, so people would expect it to skip sending collision events for non-penetrating collisions.

I made an issue about this (#224) and will try to fix it for 0.4

[johanhelsing]

Alright, just wanted make sure it's possible to figure out how to use the engine correctly...

Are you sure it's not simpler to just use meters everywhere?

• get rids of the weirdness surrounding the value of default gravity
• the actual values of mass, velocities, forces etc. will be in a more natural range that's easier for humans to reason about.
• Not all games are pixel-based either. 3D games with 2d physics are not uncommon either.
• Matches the conventions in other 2d physics engines (rapier, Unity/box2d)
• 2D and 3D have less differences/special cases