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:
- a code review of the diff for bugs
- a drivetrain physics audit of
src/sim.js - a 3D mechanics audit of
src/vehicle.js - an audit of the lessons, narration text and audio
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:
- They moved the clutch touch point to pedal 0.82.
- They made
engagementFromPedala torque fraction that jumps from 0 to 0.1 at the touch point. - They built idle creep from first-gear special cases on top of a clutch solver that already had a sign bug.
Thresholds elsewhere still assume the old curve:
- the
open/slipping/lockedmode - the shift gate
- the starter interlock
- the stall gate
- the slider label and the CSS bite band
- the drawn plate gap
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
- Where:
src/sim.js:373(stall gate),src/sim.js:286(idle control gated on brake) - Problem:
- Stall detection only runs when
engagement > 0.62, which on the new curve is roughly the last 16% of pedal travel. - Idle control switches off when the clutch is loaded and
brake >= 0.12. - So across the whole bite zone, the crank can be pulled to 0 rpm while
alivestaystrue.
- Stall detection only runs when
- Measured:
- 1st gear, clutch 0.5, brake 0.5, throttle 0 for 3 s:
alive=true,rpm=0, modeslipping, narration "Bite point". The UI keeps saying "Engine running". - Releasing the brake then brings the engine back to about 794 rpm without the starter.
- 5th gear at pedal 0.3 also ends at 0 rpm and still alive.
- Holding the bite (pedal 0.5) in 3rd at idle sits at 426 rpm indefinitely.
- 1st gear, clutch 0.5, brake 0.5, throttle 0 for 3 s:
- Fix: P3. Use an idle controller that is always on, and stall when rpm drops below a single threshold. Remove both gates.
R2. Holding the starter disables stall detection
- Where:
src/sim.js:374(!sim.starterin the stall check), the starter clamp atsrc/sim.js:329, the Start button and theEkey handler insrc/main.js - Problem:
- While the starter is held, both the stall check and the anti-reverse flywheel guard are skipped, even when the engine is already running.
- Start and
Eaccept a press at any time. - The starter is not released on
pointercancel.
- Measured:
- Hold E or Start and dump the clutch in 1st: no stall.
- Hold E while braking from 14 m/s in 3rd with the clutch up:
alive=true,rpm=0, modelocked. The flywheel can go slightly negative, because the starter clamp allows −30 rad/s. - On touch, a cancelled pointer leaves the starter held, and then the engine can never stall.
- Fix:
- Let the starter act only when
!alive, and ignore it once the engine fires. - Never skip the stall check because of the starter.
- Release the starter on
pointerup,pointercancel,pointerleaveand windowblur(see R13).
- Let the starter act only when
R3. The touch point (0.82) disagrees with the "open" mode and the shift gate (0.78)
- Where:
src/sim.js:55(engagementFromPedal)src/sim.js:198(sample():engagement < 0.14→open)src/sim.js:160(requestGear:clutchPedal < 0.78refused)src/ui.js:125(labelDownabove 0.78)
- Problem: engagement jumps from 0 to 0.1 at pedal 0.82, but:
sample()still reportsopenup to engagement 0.14 (pedal 0.75–0.82).requestGearallows a shift at pedal ≥ 0.78, which is now past the touch point.
- Measured: at pedal 0.79,
requestGear(1)succeeds while the plates carry about 11.5% engagement (about 37 Nm). The car creeps to 8.4 km/h while the coupler reads "Disconnected" and the narration says "Clutch open — Engine and wheels are independent". - Fix: see "One source of truth" under R15.
R4. The lock clamp drops the sign, so the clutch can push the wrong way
- Where:
src/sim.js:258return clamp(desired, -Math.abs(lock), Math.abs(lock)) - Problem: when the predicted slip crosses zero,
lockanddesiredhave opposite signs. The symmetric bound still letsdesiredthrough, so the clutch pushes the slip past zero in the other direction. This is exactly the step-to-step chatter the function's comment says it prevents. - Measured:
- Dead engine rolling at 10 m/s in 2nd, clutch up, traced every 1/180 s step: slip alternates −11.5 / +0.2 rpm and
flowalternates −0.62 / +0.01, without end. - On a coast-to-full-throttle transition the same flip occurs for one step.
accel(body pitch) andheatboth read this oscillation.
- Dead engine rolling at 10 m/s in 2nd, clutch up, traced every 1/180 s step: slip alternates −11.5 / +0.2 rpm and
- Minimal fix:
P1 replaces the function entirely.return clamp(desired, Math.min(0, lock), Math.max(0, lock))
R5. Arrow keys on a focused pedal slider also apply full throttle or brake
- Where:
src/main.js:135 - Problem: the window
keydownhandler maps ArrowUp/ArrowDown to throttle/brake.isTypingonly exemptsINPUTandTEXTAREA, but the pedal tracks arediv role="slider". - Repro: focus the clutch slider and press ArrowUp to raise it 5%. The same event sets
held.throttle = true, so full throttle is applied while the key is down. ArrowDown on any slider applies full brake. - Fix: skip the global mapping when
event.target.closest('[role="slider"]')is set, or map only W/S globally.
R6. The plate gap and finger pose are drawn from the torque fraction, so the plates look apart at the bite
- Where:
src/vehicle.js:136const open = 1 - sample.engagement - Problem: engagement is now a torque fraction that stays between 0.1 and 0.38 through the whole slip zone. The cutaway therefore shows the plates mostly apart while they are touching and driving the car.
- Measured: in the "Hold the bite" lesson step (clutch 0.5, engagement 0.26),
spread = 0.74 × 0.07, so the plates are drawn about 74% open while the narration says "The surfaces meet and slip". At the touch point the drawn gap is still 90% of maximum. - Fix:
- Drive the geometry from pedal position, not torque. The plate gap opens only above the touch point:
lift = clamp((pedal - TOUCH) / (1 - TOUCH), 0, 1), drawn exaggerated. - The release bearing and diaphragm fingers follow the pedal over its whole travel.
- Slip is shown by the existing friction glow and by the two sides turning at different speeds.
- See M1 for the correct direction of motion.
- Drive the geometry from pedal position, not torque. The plate gap opens only above the touch point:
R7. The starter interlock allows cranking in gear past the bite
- Where:
src/sim.js:296if (gear !== 0 && engagement > 0.3) sim.starterBlocked = true - Problem: on the new curve, cranking is allowed in gear down to about pedal 0.42, where the plates carry up to about 96 Nm.
- Measured: a dead engine in 1st, pedal at 0.45, starter held: the engine starts and the car drives off at 7.7 km/h. This contradicts the README ("The clutch must be down, or the gearbox in neutral") and the "Press the clutch to start" narration.
- Fix: block unless
gear === 0 || engagement === 0(pedal ≥ TOUCH). Also consider T8: most modern manuals require the clutch down even in neutral.
R8. A fully released clutch slips for up to a second and shows the "Bite point" text
- Where:
src/sim.js:324(±48 Nm first-gear soft lock),src/explain.js:68–74 - Problem: the soft lock makes a fully clamped clutch (pedal 0, engagement 1, capacity 320 Nm) slip at 48 Nm.
explain()then shows the "Bite point" copy, which tells the driver to let a pedal that is already fully up come all the way up. - Measured:
- After a 0.35 s release in 1st with no throttle, for about 0.8 s the pedal reads 0 and the mode is
slipping(625 vs 123 rpm). The narration says "Let the pedal come all the way up", and the friction disc glows as if at the bite. - The physics run saw the engine held at 600 rpm for 1.2 s with the pedal up.
- After a 0.35 s release in 1st with no throttle, for about 0.8 s the pedal reads 0 and the mode is
- Fix: P1 removes the soft lock.
R9. Every stall not caused by braking is explained as a standstill release
- Where:
src/explain.js:26–31, plus wherestallReasonis set atsrc/sim.js:373+ - Problem: every stall that isn't from braking is tagged
lug. Thelugcopy says the pedal came up while the wheels were almost stopped, which is wrong for a lugging stall while rolling, and for reverse while rolling. - Measured: 5th gear at 20 km/h, clutch up, no throttle stalls with
stallReason 'lug'at 20.5 km/h. The panel reads "The clutch closed before the car was moving … the wheels were still almost stopped". - Fix: split the reason on
stallSpeed:- Below about 1.5 m/s: dump (current copy).
- Above that: too high a gear, e.g. "At this speed 5th gear holds the engine below idle. Change down, or press the clutch."
- Rolling the opposite way to the selected gear: wrong direction.
R10. Idle creep is a set of first-gear special cases, so near-identical gears behave differently
- Where:
src/sim.js:315–324andsrc/sim.js:286gear === 1only- a
_launchLocklatch at 0.22 m/s - a ±48 Nm clamp
- idle control gated on brake position
- Measured:
- In 1st, any release of 0.3 s or longer creeps. In reverse (ratio 3.16 vs 3.36), releases up to 0.6–0.7 s stall.
- The 0.7 s reverse case depends on frame rate: it stalls at 30 Hz and creeps at 60 and 144 Hz.
- A 0.25 s release in 1st stalls at 20, 30, 60 and 144 fps but creeps at 75, 120 and 240 fps.
- A dump while rolling at 1.0 km/h survives; at 0.7 km/h it stalls.
- Fix: P1 + P3. An idle controller with limited torque and a single stall criterion covers every gear without the latch.
R11. A frame hitch turns an instant clutch dump into a slow release
- Where:
src/main.js:191 - Problem: frame slicing ramps the pedals linearly from the previous frame's value to the current one across the whole slow frame, and the frame cap was raised to 0.5 s. A single instant input during a hitch becomes an invented slow release.
- Repro: release C (a dump) during a 0.5 s hitch such as a tab switch or GC pause. The sim gets a 0.5 s ramp from 1 to 0 over 30 slices, which in 1st creeps instead of stalling. The same input at a steady 60 fps stalls.
- Fix:
- Use a fixed-step accumulator (for example 1/240 s) and apply new inputs at the first sub-step (sample and hold) instead of interpolating.
- Cap a single frame at about 0.1 s and drop the remainder rather than simulating it.
- Pedal rate-limiting, if wanted for keyboard input, belongs on the input side and should be based on real time, not frame time.
R12. The pedal interpolation state isn't reset when a lesson is placed
- Where:
src/main.js:202 - Problem:
appliedis not resynced whenplayer.play()orsim.place()resets the pedal state. The next frame's slices interpolate from the previous free-drive pedals into the newly placed lesson. - Repro: hold the clutch down (
applied.clutch = 1) and start "Why it stalls" (setup clutch 0, 3rd gear, 14 m/s). If that first frame has more than one slice, the early slices feed clutch values between 1 and 0 into the placed sim. The lesson does not start from itssetupstate. - Fix: after
place()/play(), copy the sim's pedal state intoapplied. This goes away entirely with R11's sample-and-hold.
R13. Held keys stay latched after the window loses focus
- Where:
src/main.js:146 - Problem:
held.throttle,held.brake,held.clutchandheld.starterare cleared only onkeyup. There is noblurorvisibilitychangehandler. - Repro:
- Hold W and alt-tab away: on return, full throttle stays applied with nothing pressed.
- A stuck E has the same effect and also disables stall detection (R2).
- Fix: clear every held flag on
windowblurand onvisibilitychangewhen hidden.
R14. The narration's "Idle creep" check uses different thresholds from the sim
- Where:
src/explain.js:82(throttle < 0.22,brake < 0.08,speed 0.7–4.2) vs the sim's idle-launch conditions (throttle < 0.18,brake < 0.12) - Measured:
- Creeping in 1st at throttle 0.17 and 1,251 rpm still shows "Idle creep … The engine is only idling".
- With brake between 0.08 and 0.12, the sim still applies idle assist and the soft lock, but the narration falls through to the generic text.
- Fix: have
sample()expose a flag such asidleCreep(orgovernorActive) and branch on it, rather than copying the conditions.
R15. The clutch bite band doesn't match the sim's slip zone
- Where:
src/style.css:239(band about pedal 0.135–0.80),src/ui.js:125("Bite" label 0.2–0.78) - Problem: the sim's plates meet at 0.82 and the clamp is rigid below about 0.26.
- From pedal 0.80 to 0.82 the plates drive the car outside the highlighted band, with the label reading "Down".
- From 0.135 to 0.26 the band marks the rigid-clamp region as bite.
- So the visual hint misleads exactly where the lesson asks for precision.
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:
requestGear: allow the shift only whenclutchPedal >= CLUTCH_TOUCH.- Starter interlock: block unless
gear === 0 || clutchPedal >= CLUTCH_TOUCH. ui.jslabel:Downwhenpedal >= CLUTCH_TOUCHBitewhenmode === 'slipping'Upotherwise
- Bite band: set
--bite-start/--bite-endCSS custom properties from JS using the exported constants, instead of hard-coding them instyle.css. explain.js: branch onmodeandidleCreeponly, never on raw thresholds.vehicle.js: draw the plate gap fromclutchPedalrelative toCLUTCH_TOUCH(R6).
3. Physics (P)
P1. Replace the clutch solve with a standard grip-or-slip model and delete the launch special cases
- Where:
src/sim.js:250–259(clutchTorqueFor),src/sim.js:315–324(soft lock and_launchLock) - What's wrong:
clutchTorqueForsmooths friction withtanh(slip / 3.2)and leaves the car-side forces (drag, rolling resistance, brakes) out ofpredictedSlip(line 256).- Together with R4 this gives a two-step limit cycle while the clutch is meant to be locked:
- In 1st at throttle 0.5, clutch torque alternates 2.9 ↔ 145.5 Nm every substep.
- The sampled
accelflips −0.07 ↔ 4.07 m/s² from one frame to the next at 30 Hz, so the body pitch (vehicle.js:220) shows about half the true value. - Coasting, the slip changes sign on 359 of 360 substeps.
- The ±48 Nm cap and the
_launchLocklatch are not physical (R8, R10). - Momentum at lock-up is otherwise correct: in 2nd it locks at 1,668 rpm against 1,675 rpm ideal.
- Change: the clutch either holds or slides. Static friction is about 1.25 × kinetic friction. The lock torque is the torque that makes the two sides' speeds equal at the end of this step, including the car-side forces:
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)
- Also:
- Drive
sample().modefromsim._locked. - Reset
_lockedinengageGear. - Replace the variable remainder sub-step in
step()with a fixed-step accumulator (R11). - Optional: start
engagementFromPedalat 0, not 0.1, at the touch point (sim.js:55) to remove the 0 → 35 Nm jump.
- Drive
- Measured with P1 + P2 + P3 prototyped together:
- 17 of 18 tests pass. The 18th fails only on its
minRpm > 560assertion: the engine dips to 517 rpm but stays alive. Loosen that assertion to "did not stall" (orminRpm > 480); the real requirement is that it doesn't stall. - The four lesson tests pass.
- A 1.0 s release creeps, and a release of 0.6 s or faster stalls, identically at 20–240 fps.
- Clutch torque is constant while locked, with no sign flips.
- 17 of 18 tests pass. The 18th fails only on its
P2. Add engine losses and a realistic part-throttle torque
- Where:
src/sim.js:281(torqueCurve * throttle),src/sim.js:310(friction) - What's wrong:
- Friction is tiny. It is
0.012·ω + 1.2, about 5 Nm at 3,000 rpm. A real 2.0 L engine with the throttle shut drags at roughly 35–45 Nm (friction mep from Heywood/Bishop plus about 0.7 bar of pumping loss). - So there is almost no engine braking.
- Coasting from 60 km/h in 3rd slows at 0.25 m/s² with the clutch up and 0.21 m/s² with it down. A real car does about 0.6 against 0.2.
- With the clutch down, revs fall at 867 rpm/s; a real engine falls at about 1,500 rpm/s.
- Any throttle runs away.
torqueCurve * throttlemeans any throttle of 0.18 or more revs an unloaded engine to about 6,800 rpm. There is nothing that makes part throttle settle at a part speed. - It burns the clutch in "Pull away".
- The engine reaches 6,762 rpm before the bite and slips at about 6,570 rpm for 3 s.
- That puts 165 kJ into the clutch at a peak of 98 kW.
- A normal launch puts in about 12 kJ: slip energy is roughly the car's kinetic energy at lock-up, ½·1280·4.4² for a 1,500 rpm launch.
- Friction is tiny. It is
- Change:
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).
- Measured with the change:
- Engine braking is 0.61 m/s² in gear against 0.21 m/s² with the clutch down.
- Revs fall at 1,530 rpm/s with the clutch down.
- Unloaded, pedal 0.15 settles at about 2,350 rpm, 0.3 at about 4,500 rpm, and 0.64 at the limiter.
- Effect: no effect on the tests. The lessons need retuning, because they were written against the old torque map:
- "Pull away" throttle 0.64 → about 0.15–0.2, which gives 7–14 kJ of slip.
- The "Change gear" throttle of 0.42 at the "Match the engine" step overshoots to 4,800 rpm against a 2,400 rpm target. It wants about 0.15, or no blip at all (T2).
- See T1–T3.
P3. Make idle control and stalling come from the torque balance
- Where:
src/sim.js:286(idle control off whenbrake >= 0.12),src/sim.js:373(engagement > 0.62gate),src/sim.js:377(0.4 s grace timer) - What's wrong:
- Idle control switches off at a brake threshold. Creeping in 1st, brake 0.10 keeps running but brake 0.13 stalls at 4.3 km/h.
- Stalls are only checked when
engagement > 0.62. Holding the bite in 3rd at idle sits at 426 rpm indefinitely (R1). - The 0.4 s grace timer means braking in 3rd at 0.9 kills the engine only at about 200 rpm (about 4.9 km/h), although the lesson says "under about 500 rpm".
- At brake 0.3 it dies at 10 km/h instead. So the stall speed depends on brake pressure, which it physically shouldn't.
- Change:
- Keep the idle controller on at all times. Its indicated torque is
clamp(T_loss(850) + 0.25·(850 − rpm), 0, T_loss(850) + 88).- 88 Nm (
IDLE_ASSIST) is a defensible reserve for a drive-by-wire anti-stall. Lowering it breaks the creep tests.
- 88 Nm (
- Fade combustion torque with
smoothstep(300, 480, rpm). - The engine dies when rpm falls below
DIE_RPM = 300. Drop the timer and both gates:
The starter must not exempt a running engine from this (R2).if (sim.alive && rpmNow < DIE_RPM) { sim.alive = false; sim.stallReason = …; sim.stallSpeed = Math.abs(sim.speed) }
- Keep the idle controller on at all times. Its indicated torque is
- Measured with the change:
- Braking in 3rd crosses 520 rpm at 12.8 km/h and stalls at 7.2 km/h, whatever the brake pressure.
- In 1st, idle control holds against brake 0.3 and stalls at brake 0.5.
- The stall and clean-stop lessons still pass.
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.
WHEEL_R0.34 m matches a 225/55R17. A 205/55R16 is about 0.31 m.- With
WHEEL_R = 0.31andFINAL = 3.9: about 2,700 rpm at 100 km/h and about 7.6 km/h creep.
Acceleration. 0–100 km/h measures 8.3 s; about 9–10 s is typical for 105 kW and 1.3 t.
- Add drivetrain efficiency η ≈ 0.92 on the force through the gearbox and axle.
- Add wheel and driveline inertia, worth about +4% equivalent mass.
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
- Tyre traction:
- Every lock-up from high rpm peaks at 8.81 m/s² (0.9 g).
- A rear-drive car with this layout tops out at a = μg·(b/L) / (1 − μh/L) ≈ 0.59 g.
- Doing it properly means modelling the rear wheels' speed separately, with the tyre as a second grip-or-slip element (limit μ·N_r·R). That adds a third speed to explain.
- After P2 and the lower lesson throttle, the lessons stay at or below 3.1 m/s², so this only matters for abuse in free drive.
- Full-pedal braking:
BRAKE_FORCE7600 N is 0.61 g at full pedal; a real car does about 0.9–1.0 g. Changing it means retuning the lessons' brake 0.9. - Hills: a grade term (m·g·sinθ) would allow hill-start and roll-back lessons (N).
- Later:
- a 0.1–0.2 s air-path lag on the idle controller
- clutch friction that varies with slip speed and temperature (judder, fade)
- driveline wind-up shuffle after lock-up (at 2–5 Hz the "locked" readout would oscillate)
- bump starts
- a starter that cranks at 200–300 rpm
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
- Where:
src/lessons.js:31(throttle: 0.64with the clutch down),src/lessons.js:37–40("Hold the bite"),src/lessons.js:45–48 - Problem:
- The engine reaches about 6,900 rpm, past the red arc.
- "Hold the bite" slips about 4,500 rpm for 3 s (heat 0.83).
- The player keeps its last targets (
throttle: 0.38), so the car ends on the limiter at 71 km/h in 1st, under the text "on flat ground idle alone is enough".
- Real practice: instructors teach pulling away on idle or at about 1,200–1,500 rpm.
- Tested replacement (peaks at 1,293 rpm, ends creeping at 8.6 km/h):
| 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 |
- Copy: change "A little throttle" to describe a small rise to about 1,200–1,500 rpm, and keep "idle alone is enough" for the last step, which is now true.
T2. "Change gear" blips the throttle on an upshift and overshoots
- Where:
src/lessons.js:56(setupthrottle: 0.42),src/lessons.js:84–88("Match the engine",throttle: 0.42) - Problem:
- The engine falls to 1,100 rpm when 3rd needs about 2,000. Then 0.42 throttle flares it to 2,980 rpm, so the clutch closes about 1,000 rpm high.
- The lesson also keeps accelerating to 118 km/h.
- Real practice: an upshift is lift off and clutch down together, then release as the revs fall to the new gear's speed. A blip belongs to a downshift.
- Tested replacement (no flare):
| 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 |
- Copy:
- Replace "Match the engine" with something like "Let the revs fall. Third needs a lower engine speed, so the engine is already coming down to meet the disc."
- Keep the throttle-blip idea for a downshift lesson (N).
- Also: lower the setup throttle so the lesson ends at a steady cruise. Ending at 0.12 avoids the run to 118 km/h.
T3. "Stop cleanly" teaches coasting, and the live text treats braking in gear as a fault
- Where:
src/lessons.js:145–151(clutch 1 with brake 0.9 at 2.5 s),src/explain.js:54–59 - Problem:
- The lesson presses the clutch at the same moment as 0.9 brake, which is a hard stop at 5.3 m/s².
explain.jswarns "The brakes are slowing the engine too" whenever you brake in gear.
- Real practice:
- Brake in gear, then press the clutch as the revs approach idle.
- Holding the clutch down for the whole stop is "coasting", which is marked as a fault on the UK driving test.
- Tested replacement:
| 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 |
- Better still: let
whensteps set pedals, so the clutch goes down at an rpm threshold rather than a fixed time. Todayobserve()(src/lessons.js:241–251) only sets text. - Copy for the explain panel: "Braking in gear is normal. In 3rd the engine reaches idle at about 21 km/h; press the clutch before then."
- Speeds at which each gear reaches idle, from
IDLE_RPM,GEARS,FINALandWHEEL_R:
| Gear | 1 | 2 | 3 | 4 | 5 |
|---|---|---|---|---|---|
| km/h | 9 | 15 | 21 | 29 | 37 |
T4. The stall explanation is wrong
- Where:
README.md:27,src/lessons.js:128,src/explain.js:23, and the PR description - Problem: "Under about 500 rpm the crankshaft cannot finish the next compression stroke" is false. Engines start while the starter turns them at 150–300 rpm.
- Real mechanism: dragged below idle, the engine cannot make the torque the wheels are demanding, so it slows further and dies.
- Replacement wording: "Dragged below idle, the engine can't make the torque the wheels demand, and it dies."
- Also at
explain.js:23: the text says the engine "fell through 500 rpm" but reportsstallSpeedfrom about 0.4 s later (about 5 km/h, about 200 rpm), so the two numbers don't belong together. Show the gear's idle speed from the T3 table instead: "In 3rd the engine reaches idle at about 21 km/h."
T5. The clutch-state labels contradict the sim
- Where:
src/sim.js:198,src/ui.js:125,src/sim.js:160,src/explain.js:41 - Problem:
- At pedal 0.74–0.82, engagement is still 0.10–0.14 and the car creeps at 8.4 km/h, yet the mode reads
open("Disconnected"). - The readout says "Down" from 0.78, and shifts are allowed there.
- A steady creep at pedal 0.6 (2.6 rpm of slip) reads "Slipping", because
lockedneedsengagement > 0.8. explain.js:41uses a third threshold (engagement < 0.2).
- At pedal 0.74–0.82, engagement is still 0.10–0.14 and the car creeps at 8.4 km/h, yet the mode reads
- Fix:
openonly when engagement is 0, for the mode, the readout and the shift gate.lockedfrom P1's grip state. If P1 isn't adopted, use|slip| < 40 rpm.- See "One source of truth" in section 2.
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
- Where:
src/sim.js:157–172 - Engine off: a shift is refused "under load" when the clutch is up. With the engine off there is no load (that is how you park in gear), so allow any gear.
- Reverse: allowed up to 0.7 m/s forward, and then the engine stalls. Require
|speed| < 0.1 m/sand gearbox input below about 100 rpm, otherwise refuse with a grind (A5). - 1st at 60 km/h: allowed. Refuse a shift that would land the engine past the red arc, with copy that names the speed limit for that gear.
- Real cars: you can force a shift without the clutch, but it grinds unless rev-matched. Refusing it is a reasonable teaching rule, but the copy should say it grinds rather than claim it's impossible.
T8. The starter text is false
- Where:
src/explain.js:8,src/explain.js:37, and the README controls table - Problem:
- "The starter would have to turn the whole car" suggests it can't. In fact a starter will lurch a car that is in gear.
- Most modern manual cars won't crank without the clutch down, even in neutral.
- Copy: "Clutch down, neutral, then Start."
- Rule: consider always requiring the clutch (
src/sim.js:296, R7).
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)
- Where:
src/vehicle.js:147(bearing travel),:152(bearing spin),:153(finger pivot),:291(coverSpin.x = FLY_X),:301,:314(input shaft is a child of the disc),:330(solid pressure plate),:350–362(fork) - Now:
- The diaphragm fingers sit at x 0.717–0.723, inside the flywheel (x 0.708–0.772). In Face view 0 pixels of the fingers or the disc show, because the solid pressure plate covers the disc.
- Pressing the pedal moves the release bearing 105 mm away from the engine. The pressure plate moves back 140 mm, and the disc 70 mm.
- Because the input shaft is a child of the disc, the shaft slides back too.
- The fingers pivot at their outer edge with nothing pushing them. This contradicts
lessons.js:21("The release bearing pushes the diaphragm fingers").
- Real push-type clutch:
- The order is flywheel → friction disc → pressure plate → diaphragm spring on a pressed-steel cover → release bearing on a fixed guide sleeve.
- Pressing the pedal moves the bearing about 8–10 mm toward the engine.
- The fingers pivot on the cover's fulcrum ring at about 0.8 × plate radius. Their outer edge lifts the pressure plate about 1.5–2 mm (a lever ratio of about 4:1).
- Change:
- Grouping: put the cover, diaphragm and pressure plate in one group, behind the disc, that rotates with the flywheel.
- Fingers: pivot them at the fulcrum radius. Drive the bearing toward +x by
open * travel, and move the plate back bytravel / 4. Exaggerate both by the same factor and note it. - Pressure plate: make it an annulus, so Face view shows the fingers and, through them, the disc hub.
- Input shaft:
- Give it its own group that does not slide, extended forward to a pilot bearing in the crank.
- The disc slides only a millimetre or so on its splines.
- Release bearing: spin its inner race with
engineAngleonly, neverinputAngle(:152). - Explode: separate the cover assembly as one unit instead of bending the fingers further.
- Fork: add the guide sleeve. Pivot the fork on a ball stud rather than sliding it.
- Gap: drive it from pedal travel, as in R6.
M2. Pedals, gear lever and steering wheel are in the wrong places (small)
- Pedals (
src/vehicle.js:627–629):- The seat is at z +0.34 (
:657), so the cabin is right-hand drive. - The clutch is outboard at z 0.46 and the throttle inboard at 0.22, so from the seat the pedals read throttle – brake – clutch. That is wrong for any car.
- Right-hand drive: clutch 0.22, brake 0.34, throttle 0.46.
- Left-hand drive: mirror the cabin to clutch −0.46, brake −0.34, throttle −0.22.
- The seat is at z +0.34 (
- Shift pattern (
src/vehicle.js:833–844):leverPoseswaps the two axes, so the H lies on its side. Only 1 and R land in the right place; 2 goes forward-right and 5 back-left.- The on-screen gate (
index.html:144–150) is the standard 1-3-5 over 2-4-R. - Use:
{ 0: [0, 0], 1: [-0.28, -0.22], 2: [0.28, -0.22], 3: [-0.28, 0], 4: [0.28, 0], 5: [-0.28, 0.22], '-1': [0.28, 0.22] } - Check the sign convention against the lever's rotation axes in the scene.
- Lever position (
src/vehicle.js:632):- Now at (−0.42, 0.58, 0.28), behind the seatback.
- A rear-drive shifter rises from the gearbox tail on the transmission tunnel, at about (0.05, 0.6, 0.06).
- Steering wheel (
src/vehicle.js:666): it is on the car's centreline. Move it to the seat's z and tilt it about 20°. - Clutch linkage: the pedal drives nothing. Add a master cylinder, a hydraulic line and a slave cylinder on the bellhousing that pushes the fork, so pressing the pedal visibly moves the bearing.
M3. Gearbox motion is inconsistent (medium)
- Where:
src/vehicle.js:381–405,src/vehicle.js:184,src/vehicle.js:195,src/sim.js:396 - Now:
- Countershaft speed: the gear radii (
vehicle.js:381–383) imply a countershaft turning at input/1.6. They reproduce 3.35, 2.08, 1.42 and 1.02 againstGEARS✓. But the countershaft is animated at −1.25 × input (sim.js:396), so every gear pair's teeth slide past each other at a 2:1 speed mismatch. - Fixed gears: every mainshaft gear is fixed to the output shaft (
vehicle.js:395). In neutral, the countershaft gears grind through stationary gears. - Lighting: 5th lights 4th's pair (
vehicle.js:184), so "the gear pair that is lit" (lessons.js:62) is wrong in 5th. - Missing parts: no input-to-countershaft pair, no visible shafts, and no 5th pair.
- Reverse idler: at z = 0 it meshes with nothing (
vehicle.js:401). - Collar: the single collar is hidden inside the selected gear (
vehicle.js:195,:405). - Tooth sizes: every gear has 18 or 16 teeth, so meshing teeth have different sizes (40 mm vs 22 mm on the 1st pair).
- Countershaft speed: the gear radii (
- Real gearbox: the countershaft always turns with the input shaft. The mainshaft gears spin freely on bearings, and a sliding sleeve locks the selected one to the shaft. Neutral therefore shows every gear spinning while the mainshaft stays still, which is exactly the point the lessons make.
- Change:
- Countershaft angle =
−inputAngle / 1.6. Each mainshaft gear's angle =−counterAngle × R_counter / R_main. The mainshaft (output) angle =inputAngle / GEARS[gear], or still in neutral. - Add the input-to-countershaft pair at x ≈ 0.53 (radius 0.065 on the input, 0.105 on the countershaft) and a 5th pair at x ≈ 0.06 (radius 0.057 / 0.113).
- Set
teeth = Math.round(2 * Math.PI * r / pitch)with one tooth pitch for all gears. - Add three sleeves (1-2, 3-4, 5-R), about 0.07 in diameter, sliding ±0.025 toward their gear.
- Offset the reverse idler in z so it meshes with a countershaft gear and a mainshaft reverse gear.
- Light the input-to-countershaft pair, the selected pair and the active sleeve.
- Countershaft angle =
M4. The half-shafts spin backwards, and the differential is only a sketch (small, then medium)
- Rotation:
ringSpin.rotation.z = +wheelAngle(src/vehicle.js:162), but the wheels use−wheelAngle(src/vehicle.js:203). The half-shafts are children ofringSpin(:449), so their orange marker turns against the tyre. Negate it. - Ring and pinion (
src/vehicle.js:425–429):- The teeth are 26:14 (1.86), but
FINALis 3.62. Use something like 47:13 to match. - The pinion is a spur gear whose disc cuts through the ring's rim.
- The teeth are 26:14 (1.86), but
- Real: a hypoid set, with teeth cut on the ring's face, the ring offset to one side, and the pinion below the centreline.
- Change:
- Model the ring as a bevel gear and lower the pinion.
- Add a carrier with a cross-pin, 2 spider gears and 2 side gears. The spider gears don't turn on their pin when driving straight, so they can stay static.
- Add see-through axle tubes.
M5. The wheels render as solid discs (small)
- Where:
src/vehicle.js:755–786(makeWheel, tyre at:760), brake glow at:204 - Now:
- The tyre is a closed cylinder that encloses the rim, spokes, brake rotor and caliper; a render probe saw 0 pixels of each.
- So the brake glow never shows, although
lessons.js:115points at the brake discs. - The caliper is also outboard of the rotor, crossing the spokes' path.
- Change:
- Build the tyre with
LatheGeometry: a sidewall from radius about 0.2 to 0.34 and an open centre. - Use an open rim barrel with spokes on the outer face, the rotor inboard, and the caliper straddling the rotor's edge.
- Build the tyre with
M6. Disc and flywheel details (medium)
- Disc:
- Now a 36 mm solid friction-material cylinder (
src/vehicle.js:301). The hub and damper springs are buried inside it (:298,:308), and the springs point outward from the centre (:311). - A real disc is about 8–9 mm thick: a steel plate with two ring-shaped friction facings (inner diameter about 0.65 × outer), a splined hub, and 4–6 damper springs laid around its circumference.
- Now a 36 mm solid friction-material cylinder (
- Flywheel:
- Now 28 large teeth (
:253); a real starter ring gear has about 120–135 fine teeth. - The bolts are hidden inside the flywheel (
:266).
- Now 28 large teeth (
- Starter pinion: its centre sits on the flywheel rim (
:584). Place it at ring-gear radius + pinion radius, and slide it into mesh only while cranking.
M7. Proportions and alignment (medium–large)
- Clutch size:
- The disc is 370 mm across, which is truck-sized; this class uses 200–240 mm. The flywheel with its ring gear is 470 mm across, taller than the 0.4 m engine block.
- The gearbox shaft spacing is 175 mm (real 75–90 mm) and the ring gear is 300 mm (real 190–215 mm).
- Either scale these by about 0.65 and move the inset camera in, or say in the README and the on-screen note that they are drawn larger.
- Driveshaft angle:
- With
CRANK_Y0.6 and the axle at 0.34, the driveshaft slopes 13° (src/vehicle.js:433). U-joints normally run at 1–3°. CRANK_Y ≈ 0.44gives 4.4°. Tilt the powertrain about 3° to match the pinion.- The engine heights are hard-coded (
src/vehicle.js:497–541), so make them relative toCRANK_Yfirst.
- With
- Pistons and crank:
- At top dead centre the piston crown is at 0.837, about 90 mm below the cylinder tops (0.91) and the deck (0.94). A real crown comes up flush with the deck.
- The cylinder sleeves have radius 0.055 against a 0.042 piston.
- The connecting rod's taper is upside down: the small end is the thicker one (
:527). - The crank is offset 50 mm in z from the flywheel axis (
crankZ,:512) and stops 48 mm short of it. SetcrankZ = 0and add a flange.
- Body fit: the valve cover (top at 1.105) pokes through the hood (top at 1.0) (
:502,:690). - Bellhousing (
:368): the taper is reversed. The wide end faces the gearbox, and the engine end is narrower than the ring-gear teeth. It should run from x 0.57 to 0.83, wide at the engine block. - Driveshaft joints (
:604):- The U-joints are bare crosses with no yokes, and the shaft starts 20 mm below the mainshaft axis.
- Add the yokes, a slip yoke and a tail housing.
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:
- Rev-matched vs unmatched downshift: 3rd → 2nd at 40 km/h, once with a blip and once without. This is where the blip from T2 belongs.
- Reversing on the bite: creep backwards with the pedal held at the bite.
- Too high a gear: 5th at 20 km/h, showing the lugging stall (needs the R9 copy).
- Emergency stop: brake hard and press the clutch at the same moment. This is the one case where clutch and brake go down together.
- Coasting in neutral vs in gear: a weak contrast until P2 adds engine braking.
- Starting the engine: clutch down, neutral, Start. This needs a
startertarget in the lesson player (src/main.js:198).
These need sim changes first:
- Hill start: needs a slope (P5), a handbrake, idle control that keeps running while braking (P3), and stall detection at partial clutch (P3/R1). Today, holding the bite on the brake drags the engine to 0 rpm while it still counts as running.
- Engine braking downhill: needs a slope and closed-throttle engine drag (P2).
8. Tests to add
- Frame-rate invariance: the same pedal trace stepped at 30, 60 and 144 Hz gives the same stall or creep outcome (R10, R11, P1).
- Reverse: a 1.0 s release in reverse creeps, the same as in 1st (R10).
- Bite held against the brake: 1st, clutch 0.5, brake 0.5 for 3 s →
alive === false(R1). - Starter held: a clutch dump with the starter held still stalls (R2).
- Shift gate:
requestGearis refused wheneverengagementFromPedal(pedal) > 0(R3). - Starter interlock: cranking in gear is refused whenever engagement > 0 (R7).
- Locked state: no sign flips in clutch torque over 1 s of locked driving (R4, P1).
- Lesson sanity: "Pull away" peaks below 2,000 rpm, its clutch slip energy stays under 20 kJ, and the lesson ends below 15 km/h (T1).
- Clean stop: the clutch goes down above the gear's idle speed, and the engine stays alive (T3).
- Update the over-tight assertion: replace
minRpm > 560with a check that the engine did not stall (P1).