Creating and Using QJointObject - erayzesen/godot-quarkphysics GitHub Wiki

QJointObject is a single object that provides powerful flexibility for creating various constraints between two rigid bodies. With it, you can create distance constraints, pin objects to a point, or even build groove-type joints. It is designed exclusively for use with rigid bodies.

If you want to create constraints between QSoftBodyNode objects, please refer to the tutorial about QSpringObject.

How to Create a QJointObject

QJointObject instances are not part of the scene tree; they are created via code. You don't need to manually delete them. If Godot finds no references to them, they will be automatically removed.

To create and configure a QJointObject, you need at least one QRigidBodyNode instance. The reason only one is required is because you can create a joint between a QRigidBodyNode and a fixed point in the physics world, not necessarily another rigid body.

QJointObject provides practical and versatile configuration options depending on your needs. Once configured, it must be added to the physics world.

# Create a QJointObject
var my_joint = QJointObject.new()

# Default - Configure
my_joint.configure(rigid_body_node_a, anchor_world_pos_a, anchor_world_pos_b, rigid_body_node_b, length)

# Alternative - Configure with current distance. It calculates the 'length' argument for you.
my_joint.configure_with_current_distance(rigid_body_node_a, anchor_world_pos_a, anchor_world_pos_b, rigid_body_node_b)

# Alternative - Configure with a common anchor position. Useful for pin joints.
my_joint.configure_with_common_anchor_position(rigid_body_node_a, common_anchor_world_pos, rigid_body_node_b)

# Optional - Enable groove feature
my_joint.set_groove_enabled(true)

# Optional - Enable collisions between joined bodies (default is false)
my_joint.set_collisions_enabled(true)

#Set rigidity of the constraint- The value must be between 1.0 and 0.0
my_joint.set_rigidity(0.5)

# Add joint to the world
world_node.add_joint(my_joint)

How Does QJointObject Work?

The logic behind QJointObject is actually quite simple, and understanding this makes working with it much easier. When configuring a QJointObject, you provide rigid_body_node_a and rigid_body_node_b as arguments, along with anchor positions in physics world coordinates for both bodies. (If your goal is to anchor a rigid body to a fixed point in the world, you can set one of the rigid bodies to null.)

Once the QJointObject is configured, these defined anchor points on the world will start to move with their respective bodies. By default, you specify the distance that should be maintained between these anchor points. The QJointObject enforces this distance constraint on each frame.

If your goal is to connect two objects with a single anchor point, naturally both anchor positions will be the same and the maintained distance will be 0.

If you enable the groove feature, the constraint is only applied when the distance exceeds the specified length. If the distance is shorter than the defined length, no constraint is applied.

You can imagine the working principle of a QJointObject like this: you have a wooden plank of a certain length (this length is the length parameter), and you nail one end to one rigid body, and the other end to the second body. The nailed positions represent your anchor positions.