Module org.dyn4j

Package org.dyn4j.dynamics.joint

Class PulleyJoint<T extends PhysicsBody>

Object

Joint<T>

PulleyJoint<T>

Type Parameters:

T - the PhysicsBody type

All Implemented Interfaces:

DataContainer, Shiftable, Ownable

public class PulleyJoint<T extends PhysicsBody>
extends Joint<T>
implements Shiftable, DataContainer

Implementation of a pulley joint.

A pulley joint joins two bodies in a pulley system with a fixed length zero mass rope. The bodies are allowed to rotate freely. The bodies are allowed to translate freely up to the total length of the "rope."

The length of the "rope" connecting the two bodies is computed by distance from the pulley anchors to the body anchors including the ratio (if any) when the joint is created. The length can be changed dynamically by calling the setLength(double) method.

The pulley anchor points represent the "hanging" points for the respective bodies and can be any world space point.

This joint can also model a block-and-tackle system by setting the ratio using the setRatio(double) method. A value of 1.0 indicates no ratio. Values between 0 and 1 exclusive indicate that the first body's rope length will be 1/x times longer than the second body's rope length. Values between 1 and infinity indicate that the second body's rope length will be x times longer than the first body's rope length.

By default this joint acts very similar to two DistanceJoints in that the bodies are forced to be their respective rope-distance away from the pulley anchors (i.e. not behaving like a rope). To have the bodies behave as if connected by flexible rope pass in true to the setSlackEnabled(boolean) method.

Since:

2.1.0

Version:

4.0.0

Author:

William Bittle

See Also:

Documentation, Pulley Constraint

Constructor Summary

Constructors

Constructor	Description
PulleyJoint(T body1, T body2, Vector2 pulleyAnchor1, Vector2 pulleyAnchor2, Vector2 bodyAnchor1, Vector2 bodyAnchor2)	Minimal constructor.

Method Summary

Modifier and Type	Method	Description
Vector2	getAnchor1()	Returns the anchor point on the first PhysicsBody in world coordinates.
Vector2	getAnchor2()	Returns the anchor point on the second PhysicsBody in world coordinates.
double	getLength()	Returns the total length of the pulley "rope."
double	getLength1()	Returns the current length from the first pulley anchor point to the anchor point on the first PhysicsBody.
double	getLength2()	Returns the current length from the second pulley anchor point to the anchor point on the second PhysicsBody.
LimitState	getLimitState()	Deprecated. Deprecated in 4.0.0.
Vector2	getPulleyAnchor1()	Returns the pulley anchor point for the first PhysicsBody in world coordinates.
Vector2	getPulleyAnchor2()	Returns the pulley anchor point for the second PhysicsBody in world coordinates.
double	getRatio()	Returns the pulley ratio.
Vector2	getReactionForce(double invdt)	Returns the force applied to the PhysicsBodys in order to satisfy the constraint in newtons.
double	getReactionTorque(double invdt)	Returns the torque applied to the PhysicsBodys in order to satisfy the constraint in newton-meters.
void	initializeConstraints(TimeStep step, Settings settings)	Performs any initialization of the velocity and position constraints.
boolean	isSlackEnabled()	Returns true if slack in the rope is enabled.
void	setLength(double length)	Sets the total length of the pulley "rope."
void	setRatio(double ratio)	Sets the pulley ratio.
void	setSlackEnabled(boolean flag)	Toggles the slack in the rope.
void	shift(Vector2 shift)	Translates the object to match the given coordinate shift.
boolean	solvePositionConstraints(TimeStep step, Settings settings)	Solves the position constraints.
void	solveVelocityConstraints(TimeStep step, Settings settings)	Solves the velocity constraints.
String	toString()

Methods inherited from class Joint

getBody1, getBody2, getOtherBody, getOwner, getUserData, isActive, isCollisionAllowed, isEnabled, isOnIsland, setCollisionAllowed, setOnIsland, setOwner, setUserData

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface DataContainer

getUserData, setUserData

Constructor Detail

PulleyJoint

public PulleyJoint(T body1,
                   T body2,
                   Vector2 pulleyAnchor1,
                   Vector2 pulleyAnchor2,
                   Vector2 bodyAnchor1,
                   Vector2 bodyAnchor2)

Minimal constructor.

Creates a pulley joint between the two given PhysicsBodys using the given anchor points.

Parameters:

body1 - the first PhysicsBody

body2 - the second PhysicsBody

pulleyAnchor1 - the first pulley anchor point

pulleyAnchor2 - the second pulley anchor point

bodyAnchor1 - the first PhysicsBody's anchor point

bodyAnchor2 - the second PhysicsBody's anchor point

Throws:

NullPointerException - if body1, body2, pulleyAnchor1, pulleyAnchor2, bodyAnchor1, or bodyAnchor2 is null

