Qt Quick 3D Physics Shapes and Bodies
The objects in the simulation are represented by bodies that are subtypes of PhysicsBody. 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 StaticRigidBody and 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.
Static bodies do not move. They represent the environment in which the other bodies move.
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.
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.
The following table shows a summary:
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 |
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.