create-threenative 0.2.5 → 0.2.7

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 (631) hide show
  1. package/README.md +25 -3
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/build-profiles.md +126 -0
  4. package/agent-docs/references/capability-reference.md +1382 -65
  5. package/agent-docs/references/finding-assets.md +8 -1
  6. package/agent-docs/references/performance-basics.md +117 -0
  7. package/agent-docs/references/rigging-characters.md +51 -0
  8. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  9. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  10. package/agent-docs/references/visual-baseline.md +8 -4
  11. package/agent-docs/references/webview-ui.md +3 -2
  12. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  13. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  14. package/agent-files/.agents/skills/threenative-assets/SKILL.md +12 -4
  15. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  16. package/agent-files/.agents/skills/threenative-context/SKILL.md +9 -1
  17. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  19. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  20. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  21. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  22. package/agent-files/.claude/settings.json +38 -0
  23. package/agent-files/.codex/hooks.json +40 -0
  24. package/capabilities.json +1891 -101
  25. package/dist/index.d.ts +39 -1
  26. package/dist/index.js +480 -56
  27. package/dist/threenative.js +1247 -177
  28. package/package.json +6 -6
  29. package/template-assets/assets/mannequin-combat.glb +0 -0
  30. package/template-assets/assets/mannequin.glb +0 -0
  31. package/template-assets/assets/player-viewmodel.glb +0 -0
  32. package/template-assets/assets/sky.jpg +0 -0
  33. package/template-assets/clearwater/README.md +141 -0
  34. package/template-assets/clearwater/install.mjs +50 -0
  35. package/template-assets/clearwater/src/clearwater.ts +180 -0
  36. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  37. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  38. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  39. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  40. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  41. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  42. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  43. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  44. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  45. package/template-assets/patches/three@0.185.1.patch +2228 -105
  46. package/template-assets/worldEnvironment.ts +52 -1
  47. package/templates/action-rpg/AGENTS.md +43 -43
  48. package/templates/action-rpg/CLAUDE.md +43 -43
  49. package/templates/action-rpg/kit.json +1 -1
  50. package/templates/action-rpg/package.json +14 -8
  51. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  52. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  53. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  54. package/templates/action-rpg/src/conventions.ts +24 -18
  55. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  56. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  57. package/templates/action-rpg/src/entities/Player.ts +102 -32
  58. package/templates/action-rpg/src/game.ts +3 -3
  59. package/templates/action-rpg/src/render/camera.ts +18 -16
  60. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  61. package/templates/action-rpg/src/render/lighting.ts +45 -28
  62. package/templates/action-rpg/src/render/loading.ts +4 -4
  63. package/templates/action-rpg/src/render/materials.ts +191 -47
  64. package/templates/action-rpg/src/render/palette.ts +14 -13
  65. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  66. package/templates/action-rpg/src/render/props.ts +117 -0
  67. package/templates/action-rpg/src/render/quality.ts +40 -82
  68. package/templates/action-rpg/src/render/sky.ts +36 -13
  69. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  71. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  72. package/templates/action-rpg/src/style.css +9 -7
  73. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  74. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  75. package/templates/action-rpg/threenative.config.ts +14 -1
  76. package/templates/action-rpg/vite.config.ts +4 -1
  77. package/templates/minimal/AGENTS.md +12 -12
  78. package/templates/minimal/CLAUDE.md +12 -12
  79. package/templates/minimal/package.json +13 -7
  80. package/templates/minimal/playtests/play.playtest.json +6 -5
  81. package/templates/minimal/playtests/sky.playtest.json +27 -0
  82. package/templates/minimal/src/conventions.ts +6 -3
  83. package/templates/minimal/src/entities/Player.ts +73 -27
  84. package/templates/minimal/src/main.ts +2 -3
  85. package/templates/minimal/src/render/camera.ts +22 -4
  86. package/templates/minimal/src/render/lighting.ts +24 -48
  87. package/templates/minimal/src/render/materials.ts +158 -13
  88. package/templates/minimal/src/render/palette.ts +10 -7
  89. package/templates/minimal/src/render/postprocessing.ts +12 -25
  90. package/templates/minimal/src/render/quality.ts +35 -69
  91. package/templates/minimal/src/render/sky.ts +35 -54
  92. package/templates/minimal/src/render/touch-controls.ts +1 -1
  93. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  94. package/templates/minimal/src/scenes/Play.ts +121 -111
  95. package/templates/minimal/src/state.ts +0 -4
  96. package/templates/minimal/src/style.css +0 -10
  97. package/templates/minimal/threenative.config.ts +15 -1
  98. package/templates/minimal/vite.config.ts +4 -1
  99. package/templates/platformer/AGENTS.md +18 -56
  100. package/templates/platformer/CLAUDE.md +18 -56
  101. package/templates/platformer/kit.json +2 -2
  102. package/templates/platformer/package.json +14 -10
  103. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  104. package/templates/platformer/playtests/collect.playtest.json +8 -34
  105. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  106. package/templates/platformer/playtests/damage.playtest.json +40 -15
  107. package/templates/platformer/playtests/hud.playtest.json +34 -0
  108. package/templates/platformer/playtests/move.playtest.json +24 -0
  109. package/templates/platformer/playtests/performance.playtest.json +24 -7
  110. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  111. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  112. package/templates/platformer/playtests/survives.playtest.json +3 -19
  113. package/templates/platformer/playtests/world.playtest.json +26 -0
  114. package/templates/platformer/src/entities/Fox.ts +273 -0
  115. package/templates/platformer/src/entities/Pickup.ts +43 -60
  116. package/templates/platformer/src/entities/Walker.ts +88 -0
  117. package/templates/platformer/src/game.ts +11 -8
  118. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  119. package/templates/platformer/src/level/Stage.ts +469 -0
  120. package/templates/platformer/src/render/blocks.ts +94 -0
  121. package/templates/platformer/src/render/camera.ts +28 -3
  122. package/templates/platformer/src/render/fox.ts +196 -0
  123. package/templates/platformer/src/render/lighting.ts +42 -33
  124. package/templates/platformer/src/render/materials.ts +115 -5
  125. package/templates/platformer/src/render/palette.ts +68 -53
  126. package/templates/platformer/src/render/pickups.ts +142 -0
  127. package/templates/platformer/src/render/postprocessing.ts +12 -2
  128. package/templates/platformer/src/render/props.ts +147 -0
  129. package/templates/platformer/src/render/quality.ts +47 -99
  130. package/templates/platformer/src/render/scenery.ts +172 -0
  131. package/templates/platformer/src/render/sky.ts +120 -31
  132. package/templates/platformer/src/render/touch-controls.ts +5 -2
  133. package/templates/platformer/src/render/walkers.ts +96 -0
  134. package/templates/platformer/src/render/waterfall.ts +85 -0
  135. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  136. package/templates/platformer/src/scenes/Boot.ts +3 -4
  137. package/templates/platformer/src/scenes/Play.ts +362 -0
  138. package/templates/platformer/src/state.ts +16 -14
  139. package/templates/platformer/src/style.css +9 -8
  140. package/templates/platformer/src/ui/Hud.tsx +62 -29
  141. package/templates/platformer/src/ui/Menu.tsx +2 -2
  142. package/templates/platformer/threenative.config.ts +14 -1
  143. package/templates/platformer/vite.config.ts +4 -1
  144. package/templates/puzzle/AGENTS.md +21 -22
  145. package/templates/puzzle/CLAUDE.md +21 -22
  146. package/templates/puzzle/assets/native-proof.glb +0 -0
  147. package/templates/puzzle/assets/native-proof.png +0 -0
  148. package/templates/puzzle/kit.json +1 -1
  149. package/templates/puzzle/package.json +14 -8
  150. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  151. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  152. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  153. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  154. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  155. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  156. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  157. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  158. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  159. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  160. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  161. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  162. package/templates/puzzle/src/entities/Crate.ts +99 -42
  163. package/templates/puzzle/src/entities/Seal.ts +69 -0
  164. package/templates/puzzle/src/entities/Warden.ts +135 -0
  165. package/templates/puzzle/src/game.ts +15 -11
  166. package/templates/puzzle/src/render/camera.ts +66 -31
  167. package/templates/puzzle/src/render/crateShape.ts +70 -0
  168. package/templates/puzzle/src/render/lighting.ts +41 -41
  169. package/templates/puzzle/src/render/loading.ts +4 -4
  170. package/templates/puzzle/src/render/materials.ts +131 -27
  171. package/templates/puzzle/src/render/palette.ts +19 -29
  172. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  173. package/templates/puzzle/src/render/quality.ts +71 -80
  174. package/templates/puzzle/src/render/shapes.ts +109 -108
  175. package/templates/puzzle/src/render/sky.ts +18 -10
  176. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  177. package/templates/puzzle/src/render/vault.ts +315 -0
  178. package/templates/puzzle/src/render/warden.ts +46 -0
  179. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  180. package/templates/puzzle/src/scenes/Play.ts +793 -0
  181. package/templates/puzzle/src/state.ts +55 -24
  182. package/templates/puzzle/src/style.css +7 -8
  183. package/templates/puzzle/src/ui/App.tsx +2 -2
  184. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  185. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  186. package/templates/puzzle/threenative.config.ts +14 -1
  187. package/templates/puzzle/vite.config.ts +4 -1
  188. package/templates/racing/AGENTS.md +20 -21
  189. package/templates/racing/CLAUDE.md +20 -21
  190. package/templates/racing/package.json +14 -8
  191. package/templates/racing/playtests/boost.playtest.json +33 -12
  192. package/templates/racing/playtests/outcome.playtest.json +32 -50
  193. package/templates/racing/playtests/performance.playtest.json +2 -1
  194. package/templates/racing/playtests/ranking.playtest.json +5 -14
  195. package/templates/racing/playtests/rescue.playtest.json +2 -2
  196. package/templates/racing/playtests/reverse.playtest.json +30 -8
  197. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  198. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  199. package/templates/racing/src/entities/CarBody.ts +327 -0
  200. package/templates/racing/src/entities/LineDriver.ts +220 -0
  201. package/templates/racing/src/entities/RacingCar.ts +150 -89
  202. package/templates/racing/src/entities/Rival.ts +61 -24
  203. package/templates/racing/src/game.ts +5 -0
  204. package/templates/racing/src/render/camera.ts +49 -7
  205. package/templates/racing/src/render/lighting.ts +36 -37
  206. package/templates/racing/src/render/materials.ts +239 -19
  207. package/templates/racing/src/render/palette.ts +19 -21
  208. package/templates/racing/src/render/postprocessing.ts +12 -2
  209. package/templates/racing/src/render/quality.ts +43 -82
  210. package/templates/racing/src/render/shapes.ts +20 -6
  211. package/templates/racing/src/render/sky.ts +47 -39
  212. package/templates/racing/src/render/touch-controls.ts +1 -1
  213. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  214. package/templates/racing/src/scenes/Race.ts +107 -54
  215. package/templates/racing/src/state.ts +2 -0
  216. package/templates/racing/src/track/Checkline.ts +22 -7
  217. package/templates/racing/src/track/Lap.ts +64 -36
  218. package/templates/racing/src/track/Ranking.ts +20 -11
  219. package/templates/racing/src/track/Track.ts +809 -361
  220. package/templates/racing/src/track/TrackSector.ts +40 -11
  221. package/templates/racing/src/track/circuit.ts +477 -0
  222. package/templates/racing/src/track/rescue.ts +16 -4
  223. package/templates/racing/threenative.config.ts +14 -1
  224. package/templates/racing/vite.config.ts +4 -1
  225. package/templates/rts/AGENTS.md +96 -0
  226. package/templates/rts/CLAUDE.md +98 -0
  227. package/templates/rts/kit.json +7 -0
  228. package/templates/{defense → rts}/package.json +14 -8
  229. package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
  230. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  231. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  232. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  233. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  234. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  235. package/templates/rts/playtests/survives.playtest.json +58 -0
  236. package/templates/rts/public/favicon.svg +4 -0
  237. package/templates/rts/src/game.ts +64 -0
  238. package/templates/rts/src/orders.ts +22 -0
  239. package/templates/rts/src/render/army.ts +346 -0
  240. package/templates/rts/src/render/camera.ts +123 -0
  241. package/templates/rts/src/render/lighting.ts +61 -0
  242. package/templates/rts/src/render/loading.ts +33 -0
  243. package/templates/rts/src/render/materials.ts +152 -0
  244. package/templates/rts/src/render/models.ts +705 -0
  245. package/templates/rts/src/render/palette.ts +17 -0
  246. package/templates/rts/src/render/picking.ts +93 -0
  247. package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
  248. package/templates/rts/src/render/quality.ts +128 -0
  249. package/templates/rts/src/render/resources.ts +141 -0
  250. package/templates/rts/src/render/sky.ts +44 -0
  251. package/templates/rts/src/render/terrain.ts +116 -0
  252. package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
  253. package/templates/rts/src/scenes/Play.ts +650 -0
  254. package/templates/rts/src/sim/ai.ts +1140 -0
  255. package/templates/rts/src/sim/combat.ts +416 -0
  256. package/templates/rts/src/sim/construction.ts +374 -0
  257. package/templates/rts/src/sim/economy.ts +167 -0
  258. package/templates/rts/src/sim/game.ts +1082 -0
  259. package/templates/rts/src/sim/movement.ts +371 -0
  260. package/templates/rts/src/sim/nav.ts +276 -0
  261. package/templates/rts/src/sim/production.ts +180 -0
  262. package/templates/rts/src/sim/terrain.ts +170 -0
  263. package/templates/rts/src/sim/types.ts +647 -0
  264. package/templates/rts/src/sim/vision.ts +46 -0
  265. package/templates/rts/src/state.ts +100 -0
  266. package/templates/{defense → rts}/src/style.css +21 -8
  267. package/templates/rts/src/ui/App.tsx +21 -0
  268. package/templates/rts/src/ui/Commands.tsx +129 -0
  269. package/templates/rts/src/ui/GameUi.tsx +22 -0
  270. package/templates/rts/src/ui/Hud.tsx +165 -0
  271. package/templates/rts/src/ui/Minimap.tsx +84 -0
  272. package/templates/rts/tailwind.config.ts +2 -0
  273. package/templates/rts/threenative.config.ts +56 -0
  274. package/templates/rts/tsconfig.json +17 -0
  275. package/templates/{defense → rts}/vite.config.ts +4 -1
  276. package/templates/runner/AGENTS.md +8 -12
  277. package/templates/runner/CLAUDE.md +8 -12
  278. package/templates/runner/README.md +3 -3
  279. package/templates/runner/package.json +14 -8
  280. package/templates/runner/playtests/performance.playtest.json +2 -2
  281. package/templates/runner/src/conventions.ts +4 -3
  282. package/templates/runner/src/entities/Runner.ts +54 -7
  283. package/templates/runner/src/game.ts +2 -0
  284. package/templates/runner/src/render/camera.ts +4 -2
  285. package/templates/runner/src/render/dust.ts +5 -2
  286. package/templates/runner/src/render/lighting.ts +41 -45
  287. package/templates/runner/src/render/loading.ts +2 -2
  288. package/templates/runner/src/render/materials.ts +165 -25
  289. package/templates/runner/src/render/palette.ts +17 -28
  290. package/templates/runner/src/render/postprocessing.ts +12 -2
  291. package/templates/runner/src/render/quality.ts +42 -96
  292. package/templates/runner/src/render/shapes.ts +59 -37
  293. package/templates/runner/src/render/sky.ts +32 -41
  294. package/templates/runner/src/render/touch-controls.ts +1 -1
  295. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  296. package/templates/runner/src/scenes/Run.ts +26 -6
  297. package/templates/runner/src/track.ts +6 -1
  298. package/templates/runner/threenative.config.ts +14 -1
  299. package/templates/runner/vite.config.ts +4 -1
  300. package/templates/sailing/AGENTS.md +14 -14
  301. package/templates/sailing/CLAUDE.md +14 -14
  302. package/templates/sailing/assets/ship.glb +0 -0
  303. package/templates/sailing/package.json +14 -8
  304. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  305. package/templates/sailing/playtests/sails.playtest.json +33 -0
  306. package/templates/sailing/playtests/win.playtest.json +156 -8
  307. package/templates/sailing/src/conventions.ts +29 -2
  308. package/templates/sailing/src/entities/Ship.ts +381 -57
  309. package/templates/sailing/src/game.ts +14 -0
  310. package/templates/sailing/src/render/camera.ts +63 -9
  311. package/templates/sailing/src/render/lighting.ts +49 -27
  312. package/templates/sailing/src/render/materials.ts +50 -15
  313. package/templates/sailing/src/render/ocean.ts +647 -60
  314. package/templates/sailing/src/render/palette.ts +16 -12
  315. package/templates/sailing/src/render/postprocessing.ts +12 -2
  316. package/templates/sailing/src/render/props.ts +316 -442
  317. package/templates/sailing/src/render/quality.ts +14 -4
  318. package/templates/sailing/src/render/sky.ts +116 -23
  319. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  320. package/templates/sailing/src/scenes/Boot.ts +21 -0
  321. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  322. package/templates/sailing/src/state.ts +6 -0
  323. package/templates/sailing/src/ui/Hud.tsx +41 -9
  324. package/templates/sailing/threenative.config.ts +14 -1
  325. package/templates/sailing/vite.config.ts +4 -1
  326. package/templates/shooter/AGENTS.md +29 -44
  327. package/templates/shooter/CLAUDE.md +29 -44
  328. package/templates/shooter/index.html +1 -0
  329. package/templates/shooter/package.json +14 -8
  330. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  331. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  332. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  333. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  334. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  335. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  336. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  337. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  338. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  339. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  340. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  341. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  342. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  343. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  344. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  345. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  346. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  347. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  348. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  349. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  350. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  351. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  352. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  353. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  354. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  355. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  356. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  357. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  358. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  359. package/templates/shooter/playtests/performance.playtest.json +62 -26
  360. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  361. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  362. package/templates/shooter/playtests/survives.playtest.json +36 -30
  363. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  364. package/templates/shooter/src/entities/Breakables.ts +412 -0
  365. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  366. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  367. package/templates/shooter/src/entities/Rifle.ts +442 -0
  368. package/templates/shooter/src/entities/Target.ts +199 -83
  369. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  370. package/templates/shooter/src/game.ts +75 -41
  371. package/templates/shooter/src/main.ts +0 -1
  372. package/templates/shooter/src/postPhysics.ts +36 -0
  373. package/templates/shooter/src/render/camera.ts +78 -74
  374. package/templates/shooter/src/render/decals.ts +142 -82
  375. package/templates/shooter/src/render/facade.ts +1373 -0
  376. package/templates/shooter/src/render/gunfx.ts +704 -0
  377. package/templates/shooter/src/render/lighting.ts +52 -38
  378. package/templates/shooter/src/render/loading.ts +2 -2
  379. package/templates/shooter/src/render/materials.ts +100 -88
  380. package/templates/shooter/src/render/occlusion.ts +108 -0
  381. package/templates/shooter/src/render/palette.ts +10 -10
  382. package/templates/shooter/src/render/palm.ts +455 -0
  383. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  384. package/templates/shooter/src/render/postprocessing.ts +15 -3
  385. package/templates/shooter/src/render/quality.ts +40 -82
  386. package/templates/shooter/src/render/scale.ts +148 -15
  387. package/templates/shooter/src/render/shapes.ts +138 -613
  388. package/templates/shooter/src/render/sky.ts +35 -35
  389. package/templates/shooter/src/render/town-schematic.ts +120 -0
  390. package/templates/shooter/src/render/town.ts +986 -0
  391. package/templates/shooter/src/render/townMaterials.ts +160 -0
  392. package/templates/shooter/src/render/vehicles.ts +741 -0
  393. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  394. package/templates/shooter/src/scenes/Play.ts +727 -650
  395. package/templates/shooter/src/state.ts +26 -41
  396. package/templates/shooter/src/style.css +207 -11
  397. package/templates/shooter/src/surfaces.ts +131 -0
  398. package/templates/shooter/src/ui/App.tsx +9 -10
  399. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  400. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  401. package/templates/shooter/src/ui/Hud.tsx +428 -39
  402. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  403. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  404. package/templates/shooter/src/ui/main.tsx +2 -3
  405. package/templates/shooter/threenative.config.ts +14 -1
  406. package/templates/shooter/vite.config.ts +4 -1
  407. package/templates/starter/AGENTS.md +20 -20
  408. package/templates/starter/CLAUDE.md +20 -20
  409. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  410. package/templates/starter/package.json +15 -9
  411. package/templates/starter/playtests/play.playtest.json +2 -1
  412. package/templates/starter/playtests/{restart.playtest.json → production-readiness.playtest.json} +17 -12
  413. package/templates/starter/playtests/survives.playtest.json +1 -1
  414. package/templates/starter/src/conventions.ts +6 -3
  415. package/templates/starter/src/entities/Goal.ts +35 -42
  416. package/templates/starter/src/entities/Player.ts +99 -16
  417. package/templates/starter/src/render/arena.ts +131 -0
  418. package/templates/starter/src/render/lighting.ts +27 -44
  419. package/templates/starter/src/render/materials.ts +164 -35
  420. package/templates/starter/src/render/palette.ts +16 -16
  421. package/templates/starter/src/render/postprocessing.ts +6 -7
  422. package/templates/starter/src/render/quality.ts +43 -101
  423. package/templates/starter/src/render/shapes.ts +1 -1
  424. package/templates/starter/src/render/sky.ts +39 -45
  425. package/templates/starter/src/render/touch-controls.ts +3 -1
  426. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  427. package/templates/starter/src/scenes/Play.ts +82 -81
  428. package/templates/starter/src/ui/Hud.tsx +2 -2
  429. package/templates/starter/src/ui/Menu.tsx +5 -1
  430. package/templates/starter/threenative.config.ts +14 -1
  431. package/templates/starter/vite.config.ts +4 -1
  432. package/templates/tower-defense/.codex/config.toml +19 -0
  433. package/templates/tower-defense/.cursor/mcp.json +32 -0
  434. package/templates/tower-defense/.gemini/settings.json +32 -0
  435. package/templates/tower-defense/.mcp.json +32 -0
  436. package/templates/tower-defense/.vscode/mcp.json +36 -0
  437. package/templates/tower-defense/.zed/settings.json +36 -0
  438. package/templates/{defense → tower-defense}/AGENTS.md +16 -14
  439. package/templates/{defense → tower-defense}/CLAUDE.md +16 -14
  440. package/templates/tower-defense/README.md +16 -0
  441. package/templates/tower-defense/index.html +12 -0
  442. package/templates/tower-defense/kit.json +7 -0
  443. package/templates/tower-defense/opencode.json +41 -0
  444. package/templates/tower-defense/package.json +56 -0
  445. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  446. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  447. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  448. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  449. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  450. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  451. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  452. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  453. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  454. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  455. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  456. package/templates/tower-defense/src/balance.ts +187 -0
  457. package/templates/tower-defense/src/board/Board.ts +100 -0
  458. package/templates/tower-defense/src/board/Route.ts +84 -0
  459. package/templates/tower-defense/src/camera-rig.ts +62 -0
  460. package/templates/tower-defense/src/economy.ts +64 -0
  461. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  462. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  463. package/templates/tower-defense/src/game.ts +72 -0
  464. package/templates/tower-defense/src/intents.ts +21 -0
  465. package/templates/tower-defense/src/main.ts +15 -0
  466. package/templates/tower-defense/src/physics.ts +6 -0
  467. package/templates/tower-defense/src/render/camera.ts +38 -0
  468. package/templates/tower-defense/src/render/lighting.ts +42 -0
  469. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  470. package/templates/tower-defense/src/render/materials.ts +103 -0
  471. package/templates/tower-defense/src/render/palette.ts +58 -0
  472. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  473. package/templates/tower-defense/src/render/quality.ts +128 -0
  474. package/templates/tower-defense/src/render/shapes.ts +550 -0
  475. package/templates/tower-defense/src/render/sky.ts +27 -0
  476. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  477. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  478. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  479. package/templates/tower-defense/src/state.ts +88 -0
  480. package/templates/tower-defense/src/style.css +137 -0
  481. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  482. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  483. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  484. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  485. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  486. package/templates/tower-defense/src/ui/main.tsx +14 -0
  487. package/templates/tower-defense/src/waves.ts +90 -0
  488. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  489. package/templates/tower-defense/vite.config.ts +41 -0
  490. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  491. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  492. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -45
  493. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  494. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -57
  495. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -42
  496. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  497. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  498. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  499. package/agent-files/AGENT-ROLES.md +0 -26
  500. package/templates/action-rpg/src/render/shapes.ts +0 -269
  501. package/templates/action-rpg/src/render/types.ts +0 -3
  502. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  503. package/templates/defense/README.md +0 -10
  504. package/templates/defense/kit.json +0 -7
  505. package/templates/defense/playtests/leak.playtest.json +0 -23
  506. package/templates/defense/playtests/placement.playtest.json +0 -40
  507. package/templates/defense/playtests/scan.playtest.json +0 -20
  508. package/templates/defense/playtests/survive.playtest.json +0 -45
  509. package/templates/defense/playtests/survives.playtest.json +0 -36
  510. package/templates/defense/src/attackers/Attacker.ts +0 -120
  511. package/templates/defense/src/board/Route.ts +0 -94
  512. package/templates/defense/src/conventions.ts +0 -18
  513. package/templates/defense/src/economy.ts +0 -36
  514. package/templates/defense/src/entities/Player.ts +0 -52
  515. package/templates/defense/src/game.ts +0 -51
  516. package/templates/defense/src/physics.ts +0 -13
  517. package/templates/defense/src/placement/Buildable.ts +0 -49
  518. package/templates/defense/src/render/camera.ts +0 -16
  519. package/templates/defense/src/render/lighting.ts +0 -37
  520. package/templates/defense/src/render/materials.ts +0 -22
  521. package/templates/defense/src/render/palette.ts +0 -28
  522. package/templates/defense/src/render/quality.ts +0 -170
  523. package/templates/defense/src/render/shapes.ts +0 -246
  524. package/templates/defense/src/render/sky.ts +0 -45
  525. package/templates/defense/src/scenes/Boot.ts +0 -12
  526. package/templates/defense/src/scenes/Defense.ts +0 -231
  527. package/templates/defense/src/state.ts +0 -56
  528. package/templates/defense/src/towers/Tower.ts +0 -95
  529. package/templates/defense/src/towers/targeting.ts +0 -53
  530. package/templates/defense/src/ui/Hud.tsx +0 -62
  531. package/templates/defense/src/ui/Menu.tsx +0 -7
  532. package/templates/defense/src/waves.ts +0 -40
  533. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  534. package/templates/minimal/src/render/hud.ts +0 -69
  535. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  536. package/templates/platformer/playtests/chase.playtest.json +0 -21
  537. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  538. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  539. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  540. package/templates/platformer/playtests/physics.playtest.json +0 -14
  541. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  542. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  543. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  544. package/templates/platformer/src/conventions.ts +0 -18
  545. package/templates/platformer/src/entities/Character.ts +0 -286
  546. package/templates/platformer/src/entities/Chaser.ts +0 -118
  547. package/templates/platformer/src/entities/Patrol.ts +0 -93
  548. package/templates/platformer/src/level/Platform.ts +0 -46
  549. package/templates/platformer/src/render/rig.ts +0 -60
  550. package/templates/platformer/src/render/terrain.ts +0 -31
  551. package/templates/platformer/src/scenes/Level.ts +0 -241
  552. package/templates/puzzle/README.md +0 -43
  553. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  554. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  555. package/templates/puzzle/src/conventions.ts +0 -25
  556. package/templates/puzzle/src/entities/Ball.ts +0 -70
  557. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  558. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  559. package/templates/puzzle/src/physics.ts +0 -19
  560. package/templates/puzzle/src/room.ts +0 -83
  561. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  562. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  563. package/templates/shooter/playtests/combat.playtest.json +0 -48
  564. package/templates/shooter/playtests/fail.playtest.json +0 -31
  565. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  566. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  567. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  568. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  569. package/templates/shooter/src/combat/damage.ts +0 -40
  570. package/templates/shooter/src/conventions.ts +0 -51
  571. package/templates/shooter/src/entities/Pickup.ts +0 -70
  572. package/templates/shooter/src/entities/Player.ts +0 -310
  573. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  574. package/templates/shooter/src/playtest-events.ts +0 -15
  575. package/templates/shooter/src/render/touch-controls.ts +0 -305
  576. package/templates/shooter/src/render/types.ts +0 -3
  577. package/templates/shooter/src/render/ui.css +0 -330
  578. package/templates/shooter/src/render/ui.ts +0 -75
  579. package/templates/shooter/src/render/vfx.ts +0 -215
  580. package/templates/shooter/src/ui/Menu.tsx +0 -41
  581. package/templates/shooter/src/waves.ts +0 -50
  582. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  583. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  584. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  585. package/templates/starter/playtests/assets.playtest.json +0 -65
  586. package/templates/starter/playtests/buffer.playtest.json +0 -79
  587. package/templates/starter/playtests/cloth.playtest.json +0 -113
  588. package/templates/starter/playtests/coyote.playtest.json +0 -87
  589. package/templates/starter/playtests/gameover.playtest.json +0 -66
  590. package/templates/starter/playtests/goal.playtest.json +0 -67
  591. package/templates/starter/playtests/look.playtest.json +0 -175
  592. package/templates/starter/playtests/models-baseline.png +0 -0
  593. package/templates/starter/playtests/models.playtest.json +0 -74
  594. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  595. package/templates/starter/playtests/odometer.playtest.json +0 -54
  596. package/templates/starter/playtests/seed.playtest.json +0 -54
  597. package/templates/starter/playtests/textures-baseline.png +0 -0
  598. package/templates/starter/playtests/textures.playtest.json +0 -74
  599. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  600. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  601. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  602. package/templates/starter/src/render/coast.ts +0 -199
  603. package/templates/starter/src/render/hero.ts +0 -88
  604. package/templates/starter/src/render/implicitSurface.ts +0 -199
  605. package/templates/starter/src/render/kuwahara.ts +0 -174
  606. package/templates/starter/src/render/outline.ts +0 -141
  607. package/templates/starter/src/render/painterly.ts +0 -86
  608. package/templates/starter/src/render/rockRidge.ts +0 -198
  609. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  610. package/templates/starter/src/render/scenery.ts +0 -40
  611. package/templates/starter/src/render/textureLifetime.ts +0 -53
  612. package/templates/starter/src/render/water.ts +0 -38
  613. package/templates/starter/src/render/watercolor.ts +0 -85
  614. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  615. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  616. /package/templates/{defense → rts}/.codex/config.toml +0 -0
  617. /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
  618. /package/templates/{defense → rts}/.gemini/settings.json +0 -0
  619. /package/templates/{defense → rts}/.mcp.json +0 -0
  620. /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
  621. /package/templates/{defense → rts}/.zed/settings.json +0 -0
  622. /package/templates/{defense → rts}/index.html +0 -0
  623. /package/templates/{defense → rts}/opencode.json +0 -0
  624. /package/templates/{defense → rts}/src/main.ts +0 -0
  625. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  626. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  627. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  628. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  629. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  630. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  631. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
