Module org.dyn4j
Package org.dyn4j.dynamics.joint

Class DistanceJoint<T extends PhysicsBody>

  • Type Parameters:
    T - the PhysicsBody type
    All Implemented Interfaces:
    DataContainer, Joint<T>, LinearLimitsJoint, LinearSpringJoint, PairedBodyJoint<T>, Shiftable, Ownable
    public class DistanceJoint<T extends PhysicsBody>
extends AbstractPairedBodyJoint<T>
implements LinearLimitsJoint, LinearSpringJoint, PairedBodyJoint<T>, Joint<T>, Shiftable, DataContainer, Ownable
    Implementation of a fixed length distance joint with optional, spring-damper and limits.

    Given the two world space anchor points a distance is computed and used to constrain the attached PhysicsBodys at that distance. The bodies can rotate freely about the anchor points and the whole system can move and rotate freely, but the distance between the two anchor points is fixed. The rest distance determines the fixed distance and can be changed using setRestDistance(double). The rest distance must be zero or greater.

    This joint doubles as a spring/damper distance joint where the length can change but is constantly approaching the rest distance. Enable the spring- damper by setting the frequency and damping ratio values and using the setSpringEnabled(boolean) and setSpringDamperEnabled(boolean) methods. A good starting point is a frequency of 8.0 and damping ratio of 0.3 then adjust as necessary. You can also impose a maximum force the spring will apply by using setMaximumSpringForce(double). The maximum force needs to be enabled using setMaximumSpringForceEnabled(boolean) method. As with all spring-damper enabled joints, the spring must be enabled for the damper to be applied. Also note that when the damper is disabled, the spring still experiences "damping" aka energy loss - this is a side effect of the solver and intended behavior.

    This joint also supports limits. The joint will only accept positive limits (in contrast to other joints). A lower limit of zero (the minimum valid lower limit) means that the distance can reach zero, where the anchor points overlap. Setting the limits to the same value will create a fixed length distance joint, but this is not recommended as you will get a less stable result - instead disable the limits and set the rest distance using the setRestDistance(double) method. You can enable the upper and lower limits independently using the setLowerLimitEnabled(boolean) and setUpperLimitEnabled(boolean) methods. When limits are enabled, the rest distance is ignored. You can combine limits and spring-damper by enabling as mentioned earlier. In this case, the rest distance is used for the spring-damper and the limits control the maximum and minimum extension of the spring. The limit interval does not have to include the rest distance. If the lower and upper limits are equal or near equal (2 times the Settings.getLinearTolerance()) the joint will be treated as a fixed length joint.

    Since:
    1.0.0
    Version:
    5.0.0
    Author:
    William Bittle
    See Also:
    Documentation, Distance Constraint

    • Field Detail

      • localAnchor1

        protected final Vector2 localAnchor1
        The local anchor point on the first PhysicsBody

      • localAnchor2

        protected final Vector2 localAnchor2
        The local anchor point on the second PhysicsBody

      • restDistance

        protected double restDistance
        The rest distance

      • springEnabled

        protected boolean springEnabled
        True if the spring is enabled

      • springMode

        protected int springMode
        The current spring mode

      • springFrequency

        protected double springFrequency
        The oscillation frequency in hz

      • springStiffness

        protected double springStiffness
        The stiffness (k) of the spring

      • springDamperEnabled

        protected boolean springDamperEnabled
        True if the spring's damper is enabled

      • springDampingRatio

        protected double springDampingRatio
        The damping ratio

      • springMaximumForceEnabled

        protected boolean springMaximumForceEnabled
        True if the spring maximum force is enabled

      • springMaximumForce

        protected double springMaximumForce
        The maximum force the spring can apply

      • upperLimit

        protected double upperLimit
        The maximum distance between the two world space anchor points

      • lowerLimit

        protected double lowerLimit
        The minimum distance between the two world space anchor points

      • upperLimitEnabled

        protected boolean upperLimitEnabled
        Whether the maximum distance is enabled

      • lowerLimitEnabled

        protected boolean lowerLimitEnabled
        Whether the minimum distance is enabled

    • Constructor Detail

      • DistanceJoint

        public DistanceJoint​(T body1,
                     T body2,
                     Vector2 anchor1,
                     Vector2 anchor2)
        Minimal constructor.

        Creates a fixed distance Joint where the joined PhysicsBodys do not participate in collision detection and resolution.

        Parameters:
        body1 - the first PhysicsBody
        body2 - the second PhysicsBody
        anchor1 - in world coordinates
        anchor2 - in world coordinates
        Throws:
        NullPointerException - if body1, body2, anchor1, or anchor2 is null
        IllegalArgumentException - if body1 == body2

    • Method Detail

      • initializeConstraints

        public void initializeConstraints​(TimeStep step,
                                  Settings settings)
        Description copied from interface: Joint
        Performs any initialization of the velocity and position constraints.
        Specified by:
        initializeConstraints in interface 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 interface: Joint
        Solves the velocity constraints.
        Specified by:
        solveVelocityConstraints in interface 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 interface: Joint
        Solves the position constraints.
        Specified by:
        solvePositionConstraints in interface Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings
        Returns:
        boolean true if the position constraints were solved

      • updateSpringCoefficients

        protected void updateSpringCoefficients()
        Computes the spring coefficients from the current state of the joint.

        This method is intended to set the springStiffness OR springFrequency and damping for use during constraint solving.

      • getAnchor1

        public Vector2 getAnchor1()
        Returns the world-space anchor point on the first body.
        Returns:
        Vector2

      • getAnchor2

        public Vector2 getAnchor2()
        Returns the world-space anchor point on the second body.
        Returns:
        Vector2

      • getReactionForce

        public Vector2 getReactionForce​(double invdt)
        Description copied from interface: Joint
        Returns the force applied to the PhysicsBodys in order to satisfy the constraint in newtons.
        Specified by:
        getReactionForce in interface 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 interface 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

      • getRestDistance

        public double getRestDistance()
        Returns the rest distance between the two constrained PhysicsBodys in meters.
        Returns:
        double
        Since:
        4.2.0

      • setRestDistance

        public void setRestDistance​(double distance)
        Sets the rest distance between the two constrained PhysicsBodys in meters.
        Parameters:
        distance - the distance in meters
        Throws:
        IllegalArgumentException - if distance is less than zero
        Since:
        4.2.0

      • getCurrentDistance

        public double getCurrentDistance()
        Returns the current distance between the anchor points.
        Returns:
        double
        Since:
        4.2.0

      • setSpringDampingRatio

        public void setSpringDampingRatio​(double dampingRatio)
        Description copied from interface: LinearSpringJoint
        Sets the damping ratio.

        Larger values reduce the oscillation of the spring.

        Specified by:
        setSpringDampingRatio in interface LinearSpringJoint
        Parameters:
        dampingRatio - the damping ratio; in the range (0, 1]

      • setSpringFrequency

        public void setSpringFrequency​(double frequency)
        Description copied from interface: LinearSpringJoint
        Sets the spring frequency.

        Larger values increase the stiffness of the spring.

        Calling this method puts the spring into fixed frequency mode. In this mode, the spring stiffness is computed based on the frequency.

        Specified by:
        setSpringFrequency in interface LinearSpringJoint
        Parameters:
        frequency - the spring frequency in hz; must be greater than zero

      • setSpringStiffness

        public void setSpringStiffness​(double stiffness)
        Description copied from interface: LinearSpringJoint
        Sets the spring stiffness.

        Larger values increase the stiffness of the spring.

        Calling this method puts the spring into fixed stiffness mode. In this mode, the spring frequency is computed based on the stiffness.

        Specified by:
        setSpringStiffness in interface LinearSpringJoint
        Parameters:
        stiffness - the spring stiffness (k); must be greater than zero

      • setMaximumSpringForce

        public void setMaximumSpringForce​(double maximum)
        Description copied from interface: LinearSpringJoint
        Sets the maximum force the spring can apply.
        Specified by:
        setMaximumSpringForce in interface LinearSpringJoint
        Parameters:
        maximum - the maximum force

      • setMaximumSpringForceEnabled

        public void setMaximumSpringForceEnabled​(boolean enabled)
        Description copied from interface: LinearSpringJoint
        Sets whether the spring force is limited to the maximum.
        Specified by:
        setMaximumSpringForceEnabled in interface LinearSpringJoint
        Parameters:
        enabled - true if the spring force should be limited

      • setSpringEnabled

        public void setSpringEnabled​(boolean enabled)
        Description copied from interface: LinearSpringJoint
        Sets whether the spring is enabled or not.
        Specified by:
        setSpringEnabled in interface LinearSpringJoint
        Parameters:
        enabled - true if the spring should be enabled

      • getSpringForce

        public double getSpringForce​(double invdt)
        Description copied from interface: LinearSpringJoint
        Returns the force in netwons applied by the spring in the last timestep.
        Specified by:
        getSpringForce in interface LinearSpringJoint
        Parameters:
        invdt - the inverse delta time
        Returns:
        double

      • setUpperLimit

        public void setUpperLimit​(double upperLimit)
        Sets the upper limit in meters.
        Specified by:
        setUpperLimit in interface LinearLimitsJoint
        Parameters:
        upperLimit - the upper limit in meters; must be zero or greater
        Throws:
        IllegalArgumentException - if upperLimit is less than zero or upperLimit is less than the current lower limit

      • setUpperLimitEnabled

        public void setUpperLimitEnabled​(boolean flag)
        Description copied from interface: LinearLimitsJoint
        Sets whether the upper limit is enabled.
        Specified by:
        setUpperLimitEnabled in interface LinearLimitsJoint
        Parameters:
        flag - true if the upper limit should be enabled

      • isUpperLimitEnabled

        public boolean isUpperLimitEnabled()
        Description copied from interface: LinearLimitsJoint
        Returns true if the upper limit is enabled.
        Specified by:
        isUpperLimitEnabled in interface LinearLimitsJoint
        Returns:
        boolean true if the upper limit is enabled

      • setLowerLimit

        public void setLowerLimit​(double lowerLimit)
        Sets the lower limit in meters.
        Specified by:
        setLowerLimit in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters; must be zero or greater
        Throws:
        IllegalArgumentException - if lowerLimit is less than zero or lowerLimit is greater than the current upper limit

      • setLowerLimitEnabled

        public void setLowerLimitEnabled​(boolean flag)
        Description copied from interface: LinearLimitsJoint
        Sets whether the lower limit is enabled.
        Specified by:
        setLowerLimitEnabled in interface LinearLimitsJoint
        Parameters:
        flag - true if the lower limit should be enabled

      • isLowerLimitEnabled

        public boolean isLowerLimitEnabled()
        Description copied from interface: LinearLimitsJoint
        Returns true if the lower limit is enabled.
        Specified by:
        isLowerLimitEnabled in interface LinearLimitsJoint
        Returns:
        boolean true if the lower limit is enabled

      • setLimits

        public void setLimits​(double lowerLimit,
                      double upperLimit)
        Sets both the lower and upper limits.
        Specified by:
        setLimits in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters; must be zero or greater
        upperLimit - the upper limit in meters; must be zero or greater
        Throws:
        IllegalArgumentException - if lowerLimit is less than zero, the upperLimit is less than zero, or lowerLimit is greater than the upperLimit

      • setLimitsEnabled

        public void setLimitsEnabled​(double lowerLimit,
                             double upperLimit)
        Sets both the lower and upper limits and enables both.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters; must be zero or greater
        upperLimit - the upper limit in meters; must be zero or greater
        Throws:
        IllegalArgumentException - if lowerLimit is less than zero, the upperLimit is less than zero, or lowerLimit is greater than the upperLimit

      • setLimitsEnabled

        public void setLimitsEnabled​(boolean flag)
        Description copied from interface: LinearLimitsJoint
        Enables or disables both the lower and upper limits.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        flag - true if both limits should be enabled

      • setLimits

        public void setLimits​(double limit)
        Sets both the lower and upper limits to the given limit.
        Specified by:
        setLimits in interface LinearLimitsJoint
        Parameters:
        limit - the lower and upper limit in meters; must be zero or greater
        Throws:
        IllegalArgumentException - if limit is less than zero

      • setLimitsEnabled

        public void setLimitsEnabled​(double limit)
        Sets both the lower and upper limits to the given limit and enables both.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        limit - the lower and upper limit in meters; must be zero or greater
        Throws:
        IllegalArgumentException - if limit is less than zero