create-threenative 0.2.17 → 0.2.20

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 (387) hide show
  1. package/agent-docs/kit-mcp.md +1 -1
  2. package/agent-docs/kit-router.md +1 -1
  3. package/agent-docs/references/assertion-reference.md +54 -110
  4. package/agent-docs/references/capability-reference.md +790 -24
  5. package/agent-docs/references/conventions.md +28 -0
  6. package/agent-docs/references/kit-racing.md +4 -2
  7. package/agent-docs/references/performance-basics.md +10 -5
  8. package/agent-docs/references/terrain-authoring.md +21 -7
  9. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  10. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  11. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +7 -4
  12. package/agent-files/.claude/hooks/discovery-gate.mjs +2 -2
  13. package/dist/index.d.ts +97 -6
  14. package/dist/index.js +1040 -529
  15. package/dist/quality.d.ts +5 -1
  16. package/dist/quality.js +75 -6
  17. package/dist/terrain-kit.js +1 -1
  18. package/dist/threenative.js +98 -17
  19. package/dist/web-engine-ccd-ik-solver.js +127 -0
  20. package/dist/web-engine-gltf-loader.js +52 -14
  21. package/dist/web-engine-post-effects.js +11 -10
  22. package/dist/web-engine-runtime.js +3638 -361
  23. package/package.json +8 -7
  24. package/template-assets/assets/floor-fern-0.glb +0 -0
  25. package/template-assets/assets/floor-litter-0.glb +0 -0
  26. package/template-assets/assets/floor-log-0.glb +0 -0
  27. package/template-assets/assets/floor-log-1.glb +0 -0
  28. package/template-assets/assets/floor-stump-0.glb +0 -0
  29. package/template-assets/assets/floor-twig-0.glb +0 -0
  30. package/template-assets/clearwater/README.md +1 -1
  31. package/template-assets/patches/manifest.json +18 -0
  32. package/template-assets/quality/eslint.config.js +1 -1
  33. package/templates/action-rpg/AGENTS.md +8 -4
  34. package/templates/action-rpg/CLAUDE.md +8 -4
  35. package/templates/action-rpg/package.json +7 -7
  36. package/templates/action-rpg/src/game.ts +1 -1
  37. package/templates/action-rpg/src/loot/drops.ts +3 -7
  38. package/templates/action-rpg/src/render/atmosphere.ts +6 -0
  39. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  40. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  41. package/templates/action-rpg/src/render/camera.ts +2 -2
  42. package/templates/action-rpg/src/render/clouds.ts +16 -1
  43. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  44. package/templates/action-rpg/src/render/materials.ts +3 -2
  45. package/templates/action-rpg/src/render/quality.ts +7 -32
  46. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  47. package/templates/action-rpg/src/scenes/Play.ts +5 -16
  48. package/templates/action-rpg/src/style.css +4 -0
  49. package/templates/action-rpg/vite.config.ts +2 -0
  50. package/templates/adventure/AGENTS.md +10 -5
  51. package/templates/adventure/CLAUDE.md +10 -5
  52. package/templates/adventure/kit.json +5 -1
  53. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  54. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  55. package/templates/adventure/package.json +7 -7
  56. package/templates/adventure/playtests/grass.playtest.json +61 -0
  57. package/templates/adventure/playtests/performance.playtest.json +1 -1
  58. package/templates/adventure/playtests/survives.playtest.json +2 -2
  59. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  60. package/templates/adventure/src/entities/LockOn.ts +42 -4
  61. package/templates/adventure/src/entities/Warden.ts +4 -1
  62. package/templates/adventure/src/game.ts +1 -1
  63. package/templates/adventure/src/level/Vale.ts +241 -16
  64. package/templates/adventure/src/render/camera.ts +2 -2
  65. package/templates/adventure/src/render/foliage.ts +64 -20
  66. package/templates/adventure/src/render/grass.ts +325 -0
  67. package/templates/adventure/src/render/materials.ts +3 -2
  68. package/templates/adventure/src/render/palette.ts +3 -0
  69. package/templates/adventure/src/render/touch-controls.ts +4 -1
  70. package/templates/adventure/src/scenes/Play.ts +96 -1
  71. package/templates/adventure/src/style.css +4 -0
  72. package/templates/adventure/tsconfig.json +1 -1
  73. package/templates/adventure/vite.config.ts +2 -0
  74. package/templates/collectathon/AGENTS.md +7 -2
  75. package/templates/collectathon/CLAUDE.md +7 -2
  76. package/templates/collectathon/package.json +7 -7
  77. package/templates/collectathon/src/game.ts +1 -1
  78. package/templates/collectathon/src/level/Course.ts +55 -14
  79. package/templates/collectathon/src/level/terrain.ts +29 -7
  80. package/templates/collectathon/src/main.ts +1 -0
  81. package/templates/collectathon/src/render/camera.ts +2 -2
  82. package/templates/collectathon/src/render/foliage.ts +359 -98
  83. package/templates/collectathon/src/render/ground.ts +4 -4
  84. package/templates/collectathon/src/render/hero.ts +1 -1
  85. package/templates/collectathon/src/render/materials.ts +0 -1
  86. package/templates/collectathon/src/render/sky.ts +80 -15
  87. package/templates/collectathon/src/render/water.ts +32 -10
  88. package/templates/collectathon/src/scenes/Play.ts +18 -5
  89. package/templates/collectathon/src/style.css +4 -0
  90. package/templates/collectathon/tsconfig.json +1 -1
  91. package/templates/collectathon/vite.config.ts +2 -0
  92. package/templates/kart/AGENTS.md +7 -2
  93. package/templates/kart/CLAUDE.md +7 -2
  94. package/templates/kart/package.json +6 -6
  95. package/templates/kart/src/entities/Kart.ts +2 -1
  96. package/templates/kart/src/game.ts +1 -1
  97. package/templates/kart/src/main.ts +1 -0
  98. package/templates/kart/src/render/course.ts +2 -1
  99. package/templates/kart/src/style.css +4 -0
  100. package/templates/kart/src/track/Course.ts +3 -1
  101. package/templates/kart/tsconfig.json +1 -1
  102. package/templates/kart/vite.config.ts +2 -0
  103. package/templates/minimal/AGENTS.md +8 -3
  104. package/templates/minimal/CLAUDE.md +8 -3
  105. package/templates/minimal/package.json +6 -6
  106. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  107. package/templates/minimal/src/game.ts +1 -1
  108. package/templates/minimal/src/render/atmosphere.ts +6 -0
  109. package/templates/minimal/src/render/backlightControls.ts +10 -0
  110. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  111. package/templates/minimal/src/render/camera.ts +14 -3
  112. package/templates/minimal/src/render/clouds.ts +16 -1
  113. package/templates/minimal/src/render/lighting.ts +4 -2
  114. package/templates/minimal/src/render/materialLighting.ts +5 -5
  115. package/templates/minimal/src/render/materials.ts +13 -2
  116. package/templates/minimal/src/render/quality.ts +7 -32
  117. package/templates/minimal/src/render/touch-controls.ts +7 -6
  118. package/templates/minimal/src/scenes/Play.ts +4 -1
  119. package/templates/minimal/vite.config.ts +7 -1
  120. package/templates/platformer/AGENTS.md +9 -4
  121. package/templates/platformer/CLAUDE.md +9 -4
  122. package/templates/platformer/index.html +1 -1
  123. package/templates/platformer/main.html +12 -0
  124. package/templates/platformer/package.json +7 -7
  125. package/templates/platformer/playtests/collect.playtest.json +4 -1
  126. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  127. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  128. package/templates/platformer/src/entities/Fox.ts +21 -6
  129. package/templates/platformer/src/game.ts +1 -1
  130. package/templates/platformer/src/level/Stage.ts +2 -6
  131. package/templates/platformer/src/main.ts +1 -0
  132. package/templates/platformer/src/render/backlightControls.ts +10 -0
  133. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  134. package/templates/platformer/src/render/materialLighting.ts +5 -5
  135. package/templates/platformer/src/render/quality.ts +7 -32
  136. package/templates/platformer/src/scenes/Play.ts +4 -2
  137. package/templates/platformer/src/style.css +4 -0
  138. package/templates/platformer/src/worker-page.ts +29 -0
  139. package/templates/platformer/src/worker.ts +5 -0
  140. package/templates/platformer/tsconfig.json +1 -1
  141. package/templates/platformer/vite.config.ts +4 -0
  142. package/templates/puzzle/AGENTS.md +7 -2
  143. package/templates/puzzle/CLAUDE.md +7 -2
  144. package/templates/puzzle/package.json +7 -7
  145. package/templates/puzzle/src/entities/Warden.ts +3 -3
  146. package/templates/puzzle/src/game.ts +1 -1
  147. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  148. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  149. package/templates/puzzle/src/render/camera.ts +2 -2
  150. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  151. package/templates/puzzle/src/render/quality.ts +7 -32
  152. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  153. package/templates/puzzle/src/scenes/Play.ts +1 -1
  154. package/templates/puzzle/src/style.css +4 -0
  155. package/templates/puzzle/tsconfig.json +1 -1
  156. package/templates/puzzle/vite.config.ts +2 -0
  157. package/templates/racing/AGENTS.md +9 -4
  158. package/templates/racing/CLAUDE.md +9 -4
  159. package/templates/racing/CREDITS.md +29 -0
  160. package/templates/racing/assets/engine-loop.wav +0 -0
  161. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  162. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  163. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  164. package/templates/racing/assets/nitro-burst.wav +0 -0
  165. package/templates/racing/assets/tyre-squeal.wav +0 -0
  166. package/templates/racing/package.json +7 -7
  167. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  168. package/templates/racing/playtests/drift.playtest.json +100 -0
  169. package/templates/racing/playtests/hud.playtest.json +117 -0
  170. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  171. package/templates/racing/playtests/nitro.playtest.json +158 -0
  172. package/templates/racing/playtests/outcome.playtest.json +4 -4
  173. package/templates/racing/playtests/performance.playtest.json +1 -1
  174. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  175. package/templates/racing/src/audio/engine.ts +138 -0
  176. package/templates/racing/src/entities/CarBody.ts +83 -10
  177. package/templates/racing/src/entities/Drift.ts +243 -0
  178. package/templates/racing/src/entities/LineDriver.ts +2 -2
  179. package/templates/racing/src/entities/Nitro.ts +72 -0
  180. package/templates/racing/src/entities/RacingCar.ts +86 -21
  181. package/templates/racing/src/entities/Rival.ts +35 -21
  182. package/templates/racing/src/game.ts +7 -1
  183. package/templates/racing/src/gauges.ts +74 -0
  184. package/templates/racing/src/render/atmosphere.ts +6 -0
  185. package/templates/racing/src/render/backlightControls.ts +10 -0
  186. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  187. package/templates/racing/src/render/camera.ts +29 -4
  188. package/templates/racing/src/render/clouds.ts +16 -1
  189. package/templates/racing/src/render/effects.ts +244 -0
  190. package/templates/racing/src/render/materialLighting.ts +5 -5
  191. package/templates/racing/src/render/materials.ts +43 -8
  192. package/templates/racing/src/render/quality.ts +7 -32
  193. package/templates/racing/src/render/shapes.ts +37 -0
  194. package/templates/racing/src/render/skids.ts +84 -0
  195. package/templates/racing/src/render/touch-controls.ts +10 -10
  196. package/templates/racing/src/scenes/Race.ts +281 -26
  197. package/templates/racing/src/state.ts +35 -0
  198. package/templates/racing/src/style.css +7 -0
  199. package/templates/racing/src/track/Track.ts +132 -58
  200. package/templates/racing/src/track/TrackSector.ts +19 -1
  201. package/templates/racing/src/track/circuit.ts +21 -15
  202. package/templates/racing/src/ui/GameUi.tsx +0 -2
  203. package/templates/racing/src/ui/Hud.tsx +417 -50
  204. package/templates/racing/threenative.config.ts +15 -0
  205. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  206. package/templates/racing/tsconfig.json +1 -1
  207. package/templates/racing/vite.config.ts +2 -0
  208. package/templates/rain/AGENTS.md +6 -2
  209. package/templates/rain/CLAUDE.md +6 -2
  210. package/templates/rain/package.json +6 -6
  211. package/templates/rain/src/game.ts +1 -1
  212. package/templates/rain/src/render/noise-volume.ts +2 -1
  213. package/templates/rain/src/state.ts +3 -1
  214. package/templates/rain/src/ui/GameUi.tsx +1 -1
  215. package/templates/rain/src/ui/automation.ts +10 -8
  216. package/templates/rain/src/ui/tempest.ts +3 -4
  217. package/templates/rain/vite.config.ts +6 -0
  218. package/templates/rts/AGENTS.md +6 -2
  219. package/templates/rts/CLAUDE.md +6 -2
  220. package/templates/rts/package.json +6 -6
  221. package/templates/rts/src/game.ts +1 -1
  222. package/templates/rts/src/render/backlightControls.ts +10 -0
  223. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  224. package/templates/rts/src/render/materialLighting.ts +5 -5
  225. package/templates/rts/src/render/quality.ts +7 -31
  226. package/templates/rts/src/scenes/Play.ts +1 -1
  227. package/templates/rts/src/sim/terrain.ts +1 -0
  228. package/templates/rts/src/sim/types.ts +1 -0
  229. package/templates/rts/src/style.css +4 -0
  230. package/templates/rts/vite.config.ts +2 -0
  231. package/templates/runner/AGENTS.md +7 -2
  232. package/templates/runner/CLAUDE.md +7 -2
  233. package/templates/runner/package.json +7 -7
  234. package/templates/runner/src/game.ts +1 -1
  235. package/templates/runner/src/render/atmosphere.ts +6 -0
  236. package/templates/runner/src/render/backlightControls.ts +10 -0
  237. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  238. package/templates/runner/src/render/clouds.ts +16 -1
  239. package/templates/runner/src/render/materialLighting.ts +5 -5
  240. package/templates/runner/src/render/materials.ts +3 -2
  241. package/templates/runner/src/render/quality.ts +7 -32
  242. package/templates/runner/src/render/touch-controls.ts +7 -6
  243. package/templates/runner/src/scenes/Run.ts +8 -10
  244. package/templates/runner/src/style.css +4 -0
  245. package/templates/runner/tsconfig.json +1 -1
  246. package/templates/runner/vite.config.ts +2 -0
  247. package/templates/sailing/AGENTS.md +7 -2
  248. package/templates/sailing/CLAUDE.md +7 -2
  249. package/templates/sailing/package.json +7 -7
  250. package/templates/sailing/src/game.ts +1 -1
  251. package/templates/sailing/src/render/backlightControls.ts +10 -0
  252. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  253. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  254. package/templates/sailing/src/render/materialLighting.ts +5 -5
  255. package/templates/sailing/src/render/quality.ts +7 -32
  256. package/templates/sailing/src/render/touch-controls.ts +7 -6
  257. package/templates/sailing/src/style.css +5 -0
  258. package/templates/sailing/vite.config.ts +6 -0
  259. package/templates/shooter/AGENTS.md +6 -2
  260. package/templates/shooter/CLAUDE.md +6 -2
  261. package/templates/shooter/package.json +7 -7
  262. package/templates/shooter/src/game.ts +3 -2
  263. package/templates/shooter/src/render/atmosphere.ts +6 -0
  264. package/templates/shooter/src/render/backlightControls.ts +10 -0
  265. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  266. package/templates/shooter/src/render/clouds.ts +16 -1
  267. package/templates/shooter/src/render/materialLighting.ts +5 -5
  268. package/templates/shooter/src/render/quality.ts +7 -32
  269. package/templates/shooter/src/scenes/Play.ts +4 -1
  270. package/templates/shooter/src/style.css +4 -0
  271. package/templates/shooter/vite.config.ts +2 -0
  272. package/templates/snow/AGENTS.md +7 -2
  273. package/templates/snow/CLAUDE.md +7 -2
  274. package/templates/snow/package.json +7 -7
  275. package/templates/snow/src/entities/Explorer.ts +6 -12
  276. package/templates/snow/src/game.ts +1 -1
  277. package/templates/snow/src/render/backlightControls.ts +10 -0
  278. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  279. package/templates/snow/src/render/bootPrint.ts +3 -1
  280. package/templates/snow/src/render/camera.ts +3 -2
  281. package/templates/snow/src/render/materialLighting.ts +5 -5
  282. package/templates/snow/src/render/quality.ts +7 -32
  283. package/templates/snow/src/render/scenery.ts +3 -3
  284. package/templates/snow/src/render/touch-controls.ts +7 -6
  285. package/templates/snow/src/render/weather.ts +3 -5
  286. package/templates/snow/src/style.css +5 -0
  287. package/templates/snow/src/terrain.ts +2 -1
  288. package/templates/snow/vite.config.ts +6 -0
  289. package/templates/starter/AGENTS.md +8 -3
  290. package/templates/starter/CLAUDE.md +8 -3
  291. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  292. package/templates/starter/package.json +7 -7
  293. package/templates/starter/src/entities/Crate.ts +5 -2
  294. package/templates/starter/src/entities/Player.ts +10 -2
  295. package/templates/starter/src/game.ts +4 -3
  296. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  297. package/templates/starter/src/render/atmosphere.ts +6 -0
  298. package/templates/starter/src/render/backlightControls.ts +10 -0
  299. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  300. package/templates/starter/src/render/camera.ts +2 -2
  301. package/templates/starter/src/render/clouds.ts +16 -1
  302. package/templates/starter/src/render/contactShadow.ts +1 -1
  303. package/templates/starter/src/render/materialLighting.ts +5 -5
  304. package/templates/starter/src/render/materials.ts +3 -2
  305. package/templates/starter/src/render/postprocessing.ts +11 -10
  306. package/templates/starter/src/render/quality.ts +14 -1
  307. package/templates/starter/src/render/touch-controls.ts +7 -6
  308. package/templates/starter/src/scenes/Play.ts +13 -17
  309. package/templates/starter/src/state.ts +2 -0
  310. package/templates/starter/src/style.css +4 -0
  311. package/templates/starter/src/ui/Menu.tsx +5 -1
  312. package/templates/starter/vite.config.ts +2 -0
  313. package/templates/tower-defense/AGENTS.md +7 -2
  314. package/templates/tower-defense/CLAUDE.md +7 -2
  315. package/templates/tower-defense/package.json +7 -7
  316. package/templates/tower-defense/src/game.ts +1 -1
  317. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  318. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  319. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  320. package/templates/tower-defense/src/render/quality.ts +7 -32
  321. package/templates/tower-defense/src/render/shapes.ts +1 -2
  322. package/templates/tower-defense/src/scenes/Battle.ts +4 -9
  323. package/templates/tower-defense/src/style.css +4 -0
  324. package/templates/tower-defense/tsconfig.json +1 -1
  325. package/templates/tower-defense/vite.config.ts +2 -0
  326. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  327. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  328. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  329. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  330. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  331. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  332. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  333. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  334. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  335. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  336. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  337. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  338. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  339. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  340. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  341. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  342. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  343. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  344. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  345. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  346. package/templates/racing/src/render/environmentContribution.ts +0 -188
  347. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  348. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  349. package/templates/racing/src/render/environmentSampling.ts +0 -193
  350. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  351. package/templates/racing/src/ui/Menu.tsx +0 -7
  352. package/templates/rts/src/render/environmentContribution.ts +0 -188
  353. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  354. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  355. package/templates/rts/src/render/environmentSampling.ts +0 -193
  356. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  357. package/templates/runner/src/render/environmentContribution.ts +0 -188
  358. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  359. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  360. package/templates/runner/src/render/environmentSampling.ts +0 -193
  361. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  362. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  363. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  364. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  365. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  366. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  367. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  368. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  369. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  370. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  371. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  372. package/templates/snow/src/render/environmentContribution.ts +0 -188
  373. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  374. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  375. package/templates/snow/src/render/environmentSampling.ts +0 -193
  376. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  377. package/templates/starter/src/render/environmentContribution.ts +0 -188
  378. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  379. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  380. package/templates/starter/src/render/environmentSampling.ts +0 -193
  381. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  382. package/templates/starter/src/render/rendererGate.ts +0 -36
  383. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  384. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  385. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  386. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  387. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -1,19 +1,21 @@
