Qt Quick 3D - Ejemplo de Quick Ball
Muestra cómo crear un juego sencillo utilizando Quick3D.

Este ejemplo muestra cómo combinar Qt Quick y Qt Quick 3D para crear un sencillo juego en 3D. El objetivo del juego es acertar en las casillas objetivo lanzando una pelota. Se otorgan puntos en función de la rapidez y del número mínimo de pelotas que se utilicen para derribar todos los objetivos. ¡Apunta bien, pero sé rápido!
El código fuente se encuentra en un único archivo QML para destacar lo compacto que es este ejemplo, teniendo en cuenta que se trata de un juego totalmente jugable. Empecemos por examinar las propiedades principales. Son bastante intuitivas y puedes ajustarlas fácilmente para ver cómo afectan al juego.
// Scaling helpper
readonly property real px: 0.2 + Math.min(width, height) / 800
// This is false until the first game has started
property bool playingStarted: false
// This is true whenever game is on
property bool gameOn: false
// Sizes of our 3D models
readonly property real ballSize: 40
readonly property real targetSize: 120
// Playing time in seconds
readonly property real gameTime: 60
property real currentTime: 0
// Amount of balls per game
readonly property int gameBalls: 20
property int currentBalls: 0
// Scores
property int score: 0
property int timeBonus: 0
property int ballsBonus: 0La lógica del juego está implementada en JavaScript. View3D contiene una función para iniciar el juego, que (re)inicializa todas las variables necesarias y crea los objetivos del nivel. También contiene una función para calcular la puntuación final cuando termina el juego.
function createLevel1() {
// Simple level of target items
var level1 = [{ "x": 0, "y": 100, "z": -100, "points": 10 },
{ "x": -300, "y": 100, "z": -400, "points": 10 },
{ "x": 300, "y": 100, "z": -400, "points": 10 },
{ "x": -200, "y": 400, "z": -600, "points": 20 },
{ "x": 0, "y": 400, "z": -600, "points": 20 },
{ "x": 200, "y": 400, "z": -600, "points": 20 },
{ "x": 0, "y": 700, "z": -600, "points": 30 }];
targetsNode.addTargets(level1);
}
function startGame() {
ballModel.resetBall();
targetsNode.resetTargets();
createLevel1();
mainWindow.score = mainWindow.timeBonus = mainWindow.ballsBonus = 0;
mainWindow.currentBalls = mainWindow.gameBalls;
mainWindow.gameOn = true;
mainWindow.playingStarted = true;
}
function endGame() {
if (targetsNode.currentTargets == 0) {
// If we managed to get all targets down -> bonus points!
mainWindow.timeBonus = mainWindow.currentTime;
mainWindow.ballsBonus = mainWindow.currentBalls * 10;
}
mainWindow.gameOn = false;
ballModel.resetBall();
}La vista también contiene un nodo « PointLight » para iluminar la escena. Está situado por encima de los objetos y configurado para proyectar sombras. Fíjate en cómo se utiliza el brillo para oscurecer el área de juego cuando el juego ha terminado. La propiedad « ambientColor » se utiliza para suavizar el contraste de la luz, ya que sin ella las partes inferiores de los objetos quedarían muy oscuras.
PointLight {
x: 400
y: 1200
castsShadow: true
shadowMapQuality: Light.ShadowMapQualityHigh
shadowFactor: 50
quadraticFade: 2
ambientColor: "#202020"
brightness: mainWindow.gameOn ? 200 : 40
Behavior on brightness {
NumberAnimation {
duration: 1000
easing.type: Easing.InOutQuad
}
}
}Para lanzar la pelota se utiliza el elemento « Qt Quick » de « MouseArea », que solo se activa cuando el juego está en marcha y la pelota aún no se está moviendo.
MouseArea {
anchors.fill: parent
enabled: mainWindow.gameOn && !ballModel.ballMoving
onPressed: {
ballModel.moveBall(mouseX, mouseY);
}
onPositionChanged: {
ballModel.moveBall(mouseX, mouseY);
}
onReleased: {
ballModel.throwBall();
}
}A continuación, pasamos a los modelos 3D propiamente dichos. El modelo de la pelota es el más grande, ya que contiene la lógica de comportamiento de la pelota, sus animaciones y la detección de impactos. Veamos primero las propiedades de la pelota. La pelota utiliza un modelo esférico integrado, escalado en función de ballSize. Utilizamos PrincipledMaterial con un baseColorMap y un normalMap para crear el aspecto de una pelota de tenis.

