Joints

Joints are used to assemble more complex game objects from multiple rigid bodes. For example, joints would be used to join the limbs of a ragdoll figure, or the wheels of a car.

Box2D includes a number of different joint types, each with different parameters and functions. Some joint types can be powered by motors, and others are subject to various physical restrictions in their ranges of motion.

The simplest joint type is the “pivot” joint, which joins two objects at a single pivot point, and is illustrated in the “Bridge” and “Chains” sample projects.

To construct a joint, first construct the bodies that will be joined, and then submit those bodies to the desired joint constructor function.

Pivot joint

A pivot joint (also known as a “revolute joint” in Box2D terms) joins two bodies at an overlapping point. The initial arguments are the two bodies joined, followed by an anchor point in the global coordinates of the world.

Pivot joints can optionally be constrained in their range of rotation. For example, if constructing a “ragdoll” figure, the head/neck joint would have a limited range of angular motion.

myJoint = physics.newJoint( "pivot", crateA, crateB, 200,300 )

Joint motors

myJoint.isMotorEnabled -- (boolean)
myJoint.motorSpeed
myJoint.motorTorque  -- (get-only)
myJoint.maxMotorTorque  -- (set-only)

By default, joint motors have a fairly weak maximum torque, and therefore setting motorSpeed may appear to have little visible effect. Therefore, you should generally set maxMotorTorque to a high value (such as 100000) if you are trying to move any significant mass, such as rotating a wheel to power a car.

Rotation limits

Pivot joints can optionally be constrained in their range of rotation. For example, if constructing a "ragdoll" figure, the head/neck joint would have a limited range of angular motion. These rotation limits are specified in degrees:

myJoint.isLimitEnabled = true -- (boolean)
 
myJoint:setRotationLimits( -45, 45 )
a1, a2 = myJoint:getRotationLimits()

Other attributes:

myJoint.jointAngle -- (get-only; value in degrees)
myJoint.jointSpeed -- (get only; value in degrees per second)

Distance joint

A distance joint joins two bodies at a fixed distance. The initial arguments are the two bodies joined, followed by an (x,y) anchor point for each body. Anchor points are declared in the world coordinates.

myJoint = physics.newJoint( "distance", crateA, crateB, crateA.x,crateA.y, crateB.x,crateB.y )

Other attributes:

myJoint.length
myJoint.frequency
myJoint.dampingRatio

length is the distance between the anchor points, which should not be zero or very short (you should use a pivot joint if you need to directly anchor one body to another).

frequency is the mass-spring damping frequency (in Hz)

dampingRatio ranges from 0, for no damping, to 1, for critical damping.

Piston joint

A piston joint (also known as a “prismatic joint” in Box2D terms) joins two bodies along a single, restricted axis of motion, like the pistons or a shock absorber in a car. The initial arguments are the two bodies joined, followed by an anchor point in the first body and a vector defining the axis along which motion is allowed.

myJoint = physics.newJoint( "piston", crateA, crateB, crateA.x,crateA.y, axisDistanceX,axisDistanceY )

(Note: at least one of the bodies should be dynamic, with non-fixed rotation.)

Joint motors

A piston joint may also be driven by a motor. Unlike the pivot joint, this motion will be linear, along the specified axis, rather than rotational.

myJoint.isMotorEnabled -- (boolean)
myJoint.motorSpeed -- (linear speed, in units of pixels per second)
myJoint.motorForce  -- (get-only)
myJoint.maxMotorForce  -- (set-only)

Motion limits

In addition, limits on its range of linear motion may be specified:

myJoint.isLimitEnabled = true -- (boolean)
 
myJoint:setLimits( 100, 200 )
p1, p2 = myJoint:getLimits()

Other attributes:

myJoint.jointTranslation -- (get-only; linear value in pixels)
myJoint.jointSpeed -- (get only; value in pixels per second)

Friction joint

A friction joint is a special kind of pivot joint that resists motion, and is therefore “sticky”:

myJoint = physics.newJoint( "friction", crateA, crateB, 200,300 )

It exposes only two attributes:

myJoint.maxForce
myJoint.maxTorque

Weld joint

A weld joint “welds” two bodies together at a specified point in world coordinates:

myJoint = physics.newJoint( "weld", crateA, crateB, 200,300 )

This joint does not move or rotate at all, and so it exposes no attributes.

However, due to mathematical approximation, this joint may appear slightly “soft” during motion, and so if you want to rigidly bond multiple shapes together, you may want to specify them as multiple body elements within a single complex body, rather than using weld joints.

Wheel joint

A wheel joint (also known as a “line joint” in Box2D terms) combines a piston and a pivot joint, like a wheel mounted on the shock absorber of a car. Most of its properties are inherited from the standard piston joint; the difference is that the body at the end of the axis is allowed to rotate freely.

myJoint = physics.newJoint( "wheel", crateA, crateB, crateA.x,crateA.y, axisDistanceX,axisDistanceY )

Joint motors

Like a piston joint, the “shock absorber” portion of a wheel joint may be driven by a joint motor. This motion will be linear, along the specified axis, rather than rotational.

myJoint.isMotorEnabled -- (boolean)
myJoint.motorSpeed -- (linear speed, in units of pixels per second)
myJoint.motorForce  -- (get-only)
-- myJoint.maxMotorForce  -- (not currently supported in Box2D library; known bug)

Motion limits

In addition, limits on its range of linear motion may be specified:

myJoint.isLimitEnabled = true -- (boolean)
 
myJoint:setLimits( 100, 200 )
p1, p2 = myJoint:getLimits()

Other attributes:

myJoint.jointTranslation -- (get-only; linear value in pixels)
myJoint.jointSpeed -- (get only; value in pixels per second)

