En esta página

Qt Quick Física 3D: ejemplo sencillo

Muestra cómo configurar una escena física sencilla.

Captura de pantalla de un paisaje verde con tres objetos 3D diferentes situados uno al lado del otro

Este ejemplo ofrece una visión general introductoria de las funciones básicas de Quick 3D Physics a través del análisis del código de un ejemplo sencillo. Ten en cuenta que esta introducción da por hecho que estás familiarizado con el módulo 3D de « Qt Quick ».

Configuración

Todo el ejemplo está contenido y configurado en el archivo main.qml. Veamos primero el objeto que crea el mundo físico. Este nodo se llama « PhysicsWorld »:

PhysicsWorld {
    scene: viewport.scene
}

Establecemos la propiedad « scene » en la escena de nuestro « View3D ». La propiedad « scene » define dónde buscará la simulación los nodos físicos que debe simular. Cualquier nodo físico situado fuera del nodo de escena no formará parte de la simulación.

Escena

Echemos un vistazo a la escena.

View3D {
    id: viewport
    anchors.fill: parent

    environment: SceneEnvironment {
        clearColor: "#d6dbdf"
        backgroundMode: SceneEnvironment.Color
    }

    PerspectiveCamera {
        position: Qt.vector3d(-200, 100, 500)
        eulerRotation: Qt.vector3d(-20, -20, 0)
        clipFar: 5000
        clipNear: 1
    }

    DirectionalLight {
        eulerRotation.x: -45
        eulerRotation.y: 45
        castsShadow: true
        brightness: 1
        shadowFactor: 50
    }

    StaticRigidBody {
        position: Qt.vector3d(0, -100, 0)
        eulerRotation: Qt.vector3d(-90, 0, 0)
        collisionShapes: PlaneShape {}
        Model {
            source: "#Rectangle"
            scale: Qt.vector3d(10, 10, 1)
            materials: PrincipledMaterial {
                baseColor: "green"
            }
            castsShadows: false
            receivesShadows: true
        }
    }

    DynamicRigidBody {
        position: Qt.vector3d(-100, 100, 0)
        collisionShapes: BoxShape {
            id: boxShape
        }
        Model {
            source: "#Cube"
            materials: PrincipledMaterial {
                baseColor: "yellow"
            }
        }
    }

    DynamicRigidBody {
        position: Qt.vector3d(0, 100, 0)
        collisionShapes: SphereShape {
            id: sphereShape
        }
        Model {
            source: "#Sphere"
            materials: PrincipledMaterial {
                baseColor: "blue"
            }
        }
    }

    DynamicRigidBody {
        position: Qt.vector3d(75, 200, 0)
        collisionShapes: CapsuleShape {
            id: capsuleShape
        }

        Model {
            geometry: CapsuleGeometry {}
            materials: PrincipledMaterial {
                baseColor: "red"
            }
        }
    }
}

Nuestra escena es simplemente un ` View3D `, ya que queremos dibujar nuestros objetos físicos. Contiene un ` PerspectiveCamera ` y un ` DirectionalLight ` para el renderizado, pero, lo que es más importante, contiene un ` StaticRigidBody ` y tres nodos ` DynamicRigidBody `. En física, un cuerpo rígido es un cuerpo sólido, no deformable y de densidad uniforme. Disponemos de dos tipos de cuerpos rígidos: StaticRigidBody y DynamicRigidBody. Un StaticRigidBody es un nodo QML que contiene un cuerpo rígido estático (inamovible). Técnicamente es posible mover el cuerpo, pero ello conllevará una pérdida de rendimiento. Por otro lado, un DynamicRigidBody se utiliza para objetos que pueden moverse. Un « DynamicRigidBody » tiene una propiedad « isKinematic »; cuando se establece en «true», el cuerpo rígido no se verá afectado por fuerzas externas y podrá controlarse mediante scripts y animaciones. Por ejemplo, un balón de fútbol no sería cinemático, pero un ascensor o una plataforma móvil sí lo serían normalmente. Esto también significa que, si se actualiza la propiedad « position » del balón de fútbol, este no se movería a esa posición, mientras que el ascensor sí lo haría.

Para poder interactuar con otros objetos físicos, es necesario configurar la propiedad « collisionShapes ». La propiedad « collisionShapes » es una lista que puede contener una o más formas y que actuará como una unidad rígida combinada. Puedes colocar y rotar estas formas unas respecto a otras. Ten en cuenta que las formas «plano», «malla triangular» y «mapa de altura» solo funcionan con cuerpos dinámicos si el cuerpo es cinemático.

Formas

Nuestra escena contiene cuatro objetos físicos (plano, caja, bola y cápsula). Los analizaremos uno por uno.

Plano
StaticRigidBody {
    position: Qt.vector3d(0, -100, 0)
    eulerRotation: Qt.vector3d(-90, 0, 0)
    collisionShapes: PlaneShape {}
    Model {
        source: "#Rectangle"
        scale: Qt.vector3d(10, 10, 1)
        materials: PrincipledMaterial {
            baseColor: "green"
        }
        castsShadows: false
        receivesShadows: true
    }
}

Creamos un plano mediante un nodo « StaticRigidBody ». En este nodo, configuramos la propiedad « collisionShapes » para que contenga un « PlaneShape ». Los planos dividen el espacio en «por encima» y «por debajo» de ellos. Todo lo que se encuentre «por debajo» del plano colisionará con él y será empujado por encima. El plano se sitúa en el plano YZ, con «por encima» apuntando hacia el eje X positivo. Colocamos un «Model» dentro de nuestro nodo « StaticRigidBody » para renderizar el plano. Se trata de un patrón habitual que garantiza que el modelo también se mueva y gire de la misma forma cuando el objeto físico interactúe en la escena. Como queremos que el plano se sitúe en el plano XY, lo giramos utilizando la propiedad « eulerRotation ». Giramos el modelo de forma similar.

Caja
DynamicRigidBody {
    position: Qt.vector3d(-100, 100, 0)
    collisionShapes: BoxShape {
        id: boxShape
    }
    Model {
        source: "#Cube"
        materials: PrincipledMaterial {
            baseColor: "yellow"
        }
    }
}

Creamos una esfera creando un nodo « DynamicRigidBody » y un único « BoxShape » en « collisionShapes ». Al tratarse de un nodo dinámico, la caja interactuará con la escena colisionando y moviéndose como un objeto libre. Dado que el modelo del cubo es cien veces más grande que un cubo unitario, necesitamos escalarlo en consecuencia. Al tratarse de un cuerpo dinámico y, por lo tanto, tener un peso físico, configuramos la propiedad « density ».

Esfera
DynamicRigidBody {
    position: Qt.vector3d(0, 100, 0)
    collisionShapes: SphereShape {
        id: sphereShape
    }
    Model {
        source: "#Sphere"
        materials: PrincipledMaterial {
            baseColor: "blue"
        }
    }
}

Creamos una esfera creando un nodo « DynamicRigidBody » y un único « SphereShape » en collisionShapes.

Cápsula
DynamicRigidBody {
    position: Qt.vector3d(75, 200, 0)
    collisionShapes: CapsuleShape {
        id: capsuleShape
    }

    Model {
        geometry: CapsuleGeometry {}
        materials: PrincipledMaterial {
            baseColor: "red"
        }
    }
}

Creamos una cápsula creando un nodo « DynamicRigidBody » y un único « CapsuleShape » en « collisionShapes ». Construimos un modelo de cápsula utilizando la geometría integrada «CapsuleGeometry» que proporciona « Qt Quick 3D».

Archivos:

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