Previous topic

18.6. The CollisionUtils Object

Next topic

18.8. The Physics2DDebugDraw Object

18.7. The Constraint Object¶

18.7.1. Constructor¶

A Constraint object can be constructed with one of:

Constructors for constraints take many common parameters which are listed below

{
stiff : true,
frequency : 10,
damping : 1,
maxForce : Number.POSITIVE_INFINITY,
maxError : Number.POSITIVE_INFINITY,
removeOnBreak : true,
breakUnderForce : false,
breakUnderError : false,
ignoreInteractions : false,
sleeping : false,
disabled : false,
userData : null
}
stiff (Optional)

Defines whether a positional constraint has its positional errors solved rigidly together with contact errors, or whether positional errors are resolved through mutations of the velocity constraint making the constraint elastic.

An elastic constraint is implemented in such a way that high frequency and damping will not cause the constraint to blow up.

This parameter has no effect on velocity-only constraints such as the MotorConstraint.

Default value is true.

frequency (Optional)

Defines the frequency of the constraint’s elastic behavior when positional constraint is non-stiff.

This value must be strictly positive.

This parameter has no effect on velocity-only constraints such as the MotorConstraint, or when a position constraint is stiff.

Default value is 10.

damping (Optional)

Defines the damping of the constraint’s elastic behavior when positional constraint is non-stiff.

This value must be positive.

This parameter has no effect on velocity-only constraints such as the MotorConstraint, or when a position constraint is stiff.

Default value is 1.

maxForce (Optional)

Defines for non-stiff positional constraints, and for velocity-only constraints the maximum amount of force that may be used when solving errors in velocity.

This value must be positive.

When such a constraint has also breakUnderForce set to true. This value defines the limit at which the constraint will be broken.

Default value is Number.POSITIVE_INFINITY.

maxError (Optional)

Defines for positional constraints, the maximum amount of error which will either be solved (For non-stiff constraints) per second, or the limit at which the constraint will be broken if breakUnderError is also true.

This parameter has no effect on velocity-only constraints such as the MotorConstraint.

This value must be positive.

Default value is Number.POSITIVE_INFINITY.

removeOnBreak (Optional)

Defines behavior for when this constraint is broken.

When true, the constraint will be removed from the simulation World when broken.

When false, the constraint will remain in the world, but will become disabled.

Default value is true.

breakUnderForce (Optional)

For non-stiff positional constraints, and velocity-only constraints this parameter defines whether upon reaching the maxForce parameter, the constraint will either limit the amount of force it uses, or be broken.

Default value is false.

breakUnderError (Optional)

For positional constraints, this parameter defines whether upon reaching the maxError parameter, the amount of error resolved will be clamped (For non-stiff constraints, otherwise ignored) or broken (Both stiff and non-stiff constraints).

Default value is false.

ignoreInteractions (Optional)
Defines whether the participating RigidBody objects used by this constraint will be permitted to interact (Whether as sensors, or colliders).

Default value is false.

sleeping (Optional)

Define if the constraint is to be created in a sleeping state. When added to a World object, the constraint will remain asleep until woken.

Default value is false.

disabled (Optional).

Define whether the constraint will be created as already disabled.

Disabling a constraint permits it to remain inside of a World, but acting as though it is not, with no side effects beyond the constraint being present in the RigidBody object’s constraints list, and being removed when a related RigidBody is removed from the world.

Default value is false.

userData (Optional).

A field in which to store whatever data you may like.

Default value is null.

18.7.2. Methods¶

18.7.2.1. configure¶

Summary

Configure common constraint parameters.

Syntax

constraint.configure({
stiff : true,
frequency : 10,
damping : 1,
maxForce : Number.POSITIVE_INFINITY,
maxError : Number.POSITIVE_INFINITY,
removeOnBreak : true,
breakUnderForce : false,
breakUnderError : false,
ignoreInteractions : false
});

All parameters of the object are optional, and leaving unspecified will leave said parameter untouched.

18.7.2.2. wake¶

Summary

Manually wake this Constraint.

Waking a constraint manually is not generally required. It is only ever required to manually wake a constraint, if you manually put it to sleep or added it as a sleeping constraint.

Mutations to the constraint, and interactions with related rigid bodies in the world will otherwise automatically wake the constraint.

Syntax

constraint.wake();

18.7.2.3. sleep¶

Summary

Manually put this Constraint to sleep.

This constraint will be woken as soon as it is interacted with in a World, or is mutated in any way that would require it to wake up in normal circumstances.

