Build: The Test Ride

The whole file after this topic. If yours differs, you can copy this one and carry on.

import * as THREE from "three";

const STEP = 1 / 60; // physics always steps by 1/60 s (Topic 16.2)
const PEDAL_FORCE = 30; // newtons at the wheel: an easy pedal for a 20 kg bike (the rider is left out)
const ROLLING_DAMPING = 0.3; // linear damping while rolling: top speed = force / (mass × damping) = 30 / (20 × 0.3) = 5 m/s
const BRAKE_DAMPING = 4; // linear damping while braking
const MAX_CATCH_UP = 0.25; // seconds: never try to simulate more than this after a stall

/**
 * Phase 16: the test ride. Rapier is loaded only when the visitor starts a ride (import() keeps it out of the first
 * download). The bike is one rigid body: a box for the frame and two balls for the wheels. It may pitch over the ramp
 * (rotation round z) but not roll or steer. Its pose is copied to `root` (the loaded model) after every step.
 */
export async function createTestRide({ root, bike, scene, camera, controls }) {
  const { default: RAPIER } = await import("@dimforge/rapier3d-compat");
  await RAPIER.init();
  const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
  world.timestep = STEP;

  // the track: a long strip of floor along +x (its top at y = 0, like the stand) and a low ramp 7 m out
  const track = new THREE.Group();
  track.name = "track";
  const grey = new THREE.MeshStandardMaterial({ color: "#3a4250", roughness: 0.9 });
  const strip = new THREE.Mesh(new THREE.BoxGeometry(40, 0.02, 1.6), grey);
  strip.position.set(18, -0.011, 0);
  const ramp = new THREE.Mesh(new THREE.BoxGeometry(1.6, 0.04, 1.2), grey);
  ramp.position.set(7, 0.07, 0); // its low edge sits just below the floor, so a wheel rolls on without a lip
  ramp.rotation.z = 0.12; // about 7 degrees
  track.add(strip, ramp);
  scene.add(track);
  world.createCollider(RAPIER.ColliderDesc.cuboid(20, 0.1, 3).setTranslation(18, -0.1, 0));
  world.createCollider(RAPIER.ColliderDesc.cuboid(0.8, 0.02, 0.6).setTranslation(7, 0.07, 0).setRotation(new THREE.Quaternion().setFromEuler(ramp.rotation)));

  const start = root.position.clone();
  const body = world.createRigidBody(
    RAPIER.RigidBodyDesc.dynamic().setTranslation(start.x, start.y, start.z).setLinearDamping(ROLLING_DAMPING).setAngularDamping(0.5).enabledRotations(false, false, true),
  );
  // colliders in the bike's own space (metres, Phase 4's geometry): low, heavy frame; frictionless wheels that "roll"
  world.createCollider(RAPIER.ColliderDesc.cuboid(0.45, 0.12, 0.08).setTranslation(0, 0.55, 0).setDensity(450), body); // about 15.6 kg
  for (const x of [-0.55, 0.58]) world.createCollider(RAPIER.ColliderDesc.ball(0.35).setTranslation(x, 0.35, 0).setFriction(0).setFrictionCombineRule(RAPIER.CoefficientCombineRule.Min).setDensity(13), body); // 2.3 kg each; Min: 0 wins over the floor's 0.5 (the default would average them to 0.25)

  const input = { pedal: false, brake: false };
  const before = new THREE.Vector3();
  let accumulator = 0, flippedFor = 0;

  function reset() {
    body.setTranslation(start, true);
    body.setRotation({ x: 0, y: 0, z: 0, w: 1 }, true);
    body.setLinvel({ x: 0, y: 0, z: 0 }, true);
    body.setAngvel({ x: 0, y: 0, z: 0 }, true);
    flippedFor = 0;
    sync();
  }
  function sync() {
    before.copy(root.position);
    const p = body.translation(), q = body.rotation();
    root.position.set(p.x, p.y, p.z);
    root.quaternion.set(q.x, q.y, q.z, q.w);
    // the follow camera: move the camera and its target by the bike's movement, so the view angle stays the same
    const moved = root.position.clone().sub(before);
    camera.position.add(moved);
    controls.orbit.target.add(moved);
  }
  /** One fixed physics step with the current input. Public, so tests can drive the ride without a clock. */
  function step() {
    body.resetForces(true);
    if (input.pedal) body.addForce({ x: PEDAL_FORCE, y: 0, z: 0 }, true);
    body.setLinearDamping(input.brake ? BRAKE_DAMPING : ROLLING_DAMPING);
    world.step();
    bike.userData.speed = body.linvel().x; // Phase 9's tick turns the wheels and the crank at this speed
    const up = new THREE.Vector3(0, 1, 0).applyQuaternion(root.quaternion);
    flippedFor = up.y < 0.3 || body.translation().y < -2 ? flippedFor + STEP : 0;
    if (flippedFor > 1) reset(); // on its side (or off the track) for a second: put it back
    sync();
  }

  return {
    input,
    body, // the Rapier body, for tests and tools
    step,
    reset,
    get speed() { return body.linvel().x; },
    get distance() { return body.translation().x - start.x; },
    tick(delta) {
      accumulator += Math.min(delta, MAX_CATCH_UP);
      while (accumulator >= STEP) { accumulator -= STEP; step(); }
    },
    end() {
      reset();
      scene.remove(track);
      track.traverse((o) => o.geometry?.dispose());
      grey.dispose();
      world.free(); // frees the WebAssembly memory of the whole world
      bike.userData.speed = 1.667; // back to Phase 9's gentle showroom speed
    },
  };
}