fix: make kart boost panels drivable and drift turbos reachable

中文：修复加速带及倾斜路面的碰撞分类，增加接触加速；调整漂移转向并修复低速起跳后无法进入漂移的问题，使用真实赛道验证自然充能及释放。

Author: functionstackx

docs/mario-kart.md

@@ -33,6 +33,11 @@ mini-turbo. Pressing accelerate just after the 2 in the countdown gives a rocket
 start; pressing too early burns out. Following close behind another racer
 builds a slipstream.
 
+The nine boost panels on the final banked bend give a one-second boost on
+contact. Banking is drivable terrain, not a vertical barrier. Drift steering
+uses speed-dependent handling so ordinary bends allow natural blue/orange
+charge; a low-speed hop held through acceleration can also enter a drift.
+
 Item boxes sit in three rows around the course. The roulette lands on an item
 weighted by position, as in the original: front runners mostly see bananas and
 green shells, back markers see stars, triple mushrooms, Golden Mushrooms, and

packages/app/public/decorative/kart/README.md

@@ -56,6 +56,11 @@ All archives were downloaded on 2026-10-05 from The Models Resource.
   boundary) plus ground height. Format: `KSRF` magic, then little-endian
   `x0, z0, res` (f32), `pad, width, height` (u32), `width*height` surface bytes,
   and `width*height` int16 heights in 1/32 units.
+- The bank and all nine boost strips are restored from the shipped course's
+  baked `polygon8` (MainRoad), `polygon1` (curb), and `polygon0`
+  (`ef_dushBoard`) triangles by `bun scripts/repair-kart-surface.ts` in
+  `packages/app`. Surface codes 7 and 8 identify drivable banking and boost
+  panels; steep vertical faces and higher structures remain blocked.
 - `circuit.webp` and `circuit-mobile.webp`: screenshots of the converted course
   in this app's renderer, without HUD.
 

packages/app/public/decorative/kart/luigi-circuit-surface.bin

@@ -0,0 +1,80 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseSurface, SURFACE } from '../src/components/kart/kart-surface';
+
+// The exported course has baked world-space vertices. polygon8 is MainRoad,
+// polygon1 is the curb, and polygon0 in the course (not sky) is ef_dushBoard.
+// Restore their drivable triangles instead of treating the bank as a wall.
+const directory = new URL('../public/decorative/kart/', import.meta.url);
+const gltf = JSON.parse(readFileSync(new URL('luigi-circuit.gltf', directory), 'utf8'));
+const buffers = gltf.buffers.map((b: { uri: string }) =>
+  Buffer.from(b.uri.split(',')[1], 'base64'),
+);
+const path = fileURLToPath(new URL('luigi-circuit-surface.bin', directory));
+const bytes = readFileSync(path);
+const map = parseSurface(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+const course = gltf.nodes[gltf.nodes[gltf.scenes[0].nodes[0]].children[0]];
+let changed = 0;
+for (const [name, type] of [
+  ['polygon8', SURFACE.road],
+  ['polygon1', SURFACE.curb],
+  ['polygon0', SURFACE.boost],
+] as const) {
+  const node = course.children
+    .map((i: number) => gltf.nodes[i])
+    .find((n: { name: string }) => n.name === name);
+  const primitive = gltf.meshes[node.mesh].primitives[0];
+  if (primitive.indices !== undefined) throw new Error('Expected non-indexed course mesh');
+  const accessor = gltf.accessors[primitive.attributes.POSITION];
+  const view = gltf.bufferViews[accessor.bufferView];
+  const data = buffers[view.buffer];
+  const vertex = (i: number) =>
+    [0, 1, 2].map((axis) =>
+      data.readFloatLE(
+        (view.byteOffset ?? 0) +
+          (accessor.byteOffset ?? 0) +
+          i * (view.byteStride ?? 12) +
+          axis * 4,
+      ),
+    );
+  for (let t = 0; t < accessor.count; t += 3) {
+    const [a, b, c] = [vertex(t), vertex(t + 1), vertex(t + 2)];
+    const den = (b[2] - c[2]) * (a[0] - c[0]) + (c[0] - b[0]) * (a[2] - c[2]);
+    if (Math.abs(den) < 1e-6) continue;
+    const gx = ((b[1] - a[1]) * (c[2] - a[2]) - (c[1] - a[1]) * (b[2] - a[2])) / den;
+    const gz = ((b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1])) / den;
+    const slope = Math.hypot(gx, gz);
+    if (slope > 1.15) continue; // Keep vertical rails and curb faces blocked.
+    const surface = type !== SURFACE.boost && slope > 0.25 ? SURFACE.bank : type;
+    const minI = Math.max(0, Math.floor((Math.min(a[0], b[0], c[0]) - map.x0) / map.res));
+    const maxI = Math.min(
+      map.width - 1,
+      Math.ceil((Math.max(a[0], b[0], c[0]) - map.x0) / map.res),
+    );
+    const minJ = Math.max(0, Math.floor((Math.min(a[2], b[2], c[2]) - map.z0) / map.res));
+    const maxJ = Math.min(
+      map.height - 1,
+      Math.ceil((Math.max(a[2], b[2], c[2]) - map.z0) / map.res),
+    );
+    for (let j = minJ; j <= maxJ; j++)
+      for (let i = minI; i <= maxI; i++) {
+        const x = map.x0 + (i + 0.5) * map.res,
+          z = map.z0 + (j + 0.5) * map.res;
+        const u = ((b[2] - c[2]) * (x - c[0]) + (c[0] - b[0]) * (z - c[2])) / den;
+        const v = ((c[2] - a[2]) * (x - c[0]) + (a[0] - c[0]) * (z - c[2])) / den;
+        if (u < -1e-5 || v < -1e-5 || u + v > 1.00001) continue;
+        const y = u * a[1] + v * b[1] + (1 - u - v) * c[1];
+        const index = j * map.width + i;
+        // Do not punch through a higher structure covering the road.
+        if (map.y[index] / 32 > y + 0.5) continue;
+        if (type !== SURFACE.boost && map.type[index] === SURFACE.boost) continue;
+        if (map.type[index] !== surface || map.y[index] !== Math.round(y * 32)) changed++;
+        map.type[index] = surface;
+        map.y[index] = Math.round(y * 32);
+      }
+  }
+}
+Buffer.from(map.type).copy(bytes, 28);
+for (let i = 0; i < map.y.length; i++) bytes.writeInt16LE(map.y[i], 28 + map.type.length + i * 2);
+writeFileSync(path, bytes);
+console.log(`Updated ${changed} drivable surface samples.`);

