PhysicsWorld QML Type
控制物理模拟。更多...
| Import Statement: | import QtQuick3D.Physics |
| Since: | Qt 6.4 |
属性
- defaultDensity : real
- enableCCD : bool
- 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
- typicalLength : real
- typicalSpeed : real
- viewport : Node
信号
- frameDone(float timestep)
(since 6.5)
详细说明
“PhysicsWorld”类型用于控制物理模拟。该节点用于创建物理世界的实例并定义其属性。系统中只能存在一个物理世界。QML文件中的所有碰撞节点都会自动添加到该物理世界中。
属性文档
defaultDensity : real
该属性定义了动态对象的默认密度，单位为千克每立方单位。这相当于一个边长为1 的立方体的重量。
默认值为0.001 ，相当于 1 g/cm³：即水的密度。如果您的测量单位是米，一个合适的值是1000 。请注意，仅允许正值。
取值范围：(0, inf]
enableCCD : bool
此属性可启用连续碰撞检测。这将降低物体以高速穿过其他物体的风险（也称为“穿透”）。默认值为false 。
警告： 在启用 CCD 的情况下使用 触发体不受支持，可能会导致触发报告缺失或出现错误。
forceDebugDraw : bool
此属性可启用物理世界中所有活动形状的调试绘制。默认值为false 。
gravity : vector3d
该属性定义了物理世界的重力向量。默认值为(0, -981, 0) 。如果您的测量单位是米，且正在模拟地球重力，请将该值设置为Qt.vector3d(0, -9.81, 0) 。
maximumTimestep : real
该属性定义了模拟时间步长的最大值（单位为毫秒）。默认值为33.333 。
范围：[0, inf]
注意： 模拟时间步长 与渲染同步进行，这意味着只有在渲染帧完成后，才会开始新的模拟帧。这意味着每个渲染帧最多只会运行一个模拟帧。
minimumTimestep : real
此属性定义了模拟的最小时间步长（单位为毫秒）。默认值为1 。
范围：[0, maximumTimestep]
注意： 模拟时间步长 与渲染同步进行，这意味着只有在渲染帧完成后，才会开始新的模拟帧。这意味着每个渲染帧最多只会运行一个模拟帧。
numThreads : int [since 6.7]
此属性定义了物理仿真所使用的线程数。以下是该值范围的解释：
| 值 | 范围 | 描述 |
|---|---|---|
| 负值 | [-inf, -1] | 自动线程数。应用程序将尝试从系统查询线程数。 |
| 零 | {0} | 不进行多线程处理，模拟将按顺序运行。 |
| 正数 | [1, 256] | 指定线程数。大于 256 的值将被限制。 |
默认值为-1 ，表示自动设置线程数。
注意： 场景一旦 开始运行，就无法更改线程数。
该属性自 Qt 6.7 起引入。
reportKinematicKinematicCollisions : bool [since 6.7]
此属性控制成对的运动学动态刚体之间的碰撞是否会触发接触报告。
默认值为false 。
注意： 场景开始运行后， 无法更改此设置。
该属性在 Qt 6.7 中引入。
另请参阅 PhysicsWorld::reportStaticKinematicCollisions 、DynamicRigidBody 和PhysicsNode::bodyContact 。
reportStaticKinematicCollisions : bool [since 6.7]
此属性控制静态刚体与运动学动态刚体之间的碰撞是否会触发接触报告。
默认值为false 。
注意： 场景开始运行后， 无法更改此设置。
该属性在 Qt 6.7 中引入。
另请参阅 PhysicsWorld::reportKinematicKinematicCollisions 、StaticRigidBody 、DynamicRigidBody 以及PhysicsNode::bodyContact 。
running : bool
此属性用于启动或停止物理模拟。默认值为true 。
scene : Node
该属性定义了包含物理模拟中所有节点的最顶层节点。该节点的所有祖先物理对象都将被视为该PhysicsWorld 的一部分。
注意： 不支持为多个PhysicsWorld 使用 同一个场景节点。
typicalLength : real
此属性定义了模拟中物体的近似尺寸。它用于估算某些与长度相关的公差。远小于或远大于此尺寸的物体可能无法正常工作。默认值为100 。
范围：[0, inf]
typicalSpeed : real
该属性定义了模拟中物体速度的典型量级。它用于根据物体的碰撞速度判断应将接触视为弹跳还是静止，并设定一个动能阈值——当动能低于该阈值时，模拟可能会使物体进入休眠状态。
对于常规物理环境，一个合适的选择是物体在重力作用下自由下落一秒钟时的近似速度。默认值为1000 。
取值范围：[0, inf]
viewport : Node
该属性定义了在启用“forceDebugDraw ”时，调试组件将被绘制的视口。如果未设置该属性，则将使用“scene ”节点。
另请参阅 forceDebugDraw 和scene 。
信号文档
[since 6.5] frameDone(float timestep)
当物理模拟完成一帧的模拟时，会发出此信号。timestep 参数表示模拟中该时间步长持续的时间（以毫秒为单位）。
注意： 对应的处理函数 为onFrameDone 。
该信号在 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.
