Weld Joint2D Component

The WeldJoint2D 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 weld joint fully constrains the relative transform(position and rotation) between anchors on two bodies while allowing for springiness. Both rotation and translation can have damped springs.

Class Declaration

class WeldJoint2D : 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 WeldJoint2D 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 WeldJoint2D.
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 WeldJoint2D.

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

bool IsSpringEnabled
Enable/Disable spring. Spring allows for elastic change of distance/rotation between bodies using damping ratio and frequency.

  • Disabled - the joint will be rigid (like a solid weld) making bodies having the same movement.
  • Enabled - the joint acts as flexible connection between bodies. Imagine two cherries inside a pudding/jelly, one at top the other below it, the pudding doesn't break but acts as elastic damper between the two bodies which almost don't move/rotate relative to each other.

When disabled, frequency=0 and dampingRation=1.

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

Below is an animation showing 'springiness' between strawberry on top and the plate below, the pudding oscilates with a frequency and softly dampens the applied force to the plate.



Image Source: https://media1.giphy.com/media/v1.Y2lkPTZjMDliOTUycm81Z25hbHkwd3BxdXpxdDhyMnViNmI0dXNtZzk1NHJuNGxrbjdhYyZlcD12MV9naWZzX3NlYXJjaCZjdD1n/RwnoM2uvfwqcw/source.gif

float LinearFrequency
Spring linear stiffness, in Hertz(HZ).
This lets you configure how quickly a spring reacts for translation. 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 GetLinearFrequencyHZ()
  • Set: void SetLinearFrequencyHZ(float freq)
    • freq - should be non-negative value.

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

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

float AngularFrequency
Spring angular stiffness, in Hertz(HZ).
This lets you configure how quickly a spring reacts to rotation. 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 GetAngularFrequencyHZ()
  • Set: void SetAngularFrequencyHZ(float freq)
    • freq - should be non-negative value.

float AngularDampingRatio
Angular damping ratio of spring, lets you specify how quickly the spring will come to rest when torque applied(rotation change).
0 means no damping (energy loss) and 1 means full absorbtion (immediate energy loss).

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

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.