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,4 +1,5 @@
1
1
  import { type ICtx, InstancedBatch } from "@threenative/core";
2
+ import { Heightfield } from "@threenative/core/world";
2
3
  import { Area3D, CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
3
4
  import {
4
5
  BoxGeometry,
@@ -10,7 +11,7 @@ import {
10
11
  Vector3,
11
12
  } from "three";
12
13
  import { Boost } from "../kart/boost.js";
13
- import { createMaterials } from "../render/materials.js";
14
+ import { type IGrassMaps, createMaterials } from "../render/materials.js";
14
15
  import { grandstand, treeGeometry, tyreStackGeometry } from "../render/shapes.js";
15
16
  import type { GameState } from "../state.js";
16
17
  import { Checkline, type ChecklineId } from "./Checkline.js";
@@ -18,16 +19,17 @@ import type { IRayHit, IntersectRay } from "./TrackSector.js";
18
19
  import {
19
20
  BARRIER_OFFSET,
20
21
  CIRCUIT,
21
- GRID,
22
- GRID_DISTANCE,
22
+ GRID_SLOTS,
23
23
  HALF,
24
24
  type ICircuitSample,
25
25
  KERB_HEIGHT,
26
26
  KERB_WIDTH,
27
27
  LINE_AT,
28
+ PLAYER_SLOT,
28
29
  ROAD_LIFT,
29
30
  RUNOFF,
30
31
  TRACK_WIDTH,
32
+ gridSlot,
31
33
  groundHeight,
32
34
  lineDistance,
33
35
  terrainHeight,
@@ -200,10 +202,31 @@ function fixedTrimesh(
200
202
 
201
203
  /** The ground is drawn this far below the height the road is laid to. A 5 m grid cannot follow a
202
204
  * banked cross-section exactly, and where it errs high the grass shows through the tarmac in
203
- * patches; sinking it 30 cm turns that into a road bed standing proud of the field. It is drawn,
204
- * never collided, so nothing but the picture depends on it. */
205
+ * patches; sinking it 30 cm turns that into a road bed standing proud of the field. */
205
206
  const TERRAIN_SINK = 0.3;
206
207
 
208
+ /**
209
+ * How far the grass collider sits below the drawn grass under the road.
210
+ *
211
+ * The 5 m ground grid can interpolate a few centimetres above the banked ribbon on a tight corner
212
+ * even after {@link TERRAIN_SINK}; a wheel ray that finds it rides the grass and beaches the car.
213
+ * Under the ribbon that disagreement is hidden by the tarmac, so the collider is lowered there and
214
+ * the drawn grass is left alone — outside the corridor the collider is the drawn surface exactly.
215
+ */
216
+ const GROUND_CLEARANCE = 0.4;
217
+
218
+ /** The widest drivable ribbon plus one cell: every collider vertex that can be under the tarmac. */
219
+ const GROUND_CORRIDOR = HALF + RUNOFF + 1;
220
+
221
+ const groundProbe = new Vector3();
222
+ const groundProjection = {
223
+ curvature: 0,
224
+ distance: 0,
225
+ lateral: 0,
226
+ point: new Vector3(),
227
+ tangent: new Vector3(),
228
+ };
229
+
207
230
  function buildTerrain(ctx: TrackCtx, materials: ReturnType<typeof createMaterials>): void {
208
231
  // The ground is a grid over the circuit's bounding box and a long way past it, its height read
209
232
  // from the same {@link groundHeight} the road is draped on. That is why nothing here can be
@@ -229,15 +252,20 @@ function buildTerrain(ctx: TrackCtx, materials: ReturnType<typeof createMaterial
229
252
  const rows = Math.floor((maxZ + margin - minRow) / step) + 1;
230
253
  const positions = new Float32Array(rows * width * 3);
231
254
  const uvs = new Float32Array(rows * width * 2);
255
+ const heights = new Float32Array(rows * width);
232
256
  const indices: number[] = [];
233
257
  for (let row = 0; row < rows; row += 1) {
234
258
  for (let column = 0; column < width; column += 1) {
235
259
  const x = minColumn + column * step;
236
260
  const z = minRow + row * step;
237
261
  const at = row * width + column;
262
+ const surface = terrainHeight(x, z) - TERRAIN_SINK;
263
+ const lateral = Math.abs(CIRCUIT.project(groundProbe.set(x, 0, z), groundProjection).lateral);
264
+ const height = lateral <= GROUND_CORRIDOR ? surface - GROUND_CLEARANCE : surface;
238
265
  positions[at * 3] = x;
239
- positions[at * 3 + 1] = terrainHeight(x, z) - TERRAIN_SINK;
266
+ positions[at * 3 + 1] = height;
240
267
  positions[at * 3 + 2] = z;
268
+ heights[at] = height;
241
269
  uvs[at * 2] = x / 9;
242
270
  uvs[at * 2 + 1] = z / 9;
243
271
  if (row + 1 < rows && column + 1 < width) {
@@ -250,14 +278,38 @@ function buildTerrain(ctx: TrackCtx, materials: ReturnType<typeof createMaterial
250
278
  geometry.setAttribute("uv", new BufferAttribute(new Float32Array(uvs), 2));
251
279
  geometry.setIndex(indices);
252
280
  geometry.computeVertexNormals();
253
- // **Drawn, not collided.** Everything the wheels can reach is the drivable ribbon, and the
254
- // armco is what bounds it: a car cannot get further than 7.7 m from the centreline, and the
255
- // ribbon is 11 m of it. A second collider under the road can only disagree with the road — a 5 m
256
- // grid cannot follow a banked cross-section exactly, and the disagreement is a 10 cm ridge the
257
- // car rides up and beaches on. Measured, twice, at two different corners.
281
+ // The grass is a surface the wheels can stand on, not just a picture: a car that gets past the
282
+ // armco (a jump, or the rail's old floating collider) lands on it instead of falling to the
283
+ // rescue. One heightfield shares the drawn grid's samples, so the collider is the visible grass
284
+ // outside the ribbon and a clearance below it under the tarmac, where the 5 m grid could
285
+ // otherwise interpolate above the banked road and beach the car. The field layer is deliberate:
286
+ // wheel rays scan it, and `TrackSector`'s road probe does not, so grass is not mistaken for road.
258
287
  const ground = new Mesh(geometry, materials.grass);
259
288
  ground.receiveShadow = true;
260
289
  ctx.add(ground);
290
+ const field = new Heightfield({
291
+ columns: width,
292
+ rows,
293
+ width: (width - 1) * step,
294
+ depth: (rows - 1) * step,
295
+ origin: {
296
+ x: minColumn + ((width - 1) * step) / 2,
297
+ z: minRow + ((rows - 1) * step) / 2,
298
+ },
299
+ heights,
300
+ });
301
+ new RigidBody3D({
302
+ collisionLayer: LAYER.field,
303
+ collisionMask: LAYER.car,
304
+ physics: ctx.physics,
305
+ position: { x: field.origin.x, y: 0, z: field.origin.z },
306
+ shape: CollisionShape3D.heightfield(field.rows, field.columns, field.toColliderHeights(), {
307
+ x: field.width,
308
+ y: 1,
309
+ z: field.depth,
310
+ }),
311
+ type: "fixed",
312
+ });
261
313
  }
262
314
 
263
315
  function buildRoad(
@@ -427,12 +479,13 @@ function buildKerbs(
427
479
  }
428
480
 
429
481
  /**
430
- * The barrier line: armco all the way round, at a distance that follows the corner.
482
+ * The barrier line's **distance** from the centreline, in metres, at one station and side.
431
483
  *
432
484
  * A constant offset does not work on a 10 m hairpin — the inside barrier would land on the
433
485
  * centreline — so the inside follows the local radius and stops 1.2 m past the white line, while
434
- * the outside keeps the full run-off. That is what makes the circuit impossible to leave: there is
435
- * a collider the whole way round, so a car that runs wide loses time instead of losing the race.
486
+ * the outside keeps the full run-off. The caller owns the **sign**: the returned distance is always
487
+ * positive, and forgetting `side *` built both barriers on the right and none on the left — which
488
+ * is exactly how a car left the circuit onto the grass.
436
489
  */
437
490
  function barrierOffset(station: IStation, side: 1 | -1): number {
438
491
  const curvature = station.sample.curvature;
@@ -446,41 +499,63 @@ function buildBarriers(
446
499
  materials: ReturnType<typeof createMaterials>,
447
500
  ): void {
448
501
  const coarse = all.filter((_station, index) => index % 3 === 0);
449
- const rows: Vector3[][] = [];
450
- for (const station of coarse) {
451
- for (const side of [1, -1] as const) {
452
- const offset = barrierOffset(station, side);
453
- const inner = offset - 0.14;
454
- const outer = offset + 0.14;
502
+
503
+ // Two rails, one per side. They cannot be one strip: a strip's rows run along the track, so
504
+ // alternating the sides station by station would stitch a deck across the circuit.
505
+ for (const side of [1, -1] as const) {
506
+ const rail = coarse.map((station) => {
507
+ const offset = side * barrierOffset(station, side);
508
+ const inner = offset - side * 0.14;
509
+ const outer = offset + side * 0.14;
455
510
  const low = 0.4;
456
511
  const high = 1.04;
457
- rows.push(
458
- side > 0
459
- ? [
460
- onGround(station, inner, low),
461
- onGround(station, outer, low),
462
- onGround(station, outer, high),
463
- onGround(station, inner, high),
464
- ]
465
- : [
466
- onGround(station, outer, low),
467
- onGround(station, inner, low),
468
- onGround(station, inner, high),
469
- onGround(station, outer, high),
470
- ],
471
- );
472
- }
512
+ // Closed profile: the fifth point is the first again, so the inner face exists. Without it
513
+ // the rail is an open shell, and on the side whose winding faces away it is neither visible
514
+ // nor collidable from the track.
515
+ return side > 0
516
+ ? [
517
+ onGround(station, inner, low),
518
+ onGround(station, outer, low),
519
+ onGround(station, outer, high),
520
+ onGround(station, inner, high),
521
+ onGround(station, inner, low),
522
+ ]
523
+ : [
524
+ onGround(station, outer, low),
525
+ onGround(station, inner, low),
526
+ onGround(station, inner, high),
527
+ onGround(station, outer, high),
528
+ onGround(station, outer, low),
529
+ ];
530
+ });
531
+ const armco = new Mesh(
532
+ quadStrip(looped(rail), (row, column) => [column, row * 3.3]),
533
+ materials.armco,
534
+ );
535
+ armco.castShadow = true;
536
+ ctx.add(armco);
537
+
538
+ // The rail floats 40 cm above the ground and the car's chassis is lower than that: it drove
539
+ // under the rail. This wall starts below the drawn grass and ends at the rail's top, with both
540
+ // windings so a solver that culls back faces still meets it from the track. It is never drawn.
541
+ const wall = coarse.map((station) => {
542
+ const offset = side * barrierOffset(station, side);
543
+ const low = onGround(station, offset, -TERRAIN_SINK - 0.5);
544
+ const high = onGround(station, offset, 1.04);
545
+ // [low, high] then its mirror: the degenerate top edge between them has no area.
546
+ return [low, high, high, low];
547
+ });
548
+ const barrier = new Mesh(
549
+ quadStrip(looped(wall), (row, column) => [column, row * 3.3]),
550
+ materials.armco,
551
+ );
552
+ barrier.visible = false;
553
+ ctx.add(barrier);
554
+ fixedTrimesh(ctx, barrier, LAYER.barrier, `armco-${side > 0 ? "right" : "left"}`);
473
555
  }
474
- const armco = new Mesh(
475
- quadStrip(looped(rows), (row, column) => [column, row * 3.3]),
476
- materials.armco,
477
- );
478
- armco.castShadow = true;
479
- ctx.add(armco);
480
- fixedTrimesh(ctx, armco, LAYER.barrier, "armco");
481
556
 
482
- // The posts. Decoration: the rail above them is the collider, and a hundred-odd fixed bodies for
483
- // the same line was the cost `buildStaticColliders` used to pay.
557
+ // The posts. Decoration: the wall is the collider, and a hundred-odd fixed bodies for the same
558
+ // line was the cost `buildStaticColliders` used to pay.
484
559
  const posts = new InstancedBatch({
485
560
  geometry: new BoxGeometry(0.16, 1.2, 0.16),
486
561
  material: materials.structure,
@@ -488,7 +563,7 @@ function buildBarriers(
488
563
  for (const station of all) {
489
564
  if (station.distance % 8 >= CIRCUIT.spacing) continue;
490
565
  for (const side of [1, -1] as const) {
491
- const at = onGround(station, barrierOffset(station, side), 0.6);
566
+ const at = onGround(station, side * barrierOffset(station, side), 0.6);
492
567
  posts.place({
493
568
  position: [at.x, at.y, at.z],
494
569
  rotation: [0, Math.atan2(station.sample.right.z, station.sample.right.x), 0],
@@ -582,7 +657,8 @@ function boostPad(
582
657
  *
583
658
  * Delete a line here and that piece of furniture is gone; nothing else depends on it. Every
584
659
  * repeated prop goes into an `InstancedBatch` and every static run into one merged mesh, because
585
- * the performance playtest bounds this circuit at 330 draw calls and 105,000 triangles.
660
+ * the performance playtest bounds the race at 330 draw calls and 135,000 triangles: the circuit
661
+ * and six cars, about 5,300 triangles each (measured 126,202 with the full field).
586
662
  */
587
663
  function dressCircuit(
588
664
  ctx: TrackCtx,
@@ -812,16 +888,14 @@ function dressCircuit(
812
888
  }
813
889
  }
814
890
 
815
- export function gridPosition(which: "player" | "rival", target: Vector3): Vector3 {
816
- const distance = GRID_DISTANCE[which];
817
- const station = stationAt(distance);
818
- const at = onTrack(station, GRID[which], 0.05, target);
819
- return at;
891
+ export function gridPosition(slot: number, target: Vector3): Vector3 {
892
+ const { distance, side } = gridSlot(slot);
893
+ return onTrack(stationAt(distance), side, 0.05, target);
820
894
  }
821
895
 
822
896
  /** The direction a car on the grid is pointing: down the main straight. */
823
- export function gridHeading(which: "player" | "rival"): number {
824
- const sample = CIRCUIT.at(GRID_DISTANCE[which], CIRCUIT.createSample());
897
+ export function gridHeading(slot: number): number {
898
+ const sample = CIRCUIT.at(gridSlot(slot).distance, CIRCUIT.createSample());
825
899
  return Math.atan2(sample.tangent.z, sample.tangent.x);
826
900
  }
827
901
 
@@ -888,8 +962,8 @@ export interface ITrackBuild {
888
962
  readonly roadMeshes: readonly Mesh[];
889
963
  }
890
964
 
891
- export function buildTrack(ctx: TrackCtx): ITrackBuild {
892
- const materials = createMaterials();
965
+ export function buildTrack(ctx: TrackCtx, grass?: IGrassMaps): ITrackBuild {
966
+ const materials = createMaterials(grass);
893
967
  buildTerrain(ctx, materials);
894
968
  const all = buildRoad(ctx, materials);
895
969
  buildKerbs(ctx, all, materials);
@@ -914,8 +988,8 @@ export function buildTrack(ctx: TrackCtx): ITrackBuild {
914
988
 
915
989
  export {
916
990
  CIRCUIT,
917
- GRID,
918
- GRID_DISTANCE,
991
+ GRID_SLOTS,
992
+ PLAYER_SLOT,
919
993
  HALF,
920
994
  KERB_HEIGHT,
921
995
  KERB_WIDTH,
@@ -23,6 +23,10 @@ export interface ITrackSectorOptions {
23
23
  /** Seconds below {@link ITrackSectorOptions.stallSpeed} before a beached car is recovered. */
24
24
  readonly stallRescueDelay?: number;
25
25
  readonly stallSpeed?: number;
26
+ /** The ground's height here, so a car that leaves the surface can be caught before it falls. */
27
+ readonly groundAt?: (x: number, z: number) => number;
28
+ /** Metres below the ground at which a car is falling, not driving. */
29
+ readonly fallDepth?: number;
26
30
  }
27
31
 
28
32
  /** Records a grounded transform and returns a racer to it after leaving the road. */
@@ -35,12 +39,15 @@ export class TrackSector {
35
39
  #stalledTime = 0;
36
40
  #hasOnRoadSample = false;
37
41
  #hasMoved = false;
42
+ #falling = false;
38
43
  readonly #route: CircuitLine;
39
44
  readonly #intersectRay: IntersectRay;
40
45
  readonly #rescueDelay: number;
41
46
  readonly #rayHeight: number;
42
47
  readonly #stallRescueDelay: number;
43
48
  readonly #stallSpeed: number;
49
+ readonly #groundAt: ((x: number, z: number) => number) | undefined;
50
+ readonly #fallDepth: number;
44
51
  readonly #origin = new Vector3();
45
52
  readonly #direction = new Vector3(0, -1, 0);
46
53
  readonly #projection = {
@@ -58,7 +65,10 @@ export class TrackSector {
58
65
  this.#rayHeight = options.rayHeight ?? 3;
59
66
  this.#stallRescueDelay = options.stallRescueDelay ?? 1.2;
60
67
  this.#stallSpeed = options.stallSpeed ?? 0.6;
68
+ this.#groundAt = options.groundAt;
69
+ this.#fallDepth = options.fallDepth ?? 1.2;
61
70
  if (!(this.#rescueDelay > 0)) throw new Error("TrackSector rescueDelay must be positive.");
71
+ if (!(this.#fallDepth > 0)) throw new Error("TrackSector fallDepth must be positive.");
62
72
  if (!(this.#stallRescueDelay > 0))
63
73
  throw new Error("TrackSector stallRescueDelay must be positive.");
64
74
  }
@@ -90,6 +100,11 @@ export class TrackSector {
90
100
  this.#offRoadTime = 0;
91
101
  return true;
92
102
  }
103
+ // Off the surface is a run wide; **below** it is a car with no world under its wheels. The grass
104
+ // is a collider now, so this is the last-resort net for a jump or a future gap, caught the tick
105
+ // it happens rather than after the run-wide delay, which by then is seconds of falling.
106
+ const ground = this.#groundAt?.(position.x, position.z);
107
+ this.#falling = ground !== undefined && position.y < ground - this.#fallDepth;
93
108
  this.#offRoadTime += dt;
94
109
  return false;
95
110
  }
@@ -105,7 +120,9 @@ export class TrackSector {
105
120
  get shouldRescue(): boolean {
106
121
  return (
107
122
  this.#hasOnRoadSample &&
108
- (this.#offRoadTime >= this.#rescueDelay || this.#stalledTime >= this.#stallRescueDelay)
123
+ (this.#falling ||
124
+ this.#offRoadTime >= this.#rescueDelay ||
125
+ this.#stalledTime >= this.#stallRescueDelay)
109
126
  );
110
127
  }
111
128
 
@@ -114,6 +131,7 @@ export class TrackSector {
114
131
  rescueToLastValid(target, this.lastOnRoadPosition, this.lastOnRoadHeading);
115
132
  this.#offRoadTime = 0;
116
133
  this.#stalledTime = 0;
134
+ this.#falling = false;
117
135
  return true;
118
136
  }
119
137
  }
@@ -1,4 +1,4 @@
1
- import { CatmullRomCurve3, Vector3 } from "three";
1
+ import { CatmullRomCurve3, MathUtils, Vector3 } from "three";
2
2
 
3
3
  /**
4
4
  * The circuit, once.
@@ -126,7 +126,7 @@ function bankFade(radius: number): number {
126
126
  if (!Number.isFinite(radius) || radius >= BANK_FULL_RADIUS) return 1;
127
127
  if (radius <= BANK_NONE_RADIUS) return 0;
128
128
  const fade = (radius - BANK_NONE_RADIUS) / (BANK_FULL_RADIUS - BANK_NONE_RADIUS);
129
- return fade * fade * (3 - 2 * fade);
129
+ return MathUtils.smoothstep(fade, 0, 1);
130
130
  }
131
131
 
132
132
  /**
@@ -435,33 +435,39 @@ export function terrainHeight(x: number, z: number): number {
435
435
  const plane = centre.point.y - ROAD_LIFT - projection.lateral * centre.bank;
436
436
  if (lateral <= CORRIDOR) return plane;
437
437
  const blend = (lateral - CORRIDOR) / (BLEND_END - CORRIDOR);
438
- return plane + (open - plane) * blend * blend * (3 - 2 * blend);
438
+ return plane + (open - plane) * MathUtils.smoothstep(blend, 0, 1);
439
439
  }
440
440
 
441
441
  /** Where the start/finish line, the sectors and the grid are, as a fraction of the lap. */
442
442
  export const LINE_AT = {
443
443
  finish: 0.06,
444
444
  gridFar: 0.052,
445
- gridNear: 0.042,
446
445
  sector1: 0.28,
447
446
  sector2: 0.55,
448
447
  } as const;
449
448
 
450
449
  /**
451
- * The starting grid: the player second, the rival on pole, both on the main straight and both
452
- * short of the line, so the first gate either car meets is the one the lap is counted on.
450
+ * The starting grid: six cars on the main straight, staggered, pole first, all short of the line
451
+ * so the first gate any car meets is the one the lap is counted on.
453
452
  *
454
- * `player` sits 2.2 m to the left of the centreline and `rival` 2.2 m to the right, and the rival
455
- * is the further down the straight. Two metres aside on a 9 m road is two cars side by side and a
456
- * clear line between them — the old grid put both cars on the racing line, which is a rear-end at
457
- * the first corner.
453
+ * Slots alternate 2.2 m right and left of the centreline, {@link GRID_PITCH} apart, so two
454
+ * neighbours are side by side with a clear line between them — a grid on the racing line is a
455
+ * rear-end at the first corner. The player starts last and races through the field.
458
456
  */
459
- export const GRID = { player: -2.2, rival: 2.2 } as const;
457
+ const GRID_PITCH = 5;
458
+ export const GRID_SLOTS: ReadonlyArray<{ readonly distance: number; readonly side: number }> =
459
+ Array.from({ length: 6 }, (_, slot) => ({
460
+ distance: lineDistance(LINE_AT.gridFar) - slot * GRID_PITCH,
461
+ side: slot % 2 === 0 ? 2.2 : -2.2,
462
+ }));
463
+ export const PLAYER_SLOT = GRID_SLOTS.length - 1;
460
464
 
461
- export const GRID_DISTANCE = {
462
- player: lineDistance(LINE_AT.gridNear),
463
- rival: lineDistance(LINE_AT.gridFar),
464
- } as const;
465
+ /** A slot's own entry, which fails at the call rather than placing a car at `NaN`. */
466
+ export function gridSlot(slot: number): { readonly distance: number; readonly side: number } {
467
+ const entry = GRID_SLOTS[slot];
468
+ if (entry === undefined) throw new Error(`Grid slot ${slot} does not exist.`);
469
+ return entry;
470
+ }
465
471
 
466
472
  export function lineDistance(fraction: number): number {
467
473
  return fraction * CIRCUIT.totalLength;
@@ -1,6 +1,5 @@
1
1
  import { UiLayer } from "@threenative/ui";
2
2
  import { Hud } from "./Hud.js";
3
- import { Menu } from "./Menu.js";
4
3
 
5
4
  /**
6
5
  * Everything the player sees that is not the scene.
@@ -14,7 +13,6 @@ export function GameUi() {
14
13
  return (
15
14
  <UiLayer>
16
15
  <Hud />
17
- <Menu />
18
16
  </UiLayer>
19
17
  );
20
18
  }