Pulley joint

A pulley joint attaches two bodies with an imaginary rope whose length remains constant: if one body is pulled down, the other one will move up.

This constructor is a bit complicated, because it must specify a joint anchor point within each body, and also a stationary anchor point in world coordinates for each side of the “rope” to hang from. Finally, there is a “ratio” property to optionally simulate a block and tackle arrangement, in which one side of the rope moves faster than the other. By default, this ratio is 1.0, which simulates a simple pulley.

myJoint = physics.newJoint( "pulley", crateA, crateB, anchorA_x,anchorA_y, anchorB_x,anchorB_y, crateA.x,crateA.y, crateB.x,crateB.y, 1.0 )

It exposes the following read-only attributes:

myJoint.length1 -- (get-only; value in pixels)
myJoint.length2 -- (get-only; value in pixels)
myJoint.ratio -- (get-only)

Touch joint

A touch joint (based on the Box2D “mouse joint”) connects a single object to the current position of an onscreen touch. This connection is an elastic joint with specifiable strength and behavior, but since it is impossible to apply infinite forces to the simulation, the dragged object may "lag behind" a rapidly moving touch. However, this method allows far more realistic behavior than the non-physical drag method demonstrated in the earlier "DragPlatforms" sample.

For an example of touch joints, including their use with multitouch, see the "DebugDraw" sample code.

myJoint = physics.newJoint( "touch", crate, targetX,targetY )

The initial values of targetX and targetY should be given in world coordinates, but represent the target point on the object. For example, to drag the above object by its center point, you could do the following:

touchJount = physics.newJoint( "touch", crate, crate.x, crate.y )

Alternatively, to drag an object by the point it was touched on:

touchJount = physics.newJoint( "touch", crate, event.x, event.y )

...where the "event" is passed by a touch listener. This behavior is illustrated in the "DebugDraw" sample code.

Note: because the touch joint can follow any (x,y) values, it can also be used for things besides tracking a touch: for example, it could be used to make an object follow a path, if that path was specified as a series of (x,y) values. This should make it useful for Flight Control-style line following applications, among other things.

In general, a touch joint creates a temporary elastic joint between the object and your finger, which makes the object attempt to follow the touch. But since the object remains under simulation, its motion may be stopped by other solid objects, and will interact fully with the other bodies in the world. Also, the object will rotate realistically under gravity when "picked up by one end". (To avoid this behavior, you can connect the touch joint to the object's center of mass rather than to the specific point on the object that you touched.)

Joint target

The touch-following behavior of touch joints is created by passing the current touch (x,y) position to the joint:

myJoint:setTarget( targetX, targetY )

While the updated (targetX, targetY) values will normally come from a touch, any values can be passed. For example, the object could be made to follow another object, or track the points of a path.

The current target values can also be accessed:

targetX, targetY = myJoint:getTarget()

Maximum force

The overall speed or "lag" of the joint depends on the force exerted:

myJoint.maxForce = 10000
force = myJoint.maxForce

By default, this attribute is set to 1000 times the mass of the body, which allows for fairly rapid dragging.

Frequency

The mass-spring damping frequency of the elastic joint (in Hz):

myJoint.frequency = 50
frequency = myJoint.frequency

Damping ratio

The damping ratio of the elastic joint, ranging from 0, for no damping, to 1, for critical damping:

myJoint.dampingRatio = 0.2
damping = myJoint.dampingRatio

The above attributes behave similarly to their counterparts in the Distance joint (see above). As in that case, the default values should work fairly well, but you may want to experiment with other values.

Dragging objects with touch joints

Here is a general function for making a physics object draggable, as seen in the "DebugDraw" sample code:

local physics = require("physics")
physics.start()
system.activate( "multitouch" )
 
-- A general function for dragging physics bodies
local function dragBody( event )
        local body = event.target
        local phase = event.phase
        local stage = display.getCurrentStage()
 
        if "began" == phase then
                stage:setFocus( body, event.id )
                body.isFocus = true
 
                -- Create a temporary touch joint and store it in the object for later reference
                body.tempJoint = physics.newJoint( "touch", body, event.x, event.y )
 
        elseif body.isFocus then
                if "moved" == phase then
                
                        -- Update the joint to track the touch
                        body.tempJoint:setTarget( event.x, event.y )
 
                elseif "ended" == phase or "cancelled" == phase then
                        stage:setFocus( body, nil )
                        body.isFocus = false
                        
                        -- Remove the joint when the touch ends                 
                        body.tempJoint:removeSelf()
                        
                end
        end
 
        -- Stop further propagation of touch event
        return true
end
 
-- Add a physics object
crate = display.newImage( "crate.png" )
physics.addBody( crate, { density=0.8 } )
 
-- Make object draggable
crate:addEventListener( "touch", dragBody )

Common features of all joints

In addition to the above, all joint types share several common attributes and functions:

myJoint:getAnchorA
myJoint:getAnchorB

A function that returns the (x,y) coordinates of the joint’s anchor points within objects A and B, which are the two joined objects. The values are given in the local coordinates of each object, so an anchor point at the center of the object would be at position (0, 0).

x, y = myJoint:getAnchorA()
x, y = myJoint:getAnchorB()

myJoint:getReactionForce

A function that returns the reaction force (in Newtons) at the joint anchor in the second body.

reactionForceX, reactionForceY = myJoint:getReactionForce()

myJoint.reactionTorque

A read-only property that returns the reaction torque (in N*m) at the joint anchor in the second body.

reactionTorque = myJoint.reactionTorque

Destroying joints

To destroy an existing joint, and detach the two bodies (which may then collide), use removeSelf():

myJoint:removeSelf()