create-threenative 0.2.18 → 0.2.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/agent-docs/references/assertion-reference.md +1 -1
  2. package/agent-docs/references/capability-reference.md +792 -5
  3. package/agent-docs/references/kit-racing.md +4 -2
  4. package/agent-docs/references/performance-basics.md +2 -1
  5. package/agent-docs/references/terrain-authoring.md +25 -7
  6. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  7. package/dist/index.js +268 -237
  8. package/dist/quality.d.ts +5 -1
  9. package/dist/quality.js +75 -6
  10. package/dist/terrain-kit.js +1 -1
  11. package/dist/threenative.js +7 -5
  12. package/dist/web-engine-post-effects.js +6 -0
  13. package/dist/web-engine-runtime.js +407 -38
  14. package/package.json +6 -6
  15. package/template-assets/assets/floor-fern-0.glb +0 -0
  16. package/template-assets/assets/floor-litter-0.glb +0 -0
  17. package/template-assets/assets/floor-log-0.glb +0 -0
  18. package/template-assets/assets/floor-log-1.glb +0 -0
  19. package/template-assets/assets/floor-stump-0.glb +0 -0
  20. package/template-assets/assets/floor-twig-0.glb +0 -0
  21. package/template-assets/patches/three@0.187.0.patch +108 -21
  22. package/template-assets/quality/eslint.config.js +1 -1
  23. package/templates/action-rpg/package.json +7 -7
  24. package/templates/action-rpg/src/loot/drops.ts +3 -7
  25. package/templates/action-rpg/src/render/camera.ts +2 -2
  26. package/templates/action-rpg/src/render/clouds.ts +3 -1
  27. package/templates/action-rpg/src/render/materials.ts +3 -2
  28. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  29. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  30. package/templates/adventure/AGENTS.md +3 -3
  31. package/templates/adventure/CLAUDE.md +3 -3
  32. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  33. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  34. package/templates/adventure/package.json +7 -7
  35. package/templates/adventure/playtests/grass.playtest.json +61 -0
  36. package/templates/adventure/playtests/performance.playtest.json +1 -1
  37. package/templates/adventure/playtests/survives.playtest.json +2 -2
  38. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  39. package/templates/adventure/src/entities/LockOn.ts +42 -4
  40. package/templates/adventure/src/entities/Warden.ts +12 -3
  41. package/templates/adventure/src/level/Vale.ts +241 -16
  42. package/templates/adventure/src/render/camera.ts +2 -2
  43. package/templates/adventure/src/render/foliage.ts +64 -20
  44. package/templates/adventure/src/render/grass.ts +325 -0
  45. package/templates/adventure/src/render/materials.ts +3 -2
  46. package/templates/adventure/src/render/palette.ts +3 -0
  47. package/templates/adventure/src/render/touch-controls.ts +4 -1
  48. package/templates/adventure/src/scenes/Play.ts +96 -1
  49. package/templates/collectathon/package.json +7 -7
  50. package/templates/collectathon/src/level/Course.ts +2 -7
  51. package/templates/collectathon/src/level/terrain.ts +2 -1
  52. package/templates/collectathon/src/render/camera.ts +2 -2
  53. package/templates/collectathon/src/render/ground.ts +4 -4
  54. package/templates/collectathon/src/render/hero.ts +1 -1
  55. package/templates/collectathon/src/render/materials.ts +0 -1
  56. package/templates/collectathon/src/render/sky.ts +4 -3
  57. package/templates/kart/package.json +6 -6
  58. package/templates/kart/src/entities/Kart.ts +2 -1
  59. package/templates/kart/src/render/course.ts +2 -1
  60. package/templates/kart/src/track/Course.ts +3 -1
  61. package/templates/minimal/package.json +6 -6
  62. package/templates/minimal/src/render/camera.ts +2 -2
  63. package/templates/minimal/src/render/clouds.ts +3 -1
  64. package/templates/minimal/src/render/materials.ts +3 -2
  65. package/templates/minimal/src/render/touch-controls.ts +7 -6
  66. package/templates/platformer/package.json +7 -7
  67. package/templates/platformer/playtests/collect.playtest.json +4 -1
  68. package/templates/platformer/src/level/Stage.ts +2 -6
  69. package/templates/platformer/src/scenes/Play.ts +2 -1
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/puzzle/src/entities/Warden.ts +3 -3
  72. package/templates/puzzle/src/render/camera.ts +2 -2
  73. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  74. package/templates/racing/AGENTS.md +2 -2
  75. package/templates/racing/CLAUDE.md +2 -2
  76. package/templates/racing/CREDITS.md +29 -0
  77. package/templates/racing/assets/engine-loop.wav +0 -0
  78. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  79. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  80. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  81. package/templates/racing/assets/nitro-burst.wav +0 -0
  82. package/templates/racing/assets/tyre-squeal.wav +0 -0
  83. package/templates/racing/package.json +7 -7
  84. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  85. package/templates/racing/playtests/drift.playtest.json +100 -0
  86. package/templates/racing/playtests/hud.playtest.json +117 -0
  87. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  88. package/templates/racing/playtests/nitro.playtest.json +158 -0
  89. package/templates/racing/playtests/outcome.playtest.json +4 -4
  90. package/templates/racing/playtests/performance.playtest.json +1 -1
  91. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  92. package/templates/racing/src/audio/engine.ts +138 -0
  93. package/templates/racing/src/entities/CarBody.ts +83 -10
  94. package/templates/racing/src/entities/Drift.ts +243 -0
  95. package/templates/racing/src/entities/LineDriver.ts +2 -2
  96. package/templates/racing/src/entities/Nitro.ts +72 -0
  97. package/templates/racing/src/entities/RacingCar.ts +86 -21
  98. package/templates/racing/src/entities/Rival.ts +35 -21
  99. package/templates/racing/src/game.ts +6 -0
  100. package/templates/racing/src/gauges.ts +74 -0
  101. package/templates/racing/src/render/camera.ts +29 -4
  102. package/templates/racing/src/render/clouds.ts +3 -1
  103. package/templates/racing/src/render/effects.ts +244 -0
  104. package/templates/racing/src/render/materials.ts +43 -8
  105. package/templates/racing/src/render/shapes.ts +37 -0
  106. package/templates/racing/src/render/skids.ts +84 -0
  107. package/templates/racing/src/render/touch-controls.ts +10 -10
  108. package/templates/racing/src/scenes/Race.ts +277 -25
  109. package/templates/racing/src/state.ts +35 -0
  110. package/templates/racing/src/style.css +3 -0
  111. package/templates/racing/src/track/Ranking.ts +8 -4
  112. package/templates/racing/src/track/Track.ts +132 -58
  113. package/templates/racing/src/track/TrackSector.ts +19 -1
  114. package/templates/racing/src/track/circuit.ts +21 -15
  115. package/templates/racing/src/ui/GameUi.tsx +0 -2
  116. package/templates/racing/src/ui/Hud.tsx +417 -50
  117. package/templates/racing/threenative.config.ts +15 -0
  118. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  119. package/templates/rain/package.json +6 -6
  120. package/templates/rain/src/render/noise-volume.ts +2 -1
  121. package/templates/rain/src/state.ts +3 -1
  122. package/templates/rain/src/ui/GameUi.tsx +1 -1
  123. package/templates/rain/src/ui/automation.ts +10 -8
  124. package/templates/rain/src/ui/tempest.ts +3 -4
  125. package/templates/rts/package.json +6 -6
  126. package/templates/rts/src/sim/terrain.ts +1 -0
  127. package/templates/rts/src/sim/types.ts +1 -0
  128. package/templates/runner/package.json +7 -7
  129. package/templates/runner/src/render/clouds.ts +3 -1
  130. package/templates/runner/src/render/materials.ts +3 -2
  131. package/templates/runner/src/render/touch-controls.ts +7 -6
  132. package/templates/runner/src/scenes/Run.ts +4 -9
  133. package/templates/sailing/package.json +7 -7
  134. package/templates/sailing/src/render/touch-controls.ts +7 -6
  135. package/templates/shooter/package.json +7 -7
  136. package/templates/shooter/src/render/clouds.ts +3 -1
  137. package/templates/snow/package.json +7 -7
  138. package/templates/snow/src/entities/Explorer.ts +6 -12
  139. package/templates/snow/src/render/bootPrint.ts +3 -1
  140. package/templates/snow/src/render/camera.ts +3 -2
  141. package/templates/snow/src/render/scenery.ts +3 -3
  142. package/templates/snow/src/render/touch-controls.ts +7 -6
  143. package/templates/snow/src/render/weather.ts +3 -5
  144. package/templates/snow/src/terrain.ts +2 -1
  145. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  146. package/templates/starter/package.json +7 -7
  147. package/templates/starter/src/entities/Player.ts +10 -2
  148. package/templates/starter/src/render/camera.ts +2 -2
  149. package/templates/starter/src/render/clouds.ts +3 -1
  150. package/templates/starter/src/render/materials.ts +3 -2
  151. package/templates/starter/src/render/touch-controls.ts +7 -6
  152. package/templates/starter/src/scenes/Play.ts +1 -14
  153. package/templates/tower-defense/package.json +7 -7
  154. package/templates/tower-defense/src/render/shapes.ts +1 -2
  155. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  156. package/template-assets/terrain/alpine/assets.json +0 -12
  157. package/template-assets/terrain/alpine/bake.mjs +0 -6
  158. package/template-assets/terrain/alpine/credits.json +0 -164
  159. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  160. package/template-assets/terrain/alpine/recipe.json +0 -119
  161. package/template-assets/terrain/alpine/surface.json +0 -53
  162. package/template-assets/terrain/coastal/assets.json +0 -11
  163. package/template-assets/terrain/coastal/bake.mjs +0 -6
  164. package/template-assets/terrain/coastal/credits.json +0 -117
  165. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  166. package/template-assets/terrain/coastal/recipe.json +0 -113
  167. package/template-assets/terrain/coastal/surface.json +0 -41
  168. package/template-assets/terrain/desert/assets.json +0 -12
  169. package/template-assets/terrain/desert/bake.mjs +0 -6
  170. package/template-assets/terrain/desert/credits.json +0 -164
  171. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  172. package/template-assets/terrain/desert/recipe.json +0 -108
  173. package/template-assets/terrain/desert/surface.json +0 -54
  174. package/template-assets/terrain/forest/assets.json +0 -65
  175. package/template-assets/terrain/forest/bake.mjs +0 -8
  176. package/template-assets/terrain/forest/credits.json +0 -225
  177. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  178. package/template-assets/terrain/forest/recipe.json +0 -350
  179. package/template-assets/terrain/forest/surface.json +0 -79
  180. package/template-assets/terrain/tundra/assets.json +0 -12
  181. package/template-assets/terrain/tundra/bake.mjs +0 -6
  182. package/template-assets/terrain/tundra/credits.json +0 -164
  183. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  184. package/template-assets/terrain/tundra/recipe.json +0 -277
  185. package/template-assets/terrain/tundra/surface.json +0 -54
  186. package/templates/racing/src/ui/Menu.tsx +0 -7