Model {
id: ballModel
property real directionX: 0
property real directionY: 0
// How many ms the ball flies
readonly property real speed: 2000
readonly property real ballScale: mainWindow.ballSize / 100
property var moves: []
readonly property int maxMoves: 5
readonly property bool ballMoving: ballAnimation.running
source: "#Sphere"
scale: Qt.vector3d(ballScale, ballScale, ballScale)
materials: PrincipledMaterial {
baseColorMap: Texture {
source: "images/ball.jpg"
}
normalMap: Texture {
source: "images/ball_n.jpg"
}
normalStrength: 1.0
}Cuando se mueve el ratón o se desliza el dedo por la pantalla táctil, las últimas posiciones de maxMoves antes de soltar la pelota se almacenan en el array moves. Cuando el usuario suelta la pelota, se llama a throwBall(), que calcula la dirección de la pelota a partir de estas últimas posiciones y comienza a animarla.
function resetBall() {
moves = [];
x = 0;
y = mainWindow.ballSize/2;
z = 400;
}
function moveBall(posX, posY) {
if (!mainWindow.gameOn) return;
var pos = view3D.mapTo3DScene(Qt.vector3d(posX, posY, ballModel.z + mainWindow.ballSize));
pos.y = Math.max(mainWindow.ballSize / 2, pos.y);
var point = {"x": pos.x, "y": pos.y };
moves.push(point);
if (moves.length > maxMoves) moves.shift();
// Apply position into ball model
ballModel.x = pos.x;
ballModel.y = pos.y;
}
function throwBall() {
if (!mainWindow.gameOn) return;
mainWindow.currentBalls--;
var moveX = 0;
var moveY = 0;
if (moves.length >= 2) {
var first = moves.shift();
var last = moves.pop();
moveX = last.x - first.x;
moveY = last.y - first.y;
if (moveY < 0) moveY = 0;
}
directionX = moveX * 20;
directionY = moveY * 4;
ballAnimation.start();
}La posición de la pelota se anima por separado en los distintos ejes. Estas animaciones utilizan los valores previamente asignados a ` directionX ` y ` directionY ` para definir hacia dónde se desplaza la pelota, así como ` speed ` para determinar el tiempo de vuelo de la pelota. La posición vertical cuenta con dos animaciones secuenciales, lo que nos permite aplicar un efecto de aceleración/deceleración (easing) al rebote de la pelota. Cuando finalicen las animaciones de posición, comprobaremos si aún quedan pelotas o si el juego debe terminar. Por último, también animamos la rotación de la pelota, para que el usuario pueda lanzar bolas con efecto.
ParallelAnimation {
id: ballAnimation
running: false
// Move forward
NumberAnimation {
target: ballModel
property: "z"
duration: ballModel.speed
to: -ballModel.directionY * 5
easing.type: Easing.OutQuad
}
// Move up & down with a bounce
SequentialAnimation {
NumberAnimation {
target: ballModel
property: "y"
duration: ballModel.speed * (1 / 3)
to: ballModel.y + ballModel.directionY
easing.type: Easing.OutQuad
}
NumberAnimation {
target: ballModel
property: "y"
duration: ballModel.speed * (2 / 3)
to: mainWindow.ballSize / 4
easing.type: Easing.OutBounce
}
}
// Move sideways
NumberAnimation {
target: ballModel
property: "x"
duration: ballModel.speed
to: ballModel.x + ballModel.directionX
}
onFinished: {
if (mainWindow.currentBalls <= 0)
view3D.endGame();
ballModel.resetBall();
}
}
NumberAnimation on eulerRotation.z {
running: ballModel.ballMoving
loops: Animation.Infinite
from: ballModel.directionX < 0 ? 0 : 720
to: 360
duration: 10000 / (2 + Math.abs(ballModel.directionX * 0.05))
}Una parte importante del juego consiste en detectar cuándo la pelota golpea los objetivos. Cada vez que cambia la posición z de la pelota, recorremos en bucle la matriz targets y detectamos si la pelota está tocando alguno de ellos utilizando fuzzyEquals(). Cada vez que detectemos un impacto, llamaremos a la función hit() del objetivo y comprobaremos si todos los objetivos han sido derribados.
onZChanged: {
// Loop through target items and detect collisions
var hitMargin = mainWindow.ballSize / 2 + mainWindow.targetSize / 2;
for (var i = 0; i < targetsNode.targets.length; ++i) {
var target = targetsNode.targets[i];
var targetPos = target.scenePosition;
var hit = ballModel.scenePosition.fuzzyEquals(targetPos, hitMargin);
if (hit) {
target.hit();
if (targetsNode.currentTargets <= 0)
view3D.endGame();
}
}
}A continuación, podemos pasar a los objetivos. Estos se generan dinámicamente en un nodo de agrupación que contiene funciones auxiliares y permite, por ejemplo, animar todos los objetivos como un grupo. Ten en cuenta que la propiedad currentTargets es necesaria porque, en las matrices de QML, los cambios no activan los enlaces, por lo que actualizaremos el número de objetivos manualmente.
Node {
id: targetsNode
property var targets: []
property int currentTargets: 0
function addTargets(items) {
items.forEach(function (item) {
let instance = targetComponent.createObject(
targetsNode, { "x": item.x, "startPosY": item.y, "z": item.z, "points": item.points});
targets.push(instance);
});
currentTargets = targets.length;
}
function removeTarget(item) {
var index = targets.indexOf(item);
targets.splice(index, 1);
currentTargets = targets.length;
}
function resetTargets() {
while (targets.length > 0)
targets.pop().destroy();
currentTargets = targets.length;
}
}Los objetivos son nodos con un modelo de cubo y un elemento de texto para mostrar los puntos. Al igual que en el modelo de la bola, utilizamos las texturas « baseColorMap » y « normalMap » para crear cubos con el logotipo de Qt. Cuando se detecta un impacto, animamos secuencialmente la desaparición del cubo y mostramos los puntos obtenidos de este objetivo. Una vez finalizada la animación, eliminaremos dinámicamente el nodo del objetivo.
Component {
id: targetComponent
Node {
id: targetNode
property int points: 0
property real hide: 0
property real startPosY: 0
property real posY: 0
property real pointsOpacity: 0
function hit() {
targetsNode.removeTarget(this);
mainWindow.score += points;
hitAnimation.start();
var burstPos = targetNode.mapPositionToScene(Qt.vector3d(0, 0, 0));
hitParticleEmitter.burst(100, 200, burstPos);
}
y: startPosY + posY
SequentialAnimation {
running: mainWindow.gameOn && !hitAnimation.running
loops: Animation.Infinite
NumberAnimation {
target: targetNode
property: "posY"
from: 0
to: 150
duration: 3000
easing.type: Easing.InOutQuad
}
NumberAnimation {
target: targetNode
property: "posY"
to: 0
duration: 1500
easing.type: Easing.InOutQuad
}
}
SequentialAnimation {
id: hitAnimation
NumberAnimation {
target: targetNode
property: "hide"
to: 1
duration: 800
easing.type: Easing.InOutQuad
}
NumberAnimation {
target: targetNode
property: "pointsOpacity"
to: 1
duration: 1000
easing.type: Easing.InOutQuad
}
NumberAnimation {
target: targetNode
property: "pointsOpacity"
to: 0
duration: 200
easing.type: Easing.InOutQuad
}
ScriptAction {
script: targetNode.destroy();
}
}
Model {
id: targetModel
readonly property real targetScale: (1 + targetNode.hide) * (mainWindow.targetSize / 100)
source: "#Cube"
scale: Qt.vector3d(targetScale, targetScale, targetScale)
opacity: 0.99 - targetNode.hide * 2
materials: PrincipledMaterial {
baseColorMap: Texture {
source: "images/qt_logo.jpg"
}
normalMap: Texture {
source: "images/qt_logo_n.jpg"
}
normalStrength: 1.0
}
Vector3dAnimation on eulerRotation {
loops: Animation.Infinite
duration: 5000
from: Qt.vector3d(0, 0, 0)
to: Qt.vector3d(360, 360, 360)
}
}
Text {
anchors.centerIn: parent
scale: 1 + targetNode.pointsOpacity
opacity: targetNode.pointsOpacity
text: targetNode.points
font.pixelSize: 60 * mainWindow.px
color: "#808000"
style: Text.Outline
styleColor: "#f0f000"
}
}
}También necesitamos algunos modelos para la zona de juego. El modelo del suelo es un rectángulo con texturas de césped escaladas para cubrir una superficie mayor.
Model {
source: "#Rectangle"
scale: Qt.vector3d(50, 50, 1)
eulerRotation.x: -90
materials: PrincipledMaterial {
baseColorMap: Texture {
source: "images/grass.jpg"
tilingModeHorizontal: Texture.Repeat
tilingModeVertical: Texture.Repeat
scaleU: 25.0
scaleV: 25.0
}
normalMap: Texture {
source: "images/grass_n.jpg"
}
normalStrength: 0.6
}
}El modelo del cielo está más atrás, y como no queremos que se proyecten sombras en el cielo, configuramos « receivesShadows » en «false». Para el cielo también añadimos algunas estrellas utilizando el Qt Quick Particles el módulo. Al igual que con otros elementos 2D de « Qt Quick », las partículas también se pueden añadir directamente dentro de los nodos 3D.
Model {
id: sky
property real scaleX: 100
property real scaleY: 20
source: "#Rectangle"
scale: Qt.vector3d(sky.scaleX, sky.scaleY, 1)
position: Qt.vector3d(0, 960, -2000)
// We don't want shadows casted into sky
receivesShadows: false
materials: PrincipledMaterial {
baseColorMap: Texture {
source: "images/sky.jpg"
}
}
// Star particles
Node {
z: 500
y: 30
// Stars are far away, scale up to half the resolution
scale: Qt.vector3d(2 / sky.scaleX, 2 / sky.scaleY, 1)
ParticleSystem {
anchors.horizontalCenter: parent.horizontalCenter
anchors.top: parent.top
width: 3000
height: 400
ImageParticle {
source: "qrc:///particleresources/star.png"
rotationVariation: 360
color: "#ffffa0"
colorVariation: 0.1
}
Emitter {
anchors.fill: parent
emitRate: 4
lifeSpan: 6000
lifeSpanVariation: 4000
size: 30
sizeVariation: 20
}
}
}
}Al combinar los modelos del suelo y del cielo anteriores, obtenemos un mundo 3D como este:

Por último, añadimos algunos destellos a los objetivos, esta vez utilizando el módulo « QtQuick3D.Particles3D ». « ParticleSystem3D » contiene un « SpriteParticle3D » y asignamos « 200 » a cada uno de ellos, lo cual es suficiente para dos ráfagas simultáneas de partículas « 100 ». « ParticleEmitter3D » define las propiedades de emisión de las partículas, como la escala, la rotación, la velocidad y la duración («lifeSpan»). También añadimos un « Gravity3D » «affector» para hacer que las partículas caigan con la intensidad adecuada.
ParticleSystem3D {
id: psystem
SpriteParticle3D {
id: sprite
sprite: Texture {
source: "images/particle.png"
}
color: Qt.rgba(1.0, 1.0, 0.0, 1.0)
colorVariation: Qt.vector4d(0.4, 0.6, 0.0, 0.0)
unifiedColorVariation: true
maxAmount: 200
}
ParticleEmitter3D {
id: hitParticleEmitter
particle: sprite
particleScale: 4.0
particleScaleVariation: 2.0
particleRotationVariation: Qt.vector3d(0, 0, 180)
particleRotationVelocityVariation: Qt.vector3d(0, 0, 250)
velocity: VectorDirection3D {
direction: Qt.vector3d(0, 300, 0)
directionVariation: Qt.vector3d(200, 150, 100)
}
lifeSpan: 800
lifeSpanVariation: 200
depthBias: 100
}
Gravity3D {
magnitude: 600
}
}Con esto finalizan las partes en 3D de nuestro juego. Todavía quedan algunos elementos en 2D Qt Quick para mostrar la hora, las puntuaciones, el botón de inicio, etc., que son importantes para el juego, pero no son relevantes para esta documentación de Quick 3D.
Ahora la pelota está en tu tejado (nunca mejor dicho). ¡No dudes en ampliar el juego de diferentes maneras y crear nuevos niveles alocados!
© 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.