IllegalArgumentException - if body1 == body2

Method Detail

toString

public String toString()

Overrides:

toString in class Joint<T extends PhysicsBody>

initializeConstraints

public void initializeConstraints(TimeStep step,
                                  Settings settings)

Description copied from class: Joint

Performs any initialization of the velocity and position constraints.

Specified by:

initializeConstraints in class Joint<T extends PhysicsBody>

Parameters:

step - the time step information

settings - the current world settings

solveVelocityConstraints

public void solveVelocityConstraints(TimeStep step,
                                     Settings settings)

Description copied from class: Joint

Solves the velocity constraints.

Specified by:

solveVelocityConstraints in class Joint<T extends PhysicsBody>

Parameters:

step - the time step information

settings - the current world settings

solvePositionConstraints

public boolean solvePositionConstraints(TimeStep step,
                                        Settings settings)

Description copied from class: Joint

Solves the position constraints.

Specified by:

solvePositionConstraints in class Joint<T extends PhysicsBody>

Parameters:

step - the time step information

settings - the current world settings

Returns:

boolean true if the position constraints were solved

getAnchor1

public Vector2 getAnchor1()

Description copied from class: Joint

Returns the anchor point on the first PhysicsBody in world coordinates.

Specified by:

getAnchor1 in class Joint<T extends PhysicsBody>

Returns:

Vector2

getAnchor2

public Vector2 getAnchor2()

Description copied from class: Joint

Returns the anchor point on the second PhysicsBody in world coordinates.

Specified by:

getAnchor2 in class Joint<T extends PhysicsBody>

Returns:

Vector2

getReactionForce

public Vector2 getReactionForce(double invdt)

Description copied from class: Joint

Returns the force applied to the PhysicsBodys in order to satisfy the constraint in newtons.

Specified by:

getReactionForce in class Joint<T extends PhysicsBody>

Parameters:

invdt - the inverse delta time

Returns:

Vector2

getReactionTorque

public double getReactionTorque(double invdt)

Returns the torque applied to the PhysicsBodys in order to satisfy the constraint in newton-meters.

Not applicable to this joint. Always returns zero.

Specified by:

getReactionTorque in class Joint<T extends PhysicsBody>

Parameters:

invdt - the inverse delta time

Returns:

double

shift

public void shift(Vector2 shift)

Description copied from interface: Shiftable

Translates the object to match the given coordinate shift.

Specified by:

shift in interface Shiftable

Parameters:

shift - the amount to shift along the x and y axes

getPulleyAnchor1

public Vector2 getPulleyAnchor1()

Returns the pulley anchor point for the first PhysicsBody in world coordinates.

Returns:

Vector2

getPulleyAnchor2

public Vector2 getPulleyAnchor2()

Returns the pulley anchor point for the second PhysicsBody in world coordinates.

Returns:

Vector2

getLength

public double getLength()

Returns the total length of the pulley "rope."

Returns:

double

Since:

3.0.1

See Also:

setLength(double)

setLength

public void setLength(double length)

Sets the total length of the pulley "rope."

Typically this is computed when the joint is created by adding the distance from the first body anchor to the first pulley anchor with the distance from the second body anchor to the second pulley anchor.

Parameters:

length - the length

Since:

3.2.1

getLength1

public double getLength1()

Returns the current length from the first pulley anchor point to the anchor point on the first PhysicsBody.

This is used, in conjunction with length2, to compute the total length when the ratio is changed.

Returns:

double

getLength2

public double getLength2()

Returns the current length from the second pulley anchor point to the anchor point on the second PhysicsBody.

This is used, in conjunction with length1, to compute the total length when the ratio is changed.

Returns:

double

getRatio

public double getRatio()

Returns the pulley ratio.

Returns:

double

setRatio

public void setRatio(double ratio)

Sets the pulley ratio.

The ratio value is used to simulate a block-and-tackle. A ratio of 1.0 is the default and indicates that the pulley is not a block-and-tackle.

This method recomputes the total length of the pulley system.

Parameters:

ratio - the ratio; must be greater than zero

Throws:

IllegalArgumentException - if ratio is less than or equal to zero

isSlackEnabled

public boolean isSlackEnabled()

Returns true if slack in the rope is enabled.

Returns:

boolean

Since:

3.1.6

setSlackEnabled

public void setSlackEnabled(boolean flag)

Toggles the slack in the rope.

If slack is not enabled the rope length is fixed to the total length of the rope, acting like the DistanceJoint.

Parameters:

flag - true to enable slack

Since:

3.1.6

getLimitState

@Deprecated
public LimitState getLimitState()

Deprecated.

Deprecated in 4.0.0.

Returns the current state of the limit.

Returns:

LimitState

Since:

3.2.0