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.

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 and is true by default for all of the out-of-the-box physics entities. 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, when 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.

Synchronized or Manual Physics Motion

You can set the PhysicsMotion property of a physics-based entity to ManualMotion to prevent changes to the entity's transformation properties from being automatically synchronized with the physics backend. However, enabling ManualMotion also means that whenever you need to change the physical transformation of such an entity, you must do so via a function call such as World.setBodyCenter. Changing an entity's transformation via its transform property will have no effect on its physical representation when in ManualMotion.

TODO: more detail.