3.5 KiB
.title Physics
Use physics to enable physically plausible interactions with your scene content.
Different backends are supported such as Bullets Physics, NVIDIA PhysX and Newton Dynamics.
[TOC]
Declaring Physics
To turn a node into a rigid body, create a [RigidBody] component and assign it to the node using [Node_SetRigidBody].
To fully declare a rigid body you must attach at least one collision shape to its node. Create a [Collision] component and call [Node_SetCollision] to do so. You can attach multiple collision components to a single node.
A rigid body can be of the following type:
RBT_Dynamic: Responds in a physically plausible manner to interaction with other rigid bodies. Its motion is fully controlled by the physics engine. A dynamic rigid body will automatically go to sleep and stop consuming simulation resources when it stops moving for a long enough period of time.RBT_Kinematic: Follows the transformation of the node it belongs to. A kinematic body never goes to sleep automatically.
See [RigidBody_SetType].
The rigid body intertia tensor is computed from its collision shape properties. A zero mass rigid body is considered infinitely heavy and cannot be moved.
Simulating Physics
Create a physics backend such as [SceneNewtonPhysics] and call [SceneBullet3Physics_SceneCreatePhysicsFromAssets] to create the physics states corresponding to the scene declaration.
Note: [SceneBullet3Physics_SceneCreatePhysicsFromAssets] means that if setting up the physics states requires access to an external resource, such as a mesh, it should be loaded from the assets system. If you are working from the filesystem, use [SceneBullet3Physics_SceneCreatePhysicsFromFile].
Running the Simulation
This involves 3 steps on each update:
- Synchronize physics state with the scene declaration using [SceneBullet3Physics_SceneCreatePhysicsFromAssets]. Alternatively, you can use a more fine-grained approach using [SceneBullet3Physics_NodeCreatePhysicsFromAssets] to improve performance.
- Step the simulation using [SceneBullet3Physics_StepSimulation].
- Synchronize the updated physics transformations to the scene using [SceneBullet3Physics_SyncDynamicBodiesToScene].
Note: If you are using kinematic bodies you will also need to synchronize them from their node transformation on each update using [SceneBullet3Physics_SyncKinematicBodiesFromScene].
The Easy Way
While the low-level API offers the most flexibility most projects will use a straightforward implementation which is provided by the [SceneUpdateSystems] function. This function handles all of the above steps and does the same for other systems you may use.
When using a script system, this function will also dispatch collision events to it.
Keeping the System Synchronized
Call the physics system garbage collect method (eg. [SceneBullet3Physics_GarbageCollect]) on each update to ensure that destroyed nodes or components are properly removed. If you know that no node or component was destroyed during a particular update, not calling the garbage collector will save on performance.
Reading Physics Transformation
When a node is assigned a dynamic rigid body its transformation matrix is overriden by the physics system. Its transform component however, is not. Transform methods such as [Transform_SetPos] or [Transform_SetRot] will have no effect unless you explicitely synchronize the node to the physics system after using them.
[Transform_GetWorld] will return the transformation matrix as set by the physics system.