agent-pages

Clutch cutaway: review findings and accuracy plan (PR #1)

Download

Clutch cutaway: review findings and accuracy plan

PR: yachint/car-demos #1, Interactive clutch cutaway (cursor/clutch-cutaway-demo-ec31 → main) Reviewed at: 46671ce (PR version 4). All file:line references point at this commit. Date: 2026-10-19

This combines four passes over the branch:

Behaviour was measured by stepping src/sim.js headless in Node with scripted pedal inputs. Every number below comes from those runs unless it is marked as a real-car reference. npm test passes 18/18 at 46671ce.

Findings are numbered by area so they can be referenced from commits:

Prefix Area
R Bugs from the code review
P Physics
T Teaching: lessons, narration text and controls
M 3D model
A Audio
N New lessons

1. The short version

One root cause covers about half of the bugs. Commits 8097734 to 46671ce changed three things:

Thresholds elsewhere still assume the old curve:

The single most valuable change is to replace the clutch solve and the idle/stall logic with a standard grip-or-slip model (P1 + P3). It removes every first-gear special case. A prototype passes 17 of the 18 existing tests, and the one failure is an over-tight assertion (details in P1). It makes clutch releases behave the same from 20 to 240 fps, and it clears R1, R4, R8 and R10 outright.

Recommended order

Phase What Clears Effort
1 One-line and small fixes: half-shaft spin sign, pedal order, H-pattern table, countershaft speed, 5th gear lighting, key handling, wording M2, M3 (part), M4 (part), R5, R12, R13, T9 S
2 Grip-or-slip clutch, idle control that is always on, stall below 300 rpm P1, P3, R1, R4, R8, R10 M
3 One definition of open, slipping and locked, used everywhere; starter fixes; plate gap from pedal travel R2, R3, R6, R7, R14, R15, T5 M
4 Engine losses and part-throttle model, then retune the lessons P2, T1, T2, T3 M
5 Teaching text and gear-lever rules R9, T4, T6, T7, T8 S–M
6 3D mechanics: clutch release, gearbox motion, wheels, proportions M1, M3, M5–M7 M–L
7 Calibration, audio, new lessons, hills P4, P5, A1–A6, N M

Frame-rate robustness (R11 and a fixed-step accumulator) should land with phase 2, because P1's frame-rate guarantee depends on it.


2. Bugs from the code review (R)

R1. The engine can be dragged to 0 rpm in the bite zone without stalling

R2. Holding the starter disables stall detection

R3. The touch point (0.82) disagrees with the "open" mode and the shift gate (0.78)

R4. The lock clamp drops the sign, so the clutch can push the wrong way

R5. Arrow keys on a focused pedal slider also apply full throttle or brake

R6. The plate gap and finger pose are drawn from the torque fraction, so the plates look apart at the bite

R7. The starter interlock allows cranking in gear past the bite

R8. A fully released clutch slips for up to a second and shows the "Bite point" text

R9. Every stall not caused by braking is explained as a standstill release

R10. Idle creep is a set of first-gear special cases, so near-identical gears behave differently

R11. A frame hitch turns an instant clutch dump into a slow release

R12. The pedal interpolation state isn't reset when a lesson is placed

R13. Held keys stay latched after the window loses focus

R14. The narration's "Idle creep" check uses different thresholds from the sim

R15. The clutch bite band doesn't match the sim's slip zone

One source of truth for the clutch state (fixes R3, R7, R14, R15 and T5)

Export the pedal geometry and the clutch state from sim.js and derive everything from them:

// sim.js
export const CLUTCH_TOUCH = 0.82   // plates meet
export const CLUTCH_CLAMP = 0.04   // full clamp load
// in sample():
//   mode: 'open' iff engagement === 0, 'locked' iff sim._locked (P1), else 'slipping'
//   idleCreep: boolean that the sim itself computes

Then:


3. Physics (P)

P1. Replace the clutch solve with a standard grip-or-slip model and delete the launch special cases

const MU_RATIO = 1.25            // static / kinetic clutch friction

// inside integrate(), after the engine torque tEng is known
const G = GEARS[gear] * FINAL
const v = sim.speed
const drag = DRAG * v * Math.abs(v)
const rolling = Math.abs(v) > 0.04 ? Math.sign(v) * ROLLING : 0
const brakeCap = BRAKE_FORCE * brake
const moving = Math.abs(v) >= 0.045
const fExt = -drag - rolling - (moving ? Math.sign(v) * brakeCap : 0)

let clutchTorque = 0
if (gear !== 0 && engagement > 0) {
  const Ir = reflectedInertia(gear)                 // MASS * R² / G²
  const held = !moving && brakeCap > 0              // car held by the brakes
  const invI = 1 / I_ENGINE + (held ? 0 : 1 / Ir)
  const inputRate = held ? 0 : (G / WHEEL_R) * fExt / MASS
  const tLock = (slip + dt * (tEng / I_ENGINE - inputRate)) / (dt * invI)
  const kinetic = engagement * CLUTCH_CAPACITY
  const limit = sim._locked ? kinetic * MU_RATIO : kinetic
  if (Math.abs(tLock) <= limit) { clutchTorque = tLock; sim._locked = true }
  else { clutchTorque = Math.sign(tLock) * kinetic; sim._locked = false }
} else sim._locked = false

// after integrating the car: snap the crank to the input shaft while locked
if (sim._locked && gear !== 0) sim.engineOmega = Math.max(0, tiedNow)

P2. Add engine losses and a realistic part-throttle torque

const DISP = 2.0e-3                        // m³
const K_BAR = DISP / (4 * Math.PI) * 1e5   // 15.9 Nm per bar of mean effective pressure
const PUMP_BAR = 0.75                      // closed-throttle pumping mep
const P_AIR = 150000                       // W: air-limited indicated power at full pedal
const DIE_RPM = 300
const IDLE_KP = 0.25

function fmep(rpm) {            // bar, n = rpm / 1000
  const n = Math.max(0, rpm) / 1000
  return 0.97 + 0.15 * n + 0.05 * n * n
}
function lossTorque(rpm, m) {   // friction + pumping that grows as the throttle closes
  const w = Math.sign(rpm) * Math.min(1, Math.abs(rpm) / 200)
  return w * (fmep(rpm) + (1 - m) * PUMP_BAR) * K_BAR
}
function smoothstep(a, b, x) {
  const t = clamp((x - a) / (b - a), 0, 1)
  return t * t * (3 - 2 * t)
}

export function engineTorque(rpm, throttle, alive) {
  if (!alive) return -lossTorque(rpm, 0)
  const omega = Math.max(rpmToOmega(Math.max(rpm, 300)), 1)
  const indWot = torqueCurve(Math.max(rpm, 0)) + fmep(rpm) * K_BAR
  const pedal = Math.min(indWot, Math.pow(throttle, 1.5) * P_AIR / omega)   // air-flow limit
  const idleBase = lossTorque(IDLE_RPM, 0.16)
  const idle = clamp(idleBase + IDLE_KP * (IDLE_RPM - rpm), 0, idleBase + IDLE_ASSIST)  // P3
  let ind = Math.min(Math.max(pedal, idle), indWot)
  if (rpm > 6550) ind = Math.max(0, ind - (rpm - 6550) * 0.6)   // limiter
  ind *= smoothstep(DIE_RPM, DIE_RPM + 180, rpm)                 // combustion fades out (P3)
  return ind - lossTorque(rpm, ind / indWot)
}

The separate friction term in integrate() goes away, because the losses are now inside engineTorque. A dead engine uses -lossTorque(rpm, 0) (plus the existing small tanh term so it settles at zero).

P3. Make idle control and stalling come from the torque balance

P4. Calibration (small, no effect on the lessons)

Gearing. 100 km/h in 5th measures 2,288 rpm, which is low for a 5-speed (typically 2,600–3,000). Idle creep in 1st is 8.6 km/h; real cars creep at about 5–8.

Acceleration. 0–100 km/h measures 8.3 s; about 9–10 s is typical for 105 kW and 1.3 t.

Already right:

Constant Value Real-world check
DRAG 0.4 ½·1.2·0.30·2.2 ✓
ROLLING 170 N rolling coefficient ≈ 0.0135 ✓
CLUTCH_CAPACITY 320 Nm 1.45 × peak engine torque (1.2–1.5 is typical) ✓
I_ENGINE 0.25 kg·m² plausible with a dual-mass flywheel ✓

Braking at standstill never pushes the car backwards ✓.

P5. Further realism that might complicate the teaching


4. Teaching: lessons, narration text and controls (T)

The timelines below were tested against the current sim at 46671ce. After P2 lands, re-check the throttle values, because the new engine model makes the same pedal produce less runaway.

T1. "Pull away" revs to the redline and burns the clutch

at (s) inputs
2.0 clutch: 1
4.0 gear: 1
5.5 brake: 0, clutch: 0.62, throttle: 0.12
7.5 clutch: 0.4, throttle: 0.16
9.3 clutch: 0.02
11.0 throttle: 0

T2. "Change gear" blips the throttle on an upshift and overshoots

at (s) inputs
3.0 throttle: 0, clutch: 1
3.9 gear: 3
4.6 clutch: 0.02
5.0 throttle: 0.3
8.0 throttle: 0.12

T3. "Stop cleanly" teaches coasting, and the live text treats braking in gear as a fault

at (s) inputs
2.5 brake: 0.45
5.2 clutch: 1 (engine at about 1,190 rpm)
8.6 gear: 0
10.0 clutch: 0.04
Gear 1 2 3 4 5
km/h 9 15 21 29 37

T4. The stall explanation is wrong

T5. The clutch-state labels contradict the sim

T6. The live narration ignores context

All in src/explain.js:

Lines Problem Fix
26–31 The lug copy ("clutch closed before the car was moving") also fires for 5th at 20 km/h and for reverse while rolling. R9: when stallSpeed > 1.5 m/s, say "too high a gear".
68–74 The slipping text always describes a standing start, even while the clutch re-engages after an upshift. Branch on speed: below about 1 m/s, a launch; otherwise "matching the engine to the new gear".
48–52 Neutral at 49 km/h says "select first". Above about 10 km/h, suggest the gear that suits the speed, or describe coasting.
86 "about walking pace", but the sim creeps at about 9 km/h. Say "at about 9 km/h" (about 7.6 after P4).
93 "Compression in the cylinders resists." Most engine braking is pumping loss against the closed throttle, with fuel cut. "The throttle is shut, so the pistons pull against a near-vacuum and the fuel is cut. That pumping loss slows the car." The sim barely models this today (P2).

T7. The gear-lever rules don't match a real car

T8. The starter text is false

T9. Minor wording

Where Now Better
src/lessons.js:27 "The gear slides in without fighting the engine." "A synchro sleeve matches speeds and locks the gear to its shaft. The gears themselves stay in mesh."
src/lessons.js:69 "before they are asked to slide apart" "before the sleeve is asked to unlock"
src/lessons.js:94 "because the gear multiplies it less" "because third needs fewer engine turns per wheel turn"
index.html:111 and the PR body "the real millimetre of clearance" "about a millimetre of real clearance"

5. 3D model (M)

Model units are metres. +x is forward, +z is the driver's right, WHEEL_R is 0.34 and the wheelbase is 2.58.

M1. The clutch release works backwards, and the diaphragm can't be seen (medium–large)

M2. Pedals, gear lever and steering wheel are in the wrong places (small)

M3. Gearbox motion is inconsistent (medium)

M4. The half-shafts spin backwards, and the differential is only a sketch (small, then medium)

M5. The wheels render as solid discs (small)

M6. Disc and flywheel details (medium)

M7. Proportions and alignment (medium–large)


6. Audio (A)

src/audio.js. Pitch from rpm (rpm / 30, the firing frequency of a four-stroke four-cylinder) is correct ✓.

# Change
A1 Cranking is silent (audio.js:99, :105). Add a chug at engineRpm / 30 while the starter turns the engine.
A2 Tone follows the throttle pedal, not engine load. Drive it from max(0, sample.flow) (or clutch torque), so a closed throttle under engine braking sounds different from the same rpm under power.
A3 Add a lugging judder below about 1,100 rpm under load: a low-frequency amplitude wobble.
A4 Add a pitch glide into the stall and a short shudder when it dies.
A5 Add a 150 ms grind on a refused shift (T7).
A6 Add a quiet road and tyre layer that scales with speed, so coasting with the engine off isn't silent.

Don't add a clutch-slip squeal: a real clutch doesn't make one.


7. New lessons (N)

These work with the current sim:

These need sim changes first:


8. Tests to add