1
- import type { Vector3 } from "three";
1
+ import { MathUtils, Vector3 } from "three";
2
2
  import { Boost } from "../kart/boost.js";
3
3
  import { createMaterials } from "../render/materials.js";
4
4
  import type { ITouchInput } from "../render/touch-controls.js";
5
- import { CarBody, type CarCtx, FEEL } from "./CarBody.js";
5
+ import { CarBody, type CarCtx, FEEL, driveForce } from "./CarBody.js";
6
+ import { DRIFT, Drift } from "./Drift.js";
6
7
  import { LineDriver } from "./LineDriver.js";
8
+ import { Nitro } from "./Nitro.js";
7
9
 
8
10
  /**
9
11
  * The demo driver's pace, in m/s, and the side of the road it keeps.
10
12
  *
11
- * Just under the rival's, on purpose: the demo driver is here to show the circuit and to let a
12
- * playtest ask a car to follow it, not to win the race. A demo driver that beat the rival would
13
- * make "finishing behind the rival is a DNF" untestable from the grid, and that rule is one of the
14
- * things this template has to prove.
13
+ * Under the slowest rival's, on purpose: the demo driver is here to show the circuit and to let a
14
+ * playtest ask a car to follow it, not to win the race. A demo driver that beat the field would
15
+ * make "finishing behind a rival is a DNF" untestable from the grid, and that rule is one of the
16
+ * things this template has to prove. Slower than every car ahead, it also never runs into one.
15
17
  */
