create-threenative 0.2.18 → 0.2.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/agent-docs/references/assertion-reference.md +1 -1
  2. package/agent-docs/references/capability-reference.md +792 -5
  3. package/agent-docs/references/kit-racing.md +4 -2
  4. package/agent-docs/references/performance-basics.md +2 -1
  5. package/agent-docs/references/terrain-authoring.md +25 -7
  6. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  7. package/dist/index.js +268 -237
  8. package/dist/quality.d.ts +5 -1
  9. package/dist/quality.js +75 -6
  10. package/dist/terrain-kit.js +1 -1
  11. package/dist/threenative.js +7 -5
  12. package/dist/web-engine-post-effects.js +6 -0
  13. package/dist/web-engine-runtime.js +407 -38
  14. package/package.json +6 -6
  15. package/template-assets/assets/floor-fern-0.glb +0 -0
  16. package/template-assets/assets/floor-litter-0.glb +0 -0
  17. package/template-assets/assets/floor-log-0.glb +0 -0
  18. package/template-assets/assets/floor-log-1.glb +0 -0
  19. package/template-assets/assets/floor-stump-0.glb +0 -0
  20. package/template-assets/assets/floor-twig-0.glb +0 -0
  21. package/template-assets/patches/three@0.187.0.patch +108 -21
  22. package/template-assets/quality/eslint.config.js +1 -1
  23. package/templates/action-rpg/package.json +7 -7
  24. package/templates/action-rpg/src/loot/drops.ts +3 -7
  25. package/templates/action-rpg/src/render/camera.ts +2 -2
  26. package/templates/action-rpg/src/render/clouds.ts +3 -1
  27. package/templates/action-rpg/src/render/materials.ts +3 -2
  28. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  29. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  30. package/templates/adventure/AGENTS.md +3 -3
  31. package/templates/adventure/CLAUDE.md +3 -3
  32. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  33. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  34. package/templates/adventure/package.json +7 -7
  35. package/templates/adventure/playtests/grass.playtest.json +61 -0
  36. package/templates/adventure/playtests/performance.playtest.json +1 -1
  37. package/templates/adventure/playtests/survives.playtest.json +2 -2
  38. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  39. package/templates/adventure/src/entities/LockOn.ts +42 -4
  40. package/templates/adventure/src/entities/Warden.ts +12 -3
  41. package/templates/adventure/src/level/Vale.ts +241 -16
  42. package/templates/adventure/src/render/camera.ts +2 -2
  43. package/templates/adventure/src/render/foliage.ts +64 -20
  44. package/templates/adventure/src/render/grass.ts +325 -0
  45. package/templates/adventure/src/render/materials.ts +3 -2
  46. package/templates/adventure/src/render/palette.ts +3 -0
  47. package/templates/adventure/src/render/touch-controls.ts +4 -1
  48. package/templates/adventure/src/scenes/Play.ts +96 -1
  49. package/templates/collectathon/package.json +7 -7
  50. package/templates/collectathon/src/level/Course.ts +2 -7
  51. package/templates/collectathon/src/level/terrain.ts +2 -1
  52. package/templates/collectathon/src/render/camera.ts +2 -2
  53. package/templates/collectathon/src/render/ground.ts +4 -4
  54. package/templates/collectathon/src/render/hero.ts +1 -1
  55. package/templates/collectathon/src/render/materials.ts +0 -1
  56. package/templates/collectathon/src/render/sky.ts +4 -3
  57. package/templates/kart/package.json +6 -6
  58. package/templates/kart/src/entities/Kart.ts +2 -1
  59. package/templates/kart/src/render/course.ts +2 -1
  60. package/templates/kart/src/track/Course.ts +3 -1
  61. package/templates/minimal/package.json +6 -6
  62. package/templates/minimal/src/render/camera.ts +2 -2
  63. package/templates/minimal/src/render/clouds.ts +3 -1
  64. package/templates/minimal/src/render/materials.ts +3 -2
  65. package/templates/minimal/src/render/touch-controls.ts +7 -6
  66. package/templates/platformer/package.json +7 -7
  67. package/templates/platformer/playtests/collect.playtest.json +4 -1
  68. package/templates/platformer/src/level/Stage.ts +2 -6
  69. package/templates/platformer/src/scenes/Play.ts +2 -1
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/puzzle/src/entities/Warden.ts +3 -3
  72. package/templates/puzzle/src/render/camera.ts +2 -2
  73. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  74. package/templates/racing/AGENTS.md +2 -2
  75. package/templates/racing/CLAUDE.md +2 -2
  76. package/templates/racing/CREDITS.md +29 -0
  77. package/templates/racing/assets/engine-loop.wav +0 -0
  78. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  79. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  80. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  81. package/templates/racing/assets/nitro-burst.wav +0 -0
  82. package/templates/racing/assets/tyre-squeal.wav +0 -0
  83. package/templates/racing/package.json +7 -7
  84. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  85. package/templates/racing/playtests/drift.playtest.json +100 -0
  86. package/templates/racing/playtests/hud.playtest.json +117 -0
  87. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  88. package/templates/racing/playtests/nitro.playtest.json +158 -0
  89. package/templates/racing/playtests/outcome.playtest.json +4 -4
  90. package/templates/racing/playtests/performance.playtest.json +1 -1
  91. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  92. package/templates/racing/src/audio/engine.ts +138 -0
  93. package/templates/racing/src/entities/CarBody.ts +83 -10
  94. package/templates/racing/src/entities/Drift.ts +243 -0
  95. package/templates/racing/src/entities/LineDriver.ts +2 -2
  96. package/templates/racing/src/entities/Nitro.ts +72 -0
  97. package/templates/racing/src/entities/RacingCar.ts +86 -21
  98. package/templates/racing/src/entities/Rival.ts +35 -21
  99. package/templates/racing/src/game.ts +6 -0
  100. package/templates/racing/src/gauges.ts +74 -0
  101. package/templates/racing/src/render/camera.ts +29 -4
  102. package/templates/racing/src/render/clouds.ts +3 -1
  103. package/templates/racing/src/render/effects.ts +244 -0
  104. package/templates/racing/src/render/materials.ts +43 -8
  105. package/templates/racing/src/render/shapes.ts +37 -0
  106. package/templates/racing/src/render/skids.ts +84 -0
  107. package/templates/racing/src/render/touch-controls.ts +10 -10
  108. package/templates/racing/src/scenes/Race.ts +277 -25
  109. package/templates/racing/src/state.ts +35 -0
  110. package/templates/racing/src/style.css +3 -0
  111. package/templates/racing/src/track/Ranking.ts +8 -4
  112. package/templates/racing/src/track/Track.ts +132 -58
  113. package/templates/racing/src/track/TrackSector.ts +19 -1
  114. package/templates/racing/src/track/circuit.ts +21 -15
  115. package/templates/racing/src/ui/GameUi.tsx +0 -2
  116. package/templates/racing/src/ui/Hud.tsx +417 -50
  117. package/templates/racing/threenative.config.ts +15 -0
  118. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  119. package/templates/rain/package.json +6 -6
  120. package/templates/rain/src/render/noise-volume.ts +2 -1
  121. package/templates/rain/src/state.ts +3 -1
  122. package/templates/rain/src/ui/GameUi.tsx +1 -1
  123. package/templates/rain/src/ui/automation.ts +10 -8
  124. package/templates/rain/src/ui/tempest.ts +3 -4
  125. package/templates/rts/package.json +6 -6
  126. package/templates/rts/src/sim/terrain.ts +1 -0
  127. package/templates/rts/src/sim/types.ts +1 -0
  128. package/templates/runner/package.json +7 -7
  129. package/templates/runner/src/render/clouds.ts +3 -1
  130. package/templates/runner/src/render/materials.ts +3 -2
  131. package/templates/runner/src/render/touch-controls.ts +7 -6
  132. package/templates/runner/src/scenes/Run.ts +4 -9
  133. package/templates/sailing/package.json +7 -7
  134. package/templates/sailing/src/render/touch-controls.ts +7 -6
  135. package/templates/shooter/package.json +7 -7
  136. package/templates/shooter/src/render/clouds.ts +3 -1
  137. package/templates/snow/package.json +7 -7
  138. package/templates/snow/src/entities/Explorer.ts +6 -12
  139. package/templates/snow/src/render/bootPrint.ts +3 -1
  140. package/templates/snow/src/render/camera.ts +3 -2
  141. package/templates/snow/src/render/scenery.ts +3 -3
  142. package/templates/snow/src/render/touch-controls.ts +7 -6
  143. package/templates/snow/src/render/weather.ts +3 -5
  144. package/templates/snow/src/terrain.ts +2 -1
  145. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  146. package/templates/starter/package.json +7 -7
  147. package/templates/starter/src/entities/Player.ts +10 -2
  148. package/templates/starter/src/render/camera.ts +2 -2
  149. package/templates/starter/src/render/clouds.ts +3 -1
  150. package/templates/starter/src/render/materials.ts +3 -2
  151. package/templates/starter/src/render/touch-controls.ts +7 -6
  152. package/templates/starter/src/scenes/Play.ts +1 -14
  153. package/templates/tower-defense/package.json +7 -7
  154. package/templates/tower-defense/src/render/shapes.ts +1 -2
  155. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  156. package/template-assets/terrain/alpine/assets.json +0 -12
  157. package/template-assets/terrain/alpine/bake.mjs +0 -6
  158. package/template-assets/terrain/alpine/credits.json +0 -164
  159. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  160. package/template-assets/terrain/alpine/recipe.json +0 -119
  161. package/template-assets/terrain/alpine/surface.json +0 -53
  162. package/template-assets/terrain/coastal/assets.json +0 -11
  163. package/template-assets/terrain/coastal/bake.mjs +0 -6
  164. package/template-assets/terrain/coastal/credits.json +0 -117
  165. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  166. package/template-assets/terrain/coastal/recipe.json +0 -113
  167. package/template-assets/terrain/coastal/surface.json +0 -41
  168. package/template-assets/terrain/desert/assets.json +0 -12
  169. package/template-assets/terrain/desert/bake.mjs +0 -6
  170. package/template-assets/terrain/desert/credits.json +0 -164
  171. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  172. package/template-assets/terrain/desert/recipe.json +0 -108
  173. package/template-assets/terrain/desert/surface.json +0 -54
  174. package/template-assets/terrain/forest/assets.json +0 -65
  175. package/template-assets/terrain/forest/bake.mjs +0 -8
  176. package/template-assets/terrain/forest/credits.json +0 -225
  177. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  178. package/template-assets/terrain/forest/recipe.json +0 -350
  179. package/template-assets/terrain/forest/surface.json +0 -79
  180. package/template-assets/terrain/tundra/assets.json +0 -12
  181. package/template-assets/terrain/tundra/bake.mjs +0 -6
  182. package/template-assets/terrain/tundra/credits.json +0 -164
  183. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  184. package/template-assets/terrain/tundra/recipe.json +0 -277
  185. package/template-assets/terrain/tundra/surface.json +0 -54
  186. package/templates/racing/src/ui/Menu.tsx +0 -7
