Revolute Joint2D Component

The RevoluteJoint2D 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 revolute joint connects two bodies at a point and allows rotation, like a hinge.
Can use motor and angle limits.

Joint Scheme

Image Source: https://box2d.org/documentation/md_simulation.html

Demonstration

Class Declaration

class RevoluteJoint2D : public Component

This class inherits from the Component class and adds functionality related to defining a revolute 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 RevoluteJoint2D 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 CommonAnchorPos
Position offset of the common anchor point on same Entity which has the RevoluteJoint2D.

• Get: glm::vec2 GetCommonAnchorPos()
• Set: SetCommonAnchorPos(const glm::vec2& posLocal)

float ReferenceAngle
The angle difference between BodyB and BodyA, in degrees, this defines the zero angle for the joint rotation limit.
By defailt it uses initial configuration, but if you want you can change it.
For example if you set it to 60 and you have LowerLimitAngle=40 and UpperLimitAngle=80, the joint in world angles will be limited between [60+40; 60+80] or [100; 140].

• Get: float GetReferenceAngle()
• Set: void SetReferenceAngle(float refAngle)
  • refAngle - default is bodyB.AngleZ - bodyA.AngleZ.

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. If you enable the motor, Box2D will apply torque to reach and maintain a given angular speed (MotorSpeed), up to a specified maximum torque (MaxMotorTorque).
Works in combination 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 acts on constrained Z-axis, as if bodies have a spring between them which you wind up.
Works in combination with IsLimitEnabled=true and IsMotorEnabled=true.
When disabled, frequency=0 and dampingRatio=1.

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

bool IsRotationLimitEnabled
Enable/Disable limit. Limits angle between bodies and common anchor within a clamped range [MinDistance; MaxDistance] which must contain zero (0.0f), otherwise limit is ignored.
Works well with IsSpringEnabled=true and IsMotorEnabled=true.
When limit is disabled, angle between bodies and anchor is not clamped (unless IsSpring=true in which case the spring will try to keep bodies at initial angle when created).

• Get: bool IsRotationLimitEnabled()
• Set: void EnableRotationLimit(bool enable)
  • enable - true enables rotation limit, false disables limit.

float SpringFrequency
If IsSpingEnabled = true, this acts as spring trying to bring angle between two bodies relative to anchor at rest(initial angle when creating the joint or ReferenceAngle).
Frequency (or spring angular stiffness) is in Hertz(HZ), cycles per second. 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
Angular 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 UpperAngleLimit
When IsLimitEnabled=true, this specifies maximum angle possible between two bodies, in degrees.
This angle is relative to ReferenceAngle, which by default is BodyB.AngleZ - BodyA.AngleZ.

• Get: float GetUpperAngleLimit()
• Set: void SetUpperAngleLimit(float angleLimitDeg)
  • angleLimitDeg - maximum angle allowed between the two constrained bodies, in degrees. Must be less than 171 degrees and greater than LoweAngleLimit.

float LowerAngleLimit
When IsLimitEnabled=true, this specifies minimum angle possible between two bodies, in degrees.
This angle is relative to ReferenceAngle, which by default is BodyB.AngleZ - BodyA.AngleZ.

• Get: float GetLowerAngleLimit()
• Set: void SetLowerAngleLimit(float angleLimitDeg)
  • angleLimitDeg - minimum angle allowed between the two constrained bodies, in degrees. Must be greater than -171 degrees and less than UpperAngleLimit.

float MotorSpeed
When IsMotor=true, this specifies the speed at which the joint rotates the dynamic body relative to the hinge (common anchor) point in radians per second.
This speed won't be reached if MaxTorque is not strong enough.
Positive value rotates counter-clockwise, negative value rotates clockwise.

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

float MaxMotorTorque
When IsMotor=true, this specifies the maximum torque (angular force) the motor will apply to constrained bodies, in Newton-meters.
Note the mass of bodies for better tuning.

• Get: float GetMaxMotorTorque()
• Set: void SetMaxMotorTorque(float torque)
  • torque - non-negative value in Newton-meters.