sindicate 0.15.0 → 0.17.0

package/src/vehicle/car.js

@@ -0,0 +1,324 @@
+// A CAR — suspension, wheels, brakes, grip.
+//
+// Deliberately not a rigid-body solver: a planar body with a wheel at each corner, which is
+// what an open-world game actually needs and what can be reasoned about when it misbehaves.
+// The car owns its physics; a game owns its model, its sounds and its camera.
+//
+//   const car = createCar({ surfaceAt });
+//   car.update(dt, { throttle, brake, handbrake, steer });
+//   // then pose the model from car.pose() and the wheels from car.wheels
+//
+// `surfaceAt(x, z, fromY)` returns the height of whatever is driveable under a point, or
+// null for thin air — a raycast against the road meshes, typically. Each wheel asks
+// separately, which is what gives pitch, roll and the ability to hang a wheel over an edge.
+//
+// `obstacleAt(from, dir, reach)` answers what is standing in the way: { normal, distance } or
+// null. The GAME decides how to answer a ray; the CAR decides where to ask and what to do
+// about the answer, because that is the part with all the traps in it — which is why it
+// belongs here and not in a game's page.
+//
+// The four faults this module exists to prevent, all of them found the hard way:
+//   · a body snapped to the ground every frame is glued to it and can never leave a ramp;
+//   · an airborne test that compares one frame against gravity flickers on contact noise,
+//     and if landing costs speed the car sags to a crawl with the throttle held;
+//   · a single collision ray down the nose lets the whole body pass through anything it did
+//     not drive at head-on;
+//   · a "wall" that is really a rail alongside must never bleed speed.
+const G = 9.81;
+
+const wrapPi = (a) => Math.atan2(Math.sin(a), Math.cos(a));
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+
+export const CAR_DEFAULTS = {
+  // measured off the Synty sedan; a game passes its own model's numbers
+  wheelbase: 2.88,          // front axle to rear axle
+  track: 1.66,              // left wheel to right wheel
+  wheelRadius: 0.36,
+  rideHeight: 0.34,         // body origin above the contact patch at rest
+  mass: 1300,
+
+  suspension: {
+    travel: 0.22,           // how far a wheel may move before it tops or bottoms out
+    stiffness: 26,          // rad/s² per metre of compression — how hard it pushes back
+    damping: 7.5,           // how quickly it stops oscillating
+  },
+
+  engine: {
+    // A CAR IS POWER-LIMITED, not force-limited. A constant acceleration means it pulls as
+    // hard at 120 mph as at walking pace — 0 to 123 mph in three seconds, which is madness.
+    // Tyres cap what you can put down low; above that it is power over speed, so the pull
+    // fades as the car gains speed and top speed is approached slowly, as it should be.
+    traction: 6.5,          // m/s² — all the grip will take from a standing start
+    power: 152,             // m²/s³ — acceleration = power / speed once rolling
+    drive: 14,              // m/s² — legacy name, still honoured if a game sets it
+    topSpeed: 55,           // ~200 km/h
+    reverseSpeed: 12,
+    // COASTING. A single per-second decay is not drag: at 90 km/h a 0.55 decay takes
+    // 13.75 m/s² out of the car — harder than most braking — so lifting off felt like
+    // standing on the pedal. Real resistance is a near-constant rolling term plus air that
+    // only bites at speed, and top speed is held by the limiter rather than by drag.
+    rollingResistance: 0.35,  // m/s², roughly constant
+    airDrag: 0.0008,          // m/s² per (m/s)² — about 0.5 m/s² at 90 km/h
+  },
+
+  brakes: {
+    force: 22,              // m/s² on the pedal
+    handbrake: 9,           // the rear locking up
+  },
+
+  grip: {
+    normal: 7.5,            // how fast travel direction is dragged round to face the car
+    handbrake: 1.1,         // ...and how completely it lets go when the rear locks
+    steerRate: 1.5,         // radians/s of yaw at speed
+    steerHandbrake: 2.6,
+    steerBite: 12,          // m/s at which steering reaches full authority
+  },
+
+  // A GUARDRAIL IS A THIN BAR ON POSTS. One ray at one height slips under the rail or
+  // through the gap between two posts, so whether a fence stops you depends on the angle you
+  // happened to approach it at. Feeling for it at several heights catches the bar, the post
+  // and the kerb alike.
+  body: { halfWidth: 1.0, halfLength: 2.4, probeHeights: [0.25, 0.55, 0.9] },
+  maxLean: 0.6,             // ~35 deg: no contact reading may tip the body further than this
+  launchMargin: 3.5,        // the ground must fall away this much faster than gravity to fly
+  landingHit: 6,            // vertical speed below which a landing costs nothing
+  maxStep: 0.45,            // the tallest thing a wheel may climb onto in one go
+};
+
+// TWO DIFFERENT QUESTIONS, and conflating them is what makes a car crawl: something AHEAD
+// obstructs travel, something ALONGSIDE only stops the body moving sideways into it. A rail
+// you are driving down must never bleed speed. Probes cover the whole body, nose to tail —
+// one ray down the middle lets a back end swing clean through a barrier on a turn.
+function resolveObstacles(car, dt, obstacleAt) {
+  const { halfWidth, halfLength } = car.cfg.body;
+  const heights = car.cfg.body.probeHeights ?? [car.cfg.body.probeHeight ?? 0.4];
+  const fx = Math.sin(car.travel), fz = Math.cos(car.travel);
+  const rx = -fz, rz = fx;                                  // the car's right, in world terms
+  const ask = (ox, oz, dx, dz, reach) => {
+    let best = null;
+    for (const h of heights) {
+      const hit = obstacleAt({ x: car.pos.x + ox, y: car.pos.y + h, z: car.pos.z + oz }, { x: dx, z: dz }, reach);
+      if (hit && (!best || hit.distance < best.distance)) best = hit;
+    }
+    return best;
+  };
+
+  // AHEAD (or behind, in reverse) — only as far as the car will actually travel this frame,
+  // or every curve reads as a collision with the barrier running alongside it
+  if (Math.abs(car.speed) > 0.4) {
+    const sgn = Math.sign(car.speed);
+    const dx = fx * sgn, dz = fz * sgn;
+    const nose = halfLength * sgn;
+    const reach = 0.2 + Math.abs(car.speed) * dt;
+    for (const off of [-halfWidth, 0, halfWidth]) {
+      const hit = ask(fx * nose + rx * off, fz * nose + rz * off, dx, dz, reach);
+      if (!hit) continue;
+      const n = hit.normal;
+      // slide along it rather than stopping dead, and only scrub speed for a square hit
+      const headOn = clamp(-(n.x * dx + n.z * dz), 0, 1);
+      car.pos.x += n.x * (reach - hit.distance);
+      car.pos.z += n.z * (reach - hit.distance);
+      // square-on stops you quickly; a glancing scrape barely costs anything
+      car.speed *= 1 - 6 * headOn * Math.min(dt, 0.05);
+      // deflect where the car is GOING, not where it is pointing. Turning the facing leaves
+      // it crabbing down the road at the angle of whatever it brushed, long after the
+      // contact has gone; grip brings the nose round on its own.
+      let alongX = -n.z, alongZ = n.x;
+      if (alongX * fx + alongZ * fz < 0) { alongX = -alongX; alongZ = -alongZ; }
+      car.travel += wrapPi(Math.atan2(alongX, alongZ) - car.travel) * Math.min(1, dt * 6);
+      break;
+    }
+  }
+
+  // ALONGSIDE — push the body out, never touch its speed
+  for (const s of [-1, 1]) {
+    for (const along of [halfLength * 0.92, halfLength * 0.3, -halfLength * 0.3, -halfLength * 0.92]) {
+      const hit = ask(fx * along + rx * s * halfWidth, fz * along + rz * s * halfWidth, rx * s, rz * s, 0.35);
+      if (!hit) continue;
+      car.pos.x += hit.normal.x * (0.35 - hit.distance);
+      car.pos.z += hit.normal.z * (0.35 - hit.distance);
+    }
+  }
+}
+
+export function createCar({ surfaceAt, obstacleAt = null, x = 0, y = 0, z = 0, heading = 0, ...opts } = {}) {
+  const cfg = {
+    ...CAR_DEFAULTS, ...opts,
+    body: { ...CAR_DEFAULTS.body, ...(opts.body ?? {}) },
+    suspension: { ...CAR_DEFAULTS.suspension, ...(opts.suspension ?? {}) },
+    engine: { ...CAR_DEFAULTS.engine, ...(opts.engine ?? {}) },
+    brakes: { ...CAR_DEFAULTS.brakes, ...(opts.brakes ?? {}) },
+    grip: { ...CAR_DEFAULTS.grip, ...(opts.grip ?? {}) },
+  };
+  const halfL = cfg.wheelbase / 2, halfT = cfg.track / 2;
+
+  // wheel order: front-left, front-right, rear-left, rear-right
+  const CORNERS = [
+    { id: 'fl', along: halfL, across: -halfT, front: true },
+    { id: 'fr', along: halfL, across: halfT, front: true },
+    { id: 'rl', along: -halfL, across: -halfT, front: false },
+    { id: 'rr', along: -halfL, across: halfT, front: false },
+  ];
+
+  // seat the car ON the ground it was placed over, so it never starts by falling into place
+  const seatY = surfaceAt?.(x, z, y);
+  const car = {
+    cfg,
+    // cfg, NOT CAR_DEFAULTS. Every later frame uses cfg.rideHeight, so spawning from the
+    // default drops a vehicle with a custom one at the wrong height and pops it up on the
+    // first update — a tank at 0.9 starts 0.56 m low and jumps.
+    pos: { x, y: (seatY ?? y) + cfg.rideHeight, z },
+    heading,                 // where the car POINTS
+    travel: heading,         // where it is actually GOING — the two differ when it slides
+    speed: 0,
+    vy: 0,
+    airborne: false,
+    pitch: 0,
+    roll: 0,
+    slip: 0,
+    steer: 0,
+    spin: 0,                 // wheel rotation, radians
+    wheels: CORNERS.map((c) => ({ ...c, compression: 0, grounded: true, contactY: y })),
+
+    // where each wheel sits in world space right now
+    wheelPoints() {
+      const s = Math.sin(car.heading), c = Math.cos(car.heading);
+      return car.wheels.map((w) => ({
+        wheel: w,
+        x: car.pos.x + s * w.along - c * w.across,
+        z: car.pos.z + c * w.along + s * w.across,
+      }));
+    },
+
+    // the body's pose, for whatever is drawing it
+    pose() {
+      return {
+        x: car.pos.x, y: car.pos.y, z: car.pos.z,
+        heading: car.heading, pitch: car.pitch, roll: car.roll,
+      };
+    },
+
+    update(dt, input = {}) {
+      const { throttle = 0, brake = false, handbrake = false, steer = 0 } = input;
+      const { engine, brakes, grip, suspension } = cfg;
+      dt = Math.min(dt, 0.05);
+
+      // ── engine, brakes, drag ──
+      if (throttle > 0) {
+        const pull = Math.min(engine.traction, engine.power / Math.max(Math.abs(car.speed), 3));
+        car.speed += throttle * pull * dt;
+      } else if (throttle < 0) {
+        car.speed += throttle * engine.traction * 1.3 * dt;      // reverse, and engine braking
+      }
+      if (brake) {
+        // a brake stops you; it does not reverse you
+        const b = brakes.force * dt;
+        car.speed = Math.abs(car.speed) <= b ? 0 : car.speed - Math.sign(car.speed) * b;
+      }
+      if (handbrake) car.speed -= Math.sign(car.speed) * brakes.handbrake * dt;
+      const resist = (engine.rollingResistance + engine.airDrag * car.speed * car.speed) * dt;
+      car.speed = Math.abs(car.speed) <= resist ? 0 : car.speed - Math.sign(car.speed) * resist;
+      car.speed = clamp(car.speed, -engine.reverseSpeed, engine.topSpeed);
+
+      // ── steering, and the slide it can provoke ──
+      const authority = Math.min(1, Math.abs(car.speed) / grip.steerBite) * Math.sign(car.speed || 1);
+      car.heading += steer * dt * (handbrake ? grip.steerHandbrake : grip.steerRate) * authority;
+      const g = handbrake ? grip.handbrake : grip.normal;
+      car.slip = wrapPi(car.heading - car.travel);
+      car.travel += car.slip * Math.min(1, g * dt);
+
+      // ── travel across the ground ──
+      const fx = Math.sin(car.travel), fz = Math.cos(car.travel);
+      const step = { x: fx * car.speed * dt, z: fz * car.speed * dt };
+      const next = { x: car.pos.x + step.x, z: car.pos.z + step.z };
+
+      // ── each wheel finds its own ground ──
+      const sh = Math.sin(car.heading), ch = Math.cos(car.heading);
+      let sum = 0, grounded = 0;
+      const contacts = car.wheels.map((w) => {
+        const wx = next.x + sh * w.along - ch * w.across;
+        const wz = next.z + ch * w.along + sh * w.across;
+        let y = surfaceAt(wx, wz, car.pos.y);
+        // A WHEEL CANNOT CLIMB A GUARDRAIL — but the test must be against where the CAR is
+        // now, not where this wheel last touched. Measured against a stale per-wheel value,
+        // a single missed contact on a ramp (a seam between two deck meshes, say) leaves the
+        // wheel's memory metres below the road, and every real contact after that looks like
+        // an unclimbable wall: the car can never get back onto the ramp it is driving up.
+        // And while airborne there is no limit at all — you may land on anything.
+        const wheelLevel = car.pos.y - cfg.rideHeight;
+        if (!car.airborne && y != null && y > wheelLevel + cfg.maxStep) y = null;
+        w.grounded = y != null;
+        if (y != null) { sum += y; grounded++; w.contactY = y; }
+        return y ?? w.contactY;
+      });
+      // NOTHING UNDER ANY WHEEL means falling, not hovering. Holding the car at its current
+      // height when every wheel misses leaves it hanging in mid-air indefinitely.
+      if (!grounded) car.airborne = true;
+      const targetY = (grounded ? sum / grounded : -Infinity) + cfg.rideHeight;
+
+      // ── airborne or held down ──
+      // NOT a fixed threshold: while the wheels are down the ground dictates our vertical
+      // speed, and only when it falls away faster than gravity could take us — by a real
+      // margin, or contact noise alone will do it — do the wheels have nothing to push on.
+      const rate = grounded ? clamp((targetY - car.pos.y) / Math.max(dt, 1e-4), -30, 30) : -30;
+      // vy follows the surface rate rather than being set to it: a single settling frame
+      // (a car created below its ride height, a wheel finding a new deck) otherwise leaves a
+      // large stale value in vy, and every frame after that reads as a launch.
+      if (!car.airborne && rate < car.vy - G * dt - cfg.launchMargin) car.airborne = true;
+      else if (!car.airborne) car.vy += (rate - car.vy) * Math.min(1, 20 * dt);
+
+      car.pos.x = next.x;
+      car.pos.z = next.z;
+      if (car.airborne) {
+        car.vy -= G * dt;
+        car.pos.y += car.vy * dt;
+        if (car.pos.y <= targetY) {
+          const hit = car.vy;
+          car.pos.y = targetY;
+          car.vy = 0;
+          car.airborne = false;
+          if (hit < -cfg.landingHit) car.speed *= 0.93;   // only a real drop costs you
+        }
+      } else {
+        car.pos.y = targetY;
+      }
+
+      // ── suspension: each wheel's compression, and the lean that comes out of it ──
+      for (let i = 0; i < car.wheels.length; i++) {
+        const w = car.wheels[i];
+        const rest = car.pos.y - cfg.rideHeight;
+        const want = clamp(rest - contacts[i], -suspension.travel, suspension.travel);
+        w.compression += (want - w.compression) * Math.min(1, suspension.damping * dt);
+      }
+      // LEAN ONLY FROM WHEELS THAT ARE ACTUALLY ON SOMETHING. A wheel over an edge keeps the
+      // last height it touched, and averaging that stale value in tips the car onto a
+      // permanent angle it can never recover from — the body ends up leaning at rest.
+      const mean = (a, b) => {
+        const A = car.wheels[a], B = car.wheels[b];
+        if (A.grounded && B.grounded) return (A.contactY + B.contactY) / 2;
+        if (A.grounded) return A.contactY;
+        if (B.grounded) return B.contactY;
+        return null;
+      };
+      const f = mean(0, 1), r = mean(2, 3), l = mean(0, 2), rt = mean(1, 3);
+      const targetPitch = car.airborne || f == null || r == null
+        ? Math.atan2(car.vy, Math.max(Math.abs(car.speed), 4))
+        : Math.atan2(f - r, cfg.wheelbase);
+      const targetRoll = car.airborne || l == null || rt == null ? 0 : Math.atan2(l - rt, cfg.track);
+      const k = Math.min(1, dt * (car.airborne ? 2 : 9));
+      // whatever the ground says, a car does not lie on its side. A cap here means no
+      // contact reading, however odd, can ever leave the body at an impossible angle.
+      car.pitch = clamp(car.pitch + (targetPitch - car.pitch) * k, -cfg.maxLean, cfg.maxLean);
+      car.roll = clamp(car.roll + (targetRoll - car.roll) * k, -cfg.maxLean, cfg.maxLean);
+
+      // ── what is standing in the road ──
+      if (obstacleAt) resolveObstacles(car, dt, obstacleAt);
+
+      // ── the wheels themselves ──
+      car.spin -= (car.speed * dt) / cfg.wheelRadius * (handbrake ? 0.15 : 1);
+      car.steer += (steer * 0.5 - car.steer) * Math.min(1, dt * 8);
+      return car;
+    },
+  };
+  return car;
+}

