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
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.13",
23
- "@threenative/physics": "0.3.13",
24
- "@threenative/ui": "0.3.13",
22
+ "@threenative/core": ">=0.3.16",
23
+ "@threenative/physics": ">=0.3.16",
24
+ "@threenative/ui": ">=0.3.16",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "three": "0.187.0"
@@ -30,11 +30,11 @@
30
30
  "@tailwindcss/vite": "4.3.3",
31
31
  "@vitejs/plugin-react": "6.0.5",
32
32
  "@types/three": "0.187.0",
33
- "@threenative/assets": "0.3.14",
34
- "@threenative/playtest": "0.3.13",
33
+ "@threenative/assets": ">=0.3.17",
34
+ "@threenative/playtest": ">=0.3.16",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
- "create-threenative": "0.2.18",
37
+ "create-threenative": "0.2.21",
38
38
  "esbuild": "0.27.0",
39
39
  "playwright": "1.62.1",
40
40
  "tailwindcss": "4.3.3",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.13"
48
+ "@threenative/runtime-native": ">=0.3.16"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -1,4 +1,4 @@
1
- import { type IAssetLoader, WaveField } from "@threenative/core";
1
+ import { type IAssetLoader, WaveField, createRandom } from "@threenative/core";
2
2
  import {
3
3
  Box3,
4
4
  BoxGeometry,
@@ -228,13 +228,8 @@ function boulderGeometry(size: number, rng: () => number): BufferGeometry {
228
228
  }
229
229
 
230
230
  export function makeRng(seed: number): () => number {
231
- let state = seed >>> 0;
232
- return () => {
233
- state = (state * 1664525 + 1013904223) >>> 0;
234
- return state / 0x1_0000_0000;
235
- };
231
+ return createRandom(seed);
236
232
  }
237
-
238
233
  /**
239
234
  * The island planted: drawn from `site` on a run that has nothing stored, and read back from
240
235
  * `memo` on the next run of this build, so `buildPlanting` has the same placements either way.
@@ -1,4 +1,5 @@
1
1
  import { Heightfield } from "@threenative/core/world";
2
+ import { MathUtils } from "three";
2
3
 
3
4
  /** A rectangle [x min, x max, z min, z max] or a disc [x, z, radius] of level ground at y = 0. */
4
5
  export type LevelZone =
@@ -35,7 +36,7 @@ const HEADLAND = { x: 2, z: -60, rx: 30, rz: 26 } as const;
35
36
  const clamp01 = (t: number): number => Math.min(1, Math.max(0, t));
36
37
  const smooth = (from: number, to: number, value: number): number => {
37
38
  const t = clamp01((value - from) / (to - from));
38
- return t * t * (3 - 2 * t);
39
+ return MathUtils.smoothstep(t, 0, 1);
39
40
  };
40
41
  const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
41
42
 
@@ -151,10 +151,10 @@ export function createOrbitCamera(camera: PerspectiveCamera): IOrbitCamera {
151
151
  // Running at the camera does not spin it round: only travel within 120° of the view swings it.
152
152
  if (Math.abs(turn) < (Math.PI * 2) / 3) {
153
153
  const rate = CAMERA_RIG.swingRate * Math.min(1, speed / 9.6);
154
- yaw += turn * (1 - Math.exp(-dt * rate));
154
+ yaw = MathUtils.damp(yaw, yaw + turn, rate, dt);
155
155
  }
156
156
  }
157
- place(target, probe, 1 - Math.exp(-dt * CAMERA_RIG.followRate));
157
+ place(target, probe, MathUtils.damp(0, 1, CAMERA_RIG.followRate, dt));
158
158
  },
