Back to Qt.io
Contact Us Blog Download Qt

CharacterController QML Type

캐릭터의 동작을 제어합니다. 더 보기...

Import Statement: import QtQuick3D.Physics
Since: Qt 6.4
Inherits:

PhysicsBody

속성

신호

  • shapeHit(PhysicsNode *body, vector3D position, vector3D impulse, vector3D normal) (since 6.6)

방법

상세 설명

CharacterController 유형은 캐릭터의 동작을 제어합니다.

캐릭터는 외부의 제어를 받아 움직이지만 여전히 물리적 장벽에 의해 제약을 받고 (선택적으로) 중력의 영향을 받는 엔티티입니다. 이는 물리 시뮬레이션에 의해 완전히 제어되거나(비운동체), 장벽에 관계없이 배치된 위치에서 정확하게 움직이는(운동체) dynamic rigid bodies 과는 대조적입니다.

캐릭터 컨트롤러의 동작을 제어하려면 movement 을 원하는 속도로 설정합니다.

1인칭 시점의 경우 일반적으로 카메라가 캐릭터 컨트롤러 내부에 배치됩니다.

참고: collisionShapes 은 단일 CapsuleShape 으로 설정해야 합니다. 다른 모양은 지원되지 않습니다.

참고: 캐릭터 컨트롤러는 캡슐 도형 높이의 4분의 1보다 낮은 장애물의 크기를 조정할 수 있습니다.

도형 및 몸체 개요 문서를참조하세요 .

프로퍼티 문서

collisions : Collisions [read-only]

이 프로퍼티는 캐릭터의 현재 콜리전 상태를 저장합니다. 충돌이 없는 경우 None 또는 Side, Up, Down 의 OR 조합입니다:

상수설명
CharacterController.None캐릭터가 아무것도 건드리지 않고 있습니다. 중력이 0이 아닌 경우 캐릭터가 자유 낙하 중임을 의미합니다.
CharacterController.Side캐릭터가 옆으로 무언가를 만지고 있습니다.
CharacterController.Up캐릭터가 위의 무언가에 닿아 있습니다.
CharacterController.Down캐릭터가 그 아래에 있는 무언가에 닿아 있습니다. 표준 중력에서 이것은 캐릭터가 지면에 있음을 의미합니다.

참고: 방향은 표준 중력을 기준으로 정의됩니다. Up 는 CharacterController.gravity 의 값에 관계없이 항상 양의 y 축을 따릅니다. PhysicsWorld.gravity


enableShapeHitCallback : bool [since 6.6]

이 속성은 이 캐릭터 컨트롤러에 대한 CharacterController::shapeHit 콜백을 활성화/비활성화합니다.

기본값입니다: false

이 프로퍼티는 Qt 6.6에 도입되었습니다.


gravity : vector3d

이 프로퍼티는 캐릭터에 적용되는 중력 가속도를 정의합니다. 땅 위를 걷는 캐릭터의 경우 일반적으로 PhysicsWorld.gravity 로 설정해야 합니다. 3차원에서 이동 컨트롤이 있는 플로팅 캐릭터는 일반적으로 중력이 (0, 0, 0) 입니다.

기본값: (0, 0, 0).


midAirControl : bool

이 프로퍼티는 캐릭터가 자유 낙하 중일 때 movement 프로퍼티가 적용되는지 여부를 정의합니다. gravity 이 null이 아닌 경우에만 관련이 있습니다. true 값은 movement 이 변경될 때 캐릭터가 공중에서 방향을 바꾼다는 의미입니다. false 값은 캐릭터가 다른 물체에 부딪힐 때까지 현재 궤도를 계속 유지한다는 의미입니다.

기본값입니다: true


movement : vector3d

이 속성은 캐릭터의 제어된 동작을 정의합니다. 이 속성은 중력이 없고 다른 물리 오브젝트와 상호작용하지 않을 때 캐릭터가 움직이는 속도입니다.

이 속성은 캐릭터의 실제 속도를 반영하지 않습니다. 캐릭터가 지형에 붙어 있는 경우 캐릭터는 movement 에 정의된 속도보다 느리게 움직일 수 있습니다. 반대로 캐릭터가 자유 낙하 중이면 훨씬 빠르게 움직일 수 있습니다.

기본값입니다: (0, 0, 0)


신호 문서

[since 6.6] shapeHit(PhysicsNode *body, vector3D position, vector3D impulse, vector3D normal)

이 신호는 movement 가 호출되어 DynamicRigidBody 또는 StaticRigidBody 와 충돌하고 enableShapeHitCallback 가 true 로 설정된 경우에 발생합니다. 파라미터 body, position, impulse 및 normal 에는 접점에 대한 몸체, 위치, 임펄스 힘 및 노멀이 포함되어 있습니다.

참고: 해당 핸들러는 onShapeHit 입니다.

이 신호는 Qt 6.6에 도입되었습니다.


메서드 문서

teleport(vector3d position)

충돌 여부를 확인하지 않고 즉시 캐릭터를 position 로 이동합니다. 호출자는 정적 객체와의 중첩을 피할 책임이 있습니다.


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