Table of Contents

Class SpringConstraint

Namespace
Jitter2.SoftBodies
Assembly
Jitter2.dll

Constrains two bodies to maintain a target distance between anchor points, applying spring-like forces. Removes one translational degree of freedom along the line connecting the anchors.

public class SpringConstraint : Constraint<SpringConstraint.SpringData>, IDebugDrawable
Inheritance
SpringConstraint
Implements
Inherited Members

Remarks

This constraint is designed for soft body vertices, which act as mass points. Angular velocities of the connected bodies are not taken into account. The spring behavior is controlled by Softness and Bias, which can be set directly or computed from physical parameters using SetSpringParameters(float, float, float).

Properties

Anchor1

Gets or sets the anchor point on the first body in world space.

public JVector Anchor1 { get; set; }

Property Value

JVector

Anchor2

Gets or sets the anchor point on the second body in world space.

public JVector Anchor2 { get; set; }

Property Value

JVector

Bias

Gets or sets the bias factor (error correction strength) of the spring constraint.

public float Bias { get; set; }

Property Value

float

Default is 0.2. Higher values correct distance errors more aggressively.

Distance

Gets the current distance between the anchor points.

public float Distance { get; }

Property Value

float

Impulse

Gets the accumulated solver impulse from the last solved substep.

public float Impulse { get; }

Property Value

float

Softness

Gets or sets the softness (compliance) of the spring constraint.

public float Softness { get; set; }

Property Value

float

Default is DefaultLinearSoftness. Higher values allow more positional error but produce a softer spring. Scaled by inverse timestep during solving.

TargetDistance

Gets or sets the target resting distance of the spring.

public float TargetDistance { get; set; }

Property Value

float

Units: meters. Default is the initial distance between anchors at initialization.

Methods

Create()

Sets the solver dispatch id used by this instance. Override this in derived classes to assign the correct registered solver pair. The id is later written into the unmanaged header when the constraint is enabled.

protected override void Create()

DebugDraw(IDebugDrawer)

Draws a debug visualization of this constraint.

public override void DebugDraw(IDebugDrawer drawer)

Parameters

drawer IDebugDrawer

The debug drawer to receive visualization primitives.

Exceptions

NotImplementedException

Thrown if the derived class does not override this method.

DebugDraw(IDebugDrawer, in DebugDrawSettings)

Draws this constraint using the supplied visualization settings. Custom constraints that only override DebugDraw(IDebugDrawer) use their default visualization.

public override void DebugDraw(IDebugDrawer drawer, in DebugDrawSettings settings)

Parameters

drawer IDebugDrawer
settings DebugDrawSettings

DebugDraw(IDebugDrawer, ref JVector, in DebugDrawSettings)

Draws the spring with a caller-owned coil reference. Retain this direction between frames to keep the coil continuous through arbitrary motion, including a reversal of the spring axis.

public void DebugDraw(IDebugDrawer drawer, ref JVector reference, in DebugDrawSettings settings)

Parameters

drawer IDebugDrawer
reference JVector
settings DebugDrawSettings

Initialize(JVector, JVector)

Initializes the constraint from world-space anchor points.

public void Initialize(JVector anchor1, JVector anchor2)

Parameters

anchor1 JVector

Anchor point on the first rigid body, in world space.

anchor2 JVector

Anchor point on the second rigid body, in world space.

Remarks

Computes local anchor offsets from the current body positions. Default values: Softness = DefaultLinearSoftness, Bias = DefaultLinearBias. The TargetDistance is set to the initial distance between the anchors.

Exceptions

ArgumentException

Thrown when anchor1 or anchor2 contains a non-finite value.

IterateSpringConstraint(ref ConstraintData, in TimeStep)

Performs one iteration of the spring constraint solver.

public static void IterateSpringConstraint(ref ConstraintData constraint, in TimeStep timeStep)

Parameters

constraint ConstraintData

The constraint data reference.

timeStep TimeStep

The full step and substep timing information.

PrepareForIterationSpringConstraint(ref ConstraintData, in TimeStep)

Prepares the spring constraint for iteration.

public static void PrepareForIterationSpringConstraint(ref ConstraintData constraint, in TimeStep timeStep)

Parameters

constraint ConstraintData

The constraint data reference.

timeStep TimeStep

The full step and substep timing information.

ResetWarmStart()

Resets the cached warm-start state used by the solver for this constraint.

public override void ResetWarmStart()

Remarks

This clears only persistent solver impulses. Constraint configuration remains unchanged. Useful after restoring snapshots or other discontinuous state changes where preserving warm-starting is undesirable.

SetSpringParameters(float, float, float)

Sets the spring parameters using physical properties. This method calculates and sets the Softness and Bias properties. It assumes that the mass of the involved bodies, their translation locks, the anchor direction, and the timestep size do not change.

public void SetSpringParameters(float frequency, float damping, float dt)

Parameters

frequency float

The frequency in Hz.

damping float

The damping ratio (0 = no damping, 1 = critical damping).

dt float

The timestep of the simulation.

Remarks

At coincident anchors, the most responsive translation axis determines the effective mass used to configure the spring.

Exceptions

ArgumentOutOfRangeException

Thrown when frequency or dt is less than or equal to zero, when damping is negative, or when any value is not finite.

Edit this page