Physics in Nu

NOTE: mention how center of mass offsets are non-existent in Nu's 3D due to this issue: https://github.com/bryanedds/Nu/issues/575

TODO: basic content.

Nu has two physics engines, AetherPhysics for 2D and Bullet Physics for 3D.

The most recent manual for Bullet Physics I've found is here -

https://github.com/bulletphysics/bullet3/blob/master/docs/Bullet_User_Manual.pdf

Fast Imperative Physics Behind a Purely Functional API?

This might seem impossible, but with a technique we developed, it is actually entirely possible to wrap any imperative representation behind a purely functional API so long as it can support certain operations -

TODO: more detail.

Beware of Collision Message Filtering by BodyIndex!

Bodies that are created with BodyIndex = -1 (Constants.Physics.InternalIndex) will NOT produce physics messages / event when collided with another body with BodyIndex = -1. This is an optimization. So if you need to build a new dispatcher that needs custom physics behavior, be sure to define its BodyIndex property like -

computed Entity.BodyId (fun (entity : Entity) _ -> { BodySource = entity; BodyIndex = 0 }) None

where BodyIndex is 0 or higher.

HOWEVER, if you use a BodyIndex <> -1, then you will also need to handle physics transform events yourself, as the engine must assume that it cannot do so itself.

Model-Driven Physics Behavior

You can set the ModelDriven property of a rigid body to True to prevent changes to the entity's transformation properties from being automatically synchronized with the physics backend. However, enabling ModelDriven also means that whenever you need to change the physical transformation of a model-driven entity, you must do so via a function call such as World.setBodyCenter rather than from the model. Changing an entity's transformation via its transform property or its model will have no effect on its physical representation.

Whether or not you want to use Model-Driven physics depends on what you want to do. For an action game, it's easier to just keep the transform out of the model unless you want to implement networking with model diffs. For a non-action game, it can be better to have the transform in the model, keeping it in sync with the physics via BodyTransformEvents.

In BlazeVector, for example, the Player's transform information are entirely simulation-driven and not reflected in its model. In OmniBlade, the Avatar's transform information is model-driven and its transform in reflected in its model. It all depends on what's right for your game.