@@ -1,5 +1,5 @@
1
- import type { IPathFollow3DProjection, PathFollow3D } from "@threenative/core";
2
1
  import { Vector3 } from "three";
2
+ import { CIRCUIT, type CircuitLine } from "./circuit.js";
3
3
  import { type IRescueTarget, rescueToLastValid } from "./rescue.js";
4
4
 
5
5
  export interface IRayHit {
@@ -16,44 +16,65 @@ export type IntersectRay = (
16
16
  export type ITrackSectorTarget = IRescueTarget;
17
17
 
18
18
  export interface ITrackSectorOptions {
19
- readonly route: PathFollow3D;
19
+ readonly route: CircuitLine;
20
20
  readonly intersectRay: IntersectRay;
21
21
  readonly rescueDelay?: number;
22
22
  readonly rayHeight?: number;
23
+ /** Seconds below {@link ITrackSectorOptions.stallSpeed} before a beached car is recovered. */
24
+ readonly stallRescueDelay?: number;
25
+ readonly stallSpeed?: number;
23
26
  }
24
27
 
25
28
  /** Records a grounded transform and returns a racer to it after leaving the road. */
26
29
  export class TrackSector {
27
30
  readonly lastOnRoadPosition = new Vector3();
28
31
  readonly lastOnRoadHeading = new Vector3(1, 0, 0);
32
+ /** How far around the lap the last on-road sample was, in metres. */
29
33
  currentSector = 0;
30
34
  #offRoadTime = 0;
35
+ #stalledTime = 0;
31
36
  #hasOnRoadSample = false;
32
- readonly #route: PathFollow3D;
37
+ #hasMoved = false;
38
+ readonly #route: CircuitLine;
33
39
  readonly #intersectRay: IntersectRay;
34
40
  readonly #rescueDelay: number;
35
41
  readonly #rayHeight: number;
42
+ readonly #stallRescueDelay: number;
43
+ readonly #stallSpeed: number;
36
44
  readonly #origin = new Vector3();
37
45
  readonly #direction = new Vector3(0, -1, 0);
38
- readonly #projection: IPathFollow3DProjection = {
39
- distanceFromStart: 0,
40
- lateralDistance: 0,
46
+ readonly #projection = {
47
+ curvature: 0,
48
+ distance: 0,
49
+ lateral: 0,
41
50
  point: new Vector3(),
42
- segment: 0,
43
51
  tangent: new Vector3(0, 0, 1),
44
52
  };
45
53
 
46
54
  constructor(options: ITrackSectorOptions) {
47
- this.#route = options.route;
55
+ this.#route = options.route ?? CIRCUIT;
48
56
  this.#intersectRay = options.intersectRay;
49
57
  this.#rescueDelay = options.rescueDelay ?? 0.65;
50
58
  this.#rayHeight = options.rayHeight ?? 3;
59
+ this.#stallRescueDelay = options.stallRescueDelay ?? 1.2;
60
+ this.#stallSpeed = options.stallSpeed ?? 0.6;
51
61
  if (!(this.#rescueDelay > 0)) throw new Error("TrackSector rescueDelay must be positive.");
62
+ if (!(this.#stallRescueDelay > 0))
63
+ throw new Error("TrackSector stallRescueDelay must be positive.");
52
64
  }
53
65
 
54
- update(position: Vector3, heading: Vector3, dt: number): boolean {
66
+ /**
67
+ * `speed` is the car's measured speed in m/s. It is what makes a **beached** car recoverable: a
68
+ * ray-cast chassis that has nosed into a barrier is still standing on the road, so the off-road
69
+ * ray keeps hitting and a car pinned against a hoarding would sit there for the rest of the race.
70
+ */
71
+ update(position: Vector3, heading: Vector3, dt: number, speed = 0): boolean {
55
72
  if (!Number.isFinite(dt) || dt < 0)
56
73
  throw new Error("TrackSector.update requires a finite non-negative dt.");
74
+ if (Math.abs(speed) >= this.#stallSpeed) {
75
+ this.#stalledTime = 0;
76
+ this.#hasMoved = true;
77
+ } else if (this.#hasMoved) this.#stalledTime += dt;
57
78
  const origin = this.#origin.copy(position);
58
79
  origin.y += this.#rayHeight;
59
80
  const hit = this.#intersectRay(origin, this.#direction, this.#rayHeight + 2);
@@ -61,7 +82,7 @@ export class TrackSector {
61
82
  if (onRoad) {
62
83
  this.lastOnRoadPosition.copy(position);
63
84
  this.lastOnRoadHeading.copy(heading).setY(0).normalize();
64
- this.currentSector = this.#route.project(position, this.#projection).segment;
85
+ this.currentSector = this.#route.project(position, this.#projection).distance;
65
86
  this.#hasOnRoadSample = true;
66
87
  this.#offRoadTime = 0;
67
88
  return true;
@@ -74,14 +95,22 @@ export class TrackSector {
74
95
  return this.#offRoadTime;
75
96
  }
76
97
 
98
+ get stalledTime(): number {
99
+ return this.#stalledTime;
100
+ }
101
+
77
102
  get shouldRescue(): boolean {
78
- return this.#hasOnRoadSample && this.#offRoadTime >= this.#rescueDelay;
103
+ return (
104
+ this.#hasOnRoadSample &&
105
+ (this.#offRoadTime >= this.#rescueDelay || this.#stalledTime >= this.#stallRescueDelay)
106
+ );
79
107
  }
80
108
 
81
109
  rescue(target: ITrackSectorTarget): boolean {
82
110
  if (!this.shouldRescue) return false;
83
111
  rescueToLastValid(target, this.lastOnRoadPosition, this.lastOnRoadHeading);
84
112
  this.#offRoadTime = 0;
113
+ this.#stalledTime = 0;
85
114
  return true;
86
115
  }
87
116
  }
@@ -0,0 +1,477 @@
1
+ import { CatmullRomCurve3, Vector3 } from "three";
2
+
3
+ /**
4
+ * The circuit, once.
5
+ *
6
+ * Every other thing on this track — the road mesh, the kerbs, the run-off, the barriers, the pit
7
+ * lane, the lap gates, the sectors, the rescue points, the rival's line and the autopilot's line —
8
+ * is read off {@link CIRCUIT}. The old build drew the road as boxes between five hand-typed route
9
+ * points and drove a *different* curve, and the two drifted: the racing line bulged 4.5 m off the
10
+ * tarmac and the rival drove into the tyre walls. There is one centreline here, and nothing else
11
+ * in the template is allowed to name a coordinate of its own.
12
+ *
13
+ * ## The layout
14
+ *
15
+ * One lap, about 850 m, a teardrop with a real circuit's grammar: a long front straight, a fast
16
+ * right-hand sweeper (R 77 m) that tightens (R 55 m) into a left kink, a short straight, a 180-degree
17
+ * hairpin (R 16 m) at the far end, a run back with a four-corner esses section (R 55 m, alternating),
18
+ * and a wide last corner (R 45 m, 139 degrees) that feeds the front straight. The tarmac climbs and
19
+ * falls with {@link groundHeight}, so the straight runs downhill and the hairpin sits in a hollow.
20
+ *
21
+ * Every corner is an arc of a chosen radius and the two straights were solved so the loop closes;
22
+ * the layout is kept because it was **measured**: no two parts of the circuit come within 45 m of
23
+ * each other across more than 130 m of road, and the tightest radius is the hairpin.
24
+ */
25
+
26
+ /** The control points, in metres, in driving order. Closed: the last point joins the first.
27
+ * Laid out from arcs and straights (each turn's radius and angle chosen, then the two straights
28
+ * solved so the loop closes), so every corner is a real arc and none is a chord of the world grid. */
29
+ const CONTROL: readonly (readonly [number, number])[] = [
30
+ [-120.0, 100.0],
31
+ [-77.1, 100.0],
32
+ [-34.3, 100.0],
33
+ [8.6, 100.0],
34
+ [47.3, 110.4],
35
+ [75.6, 138.8],
36
+ [85.9, 177.6],
37
+ [85.7, 214.1],
38
+ [94.0, 253.3],
39
+ [117.8, 285.5],
40
+ [130.0, 296.3],
41
+ [134.7, 303.4],
42
+ [135.2, 311.9],
43
+ [131.5, 319.5],
44
+ [124.3, 324.3],
45
+ [115.8, 324.8],
46
+ [108.2, 321.0],
47
+ [82.0, 298.0],
48
+ [55.8, 274.9],
49
+ [41.6, 265.8],
50
+ [25.3, 261.5],
51
+ [9.0, 257.1],
52
+ [-5.3, 248.0],
53
+ [-27.5, 236.1],
54
+ [-52.6, 235.4],
55
+ [-77.8, 234.6],
56
+ [-99.9, 222.7],
57
+ [-124.8, 200.8],
58
+ [-149.8, 178.8],
59
+ [-162.1, 161.1],
60
+ [-164.7, 139.7],
61
+ [-157.1, 119.5],
62
+ [-140.9, 105.2],
63
+ ];
64
+
65
+ /** Metres between samples of the centreline. Everything sampled coarser than this reads a corner
66
+ * as a straight, and the road mesh built on it cuts the apex. */
67
+ const SPACING = 1.1;
68
+
69
+ /** Half-width, in samples, of the curvature box filter. See the constructor for why. */
70
+ const SMOOTH_RADIUS = 10;
71
+
72
+ /** Tarmac width. 9 m is two cars wide and leaves room for a run-off on each side. */
73
+ export const TRACK_WIDTH = 9;
74
+ /** Half the tarmac width: the offset every other surface on the circuit is measured from. */
75
+ export const HALF = TRACK_WIDTH / 2;
76
+
77
+ /** How proud of the tarmac the kerb stands. 50-80 mm is real kerbing and the chassis collider
78
+ * clears it, so a wheel rides over it instead of stopping dead: measured, 80 mm lifts the car 8 mm
79
+ * and costs no speed, and 120 mm stops it. */
80
+ export const KERB_HEIGHT = 0.05;
81
+ export const KERB_WIDTH = 1.1;
82
+
83
+ /** Paved run-off beyond the white line, then the barrier. A circuit with no run-off is a wall
84
+ * with a tarmac stripe on it, and a car that runs wide deserves somewhere to lose a lap. */
85
+ export const RUNOFF = 6.5;
86
+ export const BARRIER_OFFSET = RUNOFF + 1.2;
87
+
88
+ /**
89
+ * How proud of the terrain the tarmac sits, in metres.
90
+ *
91
+ * The terrain grid samples {@link terrainHeight}, which already follows the banked road plane
92
+ * inside the corridor, so this only has to cover the grid's own interpolation error across a 5 m
93
+ * cell where the bank is bending back to the open terrain — measured at 0.07 m. A tenth of a metre
94
+ * reads as a kerb-height lip at the edge of the tarmac, which is what a real circuit is.
95
+ */
96
+ export const ROAD_LIFT = 0.12;
97
+
98
+ /** How far from the centreline the terrain is the road's own banked plane, and where it is the
99
+ * open ground again. Between the two the ground is cut and filled to meet the banking. */
100
+ const CORRIDOR = HALF + RUNOFF;
101
+ const BLEND_END = CORRIDOR + 14;
102
+
103
+ /** The circuit's footprint, so the far field skips the projection entirely. */
104
+ const BOUNDS = {
105
+ maxX: Number.NEGATIVE_INFINITY,
106
+ maxZ: Number.NEGATIVE_INFINITY,
107
+ minX: Number.POSITIVE_INFINITY,
108
+ minZ: Number.POSITIVE_INFINITY,
109
+ };
110
+
111
+ /**
112
+ * Banking, and the radii it applies between.
113
+ *
114
+ * `curvature * gain` reaches the ceiling by a 30 m radius, and the ceiling is faded back to nothing
115
+ * by 20 m — so a fast sweeper is banked and a hairpin is flat, which is both what the brief asks
116
+ * for ("camber/banking on the big corners") and what a real circuit does. It also removes a real
117
+ * defect: a 6.8-degree bank across a 15 m hairpin is a 1.1 m height difference between the inside
118
+ * and the outside of the corner, and the cut-and-fill terrain has to follow all of it.
119
+ */
120
+ const BANK_GAIN = 4;
121
+ const MAX_BANK_TAN = 0.12;
122
+ const BANK_NONE_RADIUS = 20;
123
+ const BANK_FULL_RADIUS = 55;
124
+
125
+ function bankFade(radius: number): number {
126
+ if (!Number.isFinite(radius) || radius >= BANK_FULL_RADIUS) return 1;
127
+ if (radius <= BANK_NONE_RADIUS) return 0;
128
+ const fade = (radius - BANK_NONE_RADIUS) / (BANK_FULL_RADIUS - BANK_NONE_RADIUS);
129
+ return fade * fade * (3 - 2 * fade);
130
+ }
131
+
132
+ /**
133
+ * The ground the circuit is laid on: three slow sines, ±7.5 m, never steeper than about 3%.
134
+ *
135
+ * A flat circuit reads as a car on a table. This is what makes the main straight look like it
136
+ * falls away and the hairpin sit in a hollow, and it costs one function: the road mesh, the
137
+ * run-off, the barriers, the trees and the rescue ray all call it, so the car can never be
138
+ * airborne over a crest the ground does not have.
139
+ */
140
+ export function groundHeight(x: number, z: number): number {
141
+ return 3.5 * Math.sin(x / 220) + 2.5 * Math.cos((z + 141) / 170) + 1.5 * Math.sin((x + z) / 250);
142
+ }
143
+
144
+ export interface ICircuitSample {
145
+ /** The centreline point, on the terrain. */
146
+ point: Vector3;
147
+ /** Unit tangent, flattened: which way this part of the circuit runs. */
148
+ tangent: Vector3;
149
+ /** The unit vector to the **driver's right**, flattened. */
150
+ right: Vector3;
151
+ /** The left and right tarmac edges, already banked. */
152
+ left: Vector3;
153
+ rightEdge: Vector3;
154
+ /** Signed curvature in 1/m: positive turns toward `right`, so a right-hand corner is positive. */
155
+ curvature: number;
156
+ /** The signed radius, or `Infinity` on a straight. */
157
+ radius: number;
158
+ /** `tan` of the banking angle, positive raising the outside edge of a right-hand corner. */
159
+ bank: number;
160
+ }
161
+
162
+ /** Reused by {@link CircuitLine.project} so a projection allocates nothing per frame. */
163
+ const projectScratch = new Vector3();
164
+
165
+ function wrapAngle(value: number): number {
166
+ let angle = value;
167
+ while (angle > Math.PI) angle -= 2 * Math.PI;
168
+ while (angle < -Math.PI) angle += 2 * Math.PI;
169
+ return angle;
170
+ }
171
+
172
+ function clamp(value: number, low: number, high: number): number {
173
+ return value < low ? low : value > high ? high : value;
174
+ }
175
+
176
+ /**
177
+ * The centreline, resampled to a dense polyline and measured.
178
+ *
179
+ * `PathFollow3D` is the right tool for a route a car *follows*, and it is what the sibling
180
+ * templates use — but it projects a car onto 128 samples, which on an 830 m circuit is one sample
181
+ * every 6.5 m. The rival and the autopilot aim at a point 3 m ahead of where they are, so a 6.5 m
182
+ * quantisation put the aim point off the road. This is the same idea at 1.1 m, and it is also the
183
+ * geometry the road is built from, so "the line the car drives" and "the tarmac under it" are the
184
+ * same array.
185
+ */
186
+ export class CircuitLine {
187
+ readonly totalLength: number;
188
+ readonly count: number;
189
+ readonly spacing: number;
190
+ readonly #points: Vector3[] = [];
191
+ readonly #tangents: Vector3[] = [];
192
+ readonly #rights: Vector3[] = [];
193
+ readonly #curvature: number[] = [];
194
+ readonly #scratch: ICircuitSample = {
195
+ bank: 0,
196
+ curvature: 0,
197
+ left: new Vector3(),
198
+ point: new Vector3(),
199
+ radius: Number.POSITIVE_INFINITY,
200
+ right: new Vector3(),
201
+ rightEdge: new Vector3(),
202
+ tangent: new Vector3(),
203
+ };
204
+
205
+ constructor(control: readonly (readonly [number, number])[]) {
206
+ if (control.length < 4) throw new Error("CircuitLine needs at least four control points.");
207
+ const curve = new CatmullRomCurve3(
208
+ control.map(([x, z]) => new Vector3(x, 0, z)),
209
+ true,
210
+ "centripetal",
211
+ 0.5,
212
+ );
213
+ const total = curve.getLengths(4000).at(-1) ?? 0;
214
+ if (!(total > 0)) throw new Error("CircuitLine requires a positive-length circuit.");
215
+ this.totalLength = total;
216
+ const count = Math.max(16, Math.round(total / SPACING));
217
+ this.count = count;
218
+ this.spacing = total / count;
219
+ // `getSpacedPoints` returns one more point than asked for on a closed curve, and the extra one
220
+ // is the first one again. Dropping it is not cosmetic: leaving the duplicate in is what gave an
221
+ // earlier draft a 0.3 m radius at s = 0 and a 0.9 m self-approach across the seam.
222
+ const spaced = curve.getSpacedPoints(this.count);
223
+ for (let index = 0; index < this.count; index += 1) {
224
+ const point = spaced[index];
225
+ if (point === undefined) throw new Error("CircuitLine sample is missing.");
226
+ this.#points.push(new Vector3(point.x, groundHeight(point.x, point.z) + ROAD_LIFT, point.z));
227
+ }
228
+ const raw: number[] = [];
229
+ for (let index = 0; index < count; index += 1) {
230
+ const before = this.#points[(index - 1 + count) % count];
231
+ const here = this.#points[index];
232
+ const after = this.#points[(index + 1) % count];
233
+ if (before === undefined || here === undefined || after === undefined)
234
+ throw new Error("CircuitLine sample is missing.");
235
+ const tangent = new Vector3().subVectors(after, before).setY(0);
236
+ if (tangent.lengthSq() < 1e-9) throw new Error("CircuitLine has a zero-length segment.");
237
+ this.#tangents.push(tangent.normalize());
238
+ this.#rights.push(new Vector3(-tangent.z, 0, tangent.x));
239
+ const turn = wrapAngle(
240
+ Math.atan2(after.z - here.z, after.x - here.x) -
241
+ Math.atan2(here.z - before.z, here.x - before.x),
242
+ );
243
+ raw.push(turn / (2 * this.spacing));
244
+ }
245
+ // The curvature is smoothed before anything reads it, because the **banking** is derived from
246
+ // it and a ray-cast vehicle has no body roll: its chassis stays level while the surface under it
247
+ // tilts, so a camber that changes over two metres compresses one side's strut to its stop and
248
+ // the car beaches on two wheels. A real circuit's camber changes over tens of metres, and so
249
+ // does this one: a nine-tap box over 1.1 m stations is a 10 m window.
250
+ for (let index = 0; index < count; index += 1) {
251
+ let total = 0;
252
+ for (let step = -SMOOTH_RADIUS; step <= SMOOTH_RADIUS; step += 1) {
253
+ total += raw[(index + step + count) % count] ?? 0;
254
+ }
255
+ this.#curvature.push(total / (SMOOTH_RADIUS * 2 + 1));
256
+ }
257
+ }
258
+
259
+ /** The point at `distance` metres around the lap, filling and returning `target`. */
260
+ at(distance: number, target: ICircuitSample = this.#scratch): ICircuitSample {
261
+ const wrapped = ((distance % this.totalLength) + this.totalLength) % this.totalLength;
262
+ const position = wrapped / this.spacing;
263
+ const index = Math.floor(position) % this.count;
264
+ const next = (index + 1) % this.count;
265
+ const blend = position - Math.floor(position);
266
+ const here = this.#points[index];
267
+ const there = this.#points[next];
268
+ if (here === undefined || there === undefined)
269
+ throw new Error("CircuitLine sample is missing.");
270
+ const tangentHere = this.#tangents[index];
271
+ const tangentThere = this.#tangents[next];
272
+ const curvatureHere = this.#curvature[index];
273
+ const curvatureThere = this.#curvature[next];
274
+ if (
275
+ tangentHere === undefined ||
276
+ tangentThere === undefined ||
277
+ curvatureHere === undefined ||
278
+ curvatureThere === undefined
279
+ )
280
+ throw new Error("CircuitLine sample is missing.");
281
+ target.point.lerpVectors(here, there, blend);
282
+ target.tangent.lerpVectors(tangentHere, tangentThere, blend).normalize();
283
+ target.right.set(-target.tangent.z, 0, target.tangent.x);
284
+ target.curvature = curvatureHere * (1 - blend) + curvatureThere * blend;
285
+ target.radius =
286
+ Math.abs(target.curvature) < 1e-6 ? Number.POSITIVE_INFINITY : 1 / Math.abs(target.curvature);
287
+ target.bank =
288
+ clamp(target.curvature * BANK_GAIN, -MAX_BANK_TAN, MAX_BANK_TAN) * bankFade(target.radius);
289
+ const rise = target.bank * HALF;
290
+ target.left.copy(target.point).addScaledVector(target.right, -HALF);
291
+ target.left.y += rise;
292
+ target.rightEdge.copy(target.point).addScaledVector(target.right, HALF);
293
+ target.rightEdge.y -= rise;
294
+ return target;
295
+ }
296
+
297
+ /**
298
+ * A sample the caller **keeps**.
299
+ *
300
+ * {@link at} without a target fills one shared scratch, so reading two samples "at once" gives
301
+ * the same object twice. The road builder keeps 750 of them, and the racing line keeps one per
302
+ * frame, so both ask for their own.
303
+ */
304
+ createSample(): ICircuitSample {
305
+ return {
306
+ bank: 0,
307
+ curvature: 0,
308
+ left: new Vector3(),
309
+ point: new Vector3(),
310
+ radius: Number.POSITIVE_INFINITY,
311
+ right: new Vector3(),
312
+ rightEdge: new Vector3(),
313
+ tangent: new Vector3(),
314
+ };
315
+ }
316
+
317
+ /**
318
+ * Where a world position sits on the circuit: the distance around the lap, how far to the side
319
+ * of the centreline it is (positive on the driver's right) and the closest point on the line.
320
+ */
321
+ project(
322
+ position: Vector3,
323
+ target: {
324
+ distance: number;
325
+ lateral: number;
326
+ point: Vector3;
327
+ tangent: Vector3;
328
+ curvature: number;
329
+ },
330
+ ): { distance: number; lateral: number; point: Vector3; tangent: Vector3; curvature: number } {
331
+ if (![position.x, position.y, position.z].every(Number.isFinite))
332
+ throw new Error("CircuitLine projection position must be finite.");
333
+ let nearest = Number.POSITIVE_INFINITY;
334
+ let index = 0;
335
+ for (let scan = 0; scan < this.count; scan += 1) {
336
+ const point = this.#points[scan];
337
+ if (point === undefined) throw new Error("CircuitLine sample is missing.");
338
+ const gap = (point.x - position.x) ** 2 + (point.z - position.z) ** 2;
339
+ if (gap < nearest) {
340
+ nearest = gap;
341
+ index = scan;
342
+ }
343
+ }
344
+ // Refine inside the winning segment **and its neighbours**, so the answer is a point on the
345
+ // road rather than the nearest 1.1 m sample. Clamping to the winning segment alone is off by up
346
+ // to a whole sample whenever the car is nearer the one before it, and half a sample of aim
347
+ // error is a metre of the racing line on a 14 m corner.
348
+ let bestAlong = 0;
349
+ let bestSegment = index;
350
+ let bestGap = Number.POSITIVE_INFINITY;
351
+ for (let step = -1; step <= 1; step += 1) {
352
+ const at = (index + step + this.count) % this.count;
353
+ const from = this.#points[at];
354
+ const to = this.#points[(at + 1) % this.count];
355
+ if (from === undefined || to === undefined) throw new Error("CircuitLine sample is missing.");
356
+ const spanX = to.x - from.x;
357
+ const spanZ = to.z - from.z;
358
+ const spanSq = spanX * spanX + spanZ * spanZ;
359
+ const along =
360
+ spanSq > 1e-9
361
+ ? clamp(((position.x - from.x) * spanX + (position.z - from.z) * spanZ) / spanSq, 0, 1)
362
+ : 0;
363
+ const gap =
364
+ (from.x + spanX * along - position.x) ** 2 + (from.z + spanZ * along - position.z) ** 2;
365
+ if (gap < bestGap) {
366
+ bestGap = gap;
367
+ bestAlong = along;
368
+ bestSegment = at;
369
+ }
370
+ }
371
+ const from = this.#points[bestSegment];
372
+ const to = this.#points[(bestSegment + 1) % this.count];
373
+ if (from === undefined || to === undefined) throw new Error("CircuitLine sample is missing.");
374
+ target.point.lerpVectors(from, to, bestAlong);
375
+ target.tangent.set(to.x - from.x, 0, to.z - from.z);
376
+ const fallback = this.#tangents[bestSegment];
377
+ if (fallback === undefined) throw new Error("CircuitLine sample is missing.");
378
+ if (target.tangent.lengthSq() < 1e-9) target.tangent.copy(fallback);
379
+ else target.tangent.normalize();
380
+ const right = projectScratch.set(-target.tangent.z, 0, target.tangent.x);
381
+ target.lateral =
382
+ (position.x - target.point.x) * right.x + (position.z - target.point.z) * right.z;
383
+ target.distance = (bestSegment + bestAlong) * this.spacing;
384
+ const curvature = this.#curvature[bestSegment];
385
+ if (curvature === undefined) throw new Error("CircuitLine sample is missing.");
386
+ target.curvature = curvature;
387
+ return target;
388
+ }
389
+ }
390
+
391
+ /** The circuit. One instance, built once, read by everything. */
392
+ export const CIRCUIT = new CircuitLine(CONTROL);
393
+
394
+ for (let index = 0; index < CIRCUIT.count; index += 1) {
395
+ const point = CIRCUIT.at(
396
+ (index * CIRCUIT.totalLength) / CIRCUIT.count,
397
+ CIRCUIT.createSample(),
398
+ ).point;
399
+ BOUNDS.minX = Math.min(BOUNDS.minX, point.x);
400
+ BOUNDS.maxX = Math.max(BOUNDS.maxX, point.x);
401
+ BOUNDS.minZ = Math.min(BOUNDS.minZ, point.z);
402
+ BOUNDS.maxZ = Math.max(BOUNDS.maxZ, point.z);
403
+ }
404
+
405
+ const terrainSample = CIRCUIT.createSample();
406
+ const terrainProjection = {
407
+ curvature: 0,
408
+ distance: 0,
409
+ lateral: 0,
410
+ point: new Vector3(),
411
+ tangent: new Vector3(),
412
+ };
413
+
414
+ /**
415
+ * The ground's height: the road's own banked plane beside the circuit, the open terrain beyond it.
416
+ *
417
+ * This is the cut and fill a banked corner actually is. The alternative — a road that simply tilts
418
+ * on top of a smooth hill — puts one edge of the tarmac **below** the grass, and the ground then
419
+ * pokes through the racing line exactly where the corner is banked most. Measured: the autopilot
420
+ * drove into the rising edge of the buried tarmac at the exit of the hairpin and stopped dead.
421
+ */
422
+ export function terrainHeight(x: number, z: number): number {
423
+ const open = groundHeight(x, z);
424
+ if (
425
+ x < BOUNDS.minX - BLEND_END ||
426
+ x > BOUNDS.maxX + BLEND_END ||
427
+ z < BOUNDS.minZ - BLEND_END ||
428
+ z > BOUNDS.maxZ + BLEND_END
429
+ )
430
+ return open;
431
+ const projection = CIRCUIT.project(new Vector3(x, 0, z), terrainProjection);
432
+ const lateral = Math.abs(projection.lateral);
433
+ if (lateral > BLEND_END) return open;
434
+ const centre = CIRCUIT.at(projection.distance, terrainSample);
435
+ const plane = centre.point.y - ROAD_LIFT - projection.lateral * centre.bank;
436
+ if (lateral <= CORRIDOR) return plane;
437
+ const blend = (lateral - CORRIDOR) / (BLEND_END - CORRIDOR);
438
+ return plane + (open - plane) * blend * blend * (3 - 2 * blend);
439
+ }
440
+
441
+ /** Where the start/finish line, the sectors and the grid are, as a fraction of the lap. */
442
+ export const LINE_AT = {
443
+ finish: 0.06,
444
+ gridFar: 0.052,
445
+ gridNear: 0.042,
446
+ sector1: 0.28,
447
+ sector2: 0.55,
448
+ } as const;
449
+
450
+ /**
451
+ * The starting grid: the player second, the rival on pole, both on the main straight and both
452
+ * short of the line, so the first gate either car meets is the one the lap is counted on.
453
+ *
454
+ * `player` sits 2.2 m to the left of the centreline and `rival` 2.2 m to the right, and the rival
455
+ * is the further down the straight. Two metres aside on a 9 m road is two cars side by side and a
456
+ * clear line between them — the old grid put both cars on the racing line, which is a rear-end at
457
+ * the first corner.
458
+ */
459
+ export const GRID = { player: -2.2, rival: 2.2 } as const;
460
+
461
+ export const GRID_DISTANCE = {
462
+ player: lineDistance(LINE_AT.gridNear),
463
+ rival: lineDistance(LINE_AT.gridFar),
464
+ } as const;
465
+
466
+ export function lineDistance(fraction: number): number {
467
+ return fraction * CIRCUIT.totalLength;
468
+ }
469
+
470
+ /**
471
+ * A point on the tarmac: `offset` metres right of the centreline at `distance`, on the banked
472
+ * surface rather than on a flat plane through it, so anything parked on the track sits on it.
473
+ */
474
+ export function pointOnTrack(distance: number, offset: number, target: Vector3): Vector3 {
475
+ const sample = CIRCUIT.at(distance, CIRCUIT.createSample());
476
+ return target.lerpVectors(sample.left, sample.rightEdge, (offset + HALF) / TRACK_WIDTH);
477
+ }
@@ -1,7 +1,16 @@
1
1
  import { type Object3D, Quaternion, Vector3 } from "three";
2
2
 
3
+ /**
4
+ * What a rescue can put back on the road.
5
+ *
6
+ * A `VehicleBody3D` respawns with a **yaw**, because a ray-cast chassis has to be re-aimed or it
7
+ * drops in sideways: `teleport(position)` alone is a Godot `RigidBody3D` call, and the car this
8
+ * template drives is a vehicle. The heading therefore goes in with the position.
9
+ */
3
10
  export interface IRescueTarget {
4
- readonly body: { teleport(position: Pick<Vector3, "x" | "y" | "z">): void };
11
+ readonly body: {
12
+ teleport(position: Pick<Vector3, "x" | "y" | "z">, yaw: number): void;
13
+ };
5
14
  readonly mesh: Object3D;
6
15
  setHeading?(heading: Vector3): void;
7
16
  }
@@ -11,11 +20,14 @@ export function rescueToLastValid(
11
20
  position: Vector3,
12
21
  heading: Vector3,
13
22
  ): void {
14
- target.body.teleport(position);
23
+ const flat = heading.clone().setY(0);
24
+ if (flat.lengthSq() < 0.0001) return;
25
+ flat.normalize();
26
+ target.body.teleport(position, Math.atan2(flat.z, flat.x));
15
27
  if (target.setHeading !== undefined) {
16
- target.setHeading(heading);
28
+ target.setHeading(flat);
17
29
  return;
18
30
  }
19
- const rotation = new Quaternion().setFromUnitVectors(new Vector3(1, 0, 0), heading);
31
+ const rotation = new Quaternion().setFromUnitVectors(new Vector3(1, 0, 0), flat);
20
32
  target.mesh.quaternion.copy(rotation);
21
33
  }
@@ -13,7 +13,9 @@ const config: IThreeNativeConfig = {
13
13
  orientation: "landscape",
14
14
  fullscreen: true,
15
15
  keepScreenOn: true,
16
- maxFps: 60,
16
+ // No `maxFps`: the engine targets the display's own refresh rate, capped at 120 on desktop
17
+ // and web and 60 on mobile, and reports the resolved value in every `TN_FRAME_BUDGET` window.
18
+ // Set a number to override it, or 0 to remove the ceiling.
17
19
  },
18
20
  window: {
19
21
  title: "__PROJECT_NAME__",
@@ -44,6 +46,17 @@ const config: IThreeNativeConfig = {
44
46
  // Switch to "native" for a UI drawn as part of the rendered frame, with no web view and no
45
47
  // extra process — and own the appearance difference that comes with it.
46
48
  ui: { renderer: "web" },
49
+ // One asset tree, one compiler, one representation per artifact. Uncomment, then cook:
50
+ // threenative build --target android # cooks defaults.android; --profile <name> beats it
51
+ // buildProfiles: {
52
+ // defaults: { android: "compact" },
53
+ // profiles: {
54
+ // compact: {
55
+ // assets: { textures: { maxSize: 1024 }, models: { textures: { maxSize: 1024 } } },
56
+ // } },
57
+ // },
58
+ // Contract, byte definitions, the build report:
59
+ // node_modules/create-threenative/agent-docs/references/build-profiles.md
47
60
  };
48
61
 
49
62
  export default config;
@@ -14,9 +14,12 @@ function assetsWatchPlugin(): Plugin {
14
14
  return {
15
15
  name: "threenative-assets-watch",
16
16
  apply: "serve",
17
- configureServer(server) {
17
+ async configureServer(server) {
18
18
  const handle = watchAssets({ config: config.assets, cwd: server.config.root });
19
19
  server.httpServer?.once("close", () => handle.close());
20
+ // Nothing is served before the first cook settles: until it does, `public/` has no
21
+ // `assets.manifest.json` and every asset answers from its source fallback.
22
+ await handle.ready;
20
23
  },
21
24
  };
22
25
  }