Chap. 08C --- Joints

Using Joints

Joints are connectors between two scene objects that can keep the objects attached to each other. You can use joints to bind two or more objects together so that when one is moved, the other moves with it.

To create a joint using the Joint tool in the builder, click on the first object and drag to the second object, releasing the mouse button with the mouse hovering over the desired second object. This creates a joint between the two objects. you can also create a joint in script using Joint.new and then attach it between two objects using:

myJoint:setObject1(myFirstObject)
myJoint:setObject2(mySecondObject)

Note that it is possible to attach a joint to only one object. If this is done, the object becomes anchored to the scene itself at the joint's position. This is useful for doing things like anchoring an object to the ground or to a point in empty space.

Joints also have a position and rotation for their pivots, which is specified in world coordinate space.

myJoint:setPosition(desiredPosition)
myJoint:setRotation(axisAlignment)

While all joints have a position, only certain joints (such as hinge and universal) respect rotation. The rotation of the joint determines where the joint's free axes are aligned; hinge joints have one free axis, and the rotation goes from the global positive-y axis to the orientation of the joint's free axis. For universal joints, the rotation goes from the positive-y and positive-z global axes to the two free axes of the universal joint.

Types of joints

Wild Pockets supports the following types of joints (support for more types is coming soon):

Ball Allows two objects to rotate about a pivot point arbitrarily in all three axes of rotation. The distance to the pivot point is kept fixed.
Universal Allows two objects to rotate about a pivot point arbitrarily in two axes, but a third axis is kept fixed. You can imagine this joint as built with a cross-shaped connector. This type of joint is useful for building a bent linkage, where two bars are at an angle to each other but rotating one bar rotates the other bar.
Hinge Allows two objects to rotate around one specific axis of freedom.
Anchor Keeps two objects fixed to each other in terms of position and orientation.

You can select the type of joint in the builder, or by using the Joint:setType command. Note that changing from one joint to another can lose some information if you try to change back; for example, ball joints do not constrain on any axis and therefore have no concept of "joint rotation," so changing from a hinge to a ball and back to a hinge is likely to lose the axis of rotation on the hinge.

Enabling a joint

Joints must be enabled to actually effect either object they are attached to, otherwise they will just stay at their current position in world space and effectively do nothing. After attaching a joint to two objects and setting its type, you must call:

Joint:setEnabled(true)

This will start the joint acting on its attached objects. If you would like a joint to stop acting on its attached objects, simply call the same function, but set enabled to FALSE. This will again, leave the joint in its current position until you setEnabled(true) again. If you are done using a joint, simply call:

delete(joint)

Modifying joints: break force and angle constraints

You can create joints that break when more than a certain amount of force is applied to the joint. To make a joint breakable, use the following command:

myJoint:setBreakForce(desiredBreakForce)

The break force is specified in newtons; specifying 0 denotes the joint should be unbreakable. A reasonable break force to test setBreakForce is around 4000 newtons.

You can also specify a minimum and maximum deflection angle for a joint; the joint will be restricted from travelling outside the angle ranges.

myJoint:setRange(min,max)

The "min" and "max" deflections are relative to the joint's initial position. Note that disabling and re-enabling a joint resets its initial position when the joint is enabled.