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
@@ -1,19 +1,21 @@
1
- import type { Vector3 } from "three";
1
+ import { MathUtils, Vector3 } from "three";
2
2
  import { Boost } from "../kart/boost.js";
3
3
  import { createMaterials } from "../render/materials.js";
4
4
  import type { ITouchInput } from "../render/touch-controls.js";
5
- import { CarBody, type CarCtx, FEEL } from "./CarBody.js";
5
+ import { CarBody, type CarCtx, FEEL, driveForce } from "./CarBody.js";
6
+ import { DRIFT, Drift } from "./Drift.js";
6
7
  import { LineDriver } from "./LineDriver.js";
8
+ import { Nitro } from "./Nitro.js";
7
9
 
8
10
  /**
9
11
  * The demo driver's pace, in m/s, and the side of the road it keeps.
10
12
  *
11
- * Just under the rival's, on purpose: the demo driver is here to show the circuit and to let a
12
- * playtest ask a car to follow it, not to win the race. A demo driver that beat the rival would
13
- * make "finishing behind the rival is a DNF" untestable from the grid, and that rule is one of the
14
- * things this template has to prove.
13
+ * Under the slowest rival's, on purpose: the demo driver is here to show the circuit and to let a
14
+ * playtest ask a car to follow it, not to win the race. A demo driver that beat the field would
15
+ * make "finishing behind a rival is a DNF" untestable from the grid, and that rule is one of the
16
+ * things this template has to prove. Slower than every car ahead, it also never runs into one.
15
17
  */
16
- export const AUTOPILOT_PACE = 15.5;
18
+ export const AUTOPILOT_PACE = 20.5;
17
19
  const AUTOPILOT_OFFSET = -1.5;
18
20
 
19
21
  /**
@@ -28,13 +30,19 @@ const AUTOPILOT_OFFSET = -1.5;
28
30
  */
