Distance Joint2D Component

The DistanceJoint2D class is a component in Tsar engine used to define a joint connection between two Rigidbody2D.
The joint has to reference another Entity which has Rigidbody2D Component.
The distance joint maintains a constant length between two anchor points on two different rigid bodies.

Below is an animation showing elastic deformation of solid body, which is also how the joint would behave if EnableSpring=true and EnableLimit=true.


Animation Source: https://mm.ethz.ch/research-overview/computational-mechanics/microstructure-evolution.html

Otherwise it would be rigid and constant, for example like pendulum.
Animation Source: https://upload.wikimedia.org/wikipedia/commons/6/6f/Pendulum-no-text.gif

Class Declaration

class DistanceJoint2D : public Component

This class inherits from the Component class and adds functionality related to defining a joint connection to another Rigidbody2D for simulating 2D physics.

Public Methods

Attach

bool AttachToBody(RigidBody2D& referenceBody)

Attach the joint to Entity which has the referenced Rigidbody2D. One joint component can only have one attached Rigidbody2D.
Attaching when existing joint is present will destroy the old one.
Requires valid Rigidbody2D on both entities.

  • referenceBody - the Rigidbody2D component to which the joint will be attached.

Returns:

  • true if joint was created successfuly.
  • false if joint creation failed.

bool AttachToEntity(u64 entityID)

Attach joint directly using Entity. Requires valid Rigidbody2D on Entity.

  • entityID - id of entity to which to attach joint connection.

Returns:

  • true if joint was created successfuly.
  • false if joint creation failed.

bool DetachFromBody()

Destroys the joint connection.
Returns:

  • true if joint has been destroyed.
  • false if no joint was destroyed.

Properties

The DistanceJoint2D class exposes properties (that can also be accessed via getter and setter functions). These properties allow users to manipulate the joint properties in a more intuitive manner:

glm::vec2 AnchorPos
Position of the anchor point on Rigidbody on same Entity which has the DistanceJoint2D.
This position is a local offset.

  • Get: glm::vec2 GetAnchorPos()
  • Set: SetAnchorPos(const glm::vec2& posLocal)

glm::vec2 ConnectedAnchorPos
Position of the anchor point on referenced Entity which has Rigidbody2D.
This position is a local offset for referenced Entity, not Entity with DistanceJoint2D.

  • Get: glm::vec2 GetConnectedAnchorPos()
  • Set: SetConnectedAnchorPos(const glm::vec2& posLocal)

bool EnableMotor
Enable/Disable motor. Motor changes the distance between the two bodies using speed(direction) and max force.
Works when IsSpringEnabled=true.

  • Get: bool IsMotorEnabled()
  • Set: void EnableMotor(bool enable)
    • enable - true enables motor, false disables motor.

bool EnableSpring
Enable/Disable spring. Spring allows for elastic change of distance between bodies using damping ratio and frequency.
If disabled then the distance joint will be rigid, overriding the limit and motor.
When disabled, frequency=0 and dampingRation=1.

  • Get: bool IsSpringEnabled()
  • Set: void EnableSpring(bool enable)
    • enable - true enables spring, false disables spring.

bool EnableLimit
Enable/Disable limit. Limit allows for change of distance between bodies within a clamped range [MinDistance; MaxDistance].
The limit only works if IsSpringEnabled = true.
When limit is disabled, distance between bodies is always constant.

  • Get: bool IsLimitEnabled()
  • Set: void EnableLimit(bool enable)
    • enable - true enables limit, false disables limit.

float SpringFrequency
Frequency (or spring linear stiffness), in Hertz(HZ).
This lets you configure how quickly a spring reacts regardless of the body masses. For better stability should usually be less than a quarter of the simulation rate. For example, if the simulation runs at 60Hz then the joint stiffness should be 15Hz or less.

  • Get: float GetSpringFrequencyHZ()
  • Set: void SetSpringFrequencyHZ(float freq)
    • freq - should be non-negative value.

float SpringDampingRatio
Linear damping ratio of spring, lets you specify how quickly the spring will come to rest. 0 means no damping (energy loss) and 1 means full absorbtion (immediate energy loss).

  • Get: float GetSpringDampingRatio()
  • Set: void SetSpringDampingRatio(float ratio)
    • ratio - value in range [0; 1].

float MaxDinstance
When IsLimitEnabled=true, this specifies maximum distance possible between two bodies, in meters. Imagine this as maximum suspension travel.

  • Get: float GetMaxDistance()
  • Set: void SetMaxDistance(float maxDistance)
    • maxDistance - maximum distance allowed between the two constrained bodies, in meters.

float MinDistance
When IsLimitEnabled=true, this specifies how close the two bodies can go, in meters. Default is 0

  • Get: float GetMinDistance()
  • Set: void SetMinDistance(float minDistance)
    • minDistance - must be less than MaxDistance and >=0.

float MotorSpeed
When IsMotor=true and IsSpringEnabled=true, this specifies the speed at which the joint pushes(positive value) or pulls(negative value) in meters per second.
This is the speed of contracting(negative value) or expanding(positive value) the length of the joint (distance between bodies).

  • Get: float GetMotorSpeed()
  • Set: void SetMotorSpeed(float motorSpeed)
    • motorSpeed - meters per second.

float MaxMotorForce
When IsMotor=true and IsSpringEnabled=true, this specifies the maximum force the motor will apply to constrained body, in Newtons. Similar to spring stiffness, imagine this as the strength of the motor pulling or pushing. Note the mass of bodies for better tuning.

  • Get: float GetMaxMotorForce()
  • Set: void SetMaxMotorForce(float force)
    • force - non-negative value in Newtons.

bool CollideWithOther
Should the colliders attached to both bodies collide with each other?

  • Get: bool GetCollideWithOther()
  • Set: void SetCollideWithOther(bool collide)
    • collide - true makes bodies collide with each other, false disables collision between them.