ReactPhysics3D Documentation

The Testbed is a graphical application used to view and interact with various demo scenes. It is located in the testbed/ folder of the repository.

Requirements & Setup:

• OpenGL: Required to compile the testbed.
• CMake: You can enable the testbed during the library build process using a specific CMake option.

To use the real-time profiler, you must build the library with the RP3D_PROFILING_ENABLED CMake variable enabled.

How it works

• Collection: The profiler collects performance data while the application is running.
• Output: When the PhysicsWorld destructor is called, the profiling information is written to a text file.
• File Naming: By default, one profile file is created per PhysicsWorld. Files are named after the world (e.g., world.txt, world1.txt).
• Customization: You can change the name of a world by setting it in the WorldSettings object during PhysicsWorld creation.

Colliders can exhibit different behaviors depending on how they are configured:

• Simulation Collider: The default behavior. Colliders will physically bump into each other, generating contact points and forces.
• World Query Collider: Used for manual queries like raycast(), testOverlap(), or testPointInside(). A collider can be both a simulation collider and a world query collider.
• Trigger: A collider that does not physically collide with anything but can report when it is overlapping with another collider.

Note: A collider cannot be both a Simulation Collider and a Trigger at the same time.

ReactPhysics3D supports three types of rigid bodies, which can be set using RigidBody::setType(BodyType type):

• Static (BodyType::STATIC): Infinite mass and zero velocity. Position can be changed manually, but it does not collide with other static or kinematic bodies. Use this for floors or buildings.
• Kinematic (BodyType::KINEMATIC): Infinite mass, but velocity can be changed manually. The physics engine computes its position. It does not collide with other static or kinematic bodies. Use this for moving platforms.
• Dynamic (BodyType::DYNAMIC): Non-zero mass and velocity determined by forces. The physics engine determines its position. It can collide with all other body types. This is the default type.

Note: When a body is created, it is DYNAMIC by default.

// Change the type of the body to kinematic
body->setType(BodyType::KINEMATIC);

ReactPhysics3D uses a centralized memory management system via the PhysicsCommon object.

Object Ownership

Objects like PhysicsWorld and RigidBody are created via factory methods. You must not use the C++ delete operator on these objects. Instead, use the provided destruction methods to release memory manually, or allow the PhysicsCommon object to handle it upon its own destruction.

Manual Destruction

• To destroy a rigid body: world->destroyRigidBody(body);
• To destroy a physics world: physicsCommon.destroyPhysicsWorld(world);

Custom Allocators

By default, the library uses std::malloc() and std::free(). To use a custom allocator, inherit from the MemoryAllocator class and override allocate() and release(). Note that allocate() must return memory that is 16 bytes aligned.

ReactPhysics3D is deterministic when compiled with the same compiler and running on the same machine. To ensure two simulation runs are identical, follow these practices:

1. Reset State: Completely destroy and recreate the PhysicsWorld, all Body objects, and all Joint objects to clear cached internal simulation data.
2. Consistent Ordering: Create bodies and joints in the exact same order every time.
3. Consistent Execution: Ensure all method calls to the PhysicsWorld, bodies, and joints occur in the same sequence.

The PhysicsCommon class is the central entry point for ReactPhysics3D. It serves three primary roles:

1. Factory Module: It is used to instantiate physics worlds, collision shapes, and other objects.
2. Memory Management: It centralizes all memory allocations for the library.
3. Logging: It contains the logger for library events.

You must instantiate PhysicsCommon before creating any other physics objects.

// First you need to create the PhysicsCommon object.
PhysicsCommon physicsCommon;

// Use it to create a physics world
PhysicsWorld* world = physicsCommon.createPhysicsWorld();

// Use it to create collision shapes
SphereShape* sphereShape = physicsCommon.createSphereShape(radius);

ReactPhysics3D can be used in two primary ways:

1. Collision Testing (Static): You do not call PhysicsWorld::update(). Instead, you use methods like testOverlap(), testCollision(), or testPointInside() to query the state of bodies. This is useful if you only need to know if objects are touching without simulating motion.
2. Real-time Simulation (Dynamic): You create RigidBody objects and call PhysicsWorld::update(timeStep) every frame. The engine automatically calculates motion based on forces, collisions, and joint constraints. This is the standard approach for games.

Joints are used to constrain the motion of rigid bodies relative to each other. A single joint represents a constraint between two rigid bodies. By default, a body has six degrees of freedom (three translation, three rotation); different joint types reduce these degrees of freedom to simulate specific mechanical connections.

To create a joint, you follow a two-step process:

1. Create a JointInfo object (e.g., BallAndSocketJointInfo, HingeJointInfo, SliderJointInfo, or FixedJointInfo) containing the necessary parameters like the two rigid bodies, anchor points, and axes.
2. Call PhysicsWorld::createJoint() with that info object. This method returns a pointer to the created joint object, which you should dynamic_cast to the specific joint type to access its properties and methods.

A PhysicsWorld is the container for all bodies you want to simulate. You create it using a PhysicsCommon object. You can either use default settings or provide a PhysicsWorld::WorldSettings object to customize parameters like gravity, velocity solver iterations, and sleeping behavior at creation time.

Note: Settings provided during creation are copied. To change settings after creation, use the specific setter methods provided by the PhysicsWorld class API.

// Create the world settings
PhysicsWorld::WorldSettings settings;
settings.defaultVelocitySolverNbIterations = 20;
settings.isSleepingEnabled = false;
settings.gravity = Vector3(0, -9.81, 0);

// Create the physics world with your settings
PhysicsWorld* world = physicsCommon.createPhysicsWorld(settings);