Qt Quick 3D Physics Shapes and Bodies

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:

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.