mirror of
https://github.com/harfang3d/harfang3d.git
synced 2024-06-01 14:02:16 +00:00
55 lines
3.5 KiB
Markdown
55 lines
3.5 KiB
Markdown
.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:
|
|
|
|
1. 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.
|
|
2. Step the simulation using [SceneBullet3Physics_StepSimulation].
|
|
3. 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.
|