Qt Quick Física 3D: ejemplo de CharacterController
Muestra el tipo ` CharacterController `.

Este ejemplo muestra cómo utilizar un « CharacterController » para mover la cámara en una escena, ofreciendo una vista en primera persona. El «CharacterController» representa el punto de vista del usuario como una entidad limitada por la geometría física de la escena, que camina por el suelo, sube y baja escaleras e interactúa con los disparadores.
La escena
La escena consta de un edificio sencillo definido en Building.qml, que no se explicará en detalle. (La malla « building.mesh » se creó con Blender. Se puede recrear a partir del archivo building.gltf utilizando la herramienta Balsam.)
El edificio contiene tres disparadores:
- Un disparador que abre la puerta. Implementado internamente en Building.qml
- Un disparador «gravityField» que establece una propiedad
inGravityFieldcuando hay algo en su interior. - Un disparador «teleport» que emite una señal
teleporterTriggeredcuando algo entra en él.
El controlador del personaje
La lógica completa del controlador de personajes es la siguiente:
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
}
}El controlador de personajes necesita una forma. Solo se admite « CapsuleShape ». Ten en cuenta que la propiedad «height» se refiere a la altura de la parte cilíndrica de la cápsula: la altura total del personaje se calcula sumando la altura de los hemisferios inferior y superior:
collisionShapes: CapsuleShape {
id: capsuleShape
diameter: 50
height: wasd.crouchActive ? 0 : 100
Behavior on height {
NumberAnimation { duration: 300 }
}
}
property real characterHeight: capsuleShape.height + capsuleShape.diameterPara activar un « TriggerBody », el controlador de personajes debe tener la propiedad « sendTriggerReports » establecida en « true »:
sendTriggerReports: trueCharacterController tiene su propia propiedad « gravity », independiente de « PhysicsWorld ». El caso de uso más habitual es alternar entre caminar y volar. En este ejemplo, implementamos un campo antigravitatorio cambiando la propiedad « gravity » para que apunte hacia arriba cuando el personaje se encuentre dentro del disparador «gravityField»:
gravity: building.inGravityField ? Qt.vector3d(0, 100, 0) : physicsWorld.gravityPosición y movimiento
Cuando se emite la señal ` teleporterTriggered `, cambiamos la posición y la orientación del personaje para que vuelva a su posición inicial. Ten en cuenta que la propiedad ` position ` no debe modificarse mientras se está ejecutando la simulación. Utiliza en su lugar la función ` teleport `:
property vector3d startPos: Qt.vector3d(800, 175, -850)
position: startPos
function teleportHome() {
character.teleport(character.startPos)
wasd.cameraRotation.x = 180
}El movimiento del personaje se define estableciendo la propiedad « movement » en una velocidad. El personaje intentará entonces moverse con esa velocidad, en relación con el vector de avance. El personaje puede acabar moviéndose a una velocidad diferente, ya que puede verse bloqueado por una pared o estar en caída libre. La entrada del ratón y el teclado procede del objeto ` wasd `, que es una versión simplificada de ` WasdController`.
movement: Qt.vector3d(wasd.sideSpeed, 0, wasd.forwardSpeed)
Behavior on movement {
PropertyAnimation { duration: 200 }
}Los dos ejes de rotación se gestionan de forma diferente, con el fin de seguir la práctica habitual del movimiento con las teclas WASD al caminar por el suelo:
- La rotación vertical cambia la dirección de la vista, pero no hace que el personaje vuele por los aires ni se hunda en el suelo.
- La rotación horizontal cambia la dirección de avance del personaje. (Esto supone una excepción a la regla de que las transformaciones no deben modificarse mientras se está ejecutando la simulación física: es seguro cambiar la rotación del controlador del personaje, ya que eso no altera el estado del motor físico; solo cambia la interpretación del vector 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
}Archivos:
- charactercontroller/Building.qml
- charactercontroller/CMakeLists.txt
- charactercontroller/Wasd.qml
- charactercontroller/charactercontroller.pro
- charactercontroller/main.cpp
- charactercontroller/main.qml
- charactercontroller/qml.qrc
Imágenes:
- charactercontroller/maps/Tape001_1K_Color.jpg
- charactercontroller/maps/Tape001_1K_NormalGL.jpg
- charactercontroller/maps/Tape001_1K_Roughness.jpg
- charactercontroller/maps/Tiles107_1K_Color.jpg
- charactercontroller/maps/Tiles107_1K_NormalGL.jpg
- charactercontroller/maps/Tiles107_1K_Roughness.jpg
- charactercontroller/maps/Tiles108_1K_Color.jpg
- charactercontroller/maps/sign.png
- charactercontroller/maps/sphere.png
© 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.