Simulates a physics world and contains all physics bodies. More...

Import Statement: import VPlay 2.0



Detailed Description

The PhysicsWorld component contains all physics bodies. You can set the gravity of all objects, and display a debug view of the physics bodies and applied forces in the PhysicsWorld. The debug view is enabled by default for debug builds and is painted with an opacity of 0.5. This is how the debug view looks like:

The z property of PhysicsWorld is set to 1 by default, to guarantee the debug view is drawn on top of the other game entities and ingame menus. You can use the World::running property to pause physics simulation while the user is inside the ingame menus and not playing.

Type of Games Using Physics

There are 2 types of games that benefit of using physics:

Physics-Driven Games

This kind of games use physics for calculating the movement of all game entities, based on the physics properties of the BoxCollider and CircleCollider like density, friction and restitution and the World::gravity property. These kind of games usually benefit from setting the updatesPerSecondForPhysics to 60, because the entity positions gets then updated with the same frequency as the display refresh rate.

Examples of this kind of games include platformers like ChickenOutbreak Demo or Jump 'n' Runs like OneMoreLevel Demo. Also CarChallenge Demo is a physics-driven racing game that belongs into this section.

Physics Used Only for Collision Detection

In contrast to Physics-Driven Games, these kind of games do not get their entities' positions updated from the PhysicsWorld. That means there is no gravity set, and the position is not modified by applying forces or impulses. Instead, the positions get updated externally from AI components like MoveToPointHelper or with a NumberAnimation. An example of this kind of game is the tower-defense game Squaby, which uses the physics world for collision detection only and uses a MoveToPointHelper for movement of the game entities.

For this kind of games, set the Body::collisionTestingOnlyMode property to true, because several performance optimizations can then be performed.

So in general, all kind of games that need information when 2 entities collide should use a PhysicsWorld and the corresponding BoxCollider or CircleCollider components.

Body Queries

You can use the World::bodyAt() function to receive a Body at the given world point. This is useful for example to detect which body was clicked. See the guide Entity Based Game Design for an example usage.

Example Usage

This code adds a PhysicsWorld to the same level as the entities and sets the earth gravity:

  import VPlay 2.0
  import QtQuick 2.0

  GameWindow {
    Scene {
       id: scene

       PhysicsWorld {
           gravity.y: 9.81

       EntityBase {
           entityType: "box"

           Image {
               id: boxImage
               source: "../assets/img/box.png"
           BoxCollider {
               anchors.fill: boxImage

Property Documentation

debugDraw : DebugDraw

Provides access to the DebugDraw object used to render a debug view of the PhysicsWorld internally. Use this property to change properties like for example the opacity of the DebugDraw of the physics world.

debugDrawVisible : bool

Set this property to true, if you want to display the debug view of the PhysicsWorld. That contains a visual representation of physics bodies, forces and if the body is active.

The default value is true for debug builds and false for release builds.

updatesPerSecondForPhysics : int

This property holds how often the physics world gets updated per second.

It has a big effect on performance - the more updates per second are done, the more calculations need to be done. By default it is set to 30 updates per second, which is enough for games that are using physics only for collision detection. If you want to make a game that is physics-driven, e.g. where you apply forces and have a non-zero gravity defined, try to set this property to 60 to be in sync with the display update rate.

A performance tip in general is, to test the lowest setting for this property - if it still looks fine with a setting of 10 you can go for it. Other typical settings are 30 and 60.

Further performance tweaking properties for the PhysicsWorld are World::positionIterations and World::velocityIterations.

See also World::positionIterations and World::velocityIterations.

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
create apps
create games
cross platform
native performance
3rd party services
game network
level editor
easiest to learn
biggest time saving
best support