Ice & Pebble Physics Reference

1. Film decay: the sweeping “water film” on the sheet decays exponentially toward 0 with time constant film_decay_s.
2. Per-stone integration: for each moving stone:
   1. Sample the local surface at the stone to get multipliers for friction, curl and angular damping, plus a tiny “cross‑slope” lateral bias.
   2. Apply forces:
      • Drag (linear + quadratic): opposes motion, magnitudes lin_drag · |v| and quad_drag · |v|².
      • Base (Coulomb‑like) friction: mu_base · g opposing motion.
      • Curl force: perpendicular to motion, magnitude curl_coeff · effective_spin · |v| · curl_speed_factor(|v|).
      • Cross‑slope bias: a small extra push to the left of travel proportional to local slope and speed.

      curl_speed_factor(|v|) = 1 / (1 + curl_speed_suppression · |v|); when suppression is zero the factor stays at 1.

   3. Integrate with explicit Euler; snap to full stop if a drag reversal would flip velocity this frame.
   4. Angular damping: ω *= clamp(1 − ang_drag · dt, 0, 1); advance heading by ω · dt.
   5. Bounds: mark out of play if the stone crosses back lines or boards.
   6. Sleep: if speed stays below 0.2 m/s for 0.25 s, snap v=0, ω=0.
3. Wear: shave pebble under the running band by a small amount proportional to distance traveled this step.
4. Sweeping: when active, ahead of the stone: slightly flatten the pebble and charge the temporary film (which then decays).
5. Collisions: resolve elastic disc–disc contacts (unit restitution on the normal; no angular impulse).

The curl strength uses a smoothed “effective spin” (in the direction of ω):

reference = curl_spin_reference
min_value = curl_spin_min
max_value = curl_spin_max

gain      = ((reference - min_value) * reference) / (max_value - reference)
blend     = gain / (|ω| + gain)              // 0..1
eff_mag   = min_value + (max_value - min_value) * blend
effective_spin       = eff_mag * sign(ω)
variation_multiplier = eff_mag / reference    // scales lateral-bias response

Low |ω| → effective_spin ≈ max; high |ω| → ≈ min. If |ω| is essentially zero, curl is 0 for that instant but the bias scaling uses max/reference.

These set the global “feel” of the sheet. Local variability from pebble multiplies these.

Cross‑slope drift (micro lateral bias)

We compute a normalized cross‑slope from the local gradient (projected onto the left‑normal of travel). This produces a tiny lateral acceleration per unit speed:

// Inputs at sample point:
v         = current linear velocity (2D)
speed     = |v|
dir       = normalize(v)
left      = (-dir.y, dir.x)     // left-normal
local     = surface.sample(pos, v, ω, heading)

// Local multipliers supplied by the surface model:
μ_scale, lin_scale, quad_scale, curl_scale, ang_scale, bias_per_speed = local

// Drag (already multiplied by mass in code):
F_lin   = lin_drag  · speed          · m · lin_scale
F_quad  = quad_drag · speed²         · m · quad_scale
F_base  = mu_base   · g              · m · μ_scale
F_drag  = -(F_lin + F_quad + F_base) · dir

// Curl (mass-independent term in code; acceleration comes after /m):
spin    = effective_spin(ω)          // see mapping above
curl_speed_factor = 1 / (1 + curl_speed_suppression · speed)
F_curl  = (curl_coeff · curl_scale · spin · speed · curl_speed_factor) · left

// Cross-slope micro-bias:
F_bias  = (bias_per_speed · speed · m · variation_multiplier(spin)) · left

// Integrate:
a       = (F_drag + F_curl + F_bias) / m
v'      = v + a · dt
pos'    = pos + v · dt
ω'      = ω * clamp(1 - ang_drag · ang_scale · dt, 0, 1)

curl_speed_factor suppresses curl at higher speeds; when curl_speed_suppression = 0 the factor stays at 1.

If v' · v ≤ 0 (drag reversal), we snap the stone to rest to avoid jitter. Sleep triggers if speed stays below threshold for the configured window.

• Overall pace: start with mu_base, lin_drag, quad_drag. Get hog‑to‑hog times right first.
• Curl shape: use curl_coeff for magnitude; then refine the feel with curl_spin_* to shape late vs early finish.
• Consistency vs traffic: increase wear_um_per_pass for more visible tracks; slightly reduce curl_alpha if worn paths feel too “grabby”.
• Sweeping feel: film_friction_scale gives the immediate glide benefit; sweep_flatten_um_per_s makes paths play straighter next stone.
• Micro‑bias realism: small side_grad_gamma (≈ 0.02–0.10) with sensible spin falloff produces believable, non‑twitchy drift.

• Sheet: 45.720 m × 4.750 m; near hog at x=0; far hog at x=21.945.
• Running‑band diameter constant: 0.127 m (used for wear/sampling radius).
• Stones default to 19 kg, radius 0.1455 m.