@@ -0,0 +1,388 @@
1
+ // Bakes the racing kit's three clips into `assets/`, and proves them before it writes.
2
+ //
3
+ // node tools/make-racing-audio.mjs # write assets/*.wav and self-check them
4
+ // node tools/make-racing-audio.mjs --check # measure the committed clips, write nothing
5
+ //
6
+ // Why synthesised rather than recorded: an engine loop is pitched from 0.62× to 2.05× on the fly
7
+ // (`src/audio/engine.ts`), so it has to be a *tonal* loop with an exactly periodic seam — the one
8
+ // thing a recording of a real engine is not. The asset sources this kit can reach carry no engine,
9
+ // tyre or boost recording (the catalogue's curated packs are UI and jingles; the professional
10
+ // bundles are multi-gigabyte archives), so the sound is authored here, from maths, the way the snow
11
+ // and rain kits author theirs. Nothing is sampled from anyone, so `CREDITS.md` credits the tool.
12
+ //
13
+ // The bake is deterministic: one seeded generator, no clock, no environment, no arguments. It
14
+ // re-runs itself and compares hashes before it writes, so "two runs are byte-identical" is a
15
+ // measured fact rather than a hope.
16
+ //
17
+ // **The loops are exactly periodic, by construction rather than by cross-fade.** Every frequency in
18
+ // the engine bed is a whole number of cycles per second over a one-second loop, so sample 0 and
19
+ // sample N are the same point of the same waveform; the tyre squeal is band-limited noise run
20
+ // through its own filter over the *periodic* extension of the noise, so the filter's steady state
21
+ // is what lands in the file. The seam gate in `@threenative/assets`' audio pass then has something
22
+ // true to measure, instead of a hole papered over with a cross-fade.
23
+
24
+ import { createHash } from "node:crypto";
25
+ import { readFileSync, writeFileSync } from "node:fs";
26
+ import path from "node:path";
27
+ import { fileURLToPath } from "node:url";
28
+
29
+ const SAMPLE_RATE = 44100;
30
+ const CHANNELS = 1;
31
+ const BITS = 32;
32
+ const BYTES_PER_SAMPLE = BITS / 8;
33
+ const BLOCK_ALIGN = CHANNELS * BYTES_PER_SAMPLE;
34
+ const WAVE_FORMAT_IEEE_FLOAT = 3;
35
+
36
+ /** The seed every draw comes from. Changing it changes the files; it is not a tuning knob. */
37
+ const SEED = 0x5eed_c0de;
38
+
39
+ const CLIPS = {
40
+ // Frames are whole samples, not seconds: 0.7 s is 30 869.999… samples in a double, and a clip
41
+ // that is one frame short is a clip whose loop point is a frame off.
42
+ engine: { file: "engine-loop.wav", frames: SAMPLE_RATE },
43
+ squeal: { file: "tyre-squeal.wav", frames: SAMPLE_RATE * 1.5 },
44
+ nitro: { file: "nitro-burst.wav", frames: (SAMPLE_RATE * 7) / 10 },
45
+ };
46
+
47
+ const here = path.dirname(fileURLToPath(import.meta.url));
48
+ const assetsDir = path.resolve(here, "..", "assets");
49
+
50
+ // --- dsp ------------------------------------------------------------------------------------
51
+
52
+ /** The one generator. `mulberry32` so a run is a repeatable draw, not a nicer random. */
53
+ function mulberry32(seed) {
54
+ let a = seed >>> 0;
55
+ return () => {
56
+ a = (a + 0x6d2b79f5) >>> 0;
57
+ let t = a;
58
+ t = Math.imul(t ^ (t >>> 15), t | 1);
59
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
60
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
61
+ };
62
+ }
63
+
64
+ /** RBJ cookbook biquad coefficients, as `@threenative/assets`' own audio pass computes them. */
65
+ function biquad(kind, hz, q = Math.SQRT1_2) {
66
+ const w0 = (2 * Math.PI * hz) / SAMPLE_RATE;
67
+ const alpha = Math.sin(w0) / (2 * q);
68
+ const cos = Math.cos(w0);
69
+ const a0 = 1 + alpha;
70
+ const norm = (value) => value / a0;
71
+ const shared = { b1: norm(kind === "highpass" ? -2 * cos : 2 * cos), a1: norm(-2 * cos) };
72
+ if (kind === "lowpass")
73
+ return {
74
+ b0: norm((1 - cos) / 2),
75
+ b1: shared.b1,
76
+ b2: norm((1 - cos) / 2),
77
+ a1: shared.a1,
78
+ a2: norm(1 - alpha),
79
+ };
80
+ return {
81
+ b0: norm((1 + cos) / 2),
82
+ b1: shared.b1,
83
+ b2: norm((1 + cos) / 2),
84
+ a1: shared.a1,
85
+ a2: norm(1 - alpha),
86
+ };
87
+ }
88
+
89
+ /**
90
+ * A biquad over a **periodic** signal: `samples` is one period, and the filter is started
91
+ * `preroll` samples before its first sample on the signal's own wrap-around tail.
92
+ *
93
+ * That is the whole trick behind a noise loop with no click. Cross-fading the end into the start
94
+ * leaves a seam that is quieter but still a seam; running the filter's transient to completion on
95
+ * the periodic extension means the waveform at sample 0 is the one at sample N, whatever the
96
+ * filter is.
97
+ */
98
+ function filterPeriodic(samples, coefficients, preroll = SAMPLE_RATE * 2) {
99
+ const { b0, b1, b2, a1, a2 } = coefficients;
100
+ const length = samples.length;
101
+ let x1 = 0;
102
+ let x2 = 0;
103
+ let y1 = 0;
104
+ let y2 = 0;
105
+ const step = (index) => {
106
+ const x0 = samples[((index % length) + length) % length];
107
+ const y0 = b0 * x0 + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
108
+ x2 = x1;
109
+ x1 = x0;
110
+ y2 = y1;
111
+ y1 = y0;
112
+ return y0;
113
+ };
114
+ for (let index = -preroll; index < 0; index += 1) step(index);
115
+ const out = new Float32Array(length);
116
+ for (let index = 0; index < length; index += 1) out[index] = step(index);
117
+ return out;
118
+ }
119
+
120
+ function encodeWav(samples) {
121
+ const frames = samples.length;
122
+ const dataBytes = frames * BLOCK_ALIGN;
123
+ const buffer = Buffer.alloc(44 + dataBytes);
124
+ buffer.write("RIFF", 0, "ascii");
125
+ buffer.writeUInt32LE(36 + dataBytes, 4);
126
+ buffer.write("WAVE", 8, "ascii");
127
+ buffer.write("fmt ", 12, "ascii");
128
+ buffer.writeUInt32LE(16, 16);
129
+ buffer.writeUInt16LE(WAVE_FORMAT_IEEE_FLOAT, 20);
130
+ buffer.writeUInt16LE(CHANNELS, 22);
131
+ buffer.writeUInt32LE(SAMPLE_RATE, 24);
132
+ buffer.writeUInt32LE(SAMPLE_RATE * BLOCK_ALIGN, 28);
133
+ buffer.writeUInt16LE(BLOCK_ALIGN, 32);
134
+ buffer.writeUInt16LE(BITS, 34);
135
+ buffer.write("data", 36, "ascii");
136
+ buffer.writeUInt32LE(dataBytes, 40);
137
+ for (let index = 0; index < frames; index += 1)
138
+ buffer.writeFloatLE(samples[index], 44 + index * BLOCK_ALIGN);
139
+ return buffer;
140
+ }
141
+
142
+ // --- the three voices -----------------------------------------------------------------------
143
+
144
+ /**
145
+ * The engine bed: a firing frequency and its harmonics, with the lope of a four-cylinder at idle.
146
+ *
147
+ * 42 Hz is the firing rate at playback rate 1.0 — about 1 300 rpm, where a small four-cylinder
148
+ * sits — and the game's rate law takes it to 90 Hz at the rev limit. Forty harmonics rather than a
149
+ * handful, because pitch-shifting a pure tone up 2× keeps it a pure tone while an exhaust keeps its
150
+ * buzz; `1 / k ** 0.8` is bright enough to still be an engine two octaves up.
151
+ */
152
+ function engineBody() {
153
+ const length = CLIPS.engine.frames;
154
+ const firingHz = 42;
155
+ const harmonics = 40;
156
+ const out = new Float32Array(length);
157
+ for (let index = 0; index < length; index += 1) {
158
+ const time = index / SAMPLE_RATE;
159
+ let body = 0;
160
+ for (let k = 1; k <= harmonics; k += 1) {
161
+ // A fixed golden-angle phase spread: it keeps the partials from summing into one spike at
162
+ // t = 0 in every period, which is what a naive all-zero-phase series does (it sounds like a
163
+ // click 44 times a second).
164
+ body += Math.sin(2 * Math.PI * k * firingHz * time + k * 2.399963229728653) / k ** 0.8;
165
+ }
166
+ // 11 Hz and 22 Hz are whole numbers of cycles in a one-second loop, so the lope wraps too.
167
+ const lope = 0.74 + 0.26 * Math.sin(2 * Math.PI * 11 * time);
168
+ const rumble = 0.3 * Math.sin(2 * Math.PI * 22 * time);
169
+ out[index] = Math.tanh(1.5 * (0.42 * body * lope + rumble));
170
+ }
171
+ return normalise(out, 0.7);
172
+ }
173
+
174
+ /**
175
+ * The tyre squeal: band-limited noise under a narrow tone with vibrato, at a slow swell.
176
+ *
177
+ * A sliding tyre is stick-slip, which is a squeal with a pitch in it rather than hiss. The noise
178
+ * carries the grit (800..3400 Hz) and the tone carries the pitch (1 250 Hz, ±40 Hz at 2 Hz); the
179
+ * vibrato is phase-integrated so it too wraps exactly at the loop point.
180
+ */
181
+ function squealBody() {
182
+ const length = CLIPS.squeal.frames;
183
+ const seconds = length / SAMPLE_RATE;
184
+ // Whole cycles per loop, or the modulation leaves a step at the wrap.
185
+ const vibratoCycles = 3;
186
+ const swellCycles = 2;
187
+ const toneHz = 1250;
188
+ const vibratoHz = 40;
189
+ const rng = mulberry32(SEED);
190
+ const noise = new Float32Array(length);
191
+ for (let index = 0; index < length; index += 1) noise[index] = rng() * 2 - 1;
192
+ const grit = filterPeriodic(
193
+ filterPeriodic(noise, biquad("highpass", 800)),
194
+ biquad("lowpass", 3400),
195
+ );
196
+ const out = new Float32Array(length);
197
+ for (let index = 0; index < length; index += 1) {
198
+ const time = index / SAMPLE_RATE;
199
+ const phase =
200
+ 2 * Math.PI * toneHz * time +
201
+ (vibratoHz / (vibratoCycles / seconds)) *
202
+ Math.cos(2 * Math.PI * (vibratoCycles / seconds) * time);
203
+ const swell =
204
+ 0.78 + 0.22 * Math.sin(2 * Math.PI * (swellCycles / seconds) * time - Math.PI / 2);
205
+ out[index] = swell * (0.8 * grit[index] * 1.6 + 0.22 * Math.sin(phase));
206
+ }
207
+ return normalise(out, 0.62);
208
+ }
209
+
210
+ /**
211
+ * The nitro burst: a pressure wave falling away, with a hiss on top. One shot, so it is allowed
212
+ * not to loop and is declared `loop: false` in `threenative.config.ts`.
213
+ */
214
+ function nitroBody() {
215
+ const length = CLIPS.nitro.frames;
216
+ const rng = mulberry32(SEED ^ 0x9e37_79b9);
217
+ const noise = new Float32Array(length);
218
+ for (let index = 0; index < length; index += 1) noise[index] = rng() * 2 - 1;
219
+ const hiss = filterPeriodic(noise, biquad("highpass", 900));
220
+ const out = new Float32Array(length);
221
+ let phase = 0;
222
+ for (let index = 0; index < length; index += 1) {
223
+ const time = index / SAMPLE_RATE;
224
+ // 10 ms attack, exponential release: a valve opening and a tank emptying.
225
+ const attack = Math.min(1, time / 0.01);
226
+ const release = Math.exp(-time * 5.2);
227
+ const sweepHz = 900 * Math.exp(-time * 3.4) + 120;
228
+ phase += (2 * Math.PI * sweepHz) / SAMPLE_RATE;
229
+ out[index] = attack * release * (0.55 * Math.sin(phase) + 0.5 * hiss[index] * 0.9);
230
+ }
231
+ return normalise(out, 0.66);
232
+ }
233
+
234
+ /** Scales a clip to a peak, so the mix law in `src/audio/engine.ts` is the only level control. */
235
+ function normalise(samples, peak) {
236
+ let loudest = 0;
237
+ for (const value of samples) loudest = Math.max(loudest, Math.abs(value));
238
+ if (loudest === 0) throw new Error("TN_RACING_AUDIO_INVALID: a clip baked as silence.");
239
+ const scale = peak / loudest;
240
+ for (let index = 0; index < samples.length; index += 1) samples[index] *= scale;
241
+ return samples;
242
+ }
243
+
244
+ // --- the checks -----------------------------------------------------------------------------
245
+
246
+ function bake() {
247
+ return {
248
+ engine: engineBody(),
249
+ nitro: nitroBody(),
250
+ squeal: squealBody(),
251
+ };
252
+ }
253
+
254
+ function fail(what) {
255
+ throw new Error(`TN_RACING_AUDIO_INVALID: ${what}`);
256
+ }
257
+
258
+ function assert(what, condition) {
259
+ if (!condition) fail(what);
260
+ }
261
+
262
+ /** Peak, RMS, and the count of samples that are not finite. */
263
+ function measure(samples) {
264
+ let peak = 0;
265
+ let sum = 0;
266
+ let bad = 0;
267
+ for (const value of samples) {
268
+ if (!Number.isFinite(value)) bad += 1;
269
+ else peak = Math.max(peak, Math.abs(value));
270
+ sum += value * value;
271
+ }
272
+ return { bad, peak, rms: Math.sqrt(sum / samples.length) };
273
+ }
274
+
275
+ /**
276
+ * The wrap step against the largest ordinary step near it — the ratio
277
+ * `packages/assets/src/passes/audio.ts` fails a build on, computed the same way so this tool and
278
+ * the cooker cannot disagree about whether a loop is clean.
279
+ */
280
+ function seamRatio(samples) {
281
+ const wrap = Math.abs(samples[0] - samples[samples.length - 1]);
282
+ const steps = [];
283
+ for (let index = 1; index < samples.length; index += 1)
284
+ steps.push(Math.abs(samples[index] - samples[index - 1]));
285
+ steps.sort((a, b) => a - b);
286
+ const near = steps[Math.floor(steps.length * 0.99)];
287
+ return near <= 0 ? (wrap <= 0 ? 0 : Number.POSITIVE_INFINITY) : wrap / near;
288
+ }
289
+
290
+ /**
291
+ * The magnitude of one exact DFT bin, in Hz.
292
+ *
293
+ * A one-second loop has integer-Hz bins, so the engine's fundamental lands exactly on the bin it
294
+ * is asked about. Autocorrelation is the wrong probe here: the bed's own 11 Hz lope is a quarter
295
+ * of a cycle off at a one-period lag, and a genuine pitch then measures as noise.
296
+ */
297
+ function bin(samples, hz) {
298
+ let real = 0;
299
+ let imaginary = 0;
300
+ for (let index = 0; index < samples.length; index += 1) {
301
+ const angle = (2 * Math.PI * hz * index) / SAMPLE_RATE;
302
+ real += samples[index] * Math.cos(angle);
303
+ imaginary += samples[index] * Math.sin(angle);
304
+ }
305
+ return Math.hypot(real, imaginary) / samples.length;
306
+ }
307
+
308
+ const LOOP_SLACK = 0.75;
309
+
310
+ function verify(clips) {
311
+ for (const [name, clip] of Object.entries(CLIPS)) {
312
+ const samples = clips[name];
313
+ const stats = measure(samples);
314
+ assert(`${name}: non-finite samples`, stats.bad === 0);
315
+ assert(`${name}: silent`, stats.peak > 0.1);
316
+ assert(`${name}: peak over full scale (${stats.peak.toFixed(3)})`, stats.peak <= 1);
317
+ assert(`${name}: sample count`, samples.length === clip.frames);
318
+ if (name === "nitro") continue;
319
+ // The seam ratio is the gate the asset pass applies at cook time; it is measured here too, so
320
+ // a bake that would fail a build fails before the file is written.
321
+ const ratio = seamRatio(samples);
322
+ assert(
323
+ `${name}: seam step is ${ratio.toFixed(2)}× the local step, which the cook would reject`,
324
+ ratio <= LOOP_SLACK,
325
+ );
326
+ }
327
+ // The engine's pitch: one firing period is 1/44 s, and a bed with a body in it correlates with
328
+ // itself there. Without this the file could be shaped noise and every other check would pass.
329
+ // The bed's pitch: 42 Hz and its third harmonic stand well clear of the bins between them, which
330
+ // is what "an engine and not shaped noise" means in the file rather than in the source.
331
+ const fundamental = bin(clips.engine, 42);
332
+ const between = (bin(clips.engine, 43) + bin(clips.engine, 62) + bin(clips.engine, 85)) / 3;
333
+ assert(
334
+ `engine: no 42 Hz body (bin ${fundamental.toFixed(4)} against ${between.toFixed(4)} between the partials)`,
335
+ fundamental > between * 8,
336
+ );
337
+ assert("engine: no third harmonic", bin(clips.engine, 126) > between * 4);
338
+ }
339
+
340
+ /** The hash of a bake, taken from the samples rather than the bytes, so it is container-free. */
341
+ function digest(clips) {
342
+ const hash = createHash("sha256");
343
+ for (const name of Object.keys(CLIPS).sort()) {
344
+ for (const value of clips[name]) hash.update(Float32Array.of(value));
345
+ }
346
+ return hash.digest("hex");
347
+ }
348
+
349
+ function report(clips) {
350
+ const rows = Object.entries(CLIPS).map(([name, clip]) => {
351
+ const stats = measure(clips[name]);
352
+ return {
353
+ clip: clip.file,
354
+ seconds: Number((clip.frames / SAMPLE_RATE).toFixed(2)),
355
+ peak: Number(stats.peak.toFixed(3)),
356
+ rms: Number(stats.rms.toFixed(3)),
357
+ seam: name === "nitro" ? "one shot" : seamRatio(clips[name]).toFixed(2),
358
+ };
359
+ });
360
+ console.table(rows);
361
+ }
362
+
363
+ // --- main -----------------------------------------------------------------------------------
364
+
365
+ const checking = process.argv.includes("--check");
366
+ const clips = bake();
367
+ verify(clips);
368
+ const again = bake();
369
+ assert("the bake is not deterministic", digest(clips) === digest(again));
370
+
371
+ if (checking) {
372
+ for (const [name, clip] of Object.entries(CLIPS)) {
373
+ const committed = readFileSync(path.join(assetsDir, clip.file));
374
+ assert(
375
+ `${clip.file} is stale: run node tools/make-racing-audio.mjs`,
376
+ Buffer.compare(committed, encodeWav(bake()[name])) === 0,
377
+ );
378
+ }
379
+ report(clips);
380
+ console.log("committed clips match the bake");
381
+ } else {
382
+ for (const [name, clip] of Object.entries(CLIPS))
383
+ writeFileSync(path.join(assetsDir, clip.file), encodeWav(clips[name]));
384
+ report(clips);
385
+ console.log(
386
+ `baked ${Object.keys(CLIPS).length} clips into assets/ (sha256 ${digest(clips).slice(0, 16)})`,
387
+ );
388
+ }
@@ -18,8 +18,8 @@
18
18
  "format:check": "biome format src"