Syntax

constraint.sleep();

18.7.2.4. isEnabled¶

Summary

Query whether this constraint is currently enabled.

Syntax

var enabled = constraint.isEnabled();

18.7.2.5. isDisabled¶

Summary

Query whether this constraint is currently disabled.

Syntax

var disabled = constraint.isDisabled();

18.7.2.6. enable¶

Summary

Enable this constraint.

Syntax

constraint.enable();

18.7.2.7. disable¶

Summary

Disable this constraint.

Syntax

constraint.disable();

Summary

Add a new event listener for this Constraint.

Syntax

eventType

One of:

‘wake’
Issued when this constraint is woken. This event is not generated when using the wake() method manually.
‘sleep’
Issued when this constraint is put to sleep. This event is not generated when using the sleep() method manually.
‘break’
Issued when this constraint is broken.
handler

Function to be called when this event occurs (Noting that events as usual are deferred until the end of the world step()).

Function is called with no arguments, and with its this object as the Constraint to which the event relates.

This function will fail, and return false if the event type was not accepted, or if the handler already exists for the given event type.

Example:

function breakHandler() {
console.log("Constraint named: " + this.userData.name + "was broken :(");
}

constraint.userData = {
name : "Constraint no. 1"
};

You may add as many handlers for a given event type as you wish, and handlers will be called in the same order in which they were added.

18.7.2.9. removeEventListener¶

Summary

Remove existing event listener from this Constraint.

Syntax

var success = constraint.removeEventListener(eventType, handler);

This function will fail, and return false if the event type was not accepted, or if the handler was not found on the constraint for the given event type.

18.7.2.10. getImpulseForBody¶

Summary

Query the impulse applied to the given RigidBody by this constraint in the previous simulation step.

The impulse returned is of 3 dimensions, the third equal to the angular impulse the constraint applied.

Syntax

var impulse = constraint.getImpulseForBody(body);
// or
constraint.getImpulseForBody(body, impulse);
impulse (Optional)
If specified, the impulse will be stored in this array, otherwise a new array will be created to be returned.

Should the input body be unrelated to this constraint, the impulse returned will be [0, 0, 0]

18.7.2.11. getAnchorA¶

Summary

Get local anchor point on first rigid body.

Syntax

var anchor = constraint.getAnchorA();
// or
constraint.getAnchorA(anchor);
anchor (Optional)
If specified, the anchor will be stored in this array, otherwise a new array will be created to be returned.

Note

Available for constraint types: Point, Distance, Pulley, Weld, Line only.

18.7.2.12. setAnchorA¶

Summary

Set the local anchor point on first rigid body.

Syntax

constraint.setAnchorA(anchor);
anchor
The new anchor point for first rigid body in constraint.

Note

Available for constraint types: Point, Distance, Pulley, Weld, Line only.

18.7.2.13. getAnchorB¶

Summary

Get local anchor point on second rigid body.

Syntax

var anchor = constraint.getAnchorB();
// or
constraint.getAnchorB(anchor);
anchor (Optional)
If specified, the anchor will be stored in this array, otherwise a new array will be created to be returned.

Note

Available for constraint types: Point, Distance, Pulley, Weld, Line only.

18.7.2.14. setAnchorB¶

Summary

Set the local anchor point on second rigid body.

Syntax

constraint.setAnchorB(anchor);
anchor
The new anchor point for second rigid body in constraint.

Note

Available for constraint types: Point, Distance, Pulley, Weld, Line only.

18.7.2.15. getAnchorC¶

Summary

Get local anchor point on third rigid body.

Syntax

var anchor = constraint.getAnchorC();
// or
constraint.getAnchorC(anchor);
anchor (Optional)
If specified, the anchor will be stored in this array, otherwise a new array will be created to be returned.

Note

Available for constraint type Pulley only.

18.7.2.16. setAnchorC¶

Summary

Set the local anchor point on third rigid body.

Syntax

constraint.setAnchorC(anchor);
anchor
The new anchor point for third rigid body in constraint.

Note

Available for constraint type Pulley only.

18.7.2.17. getAnchorD¶

Summary

Get local anchor point on fourth rigid body.

Syntax

var anchor = constraint.getAnchorD();
// or
constraint.getAnchorD(anchor);
anchor (Optional)
If specified, the anchor will be stored in this array, otherwise a new array will be created to be returned.

Note

Available for constraint type Pulley only.

18.7.2.18. setAnchorD¶

