Module org.dyn4j

Class WheelJoint<T extends PhysicsBody>

  • Type Parameters:
    T - the PhysicsBody type
    All Implemented Interfaces:
    DataContainer, AngularMotorJoint, Joint<T>, LinearLimitsJoint, LinearSpringJoint, PairedBodyJoint<T>, Shiftable, Ownable

    public class WheelJoint<T extends PhysicsBody>
    extends AbstractPairedBodyJoint<T>
    implements LinearLimitsJoint, LinearSpringJoint, AngularMotorJoint, PairedBodyJoint<T>, Joint<T>, Shiftable, DataContainer, Ownable
    Implementation of a wheel joint.

    A wheel joint is used to simulate a vehicle's wheel and suspension. The wheel is allowed to rotate freely about the given anchor point. The suspension is allowed to translate freely along the given axis. The whole system can translate and rotate freely.

    The given axis fixed to the first body (frame) given. So as the first body rotates, the axis will rotate with it. The given anchor point represents the center of rotation of the second body (wheel), typically the wheel's world space center of mass.

    By default the frequency and damping ratio are set to 8.0 and 0.0 respectively. Unlike other joints, the spring-damper for this joint is enabled by default. You can enable/disable the various spring-damper features using setSpringEnabled(boolean), setSpringDamperEnabled(boolean), setMaximumSpringForceEnabled(boolean) methods. 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 has an added spring feature called the rest offset. Similar to the rest distance in the distance joint, but only applied when the spring is enabled. When you build the joint, the default distance between the two bodies is their initial distance. You can use the setSpringRestOffset(double) to raise or lower the distance between the bodies when the spring is active.

    This joint also supports a motor. The motor is an angular motor about the anchor point. The motor speed can be positive or negative to indicate a clockwise or counter-clockwise rotation. The maximum motor torque must be greater than zero for the motor to apply any motion. The motor must be enabled using setMotorEnabled(boolean).

    The joint also supports upper and lower limits. The limits represent the maximum displacement from the anchor point along the given axis. This means that the limits are typically negative for the lower limit and positive for the upper limit. The limits are solved relative to the given axis's direction. The limits can be enabled separately using setLowerLimitEnabled(boolean) and setUpperLimitEnabled(boolean). This also means that the limits are relative to the initial starting position of the bodies.

    NOTE: In versions of dyn4j before 5.0.0, the body arguments in the constructor were reversed, you would specify the wheel first, then frame. It was changed to accept the frame first, then the wheel to make things more natural.

    Since:
    3.0.0
    Version:
    5.0.0
    Author:
    William Bittle
    See Also:
    Documentation
    • 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
      • xAxis

        protected final Vector2 xAxis
        The local space x axis representing the allowed linear motion
      • yAxis

        protected final Vector2 yAxis
        The local space y axis representing the constrained linear motion
      • upperLimitEnabled

        protected boolean upperLimitEnabled
        True if the upper limit is enabled
      • lowerLimitEnabled

        protected boolean lowerLimitEnabled
        True if the lower limit is enabled
      • upperLimit

        protected double upperLimit
        the upper limit in meters
      • lowerLimit

        protected double lowerLimit
        the lower limit in meters
      • motorEnabled

        protected boolean motorEnabled
        Whether the motor is enabled or not
      • motorSpeed

        protected double motorSpeed
        The target velocity in radians / second
      • motorMaximumTorqueEnabled

        protected boolean motorMaximumTorqueEnabled
        True if the motor maximum torque is enabled
      • motorMaximumTorque

        protected double motorMaximumTorque
        The maximum torque the motor can apply in newton-meters
      • springEnabled

        protected boolean springEnabled
        True if the spring is enabled
      • springDamperEnabled

        protected boolean springDamperEnabled
        True if the spring-damper is enabled
      • springMode

        protected int springMode
        The spring mode (frequency or stiffness)
      • springFrequency

        protected double springFrequency
        The oscillation frequency in hz
      • springStiffness

        protected double springStiffness
        The stiffness of the spring
      • 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 will apply
      • springRestOffset

        protected double springRestOffset
        The rest offset of the spring
    • 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()
        The anchor point in world coordinates for the frame (body1).
        Returns:
        Vector2
      • getAnchor2

        public Vector2 getAnchor2()
        The anchor point in world coordinates for the wheel (body2).
        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)
        Description copied from interface: Joint
        Returns the torque applied to the PhysicsBodys in order to satisfy the constraint in newton-meters.
        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
      • getLinearSpeed

        public double getLinearSpeed()
        Returns the linear speed along the axis between the two joined bodies
        Returns:
        double
        Since:
        3.2.1
      • getAngularSpeed

        public double getAngularSpeed()
        Returns the current angular speed between the two joined bodies.
        Returns:
        double
        Since:
        3.2.1
      • getLinearTranslation

        public double getLinearTranslation()
        Returns the current linear translation along the joint axis.
        Returns:
        double
        Since:
        3.2.1
      • getAngularTranslation

        public double getAngularTranslation()
        Returns the current angular translation between the joined bodies.
        Returns:
        double
        Since:
        3.2.1
      • getAxis

        public Vector2 getAxis()
        Returns the axis in world coordinates for the frame (body1).
        Returns:
        Vector2
      • setSpringRestOffset

        public void setSpringRestOffset​(double offset)
        Set's the spring rest offset.

        This can be any value and is used to offset the spring's rest distance. This is only applicable when the spring is enabled.

        Parameters:
        offset - the offset
        Since:
        5.0.0
      • getSpringRestOffset

        public double getSpringRestOffset()
        Returns the spring's rest offset.
        Returns:
        double
        Since:
        5.0.0
      • setMotorEnabled

        public void setMotorEnabled​(boolean motorEnabled)
        Description copied from interface: AngularMotorJoint
        Enables or disables the motor.
        Specified by:
        setMotorEnabled in interface AngularMotorJoint
        Parameters:
        motorEnabled - true if the motor should be enabled
      • setMaximumMotorTorqueEnabled

        public void setMaximumMotorTorqueEnabled​(boolean enabled)
        Description copied from interface: AngularMotorJoint
        Sets whether the maximum motor torque is enabled.
        Specified by:
        setMaximumMotorTorqueEnabled in interface AngularMotorJoint
        Parameters:
        enabled - true if the maximum motor torque should be enabled
      • getMaximumMotorTorque

        public double getMaximumMotorTorque()
        Description copied from interface: AngularMotorJoint
        Returns the maximum torque the motor can apply to the joint to achieve the target speed.
        Specified by:
        getMaximumMotorTorque in interface AngularMotorJoint
        Returns:
        double
      • getMotorTorque

        public double getMotorTorque​(double invdt)
        Description copied from interface: AngularMotorJoint
        Returns the applied motor torque.
        Specified by:
        getMotorTorque in interface AngularMotorJoint
        Parameters:
        invdt - the inverse delta time from the time step
        Returns:
        double
      • 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)
        Description copied from interface: LinearLimitsJoint
        Sets the upper limit in meters.
        Specified by:
        setUpperLimit in interface LinearLimitsJoint
        Parameters:
        upperLimit - the upper limit in meters
      • 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)
        Description copied from interface: LinearLimitsJoint
        Sets the lower limit in meters.
        Specified by:
        setLowerLimit in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters
      • 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)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits.
        Specified by:
        setLimits in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters
        upperLimit - the upper limit in meters
      • setLimitsEnabled

        public void setLimitsEnabled​(double lowerLimit,
                                     double upperLimit)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits and enables both.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters
        upperLimit - the upper limit in meters
      • 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)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits to the given limit.
        Specified by:
        setLimits in interface LinearLimitsJoint
        Parameters:
        limit - the desired limit in meters
      • setLimitsEnabled

        public void setLimitsEnabled​(double limit)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits to the given limit and enables both.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        limit - the desired limit in meters