Prismatic Joint2D Component

The PrismaticJoint2D 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 prismatic joint limits translation (relative movement) between two bodies on a fixed axis.
Think of it like a sliding piston or platform.
For convenience body with PrismaticJoint2D will be refered as BodyA and other/referenced body as BodyB.

This animation is in 3D, but the idea is same in 2D as well.
Animation Source: https://gepettoweb.laas.fr/hpp/pinocchio/doxygen-html/md_doc_c-maths_c-joints.html

Class Declaration

class PrismaticJoint2D : 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 PrismaticJoint2D 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 rigid body on same Entity which has the PrismaticJoint2D.
This position is a local offset at which the body is attached.

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

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

  • Get: glm::vec2 GetAnchorPosReferencedBody()
  • Set: void SetAnchorPosReferencedBody(const glm::vec2& posLocal)

glm::vec2 LimitedAxis()
World direction vector specifying constrained axis. Movement of both bodies is limited only along this axis. {1.0, 0.0} - Horizontal movement {0.0, 1.0} - Vertical movement {0.5, 0.5}, {-0.5, -0.5} - Diagonal movement

  • Get: glm::vec2 GetLimitedAxis()
  • Set: void SetLimitedAxis(const glm::vec2& axis2D)
    • axis2D - direction/axis vector, value is normalized by default.

float ReferenceAngle
The joint preserves the desired relative rotation between the bodies throughout the simulation.
For example, if you want bodyB to be tilted 5 degrees counter-clockwise relative to bodyA, you can set ReferenceAngle to 5 degrees.

  • Get: float GetReferenceAngle()
  • Set: void SetReferenceAngle(float refAngle)
    • refAngle - The constrained angle between the bodies: bodyB_angle - bodyA_angle.

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.

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

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

bool IsSpringEnabled
Enable/Disable spring. Spring allows for elastic change of distance between bodies using damping ratio and frequency.
Works well in combination with IsLimitEnabled=true and IsMotorEnabled=true.
When disabled, frequency=0 and dampingRation=1.

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

bool IsLimitEnabled
Enable/Disable limit. Limit allows for change of distance between bodies within a clamped range [MinDistance; MaxDistance].
Works in combination with IsSpringEnabled=true and IsMotorEnabled=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 SpringTargetTranslation
If IsSpringEnabled = true, The spring-damper will drive to this translation.
The joint translation is zero when the local anchor points coincide in world space.

  • Get: float GetSpringTargetTranslation()
  • Set: void SetSpringTargetTranslation(float distance)
    • distance - distance between two bodies, in meters.

Example:

LimitedAxis = {0.0f, 1.0f};     // Vertical axis
SprintTargetTranslation = 1.5f; // 1.5 meters above BodyA

LimitedAxis = {0.0f, 1.0f};      // Vertical axis
SprintTargetTranslation = -1.2f; // 1.2 meters below BodyA

LimitedAxis = {1.0f, 0.0f};     // Horizontal axis
SprintTargetTranslation = 2.f;  // 2 meters right of BodyA

float SpringFrequency
If IsSpingEnabled = true, this allows the distance between two bodies to behave like a spring, instead of being constant and rigid.
Frequency (or spring linear stiffness) is in Hertz(HZ).
This 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, non-dimensional.
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 UpperTranslationLimit
When IsLimitEnabled=true, this specifies maximum translation distance possible between two bodies, in meters.
The joint translation is zero when the local anchor points coincide in world space.

  • Get: float GetUpperTranslationLimit()
  • Set: void SetUpperTranslationLimit(float maxDist)
    • maxDist - must be greater than LowerTranslationLimit, in meters.

float LowerTranslationLimit
When IsLimitEnabled=true, this specifies minimum translation distance possible between two bodies, in meters.
The joint translation is zero when the local anchor points coincide in world space.

  • Get: float LowerTranslationLimit()
  • Set: void SetLowerTranslationLimit(float minDist)
    • maxDist - must be less than UpperTranslationLimit, in meters.

float MotorSpeed
When IsMotor=true, this specifies the speed at which the joint pushes(positive value) or pulls(negative value) BodyB along the LimitedAxis direction, in meters per second.

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

Example:

myJoint.LimitedAxis = {0.0f, 1.0f}; // Vectical axis
myJoint.MotorSpeed = 1.0f; // Move Up at 1 m/s

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.