@@ -0,0 +1,138 @@
1
+ import { AudioBus } from "@threenative/core";
2
+ import type { Audio, Object3D } from "three";
3
+
4
+ /**
5
+ * The race's sound: an engine bed that pitches with the revs, a tyre squeal that opens with the
6
+ * drift angle, and a nitro burst on the button press.
7
+ *
8
+ * Every clip is baked from maths by `tools/make-racing-audio.mjs` — an engine loop has to be
9
+ * tonal and exactly periodic to be pitched live, and a recording of a real engine is neither. The
10
+ * contested part of this file is the **pitch law**: `engineRate` is the single place the needle
11
+ * becomes a frequency, and the playtest asserts it rises with speed.
12
+ *
13
+ * One runtime gap, named rather than papered over. Pitch is a `playbackRate` write, and the native
14
+ * host binds `playbackRate` on an audio source as a *passive* parameter
15
+ * (`runtime-native/src/audio/audio_bindings.cpp` `createPassiveAudioParamJS`): the write lands and
16
+ * nothing moves, so on native the bed plays at rate 1 with the same volume, squeal and burst. That
17
+ * is a degraded engine note, not a silent game, and no part of this file claims otherwise.
18
+ */
19
+ export const ENGINE_SOUND = {
20
+ /** The bed's playback rate at a standstill and at the rev limit. */
21
+ idleRate: 0.62,
22
+ redlineRate: 2.05,
23
+ /** The bed's level with the throttle closed, and the extra it gains under a nitro burn. */
24
+ volume: 0.34,
25
+ nitroVolume: 0.62,
26
+ /** The squeal's level at full lock in a slide, and the slip angle that counts as full lock. */
27
+ squealVolume: 0.5,
28
+ squealAngle: 0.55,
29
+ /** The burst's level. */
30
+ burstVolume: 0.85,
31
+ /** Baked by `tools/make-racing-audio.mjs`, logical paths into `assets/`. */
32
+ clips: {
33
+ engine: "engine-loop.wav",
34
+ squeal: "tyre-squeal.wav",
35
+ nitro: "nitro-burst.wav",
36
+ },
37
+ } as const;
38
+
39
+ /** The bed's pitch for one needle reading, 0 to 1: geometric, because pitch is logarithmic. */
40
+ export function engineRate(rpm: number): number {
41
+ const reading = Math.min(1, Math.max(0, rpm));
42
+ return ENGINE_SOUND.idleRate * (ENGINE_SOUND.redlineRate / ENGINE_SOUND.idleRate) ** reading;
43
+ }
44
+
45
+ export interface IEngineAudioInput {
46
+ /** Whether the race is running sound at all: a pause or the outcome panel silences the car. */
47
+ readonly running: boolean;
48
+ /** The needle, 0 to 1, from `gauges.ts`. */
49
+ readonly rpm: number;
50
+ /** The rear slip in radians and whether a tyre is sliding this tick. */
51
+ readonly driftAngle: number;
52
+ readonly sliding: boolean;
53
+ readonly nitroActive: boolean;
54
+ }
55
+
56
+ /**
57
+ * The bus a pause intent mutes: one race sounds at a time, so there is one handle to reach.
58
+ *
59
+ * A muted mix rather than a stopped one. `bus.pause()` holds every voice where it stands and
60
+ * `resume()` starts it again, which is right for a menu bed and wrong for an engine: a paused
61
+ * race must not be audible, and the frame loop does not tick while paused, so nothing would
62
+ * unmute a stopped voice from inside the scene.
63
+ */
64
+ let sounding: EngineAudio | undefined;
65
+
66
+ export function setRaceAudioMuted(muted: boolean): void {
67
+ sounding?.bus.setVolume(muted ? 0 : 1, 0.15);
68
+ }
69
+
70
+ /**
71
+ * The car's own sound, over one `AudioBus`.
72
+ *
73
+ * `AudioBus` queues a cue played before the first gesture and starts it on the browser's unlock
74
+ * (`keydown`/`pointerdown`/`touchstart`, installed by the bus itself), so nothing here needs a
75
+ * "click to start" gate of its own.
76
+ */
77
+ export class EngineAudio {
78
+ readonly bus: AudioBus;
79
+ /** The rate last written to the bed. 0 until the clip has loaded: a claim needs a sound. */
80
+ rate = 0;
81
+ #engine: Audio | undefined;
82
+ #squeal: Audio | undefined;
83
+ #nitro: AudioBuffer | undefined;
84
+ #nitroWasActive = false;
85
+
86
+ constructor(camera: Object3D, load: (name: string) => Promise<AudioBuffer>) {
87
+ this.bus = new AudioBus({ camera });
88
+ sounding = this;
89
+ const start = (name: keyof typeof ENGINE_SOUND.clips, cue: string, volume: number): void => {
90
+ void load(ENGINE_SOUND.clips[name])
91
+ .then((buffer) => {
92
+ if (name === "nitro") {
93
+ this.#nitro = buffer;
94
+ return;
95
+ }
96
+ const voice = this.bus.play(buffer, { cue, loop: true, volume });
97
+ if (name === "engine") this.#engine = voice;
98
+ else this.#squeal = voice;
99
+ })
100
+ .catch((error: unknown) => {
101
+ // Sound is not the race. A missing clip is reported once, by name, and the rest plays.
102
+ console.warn(
103
+ `TN_RACING_AUDIO_MISSING ${name}: ${error instanceof Error ? error.message : String(error)}`,
104
+ );
105
+ });
106
+ };
107
+ start("engine", "engine", ENGINE_SOUND.volume);
108
+ start("squeal", "tyre-squeal", 0);
109
+ start("nitro", "nitro-burst", 0);
110
+ }
111
+
112
+ update(input: IEngineAudioInput): void {
113
+ const target = input.running ? engineRate(input.rpm) : ENGINE_SOUND.idleRate * 0.7;
114
+ if (this.#engine !== undefined && Math.abs(target - this.rate) > 0.004) {
115
+ this.#engine.setPlaybackRate(target);
116
+ this.rate = target;
117
+ }
118
+ // Three's own `setVolume` is a 10 ms `setTargetAtTime` ramp on the voice's gain, on every
119
+ // runtime: a step in a sounding loop is a click, and smoothing it twice only makes the swell
120
+ // late. The bed swells under a burn and settles back.
121
+ this.#engine?.setVolume(
122
+ input.running ? ENGINE_SOUND.volume + (input.nitroActive ? ENGINE_SOUND.nitroVolume : 0) : 0,
123
+ );
124
+ const squeal = input.running
125
+ ? Math.min(1, Math.abs(input.driftAngle) / ENGINE_SOUND.squealAngle) *
126
+ ENGINE_SOUND.squealVolume
127
+ : 0;
128
+ this.#squeal?.setVolume(squeal * (input.sliding ? 1 : 0));
129
+ if (input.nitroActive && !this.#nitroWasActive && input.running && this.#nitro !== undefined)
130
+ this.bus.play(this.#nitro, { cue: "nitro-burst", volume: ENGINE_SOUND.burstVolume });
131
+ this.#nitroWasActive = input.nitroActive;
132
+ }
133
+
134
+ dispose(): void {
135
+ if (sounding === this) sounding = undefined;
136
+ this.bus.dispose();
137
+ }
138
+ }
@@ -62,19 +62,27 @@ export const CAR = {
62
62
  * both cars on the circuit: the rival drives the same chassis with the same tyres, so it is a
63
63
  * driver, not a faster class of car.
64
64
  *
65
- * `topSpeed` is **reached, not clamped**. The engine force falls linearly to zero there, which is
66
- * a torque curve rather than a speed limit: the tyres, the suspension and the barriers all still
67
- * decide what happens, and a car that hits a wall at 17 m/s stops at the wall.
65
+ * `topSpeed` is **reached, not clamped**. The engine force holds flat, then falls to zero across
66
+ * the last {@link FEEL.torqueFade} of it ({@link driveForce}), which is a torque curve rather than
67
+ * a speed limit: the tyres, the suspension and the barriers all still decide what happens. A
68
+ * straight line to zero from a standstill made the car stop pulling at about 50 km/h.
68
69
  */
70
+ /** The engine force share at `speed` for a curve that reaches zero at `top`: 1, then down to 0. */
71
+ export function driveForce(speed: number, top: number): number {
72
+ return MathUtils.clamp((top - speed) / (top * FEEL.torqueFade), 0, 1);
73
+ }
74
+
69
75
  export const FEEL = {
70
76
  /** Newton's per driven wheel at zero speed. Two rear wheels, so this is half the push. */
71
77
  engineForce: 3400,
72
78
  /** Godot's `brake`: a braking impulse on every wheel, not a force. */
73
79
  brake: 60,
74
80
  /** Where the torque curve reaches zero, in m/s. */
75
- topSpeed: 17,
81
+ topSpeed: 26,
76
82
  /** The boost lifts the curve's zero point, so a boost genuinely raises the top speed. */
77
- boostTopSpeed: 23,
83
+ boostTopSpeed: 34,
84
+ /** The share of the top speed over which the engine force falls from full to zero. */
85
+ torqueFade: 0.35,
78
86
  /** And lifts the force behind it, so it arrives sooner as well as going further. */
79
87
  boostForce: 1.9,
80
88
  /** Holding back above this brakes; at or below it, reverse engages. */
@@ -129,6 +137,9 @@ export function noseRotation(yaw: number): number {
129
137
  }
130
138
 
131
139
  const DEG = Math.PI / 180;
140
+
141
+ /** How fast the measured load follows the tyres, per second: about a 0.17 s time constant. */
142
+ const LOAD_SMOOTHING = 6;
132
143
  const _box = new Box3();
133
144
  const _size = new Vector3();
134
145
  const _point = new Vector3();
@@ -180,6 +191,8 @@ export class CarBody {
180
191
  readonly chassis: Group;
181
192
  /** The leanable shell inside `chassis`, named `body` by `shapes.ts`. */
182
193
  readonly lean: Object3D;
194
+ /** The nitro flame behind the exhausts, named `nitro-flame` by `shapes.ts`. */
195
+ readonly flame: Object3D;
183
196
  /** The four wheel groups, in the same order as `body.wheels`. */
184
197
  readonly wheels: readonly Object3D[];
185
198
  /** The retained `normaliseToMetres` factor, which the playtest asserts is below one. */
@@ -192,10 +205,26 @@ export class CarBody {
192
205
  lateralLoad = 0;
193
206
  /** Forward acceleration in m/s²: positive under power, negative under braking. */
194
207
  longLoad = 0;
208
+ /** Bumped by every `teleport`, so a chase camera can cut instead of flying after the car. */
209
+ teleports = 0;
210
+ /** Speed over the ground in m/s. In a slide this is more than the forward `speed`. */
211
+ groundSpeed = 0;
212
+ /**
213
+ * The rear axle's slip angle in radians: + when the nose points right of where the tail is
214
+ * going, which is a right-hand slide. It is zero in a tight turn on full grip, where the whole
215
+ * car's heading still leads its velocity by the steering geometry alone, so it is the reading
216
+ * a drift is detected on.
217
+ */
218
+ rearSlip = 0;
219
+ #yaw = 0;
195
220
  #velocity = new Vector3();
196
221
  #last = new Vector3();
197
222
  #right = new Vector3();
198
223
  #delta = new Vector3();
224
+ #burn = 0;
225
+ #flicker = 0;
226
+ /** The rear axle's x in the chassis frame, in metres: negative, behind the centre of mass. */
227
+ #rearAxle = -WHEELBASE / 2;
199
228
 
200
229
  constructor(
201
230
  ctx: CarCtx,
@@ -215,6 +244,7 @@ export class CarBody {
215
244
  this.chassis = chassis;
216
245
  this.wheels = WHEEL_NAMES.map((name) => requireNamed(chassis, name));
217
246
  this.lean = requireNamed(chassis, "body");
247
+ this.flame = requireNamed(chassis, "nitro-flame");
218
248
  this.body = new VehicleBody3D({
219
249
  collisionLayer: CAR.collisionLayer,
220
250
  collisionMask: CAR.collisionMask,
@@ -240,6 +270,8 @@ export class CarBody {
240
270
  };
241
271
  }),
242
272
  });
273
+ this.#rearAxle = (this.body.wheels[2] as IVehicleWheel3D).position.x;
274
+ this.#yaw = options.yaw;
243
275
  }
244
276
 
245
277
  /** Godot's signed forward speed: positive while accelerating forward. */
@@ -286,8 +318,33 @@ export class CarBody {
286
318
  this.#delta.copy(this.#velocity).sub(this.#last);
287
319
  this.#last.copy(this.#velocity);
288
320
  const perSecond = dt > 0 ? 1 / dt : 60;
289
- this.lateralLoad = this.#delta.dot(this.#right) * perSecond;
290
- this.longLoad = this.#delta.dot(this.forward) * perSecond;
321
+ // The rear axle's own sideways speed: the chassis's, less what the yaw swings the tail by.
322
+ const yaw = Math.atan2(this.forward.z, this.forward.x);
323
+ const yawRate =
324
+ (MathUtils.euclideanModulo(yaw - this.#yaw + Math.PI, Math.PI * 2) - Math.PI) * perSecond;
325
+ this.#yaw = yaw;
326
+ this.groundSpeed = this.#velocity.length();
327
+ const along = this.#velocity.dot(this.forward);
328
+ const rearSide = this.#velocity.dot(this.#right) + yawRate * this.#rearAxle;
329
+ this.rearSlip = this.groundSpeed > 1 ? -Math.atan2(rearSide, Math.abs(along)) : 0;
330
+ // One tick's velocity change is the tyres' impulse for that tick, and the ray-cast vehicle's
331
+ // friction alternates from tick to tick: measured, the raw reading swung the full ±30 m/s² in
332
+ // one tick mid-corner, which flipped the lean ±5° and the camera bank ±3° every tick — the
333
+ // shake. The load a driver feels is the average over a few ticks, so it is low-passed here.
334
+ // A barrier hit is hundreds of m/s² for one tick; past the tyres' limit the lean is already
335
+ // full, so the reading is clamped there before it is averaged.
336
+ const lateral = MathUtils.clamp(
337
+ this.#delta.dot(this.#right) * perSecond,
338
+ -FEEL.lateral,
339
+ FEEL.lateral,
340
+ );
341
+ const long = MathUtils.clamp(
342
+ this.#delta.dot(this.forward) * perSecond,
343
+ -FEEL.lateral,
344
+ FEEL.lateral,
345
+ );
346
+ this.lateralLoad = MathUtils.damp(this.lateralLoad, lateral, LOAD_SMOOTHING, dt);
347
+ this.longLoad = MathUtils.damp(this.longLoad, long, LOAD_SMOOTHING, dt);
291
348
  }
292
349
 
293
350
  /**
@@ -300,24 +357,40 @@ export class CarBody {
300
357
  * across the struts at 1.2 g lateral) and there is no real body roll to read. Roll and dive are
301
358
  * functions of lateral and forward load; this is that function, with the car's own load as input.
302
359
  */
303
- settleVisuals(): void {
360
+ settleVisuals(nitro = false, dt = 1 / 60): void {
361
+ // The flame: on within a few ticks, off over a quarter of a second, and never the same
362
+ // length two ticks running.
363
+ this.#burn = MathUtils.damp(this.#burn, nitro ? 1 : 0, nitro ? 22 : 9, dt);
364
+ this.flame.visible = this.#burn > 0.02;
365
+ if (this.flame.visible) {
366
+ this.#flicker += dt * 47;
367
+ const pulse = 0.82 + 0.18 * Math.sin(this.#flicker) + 0.12 * Math.sin(this.#flicker * 2.7);
368
+ this.flame.scale.set(this.#burn * pulse, 0.85 + 0.15 * this.#burn, 0.85 + 0.15 * this.#burn);
369
+ }
304
370
  for (const [index, wheel] of this.wheels.entries()) {
305
371
  // Rolling forward turns the wheel about its own -z and Rapier's rotation runs the other way,
306
372
  // so the sign is inverted here; the front pair also takes the steer angle it was given.
307
373
  wheel.rotation.z = -this.body.wheelRotation(index);
308
374
  if (index < 2) wheel.rotation.y = this.body.steering;
309
375
  }
310
- this.lean.rotation.z =
311
- MathUtils.clamp(this.lateralLoad / FEEL.lateral, -1, 1) * FEEL.leanRoll * DEG;
376
+ // The nose is +x and the right side is +z, so roll turns about x and pitch about z. The body
377
+ // rolls away from the corner (load to the right tips the roof left) and squats under throttle.
312
378
  this.lean.rotation.x =
379
+ -MathUtils.clamp(this.lateralLoad / FEEL.lateral, -1, 1) * FEEL.leanRoll * DEG;
380
+ this.lean.rotation.z =
313
381
  MathUtils.clamp(this.longLoad / FEEL.lateral, -1, 1) * FEEL.leanPitch * DEG;
314
382
  }
315
383
 
316
384
  /** Godot's `VehicleBody3D.teleport`: move the chassis and face the heading `yaw`. */
317
385
  teleport(position: Pick<Vector3, "x" | "y" | "z">, yaw: number): void {
318
386
  this.body.teleport(position, noseRotation(yaw));
387
+ this.teleports += 1;
319
388
  this.#last.set(0, 0, 0);
389
+ this.lateralLoad = 0;
390
+ this.longLoad = 0;
391
+ this.#yaw = yaw;
320
392
  this.measure(1 / 60);
393
+ this.rearSlip = 0;
321
394
  }
322
395
 
323
396
  dispose(): void {
@@ -0,0 +1,243 @@
1
+ import { CAR, type CarBody, FEEL } from "./CarBody.js";
2
+
3
+ /**
4
+ * The handbrake drift, and the drift score.
5
+ *
6
+ * The handbrake drops the rear pair's grip cap (`wheelFrictionSlip`), so the tail steps out on
7
+ * the real tyre model rather than on a scripted yaw. While the car is sideways the rear keeps a
8
+ * reduced grip: steering into the slide holds it, a neutral wheel lets it bleed off, and
9
+ * counter-steer catches it (NASCAR 98's `lateral-slide` rule). Past {@link DRIFT.governStart} the
10
+ * rear grips harder the further round the car is, so a held drift settles at an angle instead of
11
+ * spinning. When the slide ends, the grip comes back over {@link GRIP_RETURN_SECONDS}.
12
+ *
13
+ * The car also lets go **without the handbrake**: full lock held at speed is more than the rear
14
+ * tyres can hold, so past {@link DRIFT.looseSpeed} the rear grip drops to {@link DRIFT.looseGrip}
15
+ * and the same drift takes over. A sharp corner taken flat out steps the tail out; a wide one,
16
+ * taken on part lock, does not.
17
+ *
18
+ * Detection and score follow VDrift (`src/game.cpp:2595-2637`, `src/timer.h:158,212`): an angle
19
+ * with a wide hysteresis band, a spin past a right angle voids the chain, and a banked drift
20
+ * scores its distance plus a peak speed and a peak angle bonus. The angle is the rear axle's
21
+ * slip, not the chassis's: on this car's steering lock a tight turn on full grip already points
22
+ * the nose 15° off its velocity, and that is not a drift.
23
+ */
24
+ export const DRIFT = {
25
+ /** The rear grip cap while the handbrake kicks the tail out. 14 is full grip. */
26
+ handbrakeGrip: 0.5,
27
+ /** While sideways: steering into the slide, a neutral wheel, and counter-steer. */
28
+ holdGrip: 0.35,
29
+ recoverGrip: 2.6,
30
+ catchGrip: 4.5,
31
+ /** The rear grips harder across this band of slip, in radians, up to `governGrip`. */
32
+ governStart: 0.5,
33
+ governEnd: 0.9,
34
+ governGrip: 3,
35
+ /** The driver's steering lock in a slide, as a share of the lock on full grip. */
36
+ lockScale: 0.35,
37
+ /**
38
+ * Newtons along the nose while sliding on the throttle. Rapier scales a sliding wheel's drive
39
+ * by the same factor as its side grip, so a car that is sideways has almost no engine: measured,
40
+ * 14 → 8 m/s in one second of drift. This is the push a spinning rear tyre still gives.
41
+ */
42
+ thrust: 4200,
43
+ /** Where that push reaches zero, as a share of the car's top speed. */
44
+ thrustTopShare: 0.92,
45
+ /** How much of the slip angle the front wheels take as opposite lock, and the most they turn. */
46
+ counterSteer: 1,
47
+ maxCounter: 0.85,
48
+ /**
49
+ * Natural oversteer: the stick share, the speed share of `FEEL.topSpeed`, the ticks it is held.
50
+ * The move vector is normalised, so a keyboard's full right with the throttle held reads 0.707:
51
+ * a 0.9 threshold meant a keyboard driver could never reach it.
52
+ */
53
+ looseLock: 0.65,
54
+ looseSpeed: 0.62,
55
+ looseTicks: 10,
56
+ /** The rear grip cap once the tail lets go by itself. */
57
+ looseGrip: 0.6,
58
+ /** The least ticks one press of the handbrake kicks for. */
59
+ kickTicks: 9,
60
+ /** The brake impulse while the handbrake kicks: enough to load the nose, not to stop the car. */
61
+ handbrake: 8,
62
+ /** Below this the handbrake is only a brake, in m/s. VDrift's 10 m/s, scaled to a 17 m/s car. */
63
+ minSpeed: 6,
64
+ /** VDrift's thresholds, radians of slip. */
65
+ enterAngle: 0.2,
66
+ exitAngle: 0.1,
67
+ /** Past a right angle the slide is a spin, and it scores nothing. */
68
+ spinAngle: Math.PI / 2,
69
+ /** VDrift's bank bonus weights, and the distance a drift must cover to be banked. */
70
+ speedBonus: 0.5,
71
+ angleBonus: 40,
72
+ bankThreshold: 5,
73
+ /**
74
+ * How long a banked score stays on screen, in **game** seconds. It was wall clock in the HUD, which
75
+ * meant a pause ate the popup and a harness that advances ticks faster than real time outlived it;
76
+ * the clock lives here so it stops when the race does.
77
+ */
78
+ popupSeconds: 1.6,
79
+ } as const;
80
+
81
+ const GRIP_RETURN_SECONDS = 0.3;
82
+ /** How long the rear grip takes to fall to a lower target. The rise is deliberately slower than
83
+ * the fall — grip comes back over 0.3 s — but neither may happen in one tick: the tyre's side grip
84
+ * is a bristle model, and a target that flips between 0.35 and 4.5 as the steering crosses centre
85
+ * sawtoothed the car through a held slide. */
86
+ const GRIP_FALL_SECONDS = 0.05;
87
+ const REAR = [2, 3] as const;
88
+
89
+ export class Drift {
90
+ /** Whether the car is in a scored drift this tick. */
91
+ drifting = false;
92
+ /** The rear slip in radians: + in a right-hand slide. */
93
+ angle = 0;
94
+ /** The running score of the drift in progress, before it is banked. */
95
+ chain = 0;
96
+ /** Everything banked this race. */
97
+ score = 0;
98
+ /** The last drift that was banked, for the HUD popup. 0 until one is. */
99
+ lastBanked = 0;
100
+ /** Seconds the last banked score still shows, counted in game time so a pause freezes it. */
101
+ popup = 0;
102
+ banked = 0;
103
+ spins = 0;
104
+ /** The rear grip cap written this tick. */
105
+ grip: number = CAR.wheelFrictionSlip;
106
+ /** 0 on full grip, 1 once the rear is loose: how far the steering is into its slide mode. */
107
+ get slide(): number {
108
+ // Not while the tail is only letting go: slide steering cuts the lock, and cut before the
109
+ // rear has stepped out it turned the car less, which held the tail in.
110
+ if (this.loose) return 0;
111
+ const span = CAR.wheelFrictionSlip - DRIFT.catchGrip;
112
+ return Math.min(1, Math.max(0, (CAR.wheelFrictionSlip - this.grip) / span));
113
+ }
114
+
115
+ /** The lowest rear grip written, so a scenario can prove the handbrake reached the tyres. */
116
+ lowestGrip: number = CAR.wheelFrictionSlip;
117
+ /** The largest slip seen in a scored drift. */
118
+ peakSlip = 0;
119
+ #peakSpeed = 0;
120
+ #peakAngle = 0;
121
+ #teleports = 0;
122
+ #kickTicks = 0;
123
+ #lockTicks = 0;
124
+ /** Whether the tail let go by itself this tick, with no handbrake. */
125
+ loose = false;
126
+
127
+ /**
128
+ * Whether the handbrake kicks the tail out this tick, rather than only braking: at speed, with
129
+ * the wheel turned or the car already sideways.
130
+ */
131
+ kicks(car: CarBody, handbrake: boolean, steer: number): boolean {
132
+ const asked =
133
+ handbrake && car.groundSpeed > DRIFT.minSpeed && (Math.abs(steer) > 0.2 || this.drifting);
134
+ // A tap is a kick: a 60 ms press is shorter than the tail takes to step out, so it is held on.
135
+ if (asked) this.#kickTicks = DRIFT.kickTicks;
136
+ else if (this.#kickTicks > 0) this.#kickTicks -= 1;
137
+ return (
138
+ asked || (this.#kickTicks > 0 && car.groundSpeed > DRIFT.minSpeed && Math.abs(steer) > 0.2)
139
+ );
140
+ }
141
+
142
+ /** One tick, after `car.measure`. `steer` is the wheel, + to the right. */
143
+ update(car: CarBody, kick: boolean, steer: number, dt: number): void {
144
+ // A tick's subtraction leaves float noise (~1e-16). Snap it: the popup has to end at exactly
145
+ // zero, or `quantize` publishes a live popup one tick longer than it should.
146
+ const left = this.popup - dt;
147
+ this.popup = left > 1e-6 ? left : 0;
148
+ // A rescue or the autopilot's rejoin teleports the car: that is not a drift, and not a spin.
149
+ if (car.teleports !== this.#teleports) {
150
+ this.#teleports = car.teleports;
151
+ this.reset(car);
152
+ }
153
+ const speed = car.groundSpeed;
154
+ this.angle = car.rearSlip;
155
+ const slip = Math.abs(this.angle);
156
+ const onRoad = car.body.wheelContact(2) || car.body.wheelContact(3);
157
+
158
+ if (!this.drifting) {
159
+ if (onRoad && speed > DRIFT.minSpeed && slip > DRIFT.enterAngle && slip < DRIFT.spinAngle) {
160
+ this.drifting = true;
161
+ this.chain = 0;
162
+ this.#peakSpeed = 0;
163
+ this.#peakAngle = 0;
164
+ }
165
+ } else if (slip >= DRIFT.spinAngle) {
166
+ this.drifting = false;
167
+ this.chain = 0;
168
+ this.spins += 1;
169
+ } else if (slip < DRIFT.exitAngle || speed < DRIFT.minSpeed * 0.5 || !onRoad) {
170
+ this.#bank();
171
+ } else {
172
+ this.chain += speed * dt;
173
+ this.#peakSpeed = Math.max(this.#peakSpeed, speed);
174
+ this.#peakAngle = Math.max(this.#peakAngle, slip);
175
+ this.peakSlip = Math.max(this.peakSlip, slip);
176
+ }
177
+
178
+ const pushing =
179
+ !kick &&
180
+ onRoad &&
181
+ Math.abs(steer) >= DRIFT.looseLock &&
182
+ speed > DRIFT.looseSpeed * FEEL.topSpeed;
183
+ this.#lockTicks = pushing ? this.#lockTicks + 1 : 0;
184
+ this.loose = !this.drifting && this.#lockTicks >= DRIFT.looseTicks;
185
+
186
+ let wanted: number = CAR.wheelFrictionSlip;
187
+ if (this.loose) wanted = DRIFT.looseGrip;
188
+ else if (kick || this.drifting) {
189
+ const into = steer * Math.sign(this.angle);
190
+ wanted = kick
191
+ ? DRIFT.handbrakeGrip
192
+ : into > 0.2
193
+ ? DRIFT.holdGrip
194
+ : into < -0.2
195
+ ? DRIFT.catchGrip
196
+ : DRIFT.recoverGrip;
197
+ const govern = Math.min(
198
+ 1,
199
+ Math.max(0, (slip - DRIFT.governStart) / (DRIFT.governEnd - DRIFT.governStart)),
200
+ );
201
+ wanted = Math.max(wanted, wanted + (DRIFT.governGrip - wanted) * govern);
202
+ }
203
+ // Both directions ease, over the fall and the return time: a grip that changes in one tick is a
204
+ // step input to a bristle tyre, and the slide it produces reads as a snap rather than a slide.
205
+ const rise = ((CAR.wheelFrictionSlip - DRIFT.handbrakeGrip) * dt) / GRIP_RETURN_SECONDS;
206
+ const fall = ((CAR.wheelFrictionSlip - DRIFT.handbrakeGrip) * dt) / GRIP_FALL_SECONDS;
207
+ const next =
208
+ wanted < this.grip ? Math.max(wanted, this.grip - fall) : Math.min(wanted, this.grip + rise);
209
+ if (next !== this.grip) {
210
+ this.grip = next;
211
+ this.lowestGrip = Math.min(this.lowestGrip, next);
212
+ for (const wheel of REAR) car.body.setWheelFrictionSlip(wheel, next);
213
+ }
214
+ }
215
+
216
+ /** Ends any drift without banking it, and restores the grip. */
217
+ reset(car: CarBody): void {
218
+ this.drifting = false;
219
+ this.chain = 0;
220
+ this.angle = 0;
221
+ this.loose = false;
222
+ this.#lockTicks = 0;
223
+ if (this.grip !== CAR.wheelFrictionSlip) {
224
+ this.grip = CAR.wheelFrictionSlip;
225
+ for (const wheel of REAR) car.body.setWheelFrictionSlip(wheel, this.grip);
226
+ }
227
+ }
228
+
229
+ #bank(): void {
230
+ this.drifting = false;
231
+ const total =
232
+ this.chain +
233
+ DRIFT.speedBonus * this.#peakSpeed +
234
+ (DRIFT.angleBonus * this.#peakAngle) / Math.PI;
235
+ if (this.chain > DRIFT.bankThreshold) {
236
+ this.score += total;
237
+ this.lastBanked = total;
238
+ this.banked += 1;
239
+ this.popup = DRIFT.popupSeconds;
240
+ }
241
+ this.chain = 0;
242
+ }
243
+ }
@@ -1,7 +1,7 @@
1
1
  import { MathUtils, Vector3 } from "three";
2
2
  import { CIRCUIT, type CircuitLine } from "../track/circuit.js";
3
3
  import type { CarBody } from "./CarBody.js";
4
- import { FEEL } from "./CarBody.js";
4
+ import { FEEL, driveForce } from "./CarBody.js";
5
5
 
6
6
  /**
7
7
  * The closed-loop driver: aim at a point ahead on the circuit, brake for what is coming.
@@ -177,7 +177,7 @@ export class LineDriver {
177
177
  const target = this.targetSpeed(this.#progress);
178
178
  if (speed < target) {
179
179
  const want = MathUtils.clamp((target - speed) / 2.5, 0, 1);
180
- body.engineForce = FEEL.engineForce * want * Math.max(0, 1 - speed / target);
180
+ body.engineForce = FEEL.engineForce * want * driveForce(speed, FEEL.topSpeed);
181
181
  body.brake = 0;
182
182
  } else {
183
183
  body.engineForce = 0;
@@ -0,0 +1,72 @@
1
+ import { MathUtils } from "three";
2
+
3
+ /**
4
+ * The nitro tank: 0 to 1, burned while the nitro button is held, refilled by driving and faster
5
+ * by drifting.
6
+ *
7
+ * The rules follow Need for Speed: Most Wanted (`EngineRacer.cpp:926-976`): nitro engages only
8
+ * at speed and stays on down to half that speed, the tank drains over a discharge time, a
9
+ * disengage delay runs before the refill starts, and the refill time blends between a slow and a
10
+ * fast value across a speed band.
11
+ */
12
+ export const NITRO = {
13
+ /** Seconds a full tank burns. */
14
+ dischargeSeconds: 2.6,
15
+ /** Engages at or above this, in m/s (NFS's 10 mph); stays engaged down to half of it. */
16
+ engageSpeed: 4.5,
17
+ /** Seconds after release before the tank starts to refill. */
18
+ disengageDelay: 1,
19
+ /** Seconds a passive refill takes at the low and the high end of the speed band, in m/s. */
20
+ refillSlowSeconds: 40,
21
+ refillFastSeconds: 18,
22
+ refillBand: [6, 17] as const,
23
+ /** Tank per second while the car is in a scored drift: about four seconds of drift fill it. */
24
+ driftRefillPerSecond: 0.25,
25
+ } as const;
26
+
27
+ export class Nitro {
28
+ /** The tank, 0 to 1. A race starts with it full. */
29
+ tank = 1;
30
+ engaged = false;
31
+ /** How many times nitro engaged, which is what the HUD and the boost scenario count. */
32
+ uses = 0;
33
+ /**
34
+ * Tank the **drift** path added this race, and the tank the passive path added.
35
+ *
36
+ * Two counters rather than one, because "a drifting car refills faster" is a claim about a
37
+ * rate difference, and a single tank reading cannot separate the two paths that fill it.
38
+ */
39
+ driftGain = 0;
40
+ refillGain = 0;
41
+ #delay = 0;
42
+
43
+ update(held: boolean, speed: number, drifting: boolean, dt: number): void {
44
+ const canStay = speed >= NITRO.engageSpeed * 0.5;
45
+ const canStart = speed >= NITRO.engageSpeed && this.tank > 0.05;
46
+ const next = held && this.tank > 0 && (this.engaged ? canStay : canStart);
47
+ if (next && !this.engaged) this.uses += 1;
48
+ this.engaged = next;
49
+ if (this.engaged) {
50
+ this.tank = Math.max(0, this.tank - dt / NITRO.dischargeSeconds);
51
+ this.#delay = NITRO.disengageDelay;
52
+ return;
53
+ }
54
+ if (drifting) {
55
+ const gained = Math.min(1 - this.tank, NITRO.driftRefillPerSecond * dt);
56
+ this.tank += gained;
57
+ this.driftGain += gained;
58
+ }
59
+ if (this.#delay > 0) {
60
+ this.#delay = Math.max(0, this.#delay - dt);
61
+ return;
62
+ }
63
+ // Indexed reads, not a destructure: this runs every frame while coasting.
64
+ const band = NITRO.refillBand;
65
+ const low = band[0];
66
+ const blend = MathUtils.clamp((speed - low) / (band[1] - low), 0, 1);
67
+ const seconds = MathUtils.lerp(NITRO.refillSlowSeconds, NITRO.refillFastSeconds, blend);
68
+ const gained = Math.min(1 - this.tank, dt / seconds);
69
+ this.tank += gained;
70
+ this.refillGain += gained;
71
+ }
72
+ }