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

QSpringObject allows you to create distance constraints between any two particles. By adding a QSpringObject to a QMeshNode, you can create constraints between particles within that QMeshNode. Alternatively, by adding it to a QWorldNode, you can establish distance constraints between any two particles, even across different objects. Its structure is highly flexible, allowing one of the particles to be a QParticleObject created solely through code, unattached to any other entity.

Note: If you configure a QSpringObject between a particle owned by a QMeshNode under a QRigidBodyNode (e.g., a rigid body) and another particle owned by a QMeshNode under a QSoftBodyNode (e.g., a soft body), the particle in the rigid body will not be affected by the constraint. The constraint will apply entirely to the particle in the soft body.

How to Create a QSpringObject?

QSpringObject 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.

When creating a QSpringObject, it requires four parameters for its default configuration:

  • particle_object_a: One of the particles.
  • particle_object_b: The other particle.
  • length: The length for the distance constraint.
  • internal: Indicates whether the QSpringObject is applied between particles within a QMeshNode and whether it is inside or outside the shape's boundaries. If the constraint is not between particles of a QMeshNode, you can set this to false.
#Creating a QSpringObject 
var my_spring=QSpringObject.new()
	
#Default -Configure 
my_spring.configure(particle_object_a,particle_object_b,length,is_internal)
#Alternative - Configure with Current Distance. It calculates the 'length' argument for you.
my_spring.configure_with_current_distance(particle_object_a,particle_object_b,is_internal)
	
#Set Rigidity of the Constraint- The value must be between 1.0 and 0.0
my_spring.set_rigidity(0.5)
	
#Optional- Set Distance Limit Enabled- If enabled, the spring applies full-strength constraints when the distance between particles becomes smaller or larger than the allowed range defined by the minimum and maximum distance factors.(Default is false)
my_spring.set_distance_limit_enabled(true)
my_spring.set_minimum_distance_factor(0.1)
my_spring.set_minimum_distance_factor(2.0)
	
#Using scenario 1: Add spring to the mesh
my_mesh.add_spring(my_spring)
#Using scenario 2:  Add spring to the world
world_node.add_spring(my_spring)

How Does QSpringObject Work?

QSpringObject objects check the distance between two particles in each frame of the physics simulation and attempt to correct it to maintain the specified distance based on a defined rigidity ratio. This can be likened to a real-world example where two balls are connected by a spring. The stiffness of the connection depends on how flexible the spring is.

Importance of QSpringObject in Soft Body Simulations

In soft body simulations, QSpringObject is the structure that connects particles representing mass points within a QMeshNode. This approach is known as the mass-spring model in soft body simulations, making QSpringObject a critical component. Additionally, it enables the creation of connections between two soft objects in the physics world. As explained in previous tutorials, connections for rigid objects are achieved using QJointObject.