# Frame-Rate-Independent Springs, Squash-Stretch & Ribbon Trails in Godot 4

> Typed GDScript 4 second-order damped springs, volume-preserving visual squash-stretch, Eiserloh T^2 FastNoiseLite camera trauma, and ImmediateMesh sword/dash ribbon trails.

- **Canonical page:** https://gamecrew.ai/techniques/godot/procedural-springs-trails
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Godot 4
- **Category:** gameplay
- **Tags:** `springs`, `game-feel`, `juice`, `camera-shake`, `squash-stretch`, `trails`, `immediatemesh`, `animation`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Responsive Godot 4 games separate **physics collision** (`CharacterBody3D` at scale `Vector3.ONE`) from **expressive visual motion** (a `Visual` `Node3D` child driven by second-order damped springs, plus a `Camera3D` driven by rotational $T^2$ noise trauma, and an `ImmediateMesh` ribbon for dashes/swings/projectiles).

Key GDScript 4 rules:
- Use typed math (`clampf`, `maxf`, `minf`, `sqrt`, `exp`) — never untyped `clamp`/`max` with `:=` inference!
- Never mutate `Engine.time_scale` for hit-stop in games tested by `Playtest` / `GameTest` coroutines (`await seconds(...)`); gate local simulation timers instead.

## Mathematical & Algorithmic Core

- **Substepped Second-Order Spring** ($\omega = 2\pi f$, damping $\zeta$):
  $$a = -\omega^2 (x - x_{\text{target}}) - 2\zeta\omega v$$
- **Volume-Preserving Scale**: $s_x = s_z = 1 / \sqrt{s_y}$ on the `Visual` child node.

## Engine Implementation

### Reusable Springs, Trauma & Ribbon Trail (`Assets/Game/Scripts/core/spring_feel.gd`)

```gdscript
class_name SpringFeel
extends RefCounted

class Spring1D:
	var value := 0.0
	var velocity := 0.0

	func _init(initial := 0.0) -> void:
		value = initial

	func step(target: float, freq_hz: float, damping: float, dt: float) -> float:
		if dt <= 0.0:
			return value
		var omega := TAU * maxf(0.1, freq_hz)
		var max_h := minf(0.016, 0.5 / maxf(1.0, omega))
		var rem := minf(dt, 0.2)
		while rem > 0.00001:
			var h := minf(rem, max_h)
			var acc := -omega * omega * (value - target) - 2.0 * damping * omega * velocity
			velocity += acc * h
			value += velocity * h
			rem -= h
		return value

	func impulse(dv: float) -> void:
		velocity += dv

class TraumaShaker:
	var trauma := 0.0
	var _time := 0.0
	var _noise := FastNoiseLite.new()

	func _init(seed_val := 1337) -> void:
		_noise.seed = seed_val
		_noise.frequency = 0.85

	func add(amount: float) -> void:
		trauma = clampf(trauma + maxf(0.0, amount), 0.0, 1.0)

	func sample_angles_rad(dt: float, max_deg := Vector3(3.2, 3.2, 1.8), recovery := 1.45) -> Vector3:
		trauma = maxf(0.0, trauma - recovery * maxf(0.0, dt))
		_time += dt * 24.0
		var shake := trauma * trauma
		if shake <= 0.0001:
			return Vector3.ZERO
		return Vector3(
			deg_to_rad(_noise.get_noise_2d(_time, 11.3) * max_deg.x * shake),
			deg_to_rad(_noise.get_noise_2d(_time, 47.9) * max_deg.y * shake),
			deg_to_rad(_noise.get_noise_2d(_time, 93.1) * max_deg.z * shake)
		)

static func preserve_volume(scale_y: float, base_scale := Vector3.ONE) -> Vector3:
	var sy := clampf(scale_y, 0.45, 1.85)
	var inv := 1.0 / sqrt(sy)
	return Vector3(base_scale.x * inv, base_scale.y * sy, base_scale.z * inv)

static func draw_ribbon(mesh: ImmediateMesh, points: Array[Vector3], up_axis: Vector3, half_width: float, color: Color) -> void:
	mesh.clear_surfaces()
	var n := points.size()
	if n < 2:
		return
	mesh.surface_begin(Mesh.PRIMITIVE_TRIANGLE_STRIP)
	for i in range(n):
		var t := float(i) / float(n - 1)
		var w := half_width * (1.0 - t * 0.85)
		var c := Color(color.r, color.g, color.b, color.a * (1.0 - t))
		mesh.surface_set_color(c)
		mesh.surface_add_vertex(points[i] + up_axis * w)
		mesh.surface_set_color(c)
		mesh.surface_add_vertex(points[i] - up_axis * w)
	mesh.surface_end()
```

## Browser, Mobile & Software-Renderer Budgets

- **`ImmediateMesh` Cap**: Keep ribbon history `points` capped at `16–24` samples in a ring buffer (`Unshaded` + `vertex_color_use_as_albedo = true` on `StandardMaterial3D`) for zero-allocation `< 0.05 ms` trails in WebGL 2.

## Verification Checklist

1. Add a unit test in `Assets/Game/Tests/unit/` asserting `SpringFeel.Spring1D` settles identically at `dt = 1.0 / 30.0` and `dt = 1.0 / 120.0`.
2. Capture motion with `record_test` and inspect `Captures/Recordings/*.png` to verify squash-stretch and ribbon visibility.

## Official references

- Squirrel Eiserloh (GDC 2016 — Juicing Your Cameras With Math)
- Ryan Juckett (Damped Springs)
- Godot 4 ImmediateMesh & FastNoiseLite Reference
