Revision control
++ // Copyright (C) 2022 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example simple
++ \ingroup quick3dphysics-examples
++ \title Qt Quick 3D Physics - Simple Example
++ \examplecategory {3D}
++ \brief Demonstrates setting up a simple physics scene.
++ \image simple-example.jpg {Screenshot of a green landscape with three different 3d objects next
++ to each other}
++
++ This example gives an introductory overview of the basic Quick 3D Physics features by
++ going through the code of a simple example. Note that this introduction assumes a familiarity
++ with the Qt Quick 3D module.
++
++ \section1 Setup
++
++ The whole example is contained and set up in the \e main.qml file. Let's first look
++ at the object that creates the physical world. This node is called PhysicsWorld:
++
++ \snippet simple/main.qml world
++
++ We set the \l {PhysicsWorld::} {scene} property to the scene of our View3D. The \c scene property
++ defines where the simulation will look for physics nodes to simulate. Any physics nodes placed
++ outside of the scene node will not be part of the simulation.
++
++ \section1 Scene
++
++ Let's have a look at the scene.
++
++ \snippet simple/main.qml scene
++
++ Our scene is just a View3D since we want to draw our physical objects.
++ It contains a PerspectiveCamera and a DirectionalLight for rendering, but more importantly
++ it contains a StaticRigidBody and three DynamicRigidBody nodes. In physics, a rigid body is
++ a non-deformable, solid body with uniform density. We have two types of rigid bodies available;
++ StaticRigidBody and DynamicRigidBody. A StaticRigidBody is a QML node which contains a static (immovable) rigid body.
++ It is technically possible to move the body but it will incur a performance penalty. A DynamicRigidBody
++ on the other hand is used for objects that can move. A DynamicRigidBody has a \l {DynamicRigidBody::} {isKinematic}
++ property, when it is set to true the rigid body will not be influenced by external forces and can be
++ controlled from scripts and animations. For instance a football would not be kinematic but an elevator
++ or a moving platform typically would. This also means that if you update the \c position property
++ of the football it would not move to that position whereas the elevator would.
++
++ To be able to interact with other physical objects the \l {PhysicsNode::} {collisionShapes}
++ property needs to be set. The \l {PhysicsNode::} {collisionShapes} property is a list that
++ can contain one or more shapes and will act as one rigid unit combined. You can position and
++ rotate these shapes in relation to each other. Note that plane, triangle mesh and heightmap
++ shapes only work with dynamic bodies if the body is kinematic.
++
++ \section1 Shapes
++
++ Our scene contains four physical objects (plane, box, ball, capsule). We will go through them one at a time.
++
++ \section2 Plane
++
++ \snippet simple/main.qml plane
++
++ We create a plane by making a StaticRigidBody node. In this node we set the \l {PhysicsNode::} {collisionShapes}
++ property to contain a PlaneShape. Planes divide space into "above" and "below" them. Everything "below"
++ the plane will collide with it and be pushed above it. The Plane lies on the YZ plane with "above"
++ pointing towards positive X. We put a Model inside our StaticRigidBody node to render the plane.
++ This is a common pattern which makes sure that the model also moves and rotates in the same way
++ when the physical object interacts in the scene. Since we want the plane to lie on the XY plane
++ we rotate it using the \c eulerRotation property. We rotate the model in a similar way.
++
++ \section2 Box
++
++ \snippet simple/main.qml box
++
++ We create a sphere by making a DynamicRigidBody node and a single BoxShape in \l {PhysicsNode::} {collisionShapes}.
++ Since this is a dynamic node the box will interact with the scene by colliding and moving like a free object.
++ Since the cube model is a hundred times bigger than a unit cube we need to scale it accordingly.
++ Since this is a dynamic body and thus have a physical weight we set the \l {DynamicRigidBody::} {density} property.
++
++ \section2 Sphere
++
++ \snippet simple/main.qml sphere
++
++ We create a sphere by making a DynamicRigidBody node and a single SphereShape in \l {PhysicsNode::} {collisionShapes}.
++
++ \section2 Capsule
++
++ \snippet simple/main.qml capsule
++
++ We create a capsule by making a DynamicRigidBody node and a single CapsuleShape in \l {PhysicsNode::} {collisionShapes}.
++ We build a capsule model by using the built-in CapsuleGeometry provided by Qt Quick 3D.
++ */