Qt Quick 3D Physics - CharacterController 예제

시험실 스크린샷

이 예제는 ` CharacterController `를 사용하여 씬 내에서 카메라를 이동시켜 1인칭 시점을 구현하는 방법을 보여줍니다. 캐릭터 컨트롤러는 사용자의 시점을 씬의 물리적 지오메트리에 제약받는 엔티티로 표현하며, 지면을 걷고, 계단을 오르내리며, 트리거와 상호작용합니다.

씬

이 장면은 Building.qml에 정의된 간단한 건물로 구성되어 있으며, 이에 대해서는 자세히 설명하지 않겠습니다. (메시 building.mesh 는 Blender를 사용하여 제작되었습니다. balsam 도구를 사용하여 building.gltf 파일에서 재현할 수 있습니다.)

이 건물에는 세 개의 트리거가 포함되어 있습니다:

문을 여는 트리거. Building.qml 내에서 내부적으로 구현됨
무언가가 내부에 있을 때 속성 inGravityField 을 설정하는 “gravityField” 트리거.
무언가가 들어올 때 teleporterTriggered 신호를 발산하는 “teleport” 트리거.

캐릭터 컨트롤러

캐릭터 컨트롤러의 전체 로직은 다음과 같습니다:

CharacterController {
    id: character
    property vector3d startPos: Qt.vector3d(800, 175, -850)
    position: startPos
    function teleportHome() {
        character.teleport(character.startPos)
        wasd.cameraRotation.x = 180
    }

    collisionShapes: CapsuleShape {
        id: capsuleShape
        diameter: 50
        height: wasd.crouchActive ? 0 : 100
        Behavior on height {
            NumberAnimation { duration: 300 }
        }
    }
    property real characterHeight: capsuleShape.height + capsuleShape.diameter

    sendTriggerReports: true

    movement: Qt.vector3d(wasd.sideSpeed, 0, wasd.forwardSpeed)
    Behavior on movement {
        PropertyAnimation { duration: 200 }
    }

    gravity: building.inGravityField ? Qt.vector3d(0, 100, 0) : physicsWorld.gravity

    eulerRotation.y: wasd.cameraRotation.x
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, character.characterHeight / 2 - 10, 0)
        eulerRotation.x: wasd.cameraRotation.y
        clipFar: 10000
        clipNear: 10
    }
}

캐릭터 컨트롤러에는 도형이 필요합니다. CapsuleShape 만 지원됩니다. height 속성은 캡슐의 원통 부분 높이를 나타낸다는 점에 유의하십시오. 캐릭터의 전체 높이는 하단 및 상단 반구 높이를 더하여 계산됩니다:

collisionShapes: CapsuleShape {
    id: capsuleShape
    diameter: 50
    height: wasd.crouchActive ? 0 : 100
    Behavior on height {
        NumberAnimation { duration: 300 }
    }
}
property real characterHeight: capsuleShape.height + capsuleShape.diameter

TriggerBody 를 트리거하려면 캐릭터 컨트롤러의 sendTriggerReports 속성이 true 로 설정되어 있어야 합니다:

sendTriggerReports: true

CharacterController 는 ` PhysicsWorld`과 독립적인 자체 ` gravity ` 속성을 가지고 있습니다. 일반적인 사용 사례는 걷기와 비행 사이를 전환하는 것입니다. 이 예제에서는 캐릭터가 "gravityField" 트리거 내부에 있을 때 ` gravity ` 속성을 위쪽을 가리키도록 변경하여 반중력 장을 구현합니다:

gravity: building.inGravityField ? Qt.vector3d(0, 100, 0) : physicsWorld.gravity

위치 및 이동

teleporterTriggered 신호가 발산되면, 캐릭터의 위치와 방향을 초기 위치로 되돌립니다. 시뮬레이션이 실행 중인 동안에는 position 속성을 변경해서는 안 된다는 점에 유의하십시오. 대신 teleport 함수를 사용하십시오:

property vector3d startPos: Qt.vector3d(800, 175, -850)
position: startPos
function teleportHome() {
    character.teleport(character.startPos)
    wasd.cameraRotation.x = 180
}

캐릭터의 움직임은 movement 속성을 속도로 설정하여 정의됩니다. 그러면 캐릭터는 전진 벡터를 기준으로 해당 속도로 이동하려고 시도합니다. 벽에 막히거나 자유 낙하 상태에 있을 수 있으므로, 캐릭터는 실제로는 다른 속도로 움직일 수도 있습니다. 마우스/키보드 입력은 wasd 객체를 통해 이루어지며, 이는 WasdController 의 기능이 축소된 버전입니다.

movement: Qt.vector3d(wasd.sideSpeed, 0, wasd.forwardSpeed)
Behavior on movement {
    PropertyAnimation { duration: 200 }
}

지상에서 이동할 때 WASD 키를 사용하는 일반적인 관행을 따르기 위해, 두 회전 축은 서로 다르게 처리됩니다:

수직 회전은 시야 방향을 변경할 뿐, 캐릭터가 공중으로 떠오르거나 땅속으로 파고들게 하지는 않습니다.
수평 회전은 캐릭터의 전진 방향을 변경합니다. (이는 물리 시뮬레이션이 실행 중일 때 변환을 변경해서는 안 된다는 규칙의 예외입니다. 캐릭터 컨트롤러의 회전을 변경하는 것은 물리 엔진의 상태를 변경하지 않으므로 안전합니다. 이는 단순히 movement 벡터의 해석만 변경할 뿐이기 때문입니다.)

eulerRotation.y: wasd.cameraRotation.x
PerspectiveCamera {
    id: camera
    position: Qt.vector3d(0, character.characterHeight / 2 - 10, 0)
    eulerRotation.x: wasd.cameraRotation.y
    clipFar: 10000
    clipNear: 10
}

파일:

이미지:

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