MouseJoint

The MouseJoint is used to manipulate bodies with the mouse or touch input. More...

Import Statement: import
Inherits:

Joint

Properties

Methods

Detailed Description

The MouseJoint attempts to drive the physics Body Joint::bodyB towards a target point. There is no restriction on rotation.

It is different to other joints like DistanceJoint, PrismaticJoint or RevoluteJoint in that it does not require 2 bodies to function properly. Instead, only Joint::bodyB needs to be defined, and the target property can be set to the target mouse position from the MouseArea.

Additionally, Joint::bodyA can be set to a body which should be checked for collision detection with the movingBody. For example, you could set it to the ground body, and the Joint::bodyB to a paddle entity of a pong game. That would allow to check collisions between these bodies, as long as Joint::collideConnected is set to true.

The MouseJoint is defined by Joint::bodyA (optional), Joint::bodyB, target, maxForce, frequencyHz, and dampingRatio.

The target point initially coincides with the body's anchor point. The maximum force is used to prevent violent reactions when multiple dynamic bodies interact. You can make this as large as you like. The frequency and damping ratio are used to create a spring/damper effect similar to the distance joint.

Note: Regarding the Box2D doc: Many users have tried to adapt the mouse joint for game play. Users often want to achieve precise positioning and instantaneous response. The mouse joint doesn't work very well in that context. You may wish to consider using kinematic bodies instead.

For a comprehensive documentation of all joints see the Box2D documentation at http://www.box2d.org/manual.html#_Toc258082974.

Example Usage

The following example demonstrates how to move a body towards the mouse position. In this example, a body can be selected by pressing on it

 GameWindow {

   Scene {

     PhysicsWorld {

       id: physicsWorld
       gravity.y: 9.81
     }

     // this entity contains a BoxCollider and falls down because of gravity
     Box {
     }

     // this component is used to create a MouseJoint dynamically every time a body is selected
     Component {
       id: mouseJoint
       MouseJoint {

         maxForce: 30000
         // The damping ratio. 0 = no damping, 1 = critical damping. Default is 0.7
         dampingRatio: 1
         // The response speed, default is 5
         frequencyHz: 2

         //collideConnected: true // collideConnected is only needed, if 2 bodies are connected with a MouseJoint and those should collide or not - but the typical use case for a MouseJoint is that only 1 body is affected, which should be pulled towards a targetPoint
       }
     }

     MouseArea {
       anchors.fill: parent

       property Body selectedBody: null
       property MouseJoint mouseJointWhileDragging: null

       onPressed: {

         selectedBody = physicsWorld.bodyAt(Qt.point(mouseX, mouseY));
         console.debug("selected body at position", mouseX, mouseY, ":", selectedBody);
         if(selectedBody) {
           mouseJointWhileDragging = mouseJoint.createObject(physicsWorld)

           // set the target point to the current mouse position
           mouseJointWhileDragging.target = Qt.point(mouseX, mouseY)

           // set the body to move to the currently selected one
           mouseJointWhileDragging.bodyB = selectedBody

         }
       }

       onPositionChanged: {
         if (mouseJointWhileDragging)
           mouseJointWhileDragging.target = Qt.point(mouseX, mouseY)
       }

       onReleased: {
         // if the user pressed a body initially, don't create a new box but remove the created MouseJoint
         if(selectedBody) {

           selectedBody = null
           if (mouseJointWhileDragging)
             mouseJointWhileDragging.destroy()
         }
       }
     }

   } // end of Scene
 } // end of GameWindow

Property Documentation

dampingRatio : real

The damping ratio. 0 = no damping, 1 = critical damping. The default is 0.7.


frequencyHz : real

The response speed, i.e. how fast the bodyB should move towards the targetPoint. By default, it is set to 5.


maxForce : real

The maximum constraint force that can be exerted to move the candidate body, in kg*pixels/second^2.

Usually you will express as some multiple of the weight (multiplier * mass * gravity).


target : point

The target point where the bodyB will move to, in world coordinates in pixels. It is set in world coordinates in pixels and is by default 0/0, so the top left world position.


Method Documentation

point getReactionForce(real inv_dt)

Returns the reaction force on bodyB, in kg*pixels/second^2 for a timestep of length inv_dt, in seconds.

For the Parameter inv_dt, World::timeStep can be used.


real getReactionTorque(real inv_dt)

This is always 0, since a MouseJoint applies only force and no torque.


Videos

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
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support