Qt Quick 3D Physics - CharacterController 예제

CharacterController 유형을 보여줍니다.

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

씬

씬은 Building.qml에 정의된 간단한 건물로 구성되며, 자세한 설명은 생략합니다. ( building.mesh 메쉬는 Blender를 사용하여 만들었습니다. balsam 도구를 사용하여 building.gltf에서 다시 만들 수 있습니다.)

건물에는 세 개의 트리거가 있습니다:

문을 여는 트리거. Building.qml에서 내부적으로 구현됨.
내부에 무언가가 있을 때 inGravityField 속성을 설정하는 "gravityField" 트리거.
무언가가 들어오면 teleporterTriggered 신호를 보내는 "텔레포트" 트리거.

캐릭터 컨트롤러

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

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 만 지원됩니다. 높이 속성은 캡슐의 원통 부분의 높이를 의미하며, 캐릭터의 전체 높이는 아래쪽 반구와 위쪽 반구의 높이를 더하여 계산됩니다:

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 속성을 속도로 설정하여 정의합니다. 그러면 캐릭터는 순방향 벡터를 기준으로 해당 속도로 움직이려고 시도합니다. 캐릭터가 벽에 막히거나 자유 낙하 중일 수 있으므로 결국 다른 속도로 움직이게 될 수 있습니다. 마우스/키보드 입력은 WasdController 의 축소 버전인 wasd 객체에서 제공됩니다.

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
}

파일:

이미지:

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