Qt Quick 3D 物理学 - 叶轮示例

演示如何使用触发体和碰撞信息。

一张3D渲染截图，画面中一个蓝色球体位于绿色表面上，其上方有一个粉色矩形块，最上方漂浮着一个红色球体

本示例演示了如何使用触发体和碰撞信息。场景由一个绿色的静态平面、一个红色的动态球体、一个粉色的盒形触发体以及一个蓝色的静态球体组成。当红色球体与触发体重叠时，它会变为黄色；当它与蓝色球体发生碰撞时，会被弹开。

设置

与往常一样，我们需要添加PhysicsWorld ：

PhysicsWorld {
    gravity: Qt.vector3d(0, -490, 0)
    scene: viewport.scene
}

我们还添加了一个View3D ，用于放置场景中的对象。其中包含一些视觉环境的设置：

environment: SceneEnvironment {
    clearColor: "#d6dbdf"
    backgroundMode: SceneEnvironment.Color
}

PerspectiveCamera {
    position: Qt.vector3d(0, 200, 1000)
    clipFar: 2000
    clipNear: 1
}

DirectionalLight {
    eulerRotation.x: -45
    eulerRotation.y: 45
    castsShadow: true
    brightness: 1
    shadowFactor: 50
}

物理对象

我们有一个常规的静态平面：

StaticRigidBody {
    position: Qt.vector3d(0, -100, 0)
    eulerRotation: Qt.vector3d(-90, 0, 0)
    collisionShapes: PlaneShape {}
    Model {
        source: "#Rectangle"
        scale: Qt.vector3d(500, 500, 1)
        materials: PrincipledMaterial {
            baseColor: "green"
        }
        castsShadows: false
        receivesShadows: true
    }
}

这是我们动态球体的定义方式：

DynamicRigidBody {
    id: sphere
    massMode: DynamicRigidBody.CustomDensity
    density: 0.00001
    position: Qt.vector3d(0, 600, 0)
    property bool inArea: false
    sendContactReports: true
    receiveTriggerReports: true

    onEnteredTriggerBody: {
        inArea = true
    }
    onExitedTriggerBody: {
        inArea = false
    }

    collisionShapes: SphereShape {}
    Model {
        source: "#Sphere"
        materials: PrincipledMaterial {
            baseColor: sphere.inArea ? "yellow" : "red"
        }
    }
}

inArea 属性是一个自定义属性，用于跟踪球体何时与盒状触发体发生重叠。该属性随后用于驱动baseColor 属性，当球体与盒状触发体重叠时使其变为黄色，否则变为红色。由于我们希望球体参与接触报告，因此需将属性sendContactReports 设置为true 。此外，为了让球体在进入或离开TriggerBody 时触发回调，属性receiveContactReports 也需设置为true 。我们在球体上实现了信号方法enteredTriggerBody 和exitedTriggerBody ，当球体进入或离开触发体时，会将属性inArea 分别设置为true 或false 。

现在让我们看看触发体：

TriggerBody {
    position: Qt.vector3d(0, 350, 0)
    scale: Qt.vector3d(1, 2, 1)

    collisionShapes: BoxShape {
        id: boxShape
    }
    Model {
        source: "#Cube"
        materials: PrincipledMaterial {
            baseColor: Qt.rgba(1, 0, 1, 0.2)
            alphaMode: PrincipledMaterial.Blend
        }
    }
}

该 QML 类型是TriggerBody ，其行为类似于静态物体，但其碰撞功能处于禁用状态。取而代之的是，它会在球体上触发enteredTriggerBody 和exitedTriggerBody 方法调用。

最后，让我们看看叶轮：

StaticRigidBody {
    position: Qt.vector3d(0, 0, 0)
    scale: Qt.vector3d(2, 2, 2)
    receiveContactReports: true

    collisionShapes: SphereShape {}

    Model {
        source: "#Sphere"
        materials: PrincipledMaterial {
            baseColor: "blue"
        }
    }

    onBodyContact: (body, positions, impulses, normals) => {
        for (let normal of normals) {
            let velocity = normal.times(-700)
            if (body instanceof DynamicRigidBody) {
                (body as DynamicRigidBody).setLinearVelocity(velocity)
            }
        }
    }
}

这是一个静态物体，我们将receiveContactReports 设置为true 以启用碰撞回调。每当报告碰撞时，回调方法bodyContact 就会被调用。在该方法中，我们调用setLinearVelocity 来设置与碰撞法向量相反方向的线速度，从而模拟叶轮。

文件：

© 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.