159
159
  debug() {
160
160
  return { closest, cuts, distance, elevation, peakElevation, pulledIn, tilt, yaw };
@@ -3,7 +3,7 @@
3
3
  // The island's ground: one terrain mesh whose vertex attributes say where grass, worn grass, the
4
4
  // sandy dirt path, beach sand and rock lie, by height, slope and distance to the path. The textures
5
5
  // and the blend are `groundMaterial` in surface.ts.
6
- import { BufferAttribute, BufferGeometry, Color, Mesh } from "three";
6
+ import { BufferAttribute, BufferGeometry, Color, MathUtils, Mesh } from "three";
7
7
  import { lit, seeded } from "./materials.js";
8
8
  import { C } from "./palette.js";
9
9
 
@@ -29,8 +29,8 @@ export function valueNoise(cells: number, seed: number): (u: number, v: number)
29
29
  const y = v * cells;
30
30
  const i = Math.floor(x);
31
31
  const j = Math.floor(y);
32
- const fx = (x - i) * (x - i) * (3 - 2 * (x - i));
33
- const fy = (y - j) * (y - j) * (3 - 2 * (y - j));
32
+ const fx = MathUtils.smoothstep(x - i, 0, 1);
33
+ const fy = MathUtils.smoothstep(y - j, 0, 1);
34
34
  const top = at(i, j) + (at(i + 1, j) - at(i, j)) * fx;
35
35
  const bottom = at(i, j + 1) + (at(i + 1, j + 1) - at(i, j + 1)) * fx;
36
36
  return top + (bottom - top) * fy;
@@ -39,7 +39,7 @@ export function valueNoise(cells: number, seed: number): (u: number, v: number)
39
39
 
40
40
  const smooth = (from: number, to: number, value: number): number => {
41
41
  const t = Math.min(1, Math.max(0, (value - from) / (to - from)));
42
- return t * t * (3 - 2 * t);
42
+ return MathUtils.smoothstep(t, 0, 1);
43
43
  };
44
44
 
45
45
  /**
@@ -366,7 +366,7 @@ export function createHero(): IHero {
366
366
  update(pose: IHeroPose): void {
367
367
  time += pose.dt;
368
368
  const run = Math.min(1, pose.speed / 9.6);
369
- const k = 1 - Math.exp(-pose.dt * 18);
369
+ const k = MathUtils.damp(0, 1, 18, pose.dt);
370
370
  let pitch = 0;
371
371
  let roll = 0;
372
372
  let squash = 1;
@@ -186,7 +186,6 @@ export function seeded(seed: number): () => number {
186
186
  return state / 0x1_0000_0000;
187
187
  };
188
188
  }
189
-
190
189
  /** The surfaces the island is made of, resolved once. */
191
190
  export function createMaterials() {
192
191
  return {
@@ -11,6 +11,7 @@ import {
11
11
  EquirectangularReflectionMapping,
12
12
  FogExp2,
13
13
  LinearFilter,
14
+ MathUtils,
14
15
  RGBAFormat,
15
16
  SRGBColorSpace,
16
17
  type Scene,
@@ -39,8 +40,8 @@ const LATTICE = (() => {
39
40
  function noise(x: number, y: number): number {
40
41
  const i = Math.floor(x);
41
42
  const j = Math.floor(y);
42
- const fx = (x - i) * (x - i) * (3 - 2 * (x - i));
43
- const fy = (y - j) * (y - j) * (3 - 2 * (y - j));
43
+ const fx = MathUtils.smoothstep(x - i, 0, 1);
44
+ const fy = MathUtils.smoothstep(y - j, 0, 1);
44
45
  const i0 = i & 255;
45
46
  const i1 = (i + 1) & 255;
46
47
  const j0 = (j & 255) << 8;
@@ -79,7 +80,7 @@ function density(x: number, y: number): number {
79
80
 
80
81
  const smooth = (from: number, to: number, value: number): number => {
81
82
  const t = Math.min(1, Math.max(0, (value - from) / (to - from)));
82
- return t * t * (3 - 2 * t);
83
+ return MathUtils.smoothstep(t, 0, 1);
83
84
  };
84
85
 
85
86
  /**
@@ -19,8 +19,8 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.13",
23
- "@threenative/ui": "0.3.13",
22
+ "@threenative/core": ">=0.3.16",
23
+ "@threenative/ui": ">=0.3.16",
24
24
  "react": "19.2.0",
25
25
  "react-dom": "19.2.0",
26
26
  "three": "0.187.0"
@@ -29,11 +29,11 @@
29
29
  "@tailwindcss/vite": "4.3.3",
30
30
  "@vitejs/plugin-react": "6.0.5",
31
31
  "@types/three": "0.187.0",
32
- "@threenative/assets": "0.3.14",
33
- "@threenative/playtest": "0.3.13",
32
+ "@threenative/assets": ">=0.3.17",
33
+ "@threenative/playtest": ">=0.3.16",
34
34
  "@types/react": "19.2.0",
35
35
  "@types/react-dom": "19.2.0",
36
- "create-threenative": "0.2.18",
36
+ "create-threenative": "0.2.21",
37
37
  "esbuild": "0.27.0",
38
38
  "playwright": "1.62.1",
39
39
  "tailwindcss": "4.3.3",
@@ -44,7 +44,7 @@
44
44
  "eslint": "10.13.0"
45
45
  },
46
46
  "optionalDependencies": {
47
- "@threenative/runtime-native": "0.3.13"
47
+ "@threenative/runtime-native": ">=0.3.16"
48
48
  },
49
49
  "overrides": {
50
50
  "sharp": ">=0.35.4",
@@ -1,3 +1,4 @@
1
+ import { MathUtils } from "three";
1
2
  import { type ICourse, SURFACE_DRAG, type Surface } from "../track/Course.js";
2
3
 
3
4
  /**
@@ -327,7 +328,7 @@ export class Kart {
327
328
  Math.max(0, 1 - resist) *
328
329
  (1 + this.boost + this.miniTurbo + this.catchUp);
329
330
  if (brake && this.throttle === 0 && this.speed < 0.5) target = -f.reverse;
330
- this.speed += (target - this.speed) * (1 - Math.exp(-ticks / f.lagTicks));
331
+ this.speed = MathUtils.damp(this.speed, target, 1 / f.lagTicks, ticks);
331
332
  }
332
333
 
333
334
  // Hop and drift. A press while grounded hops; with the stick held and enough speed the hop
@@ -15,6 +15,7 @@ import {
15
15
  Group,
16
16
  IcosahedronGeometry,
17
17
  InstancedMesh,
18
+ MathUtils,
18
19
  Matrix4,
19
20
  Mesh,
20
21
  MeshStandardMaterial,
@@ -521,7 +522,7 @@ export function buildCourseView(course: ICourse, seed = 734): ICourseView {
521
522
 
522
523
  function smooth(edge0: number, edge1: number, x: number): number {
523
524
  const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
524
- return t * t * (3 - 2 * t);
525
+ return MathUtils.smoothstep(t, 0, 1);
525
526
  }
526
527
 
527
528
  /** True when x/z is at least `clearance` metres from every sample of the line. */
@@ -10,6 +10,8 @@
10
10
  */
11
11
 
12
12
  /** Metres between samples of the centre line. */
13
+ import { MathUtils } from "three";
14
+
13
15
  export const STEP = 1;
14
16
 
15
17
  /** The lateral profile, in metres from the centre line. */
@@ -69,7 +71,7 @@ function plateau(s: number, at: number, length: number, flat: number, ramp: numb
69
71
 
70
72
  function smooth(edge0: number, edge1: number, x: number): number {
71
73
  const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
72
- return t * t * (3 - 2 * t);
74
+ return MathUtils.smoothstep(t, 0, 1);
73
75
  }
74
76
 
75
77
  export interface ICourse {
@@ -19,15 +19,15 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.13",
23
- "@threenative/physics": "0.3.13",
22
+ "@threenative/core": ">=0.3.16",
23
+ "@threenative/physics": ">=0.3.16",
24
24
  "three": "0.187.0"
25
25
  },
26
26
  "devDependencies": {
27
- "@threenative/assets": "0.3.14",
28
- "@threenative/playtest": "0.3.13",
27
+ "@threenative/assets": ">=0.3.17",
28
+ "@threenative/playtest": ">=0.3.16",
29
29
  "@types/three": "0.187.0",
30
- "create-threenative": "0.2.18",
30
+ "create-threenative": "0.2.21",
31
31
  "esbuild": "0.27.0",
32
32
  "playwright": "1.62.1",
33
33
  "typescript": "7.0.2",
@@ -37,7 +37,7 @@
37
37
  "eslint": "10.13.0"
38
38
  },
39
39
  "optionalDependencies": {
40
- "@threenative/runtime-native": "0.3.13"
40
+ "@threenative/runtime-native": ">=0.3.16"
41
41
  },
42
42
  "overrides": {
43
43
  "sharp": ">=0.35.4",
@@ -1,5 +1,5 @@
1
1
  // Generated for you. Camera framing is yours to edit.
2
- import { type PerspectiveCamera, Vector3 } from "three";
2
+ import { MathUtils, type PerspectiveCamera, Vector3 } from "three";
3
3
 
4
4
  /** Where the camera sits relative to the player's body centre: up and behind, over the shoulder. */
5
5
  const OFFSET = new Vector3(0.6, 1.4, 4.6);
@@ -51,7 +51,7 @@ export function followCamera(
51
51
  const wall = probe(_aim, _desired);
52
52
  if (wall === undefined) {
53
53
  const gap = camera.position.distanceTo(_desired);
54
- const step = Math.max(gap * (1 - Math.exp(-dt * 8)), SETTLE_SPEED * dt);
54
+ const step = Math.max(gap * MathUtils.damp(0, 1, 8, dt), SETTLE_SPEED * dt);
55
55
  if (gap <= 2 * step) camera.position.copy(_desired);
56
56
  else camera.position.lerp(_desired, step / gap);
57
57
  } else {
@@ -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
 
@@ -11,6 +11,7 @@ import {
11
11
  Float32BufferAttribute,
12
12
  FrontSide,
13
13
  LinearMipmapLinearFilter,
14
+ MathUtils,
14
15
  MeshStandardMaterial,
15
16
  RepeatWrapping,
16
17
  SRGBColorSpace,
@@ -84,8 +85,8 @@ function grainNormalTexture(size = 128): DataTexture {
84
85
  const y0 = Math.floor(v);
85
86
  const fx = u - x0;
86
87
  const fy = v - y0;
87
- const sx = fx * fx * (3 - 2 * fx);
88
- const sy = fy * fy * (3 - 2 * fy);
88
+ const sx = MathUtils.smoothstep(fx, 0, 1);
89
+ const sy = MathUtils.smoothstep(fy, 0, 1);
89
90
  const at = (i: number, j: number): number =>
90
91
  values[(((j % count) + count) % count) * count + (((i % count) + count) % count)] ?? 0;
91
92
  const top = at(x0, y0) + (at(x0 + 1, y0) - at(x0, y0)) * sx;
@@ -15,6 +15,9 @@ const MOVE_RADIUS = 72;
15
15
  const BUTTON_RADIUS = 62;
16
16
  const EDGE = 36;
17
17
 
18
+ /** The knob's next point: `update` runs every frame, so it uses one instance. */
19
+ const knobPosition = new Vector2();
20
+
18
21
  export interface ITouchPointer {
19
22
  readonly position: Vector2;
20
23
  }
@@ -111,13 +114,11 @@ export class TouchControls {
111
114
  }
112
115
 
113
116
  const center = this.#hasMoveAnchor ? this.#moveAnchor : this.#resting;
114
- place(
115
- this.#moveKnob,
116
- new Vector2(
117
- center.x + this.#input.move.x * MOVE_RADIUS,
118
- center.y - this.#input.move.y * MOVE_RADIUS,
119
- ),
117
+ knobPosition.set(
118
+ center.x + this.#input.move.x * MOVE_RADIUS,
119
+ center.y - this.#input.move.y * MOVE_RADIUS,
120
120
  );
121
+ place(this.#moveKnob, knobPosition);
121
122
  this.#jump.material = jump ? this.#activeMaterial : this.#idleMaterial;
122
123
  this.#input.jumpPressed = jump && !this.#wasJump;
123
124
  this.#wasJump = jump;
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.13",
23
- "@threenative/physics": "0.3.13",
24
- "@threenative/ui": "0.3.13",
22
+ "@threenative/core": ">=0.3.16",
23
+ "@threenative/physics": ">=0.3.16",
24
+ "@threenative/ui": ">=0.3.16",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "three": "0.187.0"
@@ -30,11 +30,11 @@
30
30
  "@tailwindcss/vite": "4.3.3",
31
31
  "@vitejs/plugin-react": "6.0.5",
32
32
  "@types/three": "0.187.0",
33
- "@threenative/assets": "0.3.14",
34
- "@threenative/playtest": "0.3.13",
33
+ "@threenative/assets": ">=0.3.17",
34
+ "@threenative/playtest": ">=0.3.16",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
- "create-threenative": "0.2.18",
37
+ "create-threenative": "0.2.21",
38
38
  "esbuild": "0.27.0",
39
39
  "playwright": "1.62.1",
40
40
  "tailwindcss": "4.3.3",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.13"
48
+ "@threenative/runtime-native": ">=0.3.16"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -24,7 +24,10 @@
24
24
  ],
25
25
  "assert": {
26
26
  "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
27
- "resources": [{ "changed": true, "gte": 3, "id": "state", "path": "coins" }],
27
+ "resources": [
28
+ { "changed": true, "gte": 3, "id": "state", "path": "coins" },
29
+ { "changed": true, "gte": 1, "id": "state", "path": "coins" }
30
+ ],
28
31
  "signals": [{ "entity": "player", "minCount": 3, "name": "collected" }]
29
32
  }
30
33
  }
@@ -1,3 +1,4 @@
1
+ import { createRandom } from "@threenative/core";
1
2
  import {
2
3
  BoxGeometry,
3
4
  ConeGeometry,
@@ -18,13 +19,8 @@ import { waterfall } from "../render/waterfall.js";
18
19
 
19
20
  /** Deterministic, so the route is the same course every run. */
20
21
  export function makeRng(seed = 90210): () => number {
21
- let state = seed >>> 0;
22
- return () => {
23
- state = (state * 1664525 + 1013904223) >>> 0;
24
- return state / 4294967296;
25
- };
22
+ return createRandom(seed);
26
23
  }
27
-
28
24
  export interface IStage {
29
25
  /** The one root to add to the scene and hand to `buildStaticColliders`. */
30
26
  readonly group: Group;
@@ -217,7 +217,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
217
217
  // The coin lines are the route's teaching: one along the floor, one arced over every jump.
218
218
  // The opening nine weave, but inside the reach a straight run actually collects: a coin the
219
219
  // player can see and cannot take is worse than no coin at all.
220
- for (let i = 0; i < 9; i += 1) addPickup("coin", -5 + i * 1.6, 1.25, Math.sin(i * 0.9) * 0.6);
220
+ // The line starts one step past the spawn: a coin under the spawn was collected on frame 1.
221
+ for (let i = 1; i <= 9; i += 1) addPickup("coin", -5 + i * 1.6, 1.25, Math.sin(i * 0.9) * 0.6);
221
222
  for (let i = 0; i < 8; i += 1) addPickup("coin", 12 + i * 2, 1.25, i % 2 ? 1.6 : -1.4);
222
223
  for (const point of coinArc([30, 1.3, 0], [34, 2.8, 0], 6, 1.6))
223
224
  addPickup("coin", point.x, point.y, point.z);
@@ -18,9 +18,9 @@
18
18
  "format:check": "biome format src"
19
19
  },
20
20
  "dependencies": {
21
- "@threenative/core": "0.3.13",
22
- "@threenative/physics": "0.3.13",
23
- "@threenative/ui": "0.3.13",
21
+ "@threenative/core": ">=0.3.16",
22
+ "@threenative/physics": ">=0.3.16",
23
+ "@threenative/ui": ">=0.3.16",
24
24
  "react": "19.2.0",
25
25
  "react-dom": "19.2.0",
26
26
  "three": "0.187.0"
@@ -28,13 +28,13 @@
28
28
  "devDependencies": {
29
29
  "@gltf-transform/cli": "4.4.2",
30
30
  "@tailwindcss/vite": "4.3.3",
31
- "@threenative/assets": "0.3.14",
32
- "@threenative/playtest": "0.3.13",
31
+ "@threenative/assets": ">=0.3.17",
32
+ "@threenative/playtest": ">=0.3.16",
33
33
  "@types/react": "19.2.0",
34
34
  "@types/react-dom": "19.2.0",
35
35
  "@types/three": "0.187.0",
36
36
  "@vitejs/plugin-react": "6.0.5",
37
- "create-threenative": "0.2.18",
37
+ "create-threenative": "0.2.21",
38
38
  "esbuild": "0.27.0",
39
39
  "playwright": "1.62.1",
40
40
  "tailwindcss": "4.3.3",
@@ -44,7 +44,7 @@
44
44
  "eslint": "10.13.0"
45
45
  },
46
46
  "optionalDependencies": {
47
- "@threenative/runtime-native": "0.3.13"
47
+ "@threenative/runtime-native": ">=0.3.16"
48
48
  },
49
49
  "overrides": {
50
50
  "sharp": ">=0.35.4",
@@ -1,6 +1,6 @@
1
1
  import type { ICtx } from "@threenative/core";
2
2
  import { CharacterBody3D, CollisionShape3D, type IPhysicsContext } from "@threenative/physics";
3
- import { Group, Vector3 } from "three";
3
+ import { Group, MathUtils, Vector3 } from "three";
4
4
  import { wardenFigure } from "../render/warden.js";
5
5
  import type { GameState } from "../state.js";
6
6
  import { WARDEN_MASK } from "./Crate.js";
@@ -90,12 +90,12 @@ export class Warden {
90
90
  // Shortest-arc turn, framerate independent, so the figure faces the shove rather than
91
91
  // snapping between the four arrow directions.
92
92
  const delta = Math.atan2(Math.sin(target - this.#facing), Math.cos(target - this.#facing));
93
- this.#facing += delta * (1 - Math.exp(-dt / 0.06));
93
+ this.#facing = MathUtils.damp(this.#facing, this.#facing + delta, 1 / 0.06, dt);
94
94
  this.#figure.rotation.y = this.#facing;
95
95
  }
96
96
  // Lean into the push. Purely cosmetic, and it is most of what makes the shove read.
97
97
  const lean = Math.min(0.28, Math.hypot(move.x, move.z) * 0.28);
98
- this.#figure.rotation.x += (lean - this.#figure.rotation.x) * (1 - Math.exp(-dt / 0.09));
98
+ this.#figure.rotation.x = MathUtils.damp(this.#figure.rotation.x, lean, 1 / 0.09, dt);
99
99
  }
100
100
 
101
101
  teleport(position: { readonly x: number; readonly y: number; readonly z: number }): void {
@@ -7,7 +7,7 @@
7
7
  // It still breathes. `settle` eases the framing in over the opening drop, and `nudge` lets the
8
8
  // shot drift a fraction of a metre toward the warden so the picture is not completely static.
9
9
  import type { PerspectiveCamera, Vector3 } from "three";
10
- import { Vector3 as Vec3 } from "three";
10
+ import { MathUtils, Vector3 as Vec3 } from "three";
11
11
 
12
12
  export const VAULT_SHOT = {
13
13
  fov: 31,
@@ -64,7 +64,7 @@ export function createVaultCamera(camera: PerspectiveCamera): IVaultCamera {
64
64
  desired.copy(VAULT_SHOT.position).add(aim);
65
65
  // 1 - e^(-dt/tau) is the framerate-independent form of a lerp: the same second of drift at
66
66
  // 30 fps and at 120 fps ends in the same place.
67
- camera.position.lerp(desired, 1 - Math.exp(-dt / 0.9));
67
+ camera.position.lerp(desired, MathUtils.damp(0, 1, 1 / 0.9, dt));
68
68
  camera.lookAt(currentAim);
69
69
  };
70
70
 
@@ -14,6 +14,9 @@ import { palette } from "./palette.js";
14
14
  const MOVE_RADIUS = 72;
15
15
  const EDGE = 36;
16
16
 
17
+ /** The knob's next point: `update` runs every frame, so it uses one instance. */
18
+ const knobPosition = new Vector2();
19
+
17
20
  export interface ITouchPointer {
18
21
  readonly position: Vector2;
19
22
  }
@@ -101,13 +104,11 @@ export class TouchControls {
101
104
  }
102
105
 
103
106
  const center = this.#hasMoveAnchor ? this.#moveAnchor : this.#resting;
104
- place(
105
- this.#moveKnob,
106
- new Vector2(
107
- center.x + this.#input.move.x * MOVE_RADIUS,
108
- center.y - this.#input.move.y * MOVE_RADIUS,
109
- ),
107
+ knobPosition.set(
108
+ center.x + this.#input.move.x * MOVE_RADIUS,
109
+ center.y - this.#input.move.y * MOVE_RADIUS,
110
110
  );
111
+ place(this.#moveKnob, knobPosition);
111
112
  this.#layout(size);
112
113
  return this.#input;
113
114
  }
@@ -37,8 +37,8 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
37
37
  ## This kit
38
38
 
39
39
  <!-- shared: kit-files -->
40
- Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `kart/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `track/`, `ui/`.
41
- 11 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
40
+ Source in `src/`: `audio/`, `conventions.ts`, `entities/`, `game.ts`, `gauges.ts`, `kart/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `track/`, `ui/`.
41
+ 17 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
42
  Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
43
43
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-racing.md`.
44
44
  <!-- /shared -->
@@ -39,8 +39,8 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
39
39
  ## This kit
40
40
 
41
41
  <!-- shared: kit-files -->
42
- Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `kart/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `track/`, `ui/`.
43
- 11 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
+ Source in `src/`: `audio/`, `conventions.ts`, `entities/`, `game.ts`, `gauges.ts`, `kart/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `track/`, `ui/`.
43
+ 17 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
44
44
  Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
45
45
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-racing.md`.
46
46
  <!-- /shared -->
@@ -0,0 +1,29 @@
1
+ # Credits
2
+
3
+ ## Audio
4
+
5
+ Every clip in `assets/` is **generated by this project's own tool**, `tools/make-racing-audio.mjs`,
6
+ from the maths in that file. They are original works of this repository under its MIT licence —
7
+ there is no third-party recording in them, and nothing to attribute.
8
+
9
+ | File | Made by | Licence | Source |
10
+ | --- | --- | --- | --- |
11
+ | `assets/engine-loop.wav` | `node tools/make-racing-audio.mjs` | MIT (this repository) | none — synthesised |
12
+ | `assets/tyre-squeal.wav` | `node tools/make-racing-audio.mjs` | MIT (this repository) | none — synthesised |
13
+ | `assets/nitro-burst.wav` | `node tools/make-racing-audio.mjs` | MIT (this repository) | none — synthesised |
14
+
15
+ Why not a downloaded clip: the audio catalogue the asset tools reach was searched for an engine, a
16
+ tyre and a boost (`audio_search_assets`). It returns seven items — two Kenney packs, "Interface
17
+ Sounds" and "Music Jingles", both CC0, and the five Sonniss GDC 2026 bundles, whose stated licence
18
+ is the "Sonniss GDC Game Audio Bundle License" and whose download is one multi-gigabyte archive per
19
+ part. None of them is an engine bed, a tyre squeal or a nitro burst.
20
+
21
+ An engine bed also cannot be a recording here, for a second reason: it is pitched live from 0.62×
22
+ to 2.05× (`src/audio/engine.ts`), so the loop has to be tonal and exactly periodic, and a recording
23
+ of a real engine is neither. `tools/make-racing-audio.mjs` builds the seam in — every frequency is a
24
+ whole number of cycles per loop — and the bake proves it before it writes a byte.
25
+
26
+ Swap any file for a recording without touching the game: the paths are named in `ENGINE_SOUND.clips`
27
+ and the levels in the same object. If you do, add the recording's source, licence and URL to this
28
+ file, and keep `loop: true` for the two beds in `threenative.config.ts` so the audio pass keeps
29
+ checking the join.