packages/app/scripts/repair-kart-surface.ts

@@ -18,7 +18,7 @@ import {
   type Race,
 } from './kart-engine';
 import { heightAt, parseSurface, SURFACE, surfaceAt } from './kart-surface';
-import { pointAt as trackPoint, wrapAngle } from './kart-track';
+import { nearest, pointAt as trackPoint, wrapAngle } from './kart-track';
 
 const bin = readFileSync(
   path.resolve(import.meta.dirname, '../../../public/decorative/kart/luigi-circuit-surface.bin'),
@@ -153,23 +153,117 @@ describe('kart engine', () => {
     expect(race.player.speed).toBeLessThan(0);
   });
 
-  it('drifting charges blue then orange sparks and releases a mini-turbo', () => {
+  it.each([
+    [200, 'right', 1, 1],
+    [200, 'right', 2, 1.7],
+    [400, 'left', 1, 1],
+  ] as const)(
+    'drifts from %s to the %s and naturally earns stage %s',
+    (distance, direction, stage, seconds) => {
+      const race = solo(distance);
+      race.karts = [race.player];
+      race.player.speed = 60;
+      for (let i = 0; i < Math.round(seconds / STEP); i++) {
+        stepRace(race, { ...EMPTY_CONTROLS, throttle: true, drift: true, [direction]: true }, STEP);
+        expect(race.events.some((e) => e.type === 'wall')).toBe(false);
+        race.events.length = 0;
+      }
+      expect(race.player.driftStage).toBe(stage);
+      const speed = race.player.speed;
+      stepRace(race, { ...EMPTY_CONTROLS, throttle: true }, STEP);
+      expect(race.events).toContainEqual({
+        type: 'mini-turbo',
+        kart: race.player.index,
+        value: stage,
+      });
+      expect(race.player.driftDir).toBe(0);
+      expect(race.player.driftCharge).toBe(0);
+      expect(race.player.boost).toBeCloseTo(stage === 2 ? 1.25 : 0.7);
+      run(race, { throttle: true }, 0.1);
+      expect(race.player.speed).toBeGreaterThan(speed + 2);
+    },
+  );
+
+  it('starts a held drift after accelerating out of a low-speed hop', () => {
+    const race = solo(190);
+    race.karts = [race.player];
+    race.player.speed = 11;
+    run(race, { drift: true }, 0.5);
+    expect(race.player.grounded).toBe(true);
+    expect(race.player.driftDir).toBe(0);
+    run(race, { throttle: true, drift: true, right: true }, 0.7);
+    expect(race.player.driftDir).toBe(-1);
+    expect(race.player.driftCharge).toBeGreaterThan(0);
+  });
+
+  it('does not reward an uncharged drift or a spin-out with a mini-turbo', () => {
+    for (const spin of [false, true]) {
+      const race = solo(200);
+      race.karts = [race.player];
+      race.player.speed = 60;
+      run(race, { throttle: true, drift: true, right: true }, spin ? 1 : 0.3);
+      expect(race.player.driftStage).toBe(spin ? 1 : 0);
+      if (spin) race.player.spin = 1;
+      stepRace(race, { ...EMPTY_CONTROLS, throttle: true }, STEP);
+      expect(race.player.boost).toBe(0);
+      expect(race.events.some((e) => e.type === 'mini-turbo')).toBe(false);
+    }
+  });
+
+  it('does not activate a boost strip while flying above it', () => {
     const race = solo();
-    run(race, { throttle: true }, 1.5);
-    run(race, { throttle: true, drift: true, left: true }, 0.3);
-    expect(race.player.driftDir).toBe(1);
-    run(race, { throttle: true, drift: true, left: true }, 0.5);
-    expect(race.player.driftStage).toBe(0);
-    expect(race.player.driftCharge).toBeGreaterThan(0.5);
-    // Skip ahead in the charge rather than circling into the wall on a straight.
-    race.player.driftCharge = 1.1;
-    run(race, { throttle: true, drift: true, left: true }, 0.1);
-    expect(race.player.driftStage).toBe(1);
-    race.player.driftCharge = 2.05;
-    run(race, { throttle: true, drift: true, left: true }, 0.15);
-    expect(race.player.driftStage).toBe(2);
-    run(race, { throttle: true }, STEP);
-    expect(race.player.boost).toBeGreaterThan(0);
+    race.karts = [race.player];
+    Object.assign(race.player, {
+      x: -125.13,
+      z: 511.65,
+      y: 30,
+      speed: 60,
+      grounded: false,
+    });
+    stepRace(race, { ...EMPTY_CONTROLS, throttle: true }, STEP);
+    expect(race.player.boost).toBe(0);
+    expect(race.player.boostPanelContact).toBe(false);
+  });
+
+  // Centers of all nine ef_dushBoard strips in the shipped course mesh.
+  it.each([
+    [-157.58, 505.58],
+    [-185.15, 488.04],
+    [-203.74, 462.55],
+    [-125.13, 511.65],
+    [-92.65, 505.64],
+    [-65.04, 488.15],
+    [-39.95, 439.66],
+    [-46.41, 462.68],
+    [-210.19, 439.41],
+  ])('drives through boost strip at (%s, %s) without a wall impact', (x, z) => {
+    const race = solo();
+    race.karts = [race.player];
+    expect(surfaceAt(surface, x, z)).toBe(SURFACE.boost);
+    const n = nearest(x, z);
+    Object.assign(race.player, {
+      x: x - n.tx * 9,
+      z: z - n.tz * 9,
+      heading: Math.atan2(n.tx, n.tz),
+      speed: 60,
+    });
+    race.player.y = heightAt(surface, race.player.x, race.player.z);
+    let boosts = 0;
+    for (let i = 0; i < 15; i++) {
+      stepRace(race, { ...EMPTY_CONTROLS, throttle: true }, STEP);
+      expect(race.events.some((e) => e.type === 'wall')).toBe(false);
+      boosts += race.events.filter((e) => e.type === 'boost').length;
+      race.events.length = 0;
+    }
+    expect(boosts).toBe(1);
+    expect(race.player.speed).toBeGreaterThan(70);
+    expect((race.player.x - x) * n.tx + (race.player.z - z) * n.tz).toBeGreaterThan(5);
+    // Moving to ordinary road must let the boost expire, not refresh it forever.
+    const p = pointAt(10);
+    Object.assign(race.player, { x: p.x, z: p.z, y: p.y, heading: p.heading });
+    run(race, { throttle: true }, 1.2);
+    expect(race.player.boost).toBe(0);
+    expect(race.player.boostPanelContact).toBe(false);
   });
 
   it('rocket start rewards timing and burns out when early', () => {

packages/app/src/components/kart/kart-engine.test.ts

@@ -132,6 +132,7 @@ export interface Kart {
   driftStage: 0 | 1 | 2;
   boost: number;
   boostPower: number;
+  boostPanelContact: boolean;
   draft: number;
   spin: number;
   tumble: number;
@@ -317,6 +318,7 @@ export function newRace(options: RaceOptions = {}): Race {
       driftStage: 0,
       boost: 0,
       boostPower: 1,
+      boostPanelContact: false,
       draft: 0,
       spin: 0,
       tumble: 0,
@@ -404,18 +406,26 @@ export const isStunned = (k: Kart) => k.spin > 0 || k.tumble > 0 || k.respawn >
 // ---------------------------------------------------------------------------
 // Simulation
 // ---------------------------------------------------------------------------
-const blocked = (race: Race, k: { y: number }, x: number, z: number) => {
+const blocked = (race: Race, k: { x: number; y: number; z: number }, x: number, z: number) => {
   const s = surfaceAt(race.surface, x, z);
   if (s === SURFACE.wall || s === SURFACE.none) return true;
   // Barrier rails and building ledges register as floors that are too tall to climb.
-  return heightAt(race.surface, x, z) - k.y > 1.6;
+  const allowance =
+    s === SURFACE.bank || s === SURFACE.boost ? 1.6 + Math.hypot(x - k.x, z - k.z) * 1.15 : 1.6;
+  return heightAt(race.surface, x, z) - k.y > allowance;
 };
 const RING = Array.from({ length: 10 }, (_, i) => [
   Math.cos((i / 10) * Math.PI * 2),
   Math.sin((i / 10) * Math.PI * 2),
 ]);
 /** Returns an outward wall normal if a circle at (x, z) overlaps blocked terrain. */
-function wallNormal(race: Race, k: { y: number }, x: number, z: number, r: number) {
+function wallNormal(
+  race: Race,
+  k: { x: number; y: number; z: number },
+  x: number,
+  z: number,
+  r: number,
+) {
   let nx = 0;
   let nz = 0;
   let hit = false;
@@ -877,15 +887,21 @@ function stepKart(race: Race, k: Kart, input: Controls, dt: number) {
     k.driftArmed = true;
   }
   if (!driftHeld) k.driftArmed = false;
-  if (k.hop > 0) {
-    k.hop -= dt;
-    if (driftHeld && Math.abs(k.steer) > 0.3 && k.driftDir === 0 && k.speed > 22)
-      k.driftDir = k.steer > 0 ? 1 : -1;
-  }
+  if (k.hop > 0) k.hop -= dt;
+  // A hop started below drift speed stays armed while held. Otherwise the player
+  // can accelerate through the threshold but never start drifting until re-pressing.
+  if (
+    driftHeld &&
+    (k.hop > 0 || (k.driftArmed && k.grounded)) &&
+    Math.abs(k.steer) > 0.3 &&
+    k.driftDir === 0 &&
+    k.speed > 22
+  )
+    k.driftDir = k.steer > 0 ? 1 : -1;
   if (k.driftDir !== 0) {
     if (!driftHeld || k.speed < 18 || stunned || surf === SURFACE.water) {
       // Release: mini-turbo.
-      if (!stunned && driftHeld === false && k.driftStage > 0) {
+      if (!stunned && !driftHeld && k.driftStage > 0 && k.speed >= 18 && surf !== SURFACE.water) {
         const stage = k.driftStage;
         giveBoost(k, stage === 2 ? 1.25 : 0.7, stage === 2 ? 1.3 : 1.22);
         race.events.push({ type: 'mini-turbo', kart: k.index, value: stage });
@@ -907,7 +923,8 @@ function stepKart(race: Race, k: Kart, input: Controls, dt: number) {
   let yaw =
     k.driftDir === 0
       ? k.steer * s.handling * speedFactor * Math.sign(k.speed || 1) * (k.grounded ? 1 : 0.6)
-      : k.driftDir * s.handling * (0.72 + 0.48 * k.steer * k.driftDir) * Math.min(1, k.speed / 24);
+      : // Keep the same speed-dependent steering envelope as normal driving.
+        k.driftDir * s.handling * (0.55 + 0.45 * k.steer * k.driftDir) * speedFactor;
   if (k.spin > 0) yaw = 0;
   if (k.tumble > 0) yaw *= 0.2;
   yaw *= grip;
@@ -1004,7 +1021,14 @@ function stepKart(race: Race, k: Kart, input: Controls, dt: number) {
         k.driftDir = k.steer > 0 ? 1 : -1;
     }
   }
-  if (surfaceAt(race.surface, k.x, k.z) === SURFACE.water && k.grounded) {
+  const landedSurface = surfaceAt(race.surface, k.x, k.z);
+  const onPanel = landedSurface === SURFACE.boost && k.grounded;
+  if (onPanel && !k.boostPanelContact && !stunned && !finished) {
+    giveBoost(k, 1, 1.35);
+    race.events.push({ type: 'boost', kart: k.index });
+  }
+  k.boostPanelContact = onPanel;
+  if (landedSurface === SURFACE.water && k.grounded) {
     k.respawn = 1.8;
     k.trailing = false;
     k.driftDir = 0;

packages/app/src/components/kart/kart-engine.ts

@@ -13,6 +13,8 @@ export const SURFACE = {
   water: 4,
   wall: 5,
   curb: 6,
+  bank: 7,
+  boost: 8,
 } as const;
 export type SurfaceType = (typeof SURFACE)[keyof typeof SURFACE];