Summary

Set the local anchor point on fourth rigid body.

Syntax

constraint.setAnchorD(anchor);
anchor
The new anchor point for fourth rigid body in constraint.

Note

Available for constraint type Pulley only.

18.7.2.19. getAxis¶

Summary

Get local axis point on first rigid body for line direction.

Syntax

var axis = constraint.getAxis();
// or
constraint.getAxis(axis);
axis (Optional)
If specified, the axis will be stored in this array, otherwise a new array will be created to be returned.

Note

Available for constraint type Line only.

18.7.2.20. setAxis¶

Summary

Set local axis point on first rigid body for line direction.

Syntax

constraint.setAxis(axis);
axis
The new axis point for first rigid body in constraint.

Note

Available for constraint type Line only.

18.7.2.21. getLowerBound¶

Summary

Query the lower bound for constraint.

Syntax

var lowerBound = constraint.getLowerBound();

Note

Available for constraint types: Distance, Angle, Line, Pulley only.

18.7.2.22. setLowerBound¶

Summary

Set the lower bound on constraint.

Syntax

constraint.setLowerBound(lowerBound);
lowerBound
The new lower bound for constraint. Restrictions may change depending on constraint type.

Note

Available for constraint types: Distance, Angle, Line, Pulley only.

18.7.2.23. getUpperBound¶

Summary

Query the upper bound for constraint.,

Syntax

var upperBound = constraint.getUpperBound();

Note

Available for constraint types: Distance, Angle, Line, Pulley only.

18.7.2.24. setUpperBound¶

Summary

Set the upper bound on constraint.

Syntax

constraint.setUpperBound(upperBound);
upperBound
The new upper bound for constraint. Restrictions may change depending on constraint type.

Note

Available for constraint types: Distance, Angle, Line, Pulley only.

18.7.2.25. getRatio¶

Summary

Query the current ratio parameter on constraint.

Syntax

var ratio = constraint.getRatio();

Note

Available for constraint types: Angle, Motor, Pulley only.

18.7.2.26. setRatio¶

Summary

Set the ratio parameter on constraint.

Syntax

constraint.setRatio(ratio);
ratio
The new value for ratio parameter.

Note

Available for constraint types: Angle, Motor, Pulley only.

18.7.2.27. getRate¶

Summary

Query the current motor rate parameter on constraint.

Syntax

var rate = constraint.getRate();

Note

Available for constraint type Motor only.

18.7.2.28. setRate¶

Summary

Set the motor rate parameter on constraint.

Syntax

constraint.setRate(rate);
rate
The new value for rate parameter.

Note

Available for constraint type Motor only.

18.7.2.29. getPhase¶

Summary

Query the current angular phase parameter on constraint.

Syntax

var phase = constraint.getPhase();

Note

Available for constraint type Weld only.

18.7.2.30. setPhase¶

Summary

Set the angular phase parameter on constraint.

Syntax

constraint.setPhase(phase);
phase
The new value for phase parameter.

Note

Available for constraint type Weld only.

18.7.3. Properties¶

18.7.3.1. type¶

A string identifying the type of this Constraint object, one of:

• ‘POINT’
• ‘DISTANCE’
• ‘ANGLE’
• ‘WELD’
• ‘LINE’
• ‘PULLEY’
• ‘MOTOR’
• ‘CUSTOM’

Note

18.7.3.2. world¶

Summary

The current World object that this constraint is assigned to.

Note

18.7.3.3. sleeping¶

Summary

Whether this constraint object is currently sleeping in an ongoing simulation.

Note

18.7.3.4. userData¶

Summary

Field to which you may assign whatever data you wish.

18.7.3.5. dimension¶

Summary

The dimension of this constraint.

Note

18.7.3.6. bodyA¶

Summary

The first RigidBody associated with this constraint.

Note

Read Only. Not defined for constraint type Custom.

18.7.3.7. bodyB¶

Summary

The second RigidBody associated with this constraint.

Note

Read Only. Not defined for constraint type Custom.

18.7.3.8. bodyC¶

Summary

The third RigidBody associated with this constraint.

Note

Read Only. Defined only for constraint type Pulley.

18.7.3.9. bodyD¶

Summary

The fourth RigidBody associated with this constraint.

Note

Read Only. Defined only for constraint type Pulley.

18.7.3.10. bodies¶

Summary

Set of RigidBody objects associated with this CustomConstraint.

Note

Read Only. Defined only for constraint type Custom.