19
19
  },
20
20
  "dependencies": {
21
- "@threenative/core": "0.3.13",
22
- "@threenative/ui": "0.3.13",
21
+ "@threenative/core": ">=0.3.16",
22
+ "@threenative/ui": ">=0.3.16",
23
23
  "react": "19.2.0",
24
24
  "react-dom": "19.2.0",
25
25
  "react-reconciler": "0.33.0",
@@ -27,13 +27,13 @@
27
27
  },
28
28
  "devDependencies": {
29
29
  "@tailwindcss/vite": "4.3.3",
30
- "@threenative/assets": "0.3.14",
31
- "@threenative/playtest": "0.3.13",
30
+ "@threenative/assets": ">=0.3.17",
31
+ "@threenative/playtest": ">=0.3.16",
32
32
  "@types/react": "19.2.0",
33
33
  "@types/react-dom": "19.2.0",
34
34
  "@types/three": "0.187.0",
35
35
  "@vitejs/plugin-react": "6.0.5",
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",
@@ -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",
@@ -4,6 +4,7 @@
4
4
  import {
5
5
  Data3DTexture,
6
6
  LinearFilter,
7
+ MathUtils,
7
8
  NoColorSpace,
8
9
  RGBAFormat,
9
10
  RepeatWrapping,
@@ -76,7 +77,7 @@ function sampleLattice(lattice: ILattice, x: number, y: number, z: number): numb
76
77
  values[((c % n) * n + (b % n)) * n + (a % n)] as number;
77
78
  const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
78
79
  const blend = (fx: number, fy: number, fz: number): number => {
79
- const smooth = (f: number): number => f * f * (3 - 2 * f);
80
+ const smooth = (f: number): number => MathUtils.smoothstep(f, 0, 1);
80
81
  const tx = smooth(fx);
81
82
  const ty = smooth(fy);
82
83
  const tz = smooth(fz);
@@ -6,6 +6,8 @@
6
6
  * they live here rather than in a package.
7
7
  */
8
8
 
9
+ import { MathUtils } from "three";
10
+
9
11
  export const WEATHER_KEYS = ["rain", "cloud", "wind", "fog", "exposure", "wet"] as const;
10
12
 
11
13
  export type WeatherKey = (typeof WEATHER_KEYS)[number];
@@ -74,7 +76,7 @@ export function sanitizeWeather(
74
76
 
75
77
  /** Exponential ease towards the target, independent of frame rate because `dt` is real seconds. */
76
78
  export function easeWeather(current: Weather, target: Weather, dt: number): Weather {
77
- const k = 1 - Math.exp(-dt / EASE_TAU);
79
+ const k = MathUtils.damp(0, 1, 1 / EASE_TAU, dt);
78
80
  const next = { ...current };
79
81
  for (const key of WEATHER_KEYS) next[key] = current[key] + (target[key] - current[key]) * k;
80
82
  return next;
@@ -154,7 +154,7 @@ function RainInterface() {
154
154
  return;
155
155
  qualityChosen.current = true;
156
156
  // An operator asking for high on a phone or software adapter keeps that explicit choice.
157
- const asked = automationRequest(window.location.search).quality;
157
+ const asked = automationRequest().quality;
158
158
  if (asked !== undefined) {
159
159
  send("setQuality", asked);
160
160
  return;
@@ -7,10 +7,11 @@
7
7
  * whole mapping. A name in neither list throws: a typo must not silently pick a tier and report
8
8
  * success.
9
9
  *
10
- * Query reading takes a search string rather than reaching for `location`, so the rules are the
11
- * same on every target and a test can hold one.
10
+ * Query reading goes through the engine's debug seam when no search string is given, so the same
11
+ * rule reads the URL on the web and `TN_DEBUG_*` on a native launch; a test can still hold one.
12
12
  */
13
13
 
14
+ import { debugFlag, debugValue } from "@threenative/core";
14
15
  import type { QualityName } from "../state.js";
15
16
 
16
17
  /** The four engine tiers, plus the four names the source study published for them. */
@@ -48,13 +49,14 @@ export interface IAutomationRequest {
48
49
  * What the query asks for. An unreadable tier is named in `rejectedQuality` instead of thrown: a
49
50
  * URL is a place somebody typed, and the page still has to open.
50
51
  */
51
- export function automationRequest(search: string): IAutomationRequest {
52
- const query = new URLSearchParams(search);
53
- const asked = query.get("quality");
54
- if (asked === null) return { still: query.has("still") };
52
+ export function automationRequest(search?: string): IAutomationRequest {
53
+ const query = search === undefined ? undefined : new URLSearchParams(search);
54
+ const asked = query === undefined ? debugValue("quality") : query.get("quality");
55
+ const still = query === undefined ? debugFlag("still") : query.has("still");
56
+ if (asked === null || asked === undefined) return { still };
55
57
  try {
56
- return { still: query.has("still"), quality: qualityTier(asked) };
58
+ return { still, quality: qualityTier(asked) };
57
59
  } catch {
58
- return { still: query.has("still"), rejectedQuality: asked };
60
+ return { still, rejectedQuality: asked };
59
61
  }
60
62
  }
@@ -13,7 +13,7 @@
13
13
  * browser APIs. `src/game.ts` stays portable: this sends the same validated intents the buttons do.
14
14
  */
15
15
 
16
- import type { IGame } from "@threenative/core";
16
+ import { type IGame, debugFlag } from "@threenative/core";
17
17
  import { connectUiBridge, sendUiIntent, subscribeUiState } from "@threenative/core/ui-layer";
18
18
  import type { GameState, PresetName, WeatherKey } from "../state.js";
19
19
  import type { ICaptureResult, ISceneSizes } from "./Hud.js";
@@ -78,15 +78,14 @@ export function installTempest(game: IGame<GameState>): ITempestApi {
78
78
  const send = (intent: IntentName, payload?: unknown): void => {
79
79
  sendUiIntent(bridge, intent, payload);
80
80
  };
81
- const query = new URLSearchParams(window.location.search);
82
- const request = automationRequest(window.location.search);
81
+ const request = automationRequest();
83
82
  if (request.rejectedQuality !== undefined) {
84
83
  say(
85
84
  `?quality=${request.rejectedQuality} is not a tier: expected low, balanced, high or cinematic`,
86
85
  );
87
86
  }
88
87
  if (request.quality !== undefined) send("setQuality", request.quality);
89
- if (query.has("offline")) {
88
+ if (debugFlag("offline")) {
90
89
  // The source's offline WebGL2 adapter stood in for a Three.js build it could not load from a
91
90
  // CDN. This build installs Three locally and never reaches for one, so there is no fallback
92
91
  // to select and nothing here pretends otherwise.
@@ -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"
@@ -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",
@@ -102,6 +102,7 @@ export const ROCK_FIELDS: readonly (readonly [number, number, number])[] = [
102
102
 
103
103
  const smooth01 = (t: number): number => {
104
104
  const c = Math.max(0, Math.min(1, t));
105
+ // eslint-disable-next-line no-restricted-syntax -- a sim module must not import three (rts-runtime-cost.spec), so the inline form stays here.
105
106
  return c * c * (3 - 2 * c);
106
107
  };
107
108
 
@@ -603,6 +603,7 @@ export function seeded(seed = 17): () => number {
603
603
  let s = seed;
604
604
  return () => {
605
605
  s |= 0;
606
+ // eslint-disable-next-line no-restricted-syntax -- Replays depend on this exact mulberry32 stream; the engine's seeded RNG is an LCG, so swapping it changes every recorded match.
606
607
  s = (s + 0x6d2b79f5) | 0;
607
608
  let t = Math.imul(s ^ (s >>> 15), 1 | s);
608
609
  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
@@ -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",
@@ -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
 
@@ -9,6 +9,7 @@ import {
9
9
  DataTexture,
10
10
  Float32BufferAttribute,
11
11
  LinearMipmapLinearFilter,
12
+ MathUtils,
12
13
  MeshStandardMaterial,
13
14
  RepeatWrapping,
14
15
  SRGBColorSpace,
@@ -82,8 +83,8 @@ function grainNormalTexture(size = 128): DataTexture {
82
83
  const y0 = Math.floor(v);
83
84
  const fx = u - x0;
84
85
  const fy = v - y0;
85
- const sx = fx * fx * (3 - 2 * fx);
86
- const sy = fy * fy * (3 - 2 * fy);
86
+ const sx = MathUtils.smoothstep(fx, 0, 1);
87
+ const sy = MathUtils.smoothstep(fy, 0, 1);
87
88
  const at = (i: number, j: number): number =>
88
89
  values[(((j % count) + count) % count) * count + (((i % count) + count) % count)] ?? 0;
89
90
  const top = at(x0, y0) + (at(x0 + 1, y0) - at(x0, y0)) * sx;