- Qt 6.12
- Qt Quick 3D Physics
- Qt Quick 3D Physics Shapes, Bodies and Joints
- Qt Quick 3D Physics | Commercial or GPLv3

Units

# Qt Quick 3D Physics Shapes, Bodies and Joints

The objects in the simulation are represented by any of the following four types of bodies: StaticRigidBody, DynamicRigidBody, CharacterController and TriggerBody. The physical shape of a body is represented by subtypes of CollisionShape.

## Shapes

A collision shape is used to define the physical shape and extent of an object for the purposes of the physics simulation. The collision shape will typically be simpler than the object's visual appearance.

There are some predefined shapes built into the engine: BoxShape, CapsuleShape, SphereShape, and PlaneShape. Handling of these shapes is optimized, so simulation using them will typically perform better.

In addition, there are custom shapes that are defined by data: ConvexMeshShape, HeightFieldShape, and TriangleMeshShape. These allow more flexibility at the expense of performance.

## Bodies

A body represents a physical object in the simulation. These bodies interact and collide with each other. The two main types are static bodies (StaticRigidBody) and dynamic bodies (DynamicRigidBody). The physical shape of a body is specified by a list of shapes. The effective shape is the union of these shapes. The relative position of the shapes is fixed: the bodies are rigid.

### Dynamic body

Dynamic bodies are able to move. The isKinematic property determines how it moves. When `isKinematic` is `true`, the body is positioned explicitly by modifying the kinematicPosition and kinematicRotation properties. When `isKinematic` is `false`, the object is controlled by the simulation: it will fall under gravity, and bounce off other objects.

When isKinematic is `true`, all shapes are allowed. However, non-kinematic bodies are more restricted: only convex shapes can be used. These are the pre-defined shapes BoxShape, CapsuleShape, and SphereShape; and the custom shape ConvexMeshShape. This does not mean that it is impossible to have a non-convex physical geometry: several convex shapes can be combined for a single body. The Compound Shapes Example shows how to form ring-shaped bodies based on convex shapes.

### Static body

Static bodies do not move. They represent the environment in which the other bodies move. Note that it is technically possible to move a static body, but the physical simulation will behave unexpectedly. In particular, a dynamic body that has entered a resting position on a static body will not be awoken if the static body moves. This means the dynamic body will remain in the same position even if the static body is moved.

### Character controller

The CharacterController type is a special case. It represents a character that moves through the environment. One typical use case is a first-person view where the camera is a child of the character controller, and its movement is controlled by keyboard/mouse or gamepad.

### Trigger body

There is also the TriggerBody type which is another special case. As opposed to the other bodies it is not a physical body, meaning it does not interact in collision with other bodies. As the name suggests it is only used to trigger actions when another body enters or leaves its volume as defined by its collision shapes. If another body has sendTriggerReports set to `true` and its collision volume enters a TriggerBody the bodyEntered signal is emitted.

The following table shows a summary of the different types of bodies, how they interact and can be used:

Body | Interaction | Allowed shapes
--- | --- | ---
StaticRigidBody | Does not move | All shapes
DynamicRigidBody with isKinematic `true` | Positioned programatically. Influences dynamic bodies. Stopped by nothing. | All shapes
DynamicRigidBody with isKinematic `false` | Fully controlled by simulation | Limited shapes
CharacterController | Moved programatically. Influences dynamic bodies. Stopped by static bodies. | Only a single CapsuleShape
TriggerBody | None | All shapes

## Physics Materials

The PhysicsMaterial type specifies how an object behaves when it collides with another. The dynamicFriction and staticFriction properties determine how slippery the object is, and restitution determines how bouncy it is.

## Joints

A joint constrains how two bodies move in relation to each other. A joint can for instance be used to emulate a door hinge, a rope or an arm. Various joint types are supported for different use cases, see DistanceJoint, FixedJoint, PrismaticJoint, RevoluteJoint and SphericalJoint. Every joint is based on the Joint qml type and has two bodies it connects to as well as an orientation describing its location on each body it connects. Each joint type will have different properties governing its specific physical constraints.

Units