16
- export const AUTOPILOT_PACE = 15.5;
18
+ export const AUTOPILOT_PACE = 20.5;
17
19
  const AUTOPILOT_OFFSET = -1.5;
18
20
 
19
21
  /**
@@ -28,13 +30,19 @@ const AUTOPILOT_OFFSET = -1.5;
28
30
  */
29
31
  export class RacingCar {
30
32
  readonly car: CarBody;
33
+ /** The boost pad's timed shove. */
31
34
  readonly boost = new Boost();
35
+ /** The driver's own tank, held to burn; drifting refills it. */
36
+ readonly nitro = new Nitro();
37
+ readonly drift = new Drift();
32
38
  /** The demo driver. Present whether or not it is engaged, so engaging is not an allocation. */
33
39
  readonly autopilot = new LineDriver({ offset: AUTOPILOT_OFFSET, pace: AUTOPILOT_PACE });
34
40
  #autopilotOn = false;
35
41
  #speedAfterBoost = 0;
36
42
  #topSpeed = 0;
37
43
  #boostWasActive = false;
44
+ #skidding = false;
45
+ readonly #push = new Vector3();
38
46
 
39
47
  constructor(ctx: CarCtx, spawn: Vector3, yaw = 0) {
40
48
  this.car = new CarBody(ctx, { materials: createMaterials(), spawn, yaw });
@@ -79,8 +87,17 @@ export class RacingCar {
79
87
  return this.#topSpeed;
80
88
  }
81
89
 
90
+ /** A boost pad or the nitro: either one drives the boosted torque curve. */
82
91
  get boosting(): boolean {
83
- return this.boost.active;
92
+ return this.boost.active || this.nitro.engaged;
93
+ }
94
+
95
+ /**
96
+ * Whether a rear tyre is leaving rubber this tick: sideways in a slide, or locked under the
97
+ * handbrake at speed. The smoke and the skid marks read this.
98
+ */
99
+ get skidding(): boolean {
100
+ return this.#skidding;
84
101
  }
85
102
 
86
103
  /** Whether the closed-loop driver has the wheel. Published, so a scenario can prove it drove. */
@@ -102,7 +119,6 @@ export class RacingCar {
102
119
  */
103
120
  update(ctx: CarCtx, dt: number, touch?: ITouchInput): void {
104
121
  this.boost.update(dt);
105
- if (ctx.input.justPressed("boost") || touch?.boostPressed === true) this.boost.activate();
106
122
  const move = ctx.input.vector("move");
107
123
  if (touch !== undefined) {
108
124
  move.x += touch.move.x;
@@ -113,13 +129,25 @@ export class RacingCar {
113
129
  // Touching the wheel takes it back, the way a driving game's demo lap does. A scenario that
114
130
  // wants to hand the car over presses a key; a player who grabs the stick gets their car.
115
131
  if (this.#autopilotOn && move.lengthSq() > 0.02) this.#autopilotOn = false;
132
+ const driver = !this.#autopilotOn;
133
+ const nitroHeld = driver && (ctx.input.pressed("boost") || touch?.boostPressed === true);
134
+ this.nitro.update(nitroHeld, this.car.groundSpeed, this.drift.drifting, dt);
135
+ // The handbrake (shift, the touch brake button): with the wheel turned at speed it kicks the
136
+ // tail out, and otherwise it is the hard brake that also holds a stopped car.
137
+ const handbrake = driver && (ctx.input.pressed("brake") || touch?.brakePressed === true);
138
+ const kick = this.drift.kicks(this.car, handbrake, move.x);
116
139
  if (this.#autopilotOn) {
117
140
  this.autopilot.update(this.car, dt);
118
141
  } else {
119
- this.drive(move, ctx.input.pressed("brake") || touch?.brakePressed === true);
142
+ this.drive(move, handbrake, kick);
120
143
  this.car.measure(dt);
121
144
  }
122
- if (this.boost.active) {
145
+ this.drift.update(this.car, kick, driver ? move.x : 0, dt);
146
+ this.#skidding =
147
+ this.car.groundSpeed > 3 &&
148
+ ((this.drift.slide > 0 && Math.abs(this.car.rearSlip) > 0.12) ||
149
+ (handbrake && this.car.groundSpeed > DRIFT.minSpeed));
150
+ if (this.boosting) {
123
151
  this.#boostWasActive = true;
124
152
  } else if (this.#boostWasActive) {
125
153
  this.#boostWasActive = false;
@@ -128,24 +156,46 @@ export class RacingCar {
128
156
  this.#topSpeed = Math.max(this.#topSpeed, this.speed);
129
157
  }
130
158
 
131
- private drive(move: { x: number; y: number }, braking: boolean): void {
159
+ private drive(move: { x: number; y: number }, braking: boolean, kick: boolean): void {
132
160
  const body = this.car.body;
133
161
  const speed = body.speed;
134
162
  // The sign: `move.x` is +1 to the right, and a positive Rapier steering angle turns toward the
135
163
  // chassis's -z, which is the driver's left. Flipping here keeps "right means right" for the
136
164
  // physics and for the visual front wheels, which take the same angle.
137
- body.steering = -move.x * this.car.lockAt(speed);
165
+ // In a slide the front wheels follow the direction of travel, which is opposite lock, and
166
+ // the driver's wheel steers around that: full grip on a wheel held 50° off its own velocity
167
+ // is a brake, measured at 15 → 4.6 m/s in half a second. `slide` fades it in and out with the
168
+ // rear grip, so the catch is continuous.
169
+ const slide = this.drift.slide;
170
+ body.steering =
171
+ -(kick ? Math.sign(move.x) : move.x * MathUtils.lerp(1, DRIFT.lockScale, slide)) *
172
+ this.car.lockAt(speed) +
173
+ MathUtils.clamp(this.drift.angle * DRIFT.counterSteer, -DRIFT.maxCounter, DRIFT.maxCounter) *
174
+ slide;
138
175
  // The brake key (shift, the touch brake button) wins over the throttle, and holds a stopped car.
139
- if (braking) {
176
+ if (slide > 0 && move.y > 0 && !braking) {
177
+ const top = (this.boosting ? FEEL.boostTopSpeed : FEEL.topSpeed) * DRIFT.thrustTopShare;
178
+ const push =
179
+ move.y * DRIFT.thrust * slide * MathUtils.clamp((top - this.car.groundSpeed) / 2, 0, 1);
180
+ this.#push.copy(this.car.forward).multiplyScalar(push);
181
+ body.applyForce(this.#push);
182
+ }
183
+ if (kick) {
184
+ // Rapier ignores the brake on a wheel that is driven, so the engine is cut for the kick.
185
+ body.engineForce = 0;
186
+ body.brake = DRIFT.handbrake;
187
+ } else if (braking) {
140
188
  body.engineForce = 0;
141
189
  body.brake = FEEL.brake;
142
- } else if (move.y > 0) {
143
- const top = this.boost.active ? FEEL.boostTopSpeed : FEEL.topSpeed;
190
+ } else if (move.y > 0 || this.nitro.engaged) {
191
+ // Nitro pushes on its own: holding the button is full throttle, as in most arcade racers.
192
+ const throttle = this.nitro.engaged ? 1 : move.y;
193
+ const top = this.boosting ? FEEL.boostTopSpeed : FEEL.topSpeed;
144
194
  body.engineForce =
145
- move.y *
195
+ throttle *
146
196
  FEEL.engineForce *
147
- (this.boost.active ? FEEL.boostForce : 1) *
148
- Math.max(0, 1 - speed / top);
197
+ (this.boosting ? FEEL.boostForce : 1) *
198
+ driveForce(speed, top);
149
199
  body.brake = 0;
150
200
  } else if (speed > FEEL.reverseEnterSpeed) {
151
201
  body.engineForce = 0;
@@ -178,8 +228,23 @@ export class RacingCar {
178
228
  debug(): Record<string, unknown> {
179
229
  return {
180
230
  autopilot: this.#autopilotOn,
181
- boostActive: this.boost.active,
182
- boostUses: this.boost.uses,
231
+ boostActive: this.boosting,
232
+ boostUses: this.boost.uses + this.nitro.uses,
233
+ drift: {
234
+ angle: Math.round(this.drift.angle * 1000) / 1000,
235
+ banked: this.drift.banked,
236
+ drifting: this.drift.drifting,
237
+ grip: this.drift.grip,
238
+ lowestGrip: this.drift.lowestGrip,
239
+ peakSlip: Math.round(this.drift.peakSlip * 1000) / 1000,
240
+ score: Math.round(this.drift.score),
241
+ spins: this.drift.spins,
242
+ },
243
+ nitro: {
244
+ engaged: this.nitro.engaged,
245
+ tank: Math.round(this.nitro.tank * 1000) / 1000,
246
+ uses: this.nitro.uses,
247
+ },
183
248
  lateralLoad: Math.round(this.lateralLoad * 100) / 100,
184
249
  normaliseFactor: this.car.normaliseFactor,
185
250
  position: this.car.position.toArray(),
@@ -1,15 +1,25 @@
1
1
  import { Vector3 } from "three";
2
2
  import { createMaterials } from "../render/materials.js";
3
- import { CIRCUIT, LINE_AT, lineDistance } from "../track/circuit.js";
3
+ import { CIRCUIT, LINE_AT, gridSlot, lineDistance } from "../track/circuit.js";
4
4
  import { CarBody, type CarCtx, RIDE } from "./CarBody.js";
5
5
  import { LineDriver } from "./LineDriver.js";
6
6
 
7
7
  /**
8
- * The rival's pace, in m/s. It is a **constant**, not a function of the player: the old rival ran a
9
- * fixed 7.6 m/s along the route whatever the player did, and rubber-banding it towards or away from
10
- * the player would be the same lie with more code. A fixed pace is beatable, and it is honest.
8
+ * The field, pole first: each rival's pace in m/s and the side of the road it keeps.
9
+ *
10
+ * A pace is a **constant**, not a function of the player: rubber-banding a rival towards or away
11
+ * from the player is a lie a driver feels. The ladder runs from just under the player's 26 m/s top
12
+ * speed down, and the grid is in pace order, so no rival ever catches the one ahead of it. A
13
+ * clean race with the nitro wins; a race with two rescues in it does not.
14
+ * Each keeps the side of the road its grid slot is on, so the two lines never share a car.
11
15
  */
12
- export const RIVAL_PACE = 17.4;
16
+ export const RIVALS = [
17
+ { pace: 25, offset: 1.5 },
18
+ { pace: 24.2, offset: -1.5 },
19
+ { pace: 23.4, offset: 1.5 },
20
+ { pace: 22.6, offset: -1.5 },
21
+ { pace: 21.8, offset: 1.5 },
22
+ ] as const;
13
23
 
14
24
  /**
15
25
  * Laps the rival has completed, from its progress in metres since the route origin. Counted at the
@@ -20,16 +30,12 @@ export function rivalLap(progress: number): number {
20
30
  return Math.max(0, Math.floor((progress - lineDistance(LINE_AT.finish)) / CIRCUIT.totalLength));
21
31
  }
22
32
 
23
- /** The side of the road the rival keeps, so it and the demo driver never share a line. */
24
- const RIVAL_OFFSET = 1.5;
25
-
26
33
  /**
27
- * The rival: a second `VehicleBody3D` on the same chassis, driven by the same {@link LineDriver}
34
+ * A rival: another `VehicleBody3D` on the same chassis, driven by the same {@link LineDriver}
28
35
  * the autopilot uses.
29
36
  *
30
- * It has a body, so the player cannot drive through it; it starts on its own grid slot, so the two
31
- * cars do not spawn inside each other; and it is ranked on its own progress around the circuit, so
32
- * the order on the HUD is two cars rather than one car and a constant.
37
+ * It has a body, so the player cannot drive through it; it starts on its own grid slot, so no two
38
+ * cars spawn inside each other; and it is ranked on its own progress around the circuit.
33
39
  *
34
40
  * There is no steering, throttle or braking code in this file. That is the point: the rival and the
35
41
  * autopilot are the *same* controller, so a playtest that presses the autopilot button is running
@@ -40,21 +46,29 @@ export class Rival {
40
46
  readonly driver: LineDriver;
41
47
  #lap = 0;
42
48
 
43
- constructor(ctx: CarCtx, startDistance: number) {
44
- const sample = CIRCUIT.at(startDistance, CIRCUIT.createSample());
49
+ /** `index` is the place on the grid, 0 on pole, and picks the pace and the livery. */
50
+ constructor(ctx: CarCtx, index: number) {
51
+ const spec = RIVALS[index];
52
+ if (spec === undefined) throw new Error(`There is no rival ${index}.`);
53
+ const slot = gridSlot(index);
54
+ const sample = CIRCUIT.at(slot.distance, CIRCUIT.createSample());
45
55
  const yaw = Math.atan2(sample.tangent.z, sample.tangent.x);
46
- // Same sculpt, different livery: the rival was indistinguishable from the player in the first
47
- // frame because both cars asked for the same material set.
56
+ // Same sculpt, different livery: a rival indistinguishable from the player in the first frame
57
+ // is a car the player cannot find in the mirror.
48
58
  const materials = createMaterials();
59
+ const livery = materials.rivalLiveries[index % materials.rivalLiveries.length];
49
60
  this.car = new CarBody(ctx, {
50
- materials: { ...materials, body: materials.rivalBody },
51
- // The centreline is authored on the terrain, so the spawn is its point raised to the
61
+ materials: { ...materials, body: livery ?? materials.rivalBody },
62
+ // The centreline is authored on the terrain, so the spawn is its height raised to the
52
63
  // chassis' ride height: dropping the car in from above reads as a jump start.
53
- spawn: new Vector3(sample.point.x, sample.point.y + RIDE, sample.point.z),
64
+ spawn: new Vector3()
65
+ .copy(sample.point)
66
+ .addScaledVector(sample.right, slot.side)
67
+ .setY(sample.point.y + RIDE),
54
68
  yaw,
55
69
  });
56
- this.driver = new LineDriver({ offset: RIVAL_OFFSET, pace: RIVAL_PACE });
57
- this.driver.reset(startDistance);
70
+ this.driver = new LineDriver({ offset: spec.offset, pace: spec.pace });
71
+ this.driver.reset(slot.distance);
58
72
  this.car.measure(1 / 60);
59
73
  }
60
74
 
@@ -2,6 +2,7 @@ import { defineGame } from "@threenative/core";
2
2
  import { playtest } from "@threenative/core/playtest";
3
3
  import { type IPhysicsContext, rapier } from "@threenative/physics";
4
4
  import config from "../threenative.config.js";
5
+ import { setRaceAudioMuted } from "./audio/engine.js";
5
6
  import { drainPlaytestEvents as events } from "./playtest-events.js";
6
7
  import { Boot } from "./scenes/Boot.js";
7
8
  import { Race } from "./scenes/Race.js";
@@ -18,6 +19,8 @@ const game = defineGame<GameState, IPhysicsContext>({
18
19
  up: ["ArrowUp", "KeyW"],
19
20
  },
20
21
  brake: { buttons: [1], keys: ["ShiftLeft", "ShiftRight"] },
22
+ // The handbrake: a hard brake, and with the wheel turned at speed it kicks the tail out.
23
+ // Nitro is held to burn.
21
24
  boost: { buttons: [0], keys: ["Space"] },
22
25
  restart: { keys: ["KeyR"] },
23
26
  // The demo driver: the same closed-loop controller the rival uses, on the player's car. It is
@@ -28,7 +31,7 @@ const game = defineGame<GameState, IPhysicsContext>({
28
31
  },
29
32
  plugins: [rapier({ gravity: { x: 0, y: -24, z: 0 } }), playtest({ events })],
30
33
  display: config.display,
31
- render: config.renderer,
34
+ renderer: config.renderer,
32
35
  scenes: { boot: Boot, race: Race },
33
36
  seed: 90210,
34
37
  start: "boot",
@@ -47,6 +50,9 @@ game.ui.onIntent((intent) => {
47
50
  if (intent === "restart") void game.goto("race");
48
51
  if (intent === "pause") game.pause();
49
52
  if (intent === "resume") game.resume();
53
+ // The frame loop does not tick while paused, so nothing inside the scene could silence the
54
+ // engine: the bus is muted here, where the pause intent already is.
55
+ if (intent === "pause" || intent === "resume") setRaceAudioMuted(intent === "pause");
50
56
  game.state.set({
51
57
  // `game.ui.connected` is true only once the UI announced itself, which is what tells an
52
58
  // overlay that never came up apart from a game whose HUD is simply empty.
@@ -0,0 +1,74 @@
1
+ import { MathUtils } from "three";
2
+ import { FEEL } from "./entities/CarBody.js";
3
+
4
+ /**
5
+ * The rev counter's rules, transcribed from Need for Speed: Most Wanted (`EngineRacer.cpp:606-907`).
6
+ *
7
+ * Display only — nothing here touches the car — but a rev counter that steps is the loudest tell
8
+ * that a driving game's numbers are decoration. Two rules make it read as an engine: the needle
9
+ * falls at a **capped rate** with no load, and every update is a blend of 55% of the new reading
10
+ * with 45% of the last, so a gear change sweeps instead of snapping.
11
+ */
12
+ export const GAUGES = {
13
+ /** Gears in the box. One band each, so a gear covers `topSpeed / gears` from rest. */
14
+ gears: 6,
15
+ /** The needle at a standstill, as a share of the gear's band. */
16
+ idle: 0.09,
17
+ /** Where an upshift happens, and — coming back down — where a downshift happens. */
18
+ upshift: 0.94,
19
+ downshift: 0.42,
20
+ /** The most the needle may fall in a second, as a share of a gear's band. */
21
+ fallPerSecond: 1.4,
22
+ /** NFS's own blend: 55% of the new reading, 45% of the last. */
23
+ newShare: 0.55,
24
+ } as const;
25
+
26
+ /** The speed one gear covers, in m/s: `[low, high]`, gear 1 from rest. */
27
+ export function gearBand(
28
+ gear: number,
29
+ top: number = FEEL.topSpeed,
30
+ gears: number = GAUGES.gears,
31
+ ): [number, number] {
32
+ const span = top / gears;
33
+ return [(gear - 1) * span, gear * span];
34
+ }
35
+
36
+ /** What a speed reads on the needle in a given gear, 0 to 1 of that gear's band. */
37
+ export function rpmIn(
38
+ speed: number,
39
+ gear: number,
40
+ top: number = FEEL.topSpeed,
41
+ gears: number = GAUGES.gears,
42
+ ): number {
43
+ // Indexed reads, not a destructure: this runs every frame, and destructuring a tuple allocates
44
+ // an array iterator (`template-runtime-cost.spec.ts` holds the scene to zero per frame).
45
+ const band = gearBand(gear, top, gears);
46
+ const low = band[0];
47
+ return MathUtils.clamp((speed - low) / (band[1] - low), 0, 1);
48
+ }
49
+
50
+ /**
51
+ * The needle and the gear, one tick at a time.
52
+ *
53
+ * The gear is chosen from the **reading**, never from the needle: a gear decides the needle's band,
54
+ * so a needle deciding the gear is a feedback loop that hunts on a steady speed.
55
+ */
56
+ export class Gauges {
57
+ gear = 1;
58
+ /** The needle, 0 to 1 of the current gear's band. */
59
+ rpm: number = GAUGES.idle;
60
+
61
+ /** `speed` is signed, so reverse reads as idle in first gear rather than as a negative band. */
62
+ update(speed: number, dt: number): void {
63
+ const ground = Math.max(0, speed);
64
+ // One gear per tick at most: a rescue teleport can jump the speed by 30 m/s, and climbing six
65
+ // gears in one tick is a needle that flickers through the whole box.
66
+ if (rpmIn(ground, this.gear) > GAUGES.upshift && this.gear < GAUGES.gears) this.gear += 1;
67
+ else if (rpmIn(ground, this.gear) < GAUGES.downshift && this.gear > 1) this.gear -= 1;
68
+ const reading = Math.max(GAUGES.idle, rpmIn(ground, this.gear));
69
+ // The cap is on the fall only: a shift up drops the reading, and the needle follows it over a
70
+ // few ticks. A reading that rises is followed at once, which is what a blip of throttle does.
71
+ const capped = Math.max(reading, this.rpm - GAUGES.fallPerSecond * dt);
72
+ this.rpm = GAUGES.newShare * capped + (1 - GAUGES.newShare) * this.rpm;
73
+ }
74
+ }
@@ -235,7 +235,13 @@ function march(
235
235
  * approximation in RenderMultiScatteredLuminanceLutCS); the full sphere gather overestimated the
236
236
  * ground bounce against the Unreal frames by up to 1.6x, so this uses the same two rays.
237
237
  */
238
+ // The table depends on no input: build it once a run, not once a sky refresh.
239
+ let multipleScattering: Multi | undefined;
238
240
  function multipleScatteringTable(): Multi {
241
+ multipleScattering ??= buildMultipleScatteringTable();
242
+ return multipleScattering;
243
+ }
244
+ function buildMultipleScatteringTable(): Multi {
239
245
  const nh = 12;
240
246
  const nc = 16;
241
247
  const dirs: Vec3[] = [
@@ -10,6 +10,11 @@ function finiteColor(color: Color) {
10
10
  color.b >= 0
11
11
  );
12
12
  }
13
+ /**
14
+ * Throws when a `IBacklightControls` is missing a light or names a non-finite gain.
15
+ *
16
+ * @situation fail loudly instead of drawing an unlit material when a backlight has no key light
17
+ */
13
18
  export function validateControls(controls: IBacklightControls) {
14
19
  if (
15
20
  !Number.isFinite(controls.rimGain) ||
@@ -30,6 +35,11 @@ export function validateControls(controls: IBacklightControls) {
30
35
  "Backlight controls require finite nonnegative gains, a direction and angular size in (0, 1.5].",
31
36
  );
32
37
  }
38
+ /**
39
+ * The light and camera a backlit material reads its key direction from.
40
+ *
41
+ * @situation point the backlight at the sun the scene actually has
42
+ */
33
43
  export function resolveKey(
34
44
  controls: IBacklightControls,
35
45
  direction: Vector3,
@@ -48,10 +48,10 @@ export interface IBacklightControls {
48
48
  const graphs = new WeakMap<IBacklightControls, ReturnType<typeof createGraph>>();
49
49
 
50
50
  /**
51
- * Preserve the upstream standard PBR/normal/skinning paths and original material emissive.
52
- * This is an additive artistic convention, not a physical subsurface model or IBL replacement.
53
- * Cache at the caller to preserve shared source-material relationships; dispose only conversions
54
- * it owns, never maps/source materials borrowed from a loaded model.
51
+ * The game's material, wrapped in a node twin that adds the backlit sheen it was given.
52
+ *
53
+ * @situation give a material a launcher's glow without editing its colour, texture or roughness
54
+ * @constraint every colour, gain and angular size is the caller's; this copies the game's material and adds light
55
55
  */
56
56
  export function backlightMaterial(source: MeshStandardMaterial, controls: IBacklightControls) {
57
57
  if (
@@ -10,11 +10,19 @@ const EYE_BACK = 6.6;
10
10
  const LEAD_BASE = 1.5;
11
11
  const LEAD_PER_MPS = 0.42;
12
12
 
13
+ /** How fast the chase heading turns toward the travel direction, per second (12% a 60 Hz tick). */
14
+ const TURN_RATE = 7.7;
15
+
16
+ /** A nitro burn widens the lens and pulls the camera back: the oldest speed cue there is. */
17
+ export const BASE_FOV = 56;
18
+ const BOOST_FOV = 10;
19
+ const BOOST_BACK = 0.8;
20
+
13
21
  /** The most the camera will bank, in radians. Past this a corner reads as a barrel roll. */
14
22
  const MAX_BANK = 0.055;
15
23
 
16
24
  export function setupCamera(camera: PerspectiveCamera): void {
17
- camera.fov = 56;
25
+ camera.fov = BASE_FOV;
18
26
  camera.near = 0.1;
19
27
  camera.far = 340;
20
28
  camera.updateProjectionMatrix();
@@ -24,6 +32,10 @@ export function setupCamera(camera: PerspectiveCamera): void {
24
32
  // every racing game built from this template; three Vector clones a frame was pure garbage.
25
33
  const behind = new Vector3();
26
34
  const desired = new Vector3();
35
+ /** The heading the camera chases, eased toward the travel direction rather than snapped to it. */
36
+ let chaseYaw = 0;
37
+ /** 0 at rest, 1 in a nitro burn: eased in faster than it eases out. */
38
+ let surge = 0;
27
39
  const look = new Vector3();
28
40
  const velocity = new Vector3();
29
41
 
@@ -41,6 +53,7 @@ export function chaseCamera(
41
53
  heading: Vector3,
42
54
  dt: number,
43
55
  carVelocity?: { readonly x: number; y: number; z: number },
56
+ boosting = false,
44
57
  ): void {
45
58
  // The direction the car is travelling, flattened. Under half a metre per second there is no
46
59
  // direction to speak of and the nose is the best available answer.
@@ -50,11 +63,23 @@ export function chaseCamera(
50
63
  if (velocity.lengthSq() > 0.25) behind.copy(velocity).normalize();
51
64
  }
52
65
  if (behind.lengthSq() < 0.0001) behind.set(1, 0, 0);
53
- behind.normalize();
54
- desired.copy(target).addScaledVector(behind, -EYE_BACK);
66
+ // Ease the heading, as the kart kit's camera does (12% of the gap a 60 Hz tick). Snapped to the
67
+ // raw velocity, a kerb, a wall or the 0.5 m/s switch back to the nose swung the view 84° in one
68
+ // tick; eased, a corner still opens up ahead but the camera turns like a camera operator.
69
+ const wanted = Math.atan2(behind.z, behind.x);
70
+ const gap = MathUtils.euclideanModulo(wanted - chaseYaw + Math.PI, Math.PI * 2) - Math.PI;
71
+ chaseYaw = dt >= 1 ? wanted : chaseYaw + gap * MathUtils.damp(0, 1, TURN_RATE, dt);
72
+ behind.set(Math.cos(chaseYaw), 0, Math.sin(chaseYaw));
73
+ surge = dt >= 1 ? 0 : MathUtils.damp(surge, boosting ? 1 : 0, boosting ? 5 : 2.2, dt);
74
+ const fov = BASE_FOV + BOOST_FOV * surge;
75
+ if (Math.abs(camera.fov - fov) > 0.01) {
76
+ camera.fov = fov;
77
+ camera.updateProjectionMatrix();
78
+ }
79
+ desired.copy(target).addScaledVector(behind, -EYE_BACK - BOOST_BACK * surge);
55
80
  desired.y += EYE_UP;
56
81
  if (dt >= 1) camera.position.copy(desired);
57
- else camera.position.lerp(desired, 1 - Math.exp(-dt / 0.2));
82
+ else camera.position.lerp(desired, MathUtils.damp(0, 1, 5, dt));
58
83
  // Look ahead along the same travel direction, so a fast car sees the corner it is entering
59
84
  // rather than the road immediately under its own nose.
60
85
  const speed = Math.hypot(velocity.x, velocity.z);
@@ -6,6 +6,8 @@
6
6
  // Independent CPU implementation. The material samples four Unreal textures that this repository
7
7
  // must not carry, so each one is regenerated here from a seeded noise whose per-channel value
8
8
  // quantiles and correlation lengths match the Unreal texture (measured, see the spec).
9
+ import { MathUtils } from "three";
10
+
9
11
  import {
10
12
  BOTTOM_KM,
11
13
  CAMERA_KM,
@@ -110,7 +112,7 @@ const PROFILE_COEFFICIENTS = [
110
112
  const clamp = (v: number): number => Math.max(0, Math.min(1, v));
111
113
  const smooth = (v: number): number => {
112
114
  const t = clamp(v);
113
- return t * t * (3 - 2 * t);
115
+ return MathUtils.smoothstep(t, 0, 1);
114
116
  };
115
117
  const mod = (a: number, n: number): number => ((a % n) + n) % n;
116
118
 
@@ -282,6 +284,19 @@ export interface ICloudTextures {
282
284
  }
283
285
  const textureCache = new Map<number, ICloudTextures>();
284
286
 
287
+ /**
288
+ * Hand back the textures an earlier run generated, so `cloudTextures(seed)` skips ~0.6 s of noise
289
+ * on the main thread. The scene keeps them between runs with `ctx.assets.memo`.
290
+ */
291
+ export function primeCloudTextures(textures: ICloudTextures, seed = 631): void {
292
+ if (
293
+ textures.pattern.length !== PATTERN_SIZE ** 2 * 4 ||
294
+ textures.volume.length !== VOLUME_SIZE ** 3 * 2
295
+ )
296
+ throw new Error("cloud textures do not match PATTERN_SIZE and VOLUME_SIZE.");
297
+ textureCache.set(seed, textures);
298
+ }
299
+
285
300
  export function cloudTextures(seed = 631): ICloudTextures {
286
301
  const cached = textureCache.get(seed);
287
302
  if (cached) return cached;