PhysicsWorld QML Type
Controls the physics simulation. More...
| Import Statement: | import QtQuick3D.Physics |
| Since: | Qt 6.4 |
Properties
- defaultDensity : real
- dynamicQueryStructure : QueryStructure
(since 6.13) - forceDebugDraw : bool
- gravity : vector3d
- maximumTimestep : real
- minimumTimestep : real
- numThreads : int
(since 6.7) - reportKinematicKinematicCollisions : bool
(since 6.7) - reportStaticKinematicCollisions : bool
(since 6.7) - running : bool
- scene : Node
- staticQueryStructure : QueryStructure
(since 6.13) - typicalLength : real
- typicalSpeed : real
- viewport : Node
Signals
- frameDone(float timestep)
(since 6.5)
Detailed Description
The PhysicsWorld type controls the physics simulation. This node is used to create an instance of the physics world as well as define its properties. There can only be one physics world. All collision nodes in the qml will get added automatically to the physics world.
Property Documentation
defaultDensity : real
This property defines the default density of dynamic objects, measured in kilograms per cubic unit. This is equal to the weight of a cube with side 1.
The default value is 0.001, corresponding to 1 g/cm³: the density of water. If your unit of measurement is meters, a good value would be 1000. Note that only positive values are allowed.
Range: (0, inf]
dynamicQueryStructure : QueryStructure [default: PhysicsWorld.DynamicTree, since 6.13]
The spatial pruning structure type used to accelerate scene queries (raycasts, sweeps, overlaps - used in CharacterController and a kinematic dynamic rigid body) against dynamic actors in the physics scene. It has no effect on rigid-body contact/collision detection during simulation.
The following values are available:
| Constant | Description |
|---|---|
PhysicsWorld.NoStructure | Disables the scene query acceleration structure for dynamic actors. Eliminates CPU overhead for tree maintenance when objects move, spawn, or are destroyed. Scene queries will fall back to a linear search. Ideal when scene queries are not needed for dynamic objects. |
PhysicsWorld.StaticTree | Uses a static AABB tree. Offers faster scene queries for dynamic actors, but updating the tree when objects move or spawn is very expensive. Best when dynamic actors rarely move or spend most of their time sleeping. |
PhysicsWorld.DynamicTree | Uses a dynamic self-balancing AABB tree. Allows fast, local runtime insertion (logarithmic time), movement, and removal of dynamic objects without freezing the frame. Ideal for active scenes with frequently moving or spawning dynamic actors. Note: Once the scene has started running it is not possible to change this setting. |
This property was introduced in Qt 6.13.
See also PhysicsWorld::staticQueryStructure.
forceDebugDraw : bool
This property enables debug drawing of all active shapes in the physics world. The default value is false.
gravity : vector3d
This property defines the gravity vector of the physics world. The default value is (0, -981, 0). Set the value to Qt.vector3d(0, -9.81, 0) if your unit of measurement is meters and you are simulating Earth gravity.
maximumTimestep : real
This property defines the maximum simulation timestep in milliseconds. The default value is 33.333.
Range: [0, inf]
Note: The simulation timestep works in lockstep with the rendering, meaning a new simulation frame will only be started after a rendered frame has completed. This means that at most one simulation frame will run per rendered frame.
minimumTimestep : real
This property defines the minimum simulation timestep in milliseconds. The default value is 1.
Range: [0, maximumTimestep]
Note: The simulation timestep works in lockstep with the rendering, meaning a new simulation frame will only be started after a rendered frame has completed. This means that at most one simulation frame will run per rendered frame.
numThreads : int [since 6.7]
This property defines the number of threads used for the physical simulation. This is how the range of values are interpreted:
| Value | Range | Description |
|---|---|---|
| Negative | [-inf, -1] | Automatic thread count. The application will try to query the number of threads from the system. |
| Zero | {0} | No threading, simulation will run sequentially. |
| Positive | [1, inf] | Specific thread count. |
The default value is -1, meaning automatic thread count.
Note: Once the scene has started running it is not possible to change the number of threads.
This property was introduced in Qt 6.7.
reportKinematicKinematicCollisions : bool [since 6.7]
This property controls if collisions between pairs of kinematic dynamic rigid bodies will trigger a contact report.
The default value is false.
Note: Once the scene has started running it is not possible to change this setting.
This property was introduced in Qt 6.7.
See also PhysicsWorld::reportStaticKinematicCollisions, DynamicRigidBody, and PhysicsNode::bodyContact.
reportStaticKinematicCollisions : bool [since 6.7]
This property controls if collisions between a static rigid body and a kinematic dynamic rigid body will trigger a contact report.
The default value is false.
Note: Once the scene has started running it is not possible to change this setting.
This property was introduced in Qt 6.7.
See also PhysicsWorld::reportKinematicKinematicCollisions, StaticRigidBody, DynamicRigidBody, and PhysicsNode::bodyContact.
running : bool
This property starts or stops the physical simulation. The default value is true.
scene : Node
This property defines the top-most Node that contains all the nodes of the physical simulation. All physics objects that are an ancestor of this node will be seen as part of this PhysicsWorld.
Note: Using the same scene node for several PhysicsWorld is unsupported.
staticQueryStructure : QueryStructure [default: PhysicsWorld.DynamicTree, since 6.13]
The spatial pruning structure type used to accelerate scene queries (raycasts, sweeps, overlaps - used in CharacterController and a kinematic dynamic rigid body) against static actors in the physics scene. It has no effect on rigid-body contact/collision detection during simulation.
The following values are available:
| Constant | Description |
|---|---|
PhysicsWorld.StaticTree | Uses a pre-baked static AABB tree. Offers maximum scene query performance with zero per-frame management overhead. Best for fully static, immutable scenes. Inserting or removing objects at runtime causes heavy scene rebuilds and frame spikes. |
PhysicsWorld.DynamicTree | Uses a dynamic self-balancing AABB tree. Allows fast, local runtime insertion (logarithmic time) and removal of static objects without freezing the frame. Ideal for seamless open-world streaming where static chunks are loaded dynamically. Note: Once the scene has started running it is not possible to change this setting. Note: PhysicsWorld.NoStructure is not supported for staticQueryStructure |
This property was introduced in Qt 6.13.
See also PhysicsWorld::dynamicQueryStructure.
typicalLength : real
This property defines the approximate size of objects in the simulation. This is used to estimate certain length-related tolerances. Objects much smaller or much larger than this size may not behave properly. The default value is 100.
Range: [0, inf]
typicalSpeed : real
This property defines the typical magnitude of velocities of objects in simulation. This is used to estimate whether a contact should be treated as bouncing or resting based on its impact velocity, and a kinetic energy threshold below which the simulation may put objects to sleep.
For normal physical environments, a good choice is the approximate speed of an object falling under gravity for one second. The default value is 1000.
Range: [0, inf]
viewport : Node
This property defines the viewport where debug components will be drawn if forceDebugDraw is enabled. If unset the scene node will be used.
See also forceDebugDraw and scene.
Signal Documentation
[since 6.5] frameDone(float timestep)
This signal is emitted when the physical simulation is done simulating a frame. The timestep parameter is how long in milliseconds the timestep was in the simulation.
Note: The corresponding handler is onFrameDone.
This signal was introduced in Qt 6.5.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