29
31
  export class RacingCar {
30
32
  readonly car: CarBody;
33
+ /** The boost pad's timed shove. */
31
34
  readonly boost = new Boost();
35
+ /** The driver's own tank, held to burn; drifting refills it. */
36
+ readonly nitro = new Nitro();
37
+ readonly drift = new Drift();
32
38
  /** The demo driver. Present whether or not it is engaged, so engaging is not an allocation. */
33
39
  readonly autopilot = new LineDriver({ offset: AUTOPILOT_OFFSET, pace: AUTOPILOT_PACE });
34
40
  #autopilotOn = false;
35
41
  #speedAfterBoost = 0;
36
42
  #topSpeed = 0;
37
43
  #boostWasActive = false;
44
+ #skidding = false;
45
+ readonly #push = new Vector3();
38
46
 
39
47
  constructor(ctx: CarCtx, spawn: Vector3, yaw = 0) {
40
48
  this.car = new CarBody(ctx, { materials: createMaterials(), spawn, yaw });
@@ -79,8 +87,17 @@ export class RacingCar {
79
87
  return this.#topSpeed;
80
88
  }
81
89
 
90
+ /** A boost pad or the nitro: either one drives the boosted torque curve. */
82
91
  get boosting(): boolean {
83
- return this.boost.active;
92
+ return this.boost.active || this.nitro.engaged;
93
+ }
94
+
95
+ /**
96
+ * Whether a rear tyre is leaving rubber this tick: sideways in a slide, or locked under the
97
+ * handbrake at speed. The smoke and the skid marks read this.
98
+ */
99
+ get skidding(): boolean {
100
+ return this.#skidding;
84
101
  }
85
102
 
86
103
  /** Whether the closed-loop driver has the wheel. Published, so a scenario can prove it drove. */
@@ -102,7 +119,6 @@ export class RacingCar {
102
119
  */
103
120
  update(ctx: CarCtx, dt: number, touch?: ITouchInput): void {
104
121
  this.boost.update(dt);
105
- if (ctx.input.justPressed("boost") || touch?.boostPressed === true) this.boost.activate();
106
122
  const move = ctx.input.vector("move");
107
123
  if (touch !== undefined) {
108
124
  move.x += touch.move.x;
@@ -113,13 +129,25 @@ export class RacingCar {
113
129
  // Touching the wheel takes it back, the way a driving game's demo lap does. A scenario that
114
130
  // wants to hand the car over presses a key; a player who grabs the stick gets their car.
115
131
  if (this.#autopilotOn && move.lengthSq() > 0.02) this.#autopilotOn = false;
132
+ const driver = !this.#autopilotOn;
133
+ const nitroHeld = driver && (ctx.input.pressed("boost") || touch?.boostPressed === true);
134
+ this.nitro.update(nitroHeld, this.car.groundSpeed, this.drift.drifting, dt);
135
+ // The handbrake (shift, the touch brake button): with the wheel turned at speed it kicks the
136
+ // tail out, and otherwise it is the hard brake that also holds a stopped car.
137
+ const handbrake = driver && (ctx.input.pressed("brake") || touch?.brakePressed === true);
138
+ const kick = this.drift.kicks(this.car, handbrake, move.x);
116
139
  if (this.#autopilotOn) {
117
140
  this.autopilot.update(this.car, dt);
118
141
  } else {
119
- this.drive(move, ctx.input.pressed("brake") || touch?.brakePressed === true);
142
+ this.drive(move, handbrake, kick);
120
143
  this.car.measure(dt);
121
144
  }
122
- if (this.boost.active) {
145
+ this.drift.update(this.car, kick, driver ? move.x : 0, dt);
146
+ this.#skidding =
147
+ this.car.groundSpeed > 3 &&
148
+ ((this.drift.slide > 0 && Math.abs(this.car.rearSlip) > 0.12) ||
149
+ (handbrake && this.car.groundSpeed > DRIFT.minSpeed));
150
+ if (this.boosting) {
123
151
  this.#boostWasActive = true;
124
152
  } else if (this.#boostWasActive) {
125
153
  this.#boostWasActive = false;
@@ -128,24 +156,46 @@ export class RacingCar {
128
156
  this.#topSpeed = Math.max(this.#topSpeed, this.speed);
129
157
  }
130
158
 
131
- private drive(move: { x: number; y: number }, braking: boolean): void {
159
+ private drive(move: { x: number; y: number }, braking: boolean, kick: boolean): void {
132
160
  const body = this.car.body;
133
161
  const speed = body.speed;
134
162
  // The sign: `move.x` is +1 to the right, and a positive Rapier steering angle turns toward the
135
163
  // chassis's -z, which is the driver's left. Flipping here keeps "right means right" for the
136
164
  // physics and for the visual front wheels, which take the same angle.
137
- body.steering = -move.x * this.car.lockAt(speed);
165
+ // In a slide the front wheels follow the direction of travel, which is opposite lock, and
166
+ // the driver's wheel steers around that: full grip on a wheel held 50° off its own velocity
167
+ // is a brake, measured at 15 → 4.6 m/s in half a second. `slide` fades it in and out with the
168
+ // rear grip, so the catch is continuous.
169
+ const slide = this.drift.slide;
170
+ body.steering =
171
+ -(kick ? Math.sign(move.x) : move.x * MathUtils.lerp(1, DRIFT.lockScale, slide)) *
172
+ this.car.lockAt(speed) +
173
+ MathUtils.clamp(this.drift.angle * DRIFT.counterSteer, -DRIFT.maxCounter, DRIFT.maxCounter) *
174
+ slide;
138
175
  // The brake key (shift, the touch brake button) wins over the throttle, and holds a stopped car.
139
- if (braking) {
176
+ if (slide > 0 && move.y > 0 && !braking) {
177
+ const top = (this.boosting ? FEEL.boostTopSpeed : FEEL.topSpeed) * DRIFT.thrustTopShare;
178
+ const push =
179
+ move.y * DRIFT.thrust * slide * MathUtils.clamp((top - this.car.groundSpeed) / 2, 0, 1);
180
+ this.#push.copy(this.car.forward).multiplyScalar(push);
181
+ body.applyForce(this.#push);
182
+ }
183
+ if (kick) {
184
+ // Rapier ignores the brake on a wheel that is driven, so the engine is cut for the kick.
185
+ body.engineForce = 0;
186
+ body.brake = DRIFT.handbrake;
187
+ } else if (braking) {
140
188
  body.engineForce = 0;
141
189
  body.brake = FEEL.brake;
142
- } else if (move.y > 0) {
143
- const top = this.boost.active ? FEEL.boostTopSpeed : FEEL.topSpeed;
190
+ } else if (move.y > 0 || this.nitro.engaged) {
191
+ // Nitro pushes on its own: holding the button is full throttle, as in most arcade racers.
192
+ const throttle = this.nitro.engaged ? 1 : move.y;
193
+ const top = this.boosting ? FEEL.boostTopSpeed : FEEL.topSpeed;
144
194
  body.engineForce =
145
- move.y *
195
+ throttle *
146
196
  FEEL.engineForce *
147
- (this.boost.active ? FEEL.boostForce : 1) *
148
- Math.max(0, 1 - speed / top);
197
+ (this.boosting ? FEEL.boostForce : 1) *
198
+ driveForce(speed, top);
149
199
  body.brake = 0;
150
200
  } else if (speed > FEEL.reverseEnterSpeed) {
151
201
  body.engineForce = 0;
@@ -178,8 +228,23 @@ export class RacingCar {
178
228
  debug(): Record<string, unknown> {
179
229
  return {
180
230
  autopilot: this.#autopilotOn,
181
- boostActive: this.boost.active,
182
- boostUses: this.boost.uses,
231
+ boostActive: this.boosting,
232
+ boostUses: this.boost.uses + this.nitro.uses,
233
+ drift: {
234
+ angle: Math.round(this.drift.angle * 1000) / 1000,
235
+ banked: this.drift.banked,
236
+ drifting: this.drift.drifting,
237
+ grip: this.drift.grip,
238
+ lowestGrip: this.drift.lowestGrip,
239
+ peakSlip: Math.round(this.drift.peakSlip * 1000) / 1000,
240
+ score: Math.round(this.drift.score),
241
+ spins: this.drift.spins,
242
+ },
243
+ nitro: {
244
+ engaged: this.nitro.engaged,
245
+ tank: Math.round(this.nitro.tank * 1000) / 1000,
246
+ uses: this.nitro.uses,
247
+ },
183
248
  lateralLoad: Math.round(this.lateralLoad * 100) / 100,
184
249
  normaliseFactor: this.car.normaliseFactor,
185
250
  position: this.car.position.toArray(),
@@ -1,15 +1,25 @@
1
1
  import { Vector3 } from "three";
2
2
  import { createMaterials } from "../render/materials.js";
3
- import { CIRCUIT, LINE_AT, lineDistance } from "../track/circuit.js";
3
+ import { CIRCUIT, LINE_AT, gridSlot, lineDistance } from "../track/circuit.js";
4
4
  import { CarBody, type CarCtx, RIDE } from "./CarBody.js";
5
5
  import { LineDriver } from "./LineDriver.js";
6
6
 
7
7
  /**
8
- * The rival's pace, in m/s. It is a **constant**, not a function of the player: the old rival ran a
9
- * fixed 7.6 m/s along the route whatever the player did, and rubber-banding it towards or away from
10
- * the player would be the same lie with more code. A fixed pace is beatable, and it is honest.
8
+ * The field, pole first: each rival's pace in m/s and the side of the road it keeps.
9
+ *
10
+ * A pace is a **constant**, not a function of the player: rubber-banding a rival towards or away
11
+ * from the player is a lie a driver feels. The ladder runs from just under the player's 26 m/s top
12
+ * speed down, and the grid is in pace order, so no rival ever catches the one ahead of it. A
13
+ * clean race with the nitro wins; a race with two rescues in it does not.
14
+ * Each keeps the side of the road its grid slot is on, so the two lines never share a car.
11
15
  */
12
- export const RIVAL_PACE = 17.4;
16
+ export const RIVALS = [
17
+ { pace: 25, offset: 1.5 },
18
+ { pace: 24.2, offset: -1.5 },
19
+ { pace: 23.4, offset: 1.5 },
20
+ { pace: 22.6, offset: -1.5 },
21
+ { pace: 21.8, offset: 1.5 },
22
+ ] as const;
13
23
 
14
24
  /**
15
25
  * Laps the rival has completed, from its progress in metres since the route origin. Counted at the
@@ -20,16 +30,12 @@ export function rivalLap(progress: number): number {
20
30
  return Math.max(0, Math.floor((progress - lineDistance(LINE_AT.finish)) / CIRCUIT.totalLength));
21
31
  }
22
32
 
23
- /** The side of the road the rival keeps, so it and the demo driver never share a line. */
24
- const RIVAL_OFFSET = 1.5;
25
-
26
33
  /**
27
- * The rival: a second `VehicleBody3D` on the same chassis, driven by the same {@link LineDriver}
34
+ * A rival: another `VehicleBody3D` on the same chassis, driven by the same {@link LineDriver}
28
35
  * the autopilot uses.
29
36
  *
30
- * It has a body, so the player cannot drive through it; it starts on its own grid slot, so the two
31
- * cars do not spawn inside each other; and it is ranked on its own progress around the circuit, so
32
- * the order on the HUD is two cars rather than one car and a constant.
37
+ * It has a body, so the player cannot drive through it; it starts on its own grid slot, so no two
38
+ * cars spawn inside each other; and it is ranked on its own progress around the circuit.
33
39
  *
34
40
  * There is no steering, throttle or braking code in this file. That is the point: the rival and the
35
41
  * autopilot are the *same* controller, so a playtest that presses the autopilot button is running
@@ -40,21 +46,29 @@ export class Rival {
40
46
  readonly driver: LineDriver;
41
47
  #lap = 0;
42
48
 
43
- constructor(ctx: CarCtx, startDistance: number) {
44
- const sample = CIRCUIT.at(startDistance, CIRCUIT.createSample());
49
+ /** `index` is the place on the grid, 0 on pole, and picks the pace and the livery. */
50
+ constructor(ctx: CarCtx, index: number) {
51
+ const spec = RIVALS[index];
52
+ if (spec === undefined) throw new Error(`There is no rival ${index}.`);
53
+ const slot = gridSlot(index);
54
+ const sample = CIRCUIT.at(slot.distance, CIRCUIT.createSample());
45
55
  const yaw = Math.atan2(sample.tangent.z, sample.tangent.x);
46
- // Same sculpt, different livery: the rival was indistinguishable from the player in the first
47
- // frame because both cars asked for the same material set.
56
+ // Same sculpt, different livery: a rival indistinguishable from the player in the first frame
57
+ // is a car the player cannot find in the mirror.
48
58
  const materials = createMaterials();
59
+ const livery = materials.rivalLiveries[index % materials.rivalLiveries.length];
49
60
  this.car = new CarBody(ctx, {
50
- materials: { ...materials, body: materials.rivalBody },
51
- // The centreline is authored on the terrain, so the spawn is its point raised to the
61
+ materials: { ...materials, body: livery ?? materials.rivalBody },
62
+ // The centreline is authored on the terrain, so the spawn is its height raised to the
52
63
  // chassis' ride height: dropping the car in from above reads as a jump start.
53
- spawn: new Vector3(sample.point.x, sample.point.y + RIDE, sample.point.z),
64
+ spawn: new Vector3()
65
+ .copy(sample.point)
66
+ .addScaledVector(sample.right, slot.side)
67
+ .setY(sample.point.y + RIDE),
54
68
  yaw,
55
69
  });
56
- this.driver = new LineDriver({ offset: RIVAL_OFFSET, pace: RIVAL_PACE });
57
- this.driver.reset(startDistance);
70
+ this.driver = new LineDriver({ offset: spec.offset, pace: spec.pace });
71
+ this.driver.reset(slot.distance);
58
72
  this.car.measure(1 / 60);
59
73
  }
60
74
 
@@ -2,6 +2,7 @@ import { defineGame } from "@threenative/core";
2
2
  import { playtest } from "@threenative/core/playtest";
3
3
  import { type IPhysicsContext, rapier } from "@threenative/physics";
4
4
  import config from "../threenative.config.js";
5
+ import { setRaceAudioMuted } from "./audio/engine.js";
5
6
  import { drainPlaytestEvents as events } from "./playtest-events.js";
6
7
  import { Boot } from "./scenes/Boot.js";
7
8
  import { Race } from "./scenes/Race.js";
@@ -18,6 +19,8 @@ const game = defineGame<GameState, IPhysicsContext>({
18
19
  up: ["ArrowUp", "KeyW"],
19
20
  },
20
21
  brake: { buttons: [1], keys: ["ShiftLeft", "ShiftRight"] },
22
+ // The handbrake: a hard brake, and with the wheel turned at speed it kicks the tail out.
23
+ // Nitro is held to burn.
21
24
  boost: { buttons: [0], keys: ["Space"] },
22
25
  restart: { keys: ["KeyR"] },
23
26
  // The demo driver: the same closed-loop controller the rival uses, on the player's car. It is
@@ -47,6 +50,9 @@ game.ui.onIntent((intent) => {
47
50
  if (intent === "restart") void game.goto("race");
48
51
  if (intent === "pause") game.pause();
49
52
  if (intent === "resume") game.resume();
53
+ // The frame loop does not tick while paused, so nothing inside the scene could silence the
54
+ // engine: the bus is muted here, where the pause intent already is.
55
+ if (intent === "pause" || intent === "resume") setRaceAudioMuted(intent === "pause");
50
56
  game.state.set({
51
57
  // `game.ui.connected` is true only once the UI announced itself, which is what tells an
52
58
  // overlay that never came up apart from a game whose HUD is simply empty.
@@ -0,0 +1,74 @@
1
+ import { MathUtils } from "three";
2
+ import { FEEL } from "./entities/CarBody.js";
3
+
4
+ /**
5
+ * The rev counter's rules, transcribed from Need for Speed: Most Wanted (`EngineRacer.cpp:606-907`).
6
+ *
7
+ * Display only — nothing here touches the car — but a rev counter that steps is the loudest tell
8
+ * that a driving game's numbers are decoration. Two rules make it read as an engine: the needle
9
+ * falls at a **capped rate** with no load, and every update is a blend of 55% of the new reading
10
+ * with 45% of the last, so a gear change sweeps instead of snapping.
11
+ */
12
+ export const GAUGES = {
13
+ /** Gears in the box. One band each, so a gear covers `topSpeed / gears` from rest. */
14
+ gears: 6,
15
+ /** The needle at a standstill, as a share of the gear's band. */
16
+ idle: 0.09,
17
+ /** Where an upshift happens, and — coming back down — where a downshift happens. */
18
+ upshift: 0.94,
19
+ downshift: 0.42,
20
+ /** The most the needle may fall in a second, as a share of a gear's band. */
21
+ fallPerSecond: 1.4,
22
+ /** NFS's own blend: 55% of the new reading, 45% of the last. */
23
+ newShare: 0.55,
24
+ } as const;
25
+
26
+ /** The speed one gear covers, in m/s: `[low, high]`, gear 1 from rest. */
27
+ export function gearBand(
28
+ gear: number,
29
+ top: number = FEEL.topSpeed,
30
+ gears: number = GAUGES.gears,
31
+ ): [number, number] {
32
+ const span = top / gears;
33
+ return [(gear - 1) * span, gear * span];
34
+ }
35
+
36
+ /** What a speed reads on the needle in a given gear, 0 to 1 of that gear's band. */
37
+ export function rpmIn(
38
+ speed: number,
39
+ gear: number,
40
+ top: number = FEEL.topSpeed,
41
+ gears: number = GAUGES.gears,
42
+ ): number {
43
+ // Indexed reads, not a destructure: this runs every frame, and destructuring a tuple allocates
44
+ // an array iterator (`template-runtime-cost.spec.ts` holds the scene to zero per frame).
45
+ const band = gearBand(gear, top, gears);
46
+ const low = band[0];
47
+ return MathUtils.clamp((speed - low) / (band[1] - low), 0, 1);
48
+ }
49
+
50
+ /**
51
+ * The needle and the gear, one tick at a time.
52
+ *
53
+ * The gear is chosen from the **reading**, never from the needle: a gear decides the needle's band,
54
+ * so a needle deciding the gear is a feedback loop that hunts on a steady speed.
55
+ */
56
+ export class Gauges {
57
+ gear = 1;
58
+ /** The needle, 0 to 1 of the current gear's band. */
59
+ rpm: number = GAUGES.idle;
60
+
61
+ /** `speed` is signed, so reverse reads as idle in first gear rather than as a negative band. */
62
+ update(speed: number, dt: number): void {
63
+ const ground = Math.max(0, speed);
64
+ // One gear per tick at most: a rescue teleport can jump the speed by 30 m/s, and climbing six
65
+ // gears in one tick is a needle that flickers through the whole box.
66
+ if (rpmIn(ground, this.gear) > GAUGES.upshift && this.gear < GAUGES.gears) this.gear += 1;
67
+ else if (rpmIn(ground, this.gear) < GAUGES.downshift && this.gear > 1) this.gear -= 1;
68
+ const reading = Math.max(GAUGES.idle, rpmIn(ground, this.gear));
69
+ // The cap is on the fall only: a shift up drops the reading, and the needle follows it over a
70
+ // few ticks. A reading that rises is followed at once, which is what a blip of throttle does.
71
+ const capped = Math.max(reading, this.rpm - GAUGES.fallPerSecond * dt);
72
+ this.rpm = GAUGES.newShare * capped + (1 - GAUGES.newShare) * this.rpm;
73
+ }
74
+ }
@@ -10,11 +10,19 @@ const EYE_BACK = 6.6;
10
10
  const LEAD_BASE = 1.5;
11
11
  const LEAD_PER_MPS = 0.42;
12
12
 
13
+ /** How fast the chase heading turns toward the travel direction, per second (12% a 60 Hz tick). */
14
+ const TURN_RATE = 7.7;
15
+
16
+ /** A nitro burn widens the lens and pulls the camera back: the oldest speed cue there is. */
17
+ export const BASE_FOV = 56;
18
+ const BOOST_FOV = 10;
19
+ const BOOST_BACK = 0.8;
20
+
13
21
  /** The most the camera will bank, in radians. Past this a corner reads as a barrel roll. */
14
22
  const MAX_BANK = 0.055;
15
23
 
16
24
  export function setupCamera(camera: PerspectiveCamera): void {
17
- camera.fov = 56;
25
+ camera.fov = BASE_FOV;
18
26
  camera.near = 0.1;
19
27
  camera.far = 340;
20
28
  camera.updateProjectionMatrix();
@@ -24,6 +32,10 @@ export function setupCamera(camera: PerspectiveCamera): void {
24
32
  // every racing game built from this template; three Vector clones a frame was pure garbage.
25
33
  const behind = new Vector3();
26
34
  const desired = new Vector3();
35
+ /** The heading the camera chases, eased toward the travel direction rather than snapped to it. */
36
+ let chaseYaw = 0;
37
+ /** 0 at rest, 1 in a nitro burn: eased in faster than it eases out. */
38
+ let surge = 0;
27
39
  const look = new Vector3();
28
40
  const velocity = new Vector3();
29
41
 
@@ -41,6 +53,7 @@ export function chaseCamera(
41
53
  heading: Vector3,
42
54
  dt: number,
43
55
  carVelocity?: { readonly x: number; y: number; z: number },
56
+ boosting = false,
44
57
  ): void {
45
58
  // The direction the car is travelling, flattened. Under half a metre per second there is no
46
59
  // direction to speak of and the nose is the best available answer.
@@ -50,11 +63,23 @@ export function chaseCamera(
50
63
  if (velocity.lengthSq() > 0.25) behind.copy(velocity).normalize();
51
64
  }
52
65
  if (behind.lengthSq() < 0.0001) behind.set(1, 0, 0);
53
- behind.normalize();
54
- desired.copy(target).addScaledVector(behind, -EYE_BACK);
66
+ // Ease the heading, as the kart kit's camera does (12% of the gap a 60 Hz tick). Snapped to the
67
+ // raw velocity, a kerb, a wall or the 0.5 m/s switch back to the nose swung the view 84° in one
68
+ // tick; eased, a corner still opens up ahead but the camera turns like a camera operator.
69
+ const wanted = Math.atan2(behind.z, behind.x);
70
+ const gap = MathUtils.euclideanModulo(wanted - chaseYaw + Math.PI, Math.PI * 2) - Math.PI;
71
+ chaseYaw = dt >= 1 ? wanted : chaseYaw + gap * MathUtils.damp(0, 1, TURN_RATE, dt);
72
+ behind.set(Math.cos(chaseYaw), 0, Math.sin(chaseYaw));
73
+ surge = dt >= 1 ? 0 : MathUtils.damp(surge, boosting ? 1 : 0, boosting ? 5 : 2.2, dt);
74
+ const fov = BASE_FOV + BOOST_FOV * surge;
75
+ if (Math.abs(camera.fov - fov) > 0.01) {
76
+ camera.fov = fov;
77
+ camera.updateProjectionMatrix();
78
+ }
79
+ desired.copy(target).addScaledVector(behind, -EYE_BACK - BOOST_BACK * surge);
55
80
  desired.y += EYE_UP;
56
81
  if (dt >= 1) camera.position.copy(desired);
57
- else camera.position.lerp(desired, 1 - Math.exp(-dt / 0.2));
82
+ else camera.position.lerp(desired, MathUtils.damp(0, 1, 5, dt));
58
83
  // Look ahead along the same travel direction, so a fast car sees the corner it is entering
59
84
  // rather than the road immediately under its own nose.
60
85
  const speed = Math.hypot(velocity.x, velocity.z);
@@ -6,6 +6,8 @@
6
6
  // Independent CPU implementation. The material samples four Unreal textures that this repository
7
7
  // must not carry, so each one is regenerated here from a seeded noise whose per-channel value
8
8
  // quantiles and correlation lengths match the Unreal texture (measured, see the spec).
9
+ import { MathUtils } from "three";
10
+
9
11
  import {
10
12
  BOTTOM_KM,
11
13
  CAMERA_KM,
@@ -110,7 +112,7 @@ const PROFILE_COEFFICIENTS = [
110
112
  const clamp = (v: number): number => Math.max(0, Math.min(1, v));
111
113
  const smooth = (v: number): number => {
112
114
  const t = clamp(v);
113
- return t * t * (3 - 2 * t);
115
+ return MathUtils.smoothstep(t, 0, 1);
114
116
  };
115
117
  const mod = (a: number, n: number): number => ((a % n) + n) % n;
116
118