package/src/vehicle/carAudio.js

@@ -0,0 +1,124 @@
+// CAR AUDIO — the engine you hear is four loops and a crossfade.
+//
+// The classic arrangement, and the one Kiwi used: acceleration and deceleration recorded at
+// low and high revs. Load rises with throttle, revs rise with speed, and the four are mixed
+// so that pulling away sounds like pulling away and lifting off sounds like lifting off.
+// Playback rate stretches each loop between its samples so the pitch tracks the revs
+// continuously rather than in steps.
+//
+//   const audio = createCarAudio({ listener, clips });   // clips: AudioBuffers
+//   audio.update(dt, { speed, topSpeed, throttle, slip, airborne });
+//
+// A game supplies the buffers, because a game owns its content. Everything here is Web Audio:
+// no three.js, so it can be tested and reasoned about on its own.
+
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+
+export const CAR_AUDIO_DEFAULTS = {
+  idleRevs: 0.12,           // revs at a standstill — an engine is never silent
+  revSmoothing: 4,          // how fast the revs chase the wheels (per second)
+  loadSmoothing: 6,         // ...and how fast the engine loads up under throttle
+  pitchLow: 0.75,           // playback rate for a clip at the bottom of its range
+  pitchHigh: 1.55,          // ...and at the top
+  crossover: 0.55,          // revs at which the high clips take over from the low
+  crossWidth: 0.28,         // how broad that handover is
+  skidSlip: 0.28,           // radians of slide before the tyres start to protest
+  masterGain: 0.8,
+};
+
+export function createCarAudio({ context, destination, clips = {}, ...opts } = {}) {
+  const cfg = { ...CAR_AUDIO_DEFAULTS, ...opts };
+  const ctx = context ?? new (globalThis.AudioContext ?? globalThis.webkitAudioContext)();
+  const out = ctx.createGain();
+  out.gain.value = cfg.masterGain;
+  out.connect(destination ?? ctx.destination);
+
+  // one looping voice per clip; they all run all the time and are mixed by gain, because
+  // starting and stopping sources is what makes engine audio stutter
+  const voice = (buffer) => {
+    if (!buffer) return null;
+    const src = ctx.createBufferSource();
+    const gain = ctx.createGain();
+    src.buffer = buffer;
+    src.loop = true;
+    gain.gain.value = 0;
+    src.connect(gain).connect(out);
+    src.start();
+    return { src, gain };
+  };
+  const voices = {
+    accelLow: voice(clips.accelLow),
+    accelHigh: voice(clips.accelHigh),
+    decelLow: voice(clips.decelLow),
+    decelHigh: voice(clips.decelHigh),
+    skid: voice(clips.skid),
+  };
+
+  const state = { revs: cfg.idleRevs, load: 0 };
+
+  const set = (v, value, dt) => {
+    if (!v) return;
+    // ramp rather than assign: a stepped gain is an audible click at 60 fps
+    v.gain.gain.setTargetAtTime(value, ctx.currentTime, Math.max(dt, 0.02));
+  };
+
+  return {
+    context: ctx,
+    state,
+
+    update(dt, { speed = 0, topSpeed = 55, throttle = 0, slip = 0, airborne = false } = {}) {
+      const wheelRevs = clamp01(Math.abs(speed) / Math.max(topSpeed, 1e-3));
+      // revs chase the wheels but never fall to silence, and a car in the air revs freely
+      const targetRevs = airborne ? Math.max(wheelRevs, 0.7) : Math.max(wheelRevs, cfg.idleRevs);
+      state.revs += (targetRevs - state.revs) * Math.min(1, cfg.revSmoothing * dt);
+      state.load += (clamp01(throttle) - state.load) * Math.min(1, cfg.loadSmoothing * dt);
+
+      // low clips hand over to high across a band, so there is no seam at one rev value
+      const high = clamp01((state.revs - cfg.crossover) / cfg.crossWidth + 0.5);
+      const low = 1 - high;
+      const onPower = state.load;                 // accelerating vs coasting
+      const rate = cfg.pitchLow + (cfg.pitchHigh - cfg.pitchLow) * state.revs;
+      for (const v of Object.values(voices)) {
+        if (v && v !== voices.skid) v.src.playbackRate.setTargetAtTime(rate, ctx.currentTime, 0.05);
+      }
+      set(voices.accelLow, low * onPower, dt);
+      set(voices.accelHigh, high * onPower, dt);
+      set(voices.decelLow, low * (1 - onPower), dt);
+      set(voices.decelHigh, high * (1 - onPower), dt);
+
+      // tyres complain in proportion to how far the car is sliding, and not at all in the air
+      const squeal = airborne ? 0 : clamp01((Math.abs(slip) - cfg.skidSlip) / 0.6) * clamp01(Math.abs(speed) / 8);
+      set(voices.skid, squeal, dt);
+      return state;
+    },
+
+    // a one-shot, for the horn or a collision
+    play(buffer, gain = 1) {
+      if (!buffer) return;
+      const src = ctx.createBufferSource();
+      const g = ctx.createGain();
+      src.buffer = buffer;
+      g.gain.value = gain;
+      src.connect(g).connect(out);
+      src.start();
+    },
+
+    stop() {
+      for (const v of Object.values(voices)) v?.src.stop();
+    },
+  };
+}
+
+// Load a set of clips by URL. Returns whatever decoded, so a missing file silences one voice
+// instead of taking the whole car with it.
+export async function loadCarClips(context, urls = {}) {
+  const clips = {};
+  await Promise.all(Object.entries(urls).map(async ([name, url]) => {
+    try {
+      const res = await fetch(url);
+      if (!res.ok) return;
+      clips[name] = await context.decodeAudioData(await res.arrayBuffer());
+    } catch { /* a car with no sound still drives */ }
+  }));
+  return clips;
+}