create-threenative 0.2.6 → 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 (622) hide show
  1. package/README.md +2 -2
  2. package/agent-docs/references/build-profiles.md +126 -0
  3. package/agent-docs/references/capability-reference.md +431 -20
  4. package/agent-docs/references/performance-basics.md +8 -5
  5. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  6. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  7. package/agent-docs/references/visual-baseline.md +8 -4
  8. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +5 -5
  10. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/threenative-context/SKILL.md +1 -1
  12. package/agent-files/.agents/skills/threenative-performance/SKILL.md +3 -3
  13. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  14. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  15. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  16. package/capabilities.json +555 -21
  17. package/dist/index.d.ts +30 -1
  18. package/dist/index.js +294 -55
  19. package/dist/threenative.js +714 -154
  20. package/package.json +6 -6
  21. package/template-assets/assets/mannequin-combat.glb +0 -0
  22. package/template-assets/assets/mannequin.glb +0 -0
  23. package/template-assets/assets/player-viewmodel.glb +0 -0
  24. package/template-assets/assets/sky.jpg +0 -0
  25. package/template-assets/clearwater/README.md +141 -0
  26. package/template-assets/clearwater/install.mjs +50 -0
  27. package/template-assets/clearwater/src/clearwater.ts +180 -0
  28. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  29. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  30. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  31. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  32. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  33. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  34. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  35. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  36. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  37. package/template-assets/patches/three@0.185.1.patch +2101 -138
  38. package/template-assets/worldEnvironment.ts +52 -1
  39. package/templates/action-rpg/AGENTS.md +42 -42
  40. package/templates/action-rpg/CLAUDE.md +42 -42
  41. package/templates/action-rpg/kit.json +1 -1
  42. package/templates/action-rpg/package.json +13 -7
  43. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  44. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  45. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  46. package/templates/action-rpg/src/conventions.ts +24 -18
  47. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  48. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  49. package/templates/action-rpg/src/entities/Player.ts +102 -32
  50. package/templates/action-rpg/src/game.ts +3 -3
  51. package/templates/action-rpg/src/render/camera.ts +18 -16
  52. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  53. package/templates/action-rpg/src/render/lighting.ts +45 -28
  54. package/templates/action-rpg/src/render/loading.ts +4 -4
  55. package/templates/action-rpg/src/render/materials.ts +191 -47
  56. package/templates/action-rpg/src/render/palette.ts +14 -13
  57. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  58. package/templates/action-rpg/src/render/props.ts +117 -0
  59. package/templates/action-rpg/src/render/quality.ts +40 -82
  60. package/templates/action-rpg/src/render/sky.ts +36 -13
  61. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  62. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  63. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  64. package/templates/action-rpg/src/style.css +9 -7
  65. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  66. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  67. package/templates/action-rpg/threenative.config.ts +14 -1
  68. package/templates/action-rpg/vite.config.ts +4 -1
  69. package/templates/minimal/AGENTS.md +10 -10
  70. package/templates/minimal/CLAUDE.md +10 -10
  71. package/templates/minimal/package.json +12 -6
  72. package/templates/minimal/playtests/play.playtest.json +6 -5
  73. package/templates/minimal/playtests/sky.playtest.json +27 -0
  74. package/templates/minimal/src/conventions.ts +6 -3
  75. package/templates/minimal/src/entities/Player.ts +73 -27
  76. package/templates/minimal/src/main.ts +2 -3
  77. package/templates/minimal/src/render/camera.ts +22 -4
  78. package/templates/minimal/src/render/lighting.ts +24 -48
  79. package/templates/minimal/src/render/materials.ts +158 -13
  80. package/templates/minimal/src/render/palette.ts +10 -7
  81. package/templates/minimal/src/render/postprocessing.ts +12 -25
  82. package/templates/minimal/src/render/quality.ts +35 -69
  83. package/templates/minimal/src/render/sky.ts +35 -54
  84. package/templates/minimal/src/render/touch-controls.ts +1 -1
  85. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  86. package/templates/minimal/src/scenes/Play.ts +121 -111
  87. package/templates/minimal/src/state.ts +0 -4
  88. package/templates/minimal/src/style.css +0 -10
  89. package/templates/minimal/threenative.config.ts +14 -1
  90. package/templates/minimal/vite.config.ts +4 -1
  91. package/templates/platformer/AGENTS.md +18 -56
  92. package/templates/platformer/CLAUDE.md +18 -56
  93. package/templates/platformer/kit.json +2 -2
  94. package/templates/platformer/package.json +13 -9
  95. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  96. package/templates/platformer/playtests/collect.playtest.json +8 -34
  97. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  98. package/templates/platformer/playtests/damage.playtest.json +40 -15
  99. package/templates/platformer/playtests/hud.playtest.json +34 -0
  100. package/templates/platformer/playtests/move.playtest.json +24 -0
  101. package/templates/platformer/playtests/performance.playtest.json +24 -7
  102. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  103. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  104. package/templates/platformer/playtests/survives.playtest.json +3 -19
  105. package/templates/platformer/playtests/world.playtest.json +26 -0
  106. package/templates/platformer/src/entities/Fox.ts +273 -0
  107. package/templates/platformer/src/entities/Pickup.ts +43 -60
  108. package/templates/platformer/src/entities/Walker.ts +88 -0
  109. package/templates/platformer/src/game.ts +11 -8
  110. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  111. package/templates/platformer/src/level/Stage.ts +469 -0
  112. package/templates/platformer/src/render/blocks.ts +94 -0
  113. package/templates/platformer/src/render/camera.ts +28 -3
  114. package/templates/platformer/src/render/fox.ts +196 -0
  115. package/templates/platformer/src/render/lighting.ts +42 -33
  116. package/templates/platformer/src/render/materials.ts +115 -5
  117. package/templates/platformer/src/render/palette.ts +68 -53
  118. package/templates/platformer/src/render/pickups.ts +142 -0
  119. package/templates/platformer/src/render/postprocessing.ts +12 -2
  120. package/templates/platformer/src/render/props.ts +147 -0
  121. package/templates/platformer/src/render/quality.ts +47 -99
  122. package/templates/platformer/src/render/scenery.ts +172 -0
  123. package/templates/platformer/src/render/sky.ts +120 -31
  124. package/templates/platformer/src/render/touch-controls.ts +5 -2
  125. package/templates/platformer/src/render/walkers.ts +96 -0
  126. package/templates/platformer/src/render/waterfall.ts +85 -0
  127. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  128. package/templates/platformer/src/scenes/Boot.ts +3 -4
  129. package/templates/platformer/src/scenes/Play.ts +362 -0
  130. package/templates/platformer/src/state.ts +16 -14
  131. package/templates/platformer/src/style.css +9 -8
  132. package/templates/platformer/src/ui/Hud.tsx +62 -29
  133. package/templates/platformer/src/ui/Menu.tsx +2 -2
  134. package/templates/platformer/threenative.config.ts +14 -1
  135. package/templates/platformer/vite.config.ts +4 -1
  136. package/templates/puzzle/AGENTS.md +19 -20
  137. package/templates/puzzle/CLAUDE.md +19 -20
  138. package/templates/puzzle/assets/native-proof.glb +0 -0
  139. package/templates/puzzle/assets/native-proof.png +0 -0
  140. package/templates/puzzle/kit.json +1 -1
  141. package/templates/puzzle/package.json +13 -7
  142. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  143. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  144. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  145. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  146. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  147. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  148. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  149. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  150. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  151. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  152. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  153. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  154. package/templates/puzzle/src/entities/Crate.ts +99 -42
  155. package/templates/puzzle/src/entities/Seal.ts +69 -0
  156. package/templates/puzzle/src/entities/Warden.ts +135 -0
  157. package/templates/puzzle/src/game.ts +15 -11
  158. package/templates/puzzle/src/render/camera.ts +66 -31
  159. package/templates/puzzle/src/render/crateShape.ts +70 -0
  160. package/templates/puzzle/src/render/lighting.ts +41 -41
  161. package/templates/puzzle/src/render/loading.ts +4 -4
  162. package/templates/puzzle/src/render/materials.ts +131 -27
  163. package/templates/puzzle/src/render/palette.ts +19 -29
  164. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  165. package/templates/puzzle/src/render/quality.ts +71 -80
  166. package/templates/puzzle/src/render/shapes.ts +109 -108
  167. package/templates/puzzle/src/render/sky.ts +18 -10
  168. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  169. package/templates/puzzle/src/render/vault.ts +315 -0
  170. package/templates/puzzle/src/render/warden.ts +46 -0
  171. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  172. package/templates/puzzle/src/scenes/Play.ts +793 -0
  173. package/templates/puzzle/src/state.ts +55 -24
  174. package/templates/puzzle/src/style.css +7 -8
  175. package/templates/puzzle/src/ui/App.tsx +2 -2
  176. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  177. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  178. package/templates/puzzle/threenative.config.ts +14 -1
  179. package/templates/puzzle/vite.config.ts +4 -1
  180. package/templates/racing/AGENTS.md +19 -20
  181. package/templates/racing/CLAUDE.md +19 -20
  182. package/templates/racing/package.json +13 -7
  183. package/templates/racing/playtests/boost.playtest.json +33 -12
  184. package/templates/racing/playtests/outcome.playtest.json +32 -50
  185. package/templates/racing/playtests/performance.playtest.json +2 -1
  186. package/templates/racing/playtests/ranking.playtest.json +5 -14
  187. package/templates/racing/playtests/rescue.playtest.json +2 -2
  188. package/templates/racing/playtests/reverse.playtest.json +30 -8
  189. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  190. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  191. package/templates/racing/src/entities/CarBody.ts +327 -0
  192. package/templates/racing/src/entities/LineDriver.ts +220 -0
  193. package/templates/racing/src/entities/RacingCar.ts +150 -89
  194. package/templates/racing/src/entities/Rival.ts +61 -24
  195. package/templates/racing/src/game.ts +5 -0
  196. package/templates/racing/src/render/camera.ts +49 -7
  197. package/templates/racing/src/render/lighting.ts +36 -37
  198. package/templates/racing/src/render/materials.ts +239 -19
  199. package/templates/racing/src/render/palette.ts +19 -21
  200. package/templates/racing/src/render/postprocessing.ts +12 -2
  201. package/templates/racing/src/render/quality.ts +43 -82
  202. package/templates/racing/src/render/shapes.ts +20 -6
  203. package/templates/racing/src/render/sky.ts +47 -39
  204. package/templates/racing/src/render/touch-controls.ts +1 -1
  205. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  206. package/templates/racing/src/scenes/Race.ts +107 -54
  207. package/templates/racing/src/state.ts +2 -0
  208. package/templates/racing/src/track/Checkline.ts +22 -7
  209. package/templates/racing/src/track/Lap.ts +64 -36
  210. package/templates/racing/src/track/Ranking.ts +20 -11
  211. package/templates/racing/src/track/Track.ts +809 -361
  212. package/templates/racing/src/track/TrackSector.ts +40 -11
  213. package/templates/racing/src/track/circuit.ts +477 -0
  214. package/templates/racing/src/track/rescue.ts +16 -4
  215. package/templates/racing/threenative.config.ts +14 -1
  216. package/templates/racing/vite.config.ts +4 -1
  217. package/templates/rts/AGENTS.md +96 -0
  218. package/templates/rts/CLAUDE.md +98 -0
  219. package/templates/rts/kit.json +7 -0
  220. package/templates/{defense → rts}/package.json +13 -7
  221. package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
  222. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  223. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  224. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  225. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  226. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  227. package/templates/rts/playtests/survives.playtest.json +58 -0
  228. package/templates/rts/public/favicon.svg +4 -0
  229. package/templates/rts/src/game.ts +64 -0
  230. package/templates/rts/src/orders.ts +22 -0
  231. package/templates/rts/src/render/army.ts +346 -0
  232. package/templates/rts/src/render/camera.ts +123 -0
  233. package/templates/rts/src/render/lighting.ts +61 -0
  234. package/templates/rts/src/render/loading.ts +33 -0
  235. package/templates/rts/src/render/materials.ts +152 -0
  236. package/templates/rts/src/render/models.ts +705 -0
  237. package/templates/rts/src/render/palette.ts +17 -0
  238. package/templates/rts/src/render/picking.ts +93 -0
  239. package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
  240. package/templates/rts/src/render/quality.ts +128 -0
  241. package/templates/rts/src/render/resources.ts +141 -0
  242. package/templates/rts/src/render/sky.ts +44 -0
  243. package/templates/rts/src/render/terrain.ts +116 -0
  244. package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
  245. package/templates/rts/src/scenes/Play.ts +650 -0
  246. package/templates/rts/src/sim/ai.ts +1140 -0
  247. package/templates/rts/src/sim/combat.ts +416 -0
  248. package/templates/rts/src/sim/construction.ts +374 -0
  249. package/templates/rts/src/sim/economy.ts +167 -0
  250. package/templates/rts/src/sim/game.ts +1082 -0
  251. package/templates/rts/src/sim/movement.ts +371 -0
  252. package/templates/rts/src/sim/nav.ts +276 -0
  253. package/templates/rts/src/sim/production.ts +180 -0
  254. package/templates/rts/src/sim/terrain.ts +170 -0
  255. package/templates/rts/src/sim/types.ts +647 -0
  256. package/templates/rts/src/sim/vision.ts +46 -0
  257. package/templates/rts/src/state.ts +100 -0
  258. package/templates/{defense → rts}/src/style.css +21 -8
  259. package/templates/rts/src/ui/App.tsx +21 -0
  260. package/templates/rts/src/ui/Commands.tsx +129 -0
  261. package/templates/rts/src/ui/GameUi.tsx +22 -0
  262. package/templates/rts/src/ui/Hud.tsx +165 -0
  263. package/templates/rts/src/ui/Minimap.tsx +84 -0
  264. package/templates/rts/tailwind.config.ts +2 -0
  265. package/templates/rts/threenative.config.ts +56 -0
  266. package/templates/rts/tsconfig.json +17 -0
  267. package/templates/{defense → rts}/vite.config.ts +4 -1
  268. package/templates/runner/AGENTS.md +6 -10
  269. package/templates/runner/CLAUDE.md +6 -10
  270. package/templates/runner/README.md +3 -3
  271. package/templates/runner/package.json +13 -7
  272. package/templates/runner/playtests/performance.playtest.json +2 -2
  273. package/templates/runner/src/conventions.ts +4 -3
  274. package/templates/runner/src/entities/Runner.ts +54 -7
  275. package/templates/runner/src/game.ts +2 -0
  276. package/templates/runner/src/render/camera.ts +4 -2
  277. package/templates/runner/src/render/dust.ts +5 -2
  278. package/templates/runner/src/render/lighting.ts +41 -45
  279. package/templates/runner/src/render/loading.ts +2 -2
  280. package/templates/runner/src/render/materials.ts +165 -25
  281. package/templates/runner/src/render/palette.ts +17 -28
  282. package/templates/runner/src/render/postprocessing.ts +12 -2
  283. package/templates/runner/src/render/quality.ts +42 -96
  284. package/templates/runner/src/render/shapes.ts +59 -37
  285. package/templates/runner/src/render/sky.ts +32 -41
  286. package/templates/runner/src/render/touch-controls.ts +1 -1
  287. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  288. package/templates/runner/src/scenes/Run.ts +26 -6
  289. package/templates/runner/src/track.ts +6 -1
  290. package/templates/runner/threenative.config.ts +14 -1
  291. package/templates/runner/vite.config.ts +4 -1
  292. package/templates/sailing/AGENTS.md +12 -12
  293. package/templates/sailing/CLAUDE.md +12 -12
  294. package/templates/sailing/assets/ship.glb +0 -0
  295. package/templates/sailing/package.json +13 -7
  296. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  297. package/templates/sailing/playtests/sails.playtest.json +33 -0
  298. package/templates/sailing/playtests/win.playtest.json +156 -8
  299. package/templates/sailing/src/conventions.ts +29 -2
  300. package/templates/sailing/src/entities/Ship.ts +381 -57
  301. package/templates/sailing/src/game.ts +14 -0
  302. package/templates/sailing/src/render/camera.ts +63 -9
  303. package/templates/sailing/src/render/lighting.ts +49 -27
  304. package/templates/sailing/src/render/materials.ts +50 -15
  305. package/templates/sailing/src/render/ocean.ts +647 -60
  306. package/templates/sailing/src/render/palette.ts +16 -12
  307. package/templates/sailing/src/render/postprocessing.ts +12 -2
  308. package/templates/sailing/src/render/props.ts +316 -442
  309. package/templates/sailing/src/render/quality.ts +14 -4
  310. package/templates/sailing/src/render/sky.ts +116 -23
  311. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  312. package/templates/sailing/src/scenes/Boot.ts +21 -0
  313. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  314. package/templates/sailing/src/state.ts +6 -0
  315. package/templates/sailing/src/ui/Hud.tsx +41 -9
  316. package/templates/sailing/threenative.config.ts +14 -1
  317. package/templates/sailing/vite.config.ts +4 -1
  318. package/templates/shooter/AGENTS.md +27 -42
  319. package/templates/shooter/CLAUDE.md +27 -42
  320. package/templates/shooter/index.html +1 -0
  321. package/templates/shooter/package.json +13 -7
  322. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  323. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  324. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  325. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  326. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  327. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  328. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  329. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  330. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  331. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  332. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  333. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  334. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  335. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  336. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  337. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  338. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  339. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  340. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  341. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  342. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  343. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  344. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  345. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  346. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  347. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  348. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  349. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  350. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  351. package/templates/shooter/playtests/performance.playtest.json +62 -26
  352. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  353. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  354. package/templates/shooter/playtests/survives.playtest.json +36 -30
  355. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  356. package/templates/shooter/src/entities/Breakables.ts +412 -0
  357. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  358. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  359. package/templates/shooter/src/entities/Rifle.ts +442 -0
  360. package/templates/shooter/src/entities/Target.ts +199 -83
  361. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  362. package/templates/shooter/src/game.ts +75 -41
  363. package/templates/shooter/src/main.ts +0 -1
  364. package/templates/shooter/src/postPhysics.ts +36 -0
  365. package/templates/shooter/src/render/camera.ts +78 -74
  366. package/templates/shooter/src/render/decals.ts +142 -82
  367. package/templates/shooter/src/render/facade.ts +1373 -0
  368. package/templates/shooter/src/render/gunfx.ts +704 -0
  369. package/templates/shooter/src/render/lighting.ts +52 -38
  370. package/templates/shooter/src/render/loading.ts +2 -2
  371. package/templates/shooter/src/render/materials.ts +100 -88
  372. package/templates/shooter/src/render/occlusion.ts +108 -0
  373. package/templates/shooter/src/render/palette.ts +10 -10
  374. package/templates/shooter/src/render/palm.ts +455 -0
  375. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  376. package/templates/shooter/src/render/postprocessing.ts +15 -3
  377. package/templates/shooter/src/render/quality.ts +40 -82
  378. package/templates/shooter/src/render/scale.ts +148 -15
  379. package/templates/shooter/src/render/shapes.ts +138 -613
  380. package/templates/shooter/src/render/sky.ts +35 -35
  381. package/templates/shooter/src/render/town-schematic.ts +120 -0
  382. package/templates/shooter/src/render/town.ts +986 -0
  383. package/templates/shooter/src/render/townMaterials.ts +160 -0
  384. package/templates/shooter/src/render/vehicles.ts +741 -0
  385. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  386. package/templates/shooter/src/scenes/Play.ts +727 -650
  387. package/templates/shooter/src/state.ts +26 -41
  388. package/templates/shooter/src/style.css +207 -11
  389. package/templates/shooter/src/surfaces.ts +131 -0
  390. package/templates/shooter/src/ui/App.tsx +9 -10
  391. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  392. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  393. package/templates/shooter/src/ui/Hud.tsx +428 -39
  394. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  395. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  396. package/templates/shooter/src/ui/main.tsx +2 -3
  397. package/templates/shooter/threenative.config.ts +14 -1
  398. package/templates/shooter/vite.config.ts +4 -1
  399. package/templates/starter/AGENTS.md +17 -17
  400. package/templates/starter/CLAUDE.md +17 -17
  401. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  402. package/templates/starter/package.json +13 -7
  403. package/templates/starter/playtests/play.playtest.json +2 -1
  404. package/templates/starter/playtests/survives.playtest.json +1 -1
  405. package/templates/starter/src/conventions.ts +6 -3
  406. package/templates/starter/src/entities/Goal.ts +35 -42
  407. package/templates/starter/src/entities/Player.ts +99 -16
  408. package/templates/starter/src/render/arena.ts +131 -0
  409. package/templates/starter/src/render/lighting.ts +27 -44
  410. package/templates/starter/src/render/materials.ts +164 -35
  411. package/templates/starter/src/render/palette.ts +16 -16
  412. package/templates/starter/src/render/postprocessing.ts +6 -7
  413. package/templates/starter/src/render/quality.ts +43 -101
  414. package/templates/starter/src/render/shapes.ts +1 -1
  415. package/templates/starter/src/render/sky.ts +39 -45
  416. package/templates/starter/src/render/touch-controls.ts +3 -1
  417. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  418. package/templates/starter/src/scenes/Play.ts +82 -81
  419. package/templates/starter/threenative.config.ts +14 -1
  420. package/templates/starter/vite.config.ts +4 -1
  421. package/templates/tower-defense/.codex/config.toml +19 -0
  422. package/templates/tower-defense/.cursor/mcp.json +32 -0
  423. package/templates/tower-defense/.gemini/settings.json +32 -0
  424. package/templates/tower-defense/.mcp.json +32 -0
  425. package/templates/tower-defense/.vscode/mcp.json +36 -0
  426. package/templates/tower-defense/.zed/settings.json +36 -0
  427. package/templates/{defense → tower-defense}/AGENTS.md +14 -12
  428. package/templates/{defense → tower-defense}/CLAUDE.md +14 -12
  429. package/templates/tower-defense/README.md +16 -0
  430. package/templates/tower-defense/index.html +12 -0
  431. package/templates/tower-defense/kit.json +7 -0
  432. package/templates/tower-defense/opencode.json +41 -0
  433. package/templates/tower-defense/package.json +56 -0
  434. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  435. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  436. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  437. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  438. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  439. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  440. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  441. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  442. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  443. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  444. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  445. package/templates/tower-defense/src/balance.ts +187 -0
  446. package/templates/tower-defense/src/board/Board.ts +100 -0
  447. package/templates/tower-defense/src/board/Route.ts +84 -0
  448. package/templates/tower-defense/src/camera-rig.ts +62 -0
  449. package/templates/tower-defense/src/economy.ts +64 -0
  450. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  451. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  452. package/templates/tower-defense/src/game.ts +72 -0
  453. package/templates/tower-defense/src/intents.ts +21 -0
  454. package/templates/tower-defense/src/main.ts +15 -0
  455. package/templates/tower-defense/src/physics.ts +6 -0
  456. package/templates/tower-defense/src/render/camera.ts +38 -0
  457. package/templates/tower-defense/src/render/lighting.ts +42 -0
  458. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  459. package/templates/tower-defense/src/render/materials.ts +103 -0
  460. package/templates/tower-defense/src/render/palette.ts +58 -0
  461. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  462. package/templates/tower-defense/src/render/quality.ts +128 -0
  463. package/templates/tower-defense/src/render/shapes.ts +550 -0
  464. package/templates/tower-defense/src/render/sky.ts +27 -0
  465. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  466. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  467. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  468. package/templates/tower-defense/src/state.ts +88 -0
  469. package/templates/tower-defense/src/style.css +137 -0
  470. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  471. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  472. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  473. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  474. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  475. package/templates/tower-defense/src/ui/main.tsx +14 -0
  476. package/templates/tower-defense/src/waves.ts +90 -0
  477. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  478. package/templates/tower-defense/vite.config.ts +41 -0
  479. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  480. package/agent-files/.claude/skills/ponytail/SKILL.md +0 -68
  481. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  482. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -53
  483. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  484. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -65
  485. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -58
  486. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  487. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  488. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  489. package/agent-files/AGENT-ROLES.md +0 -26
  490. package/templates/action-rpg/src/render/shapes.ts +0 -269
  491. package/templates/action-rpg/src/render/types.ts +0 -3
  492. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  493. package/templates/defense/README.md +0 -10
  494. package/templates/defense/kit.json +0 -7
  495. package/templates/defense/playtests/leak.playtest.json +0 -23
  496. package/templates/defense/playtests/placement.playtest.json +0 -40
  497. package/templates/defense/playtests/scan.playtest.json +0 -20
  498. package/templates/defense/playtests/survive.playtest.json +0 -45
  499. package/templates/defense/playtests/survives.playtest.json +0 -36
  500. package/templates/defense/src/attackers/Attacker.ts +0 -120
  501. package/templates/defense/src/board/Route.ts +0 -94
  502. package/templates/defense/src/conventions.ts +0 -18
  503. package/templates/defense/src/economy.ts +0 -36
  504. package/templates/defense/src/entities/Player.ts +0 -52
  505. package/templates/defense/src/game.ts +0 -51
  506. package/templates/defense/src/physics.ts +0 -13
  507. package/templates/defense/src/placement/Buildable.ts +0 -49
  508. package/templates/defense/src/render/camera.ts +0 -16
  509. package/templates/defense/src/render/lighting.ts +0 -37
  510. package/templates/defense/src/render/materials.ts +0 -22
  511. package/templates/defense/src/render/palette.ts +0 -28
  512. package/templates/defense/src/render/quality.ts +0 -170
  513. package/templates/defense/src/render/shapes.ts +0 -246
  514. package/templates/defense/src/render/sky.ts +0 -45
  515. package/templates/defense/src/scenes/Boot.ts +0 -12
  516. package/templates/defense/src/scenes/Defense.ts +0 -231
  517. package/templates/defense/src/state.ts +0 -56
  518. package/templates/defense/src/towers/Tower.ts +0 -95
  519. package/templates/defense/src/towers/targeting.ts +0 -53
  520. package/templates/defense/src/ui/Hud.tsx +0 -62
  521. package/templates/defense/src/ui/Menu.tsx +0 -7
  522. package/templates/defense/src/waves.ts +0 -40
  523. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  524. package/templates/minimal/src/render/hud.ts +0 -69
  525. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  526. package/templates/platformer/playtests/chase.playtest.json +0 -21
  527. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  528. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  529. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  530. package/templates/platformer/playtests/physics.playtest.json +0 -14
  531. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  532. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  533. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  534. package/templates/platformer/src/conventions.ts +0 -18
  535. package/templates/platformer/src/entities/Character.ts +0 -286
  536. package/templates/platformer/src/entities/Chaser.ts +0 -118
  537. package/templates/platformer/src/entities/Patrol.ts +0 -93
  538. package/templates/platformer/src/level/Platform.ts +0 -46
  539. package/templates/platformer/src/render/rig.ts +0 -60
  540. package/templates/platformer/src/render/terrain.ts +0 -31
  541. package/templates/platformer/src/scenes/Level.ts +0 -241
  542. package/templates/puzzle/README.md +0 -43
  543. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  544. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  545. package/templates/puzzle/src/conventions.ts +0 -25
  546. package/templates/puzzle/src/entities/Ball.ts +0 -70
  547. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  548. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  549. package/templates/puzzle/src/physics.ts +0 -19
  550. package/templates/puzzle/src/room.ts +0 -83
  551. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  552. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  553. package/templates/shooter/playtests/combat.playtest.json +0 -48
  554. package/templates/shooter/playtests/fail.playtest.json +0 -31
  555. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  556. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  557. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  558. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  559. package/templates/shooter/src/combat/damage.ts +0 -40
  560. package/templates/shooter/src/conventions.ts +0 -51
  561. package/templates/shooter/src/entities/Pickup.ts +0 -70
  562. package/templates/shooter/src/entities/Player.ts +0 -310
  563. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  564. package/templates/shooter/src/playtest-events.ts +0 -15
  565. package/templates/shooter/src/render/touch-controls.ts +0 -305
  566. package/templates/shooter/src/render/types.ts +0 -3
  567. package/templates/shooter/src/render/ui.css +0 -330
  568. package/templates/shooter/src/render/ui.ts +0 -75
  569. package/templates/shooter/src/render/vfx.ts +0 -215
  570. package/templates/shooter/src/ui/Menu.tsx +0 -41
  571. package/templates/shooter/src/waves.ts +0 -50
  572. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  573. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  574. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  575. package/templates/starter/playtests/assets.playtest.json +0 -65
  576. package/templates/starter/playtests/buffer.playtest.json +0 -79
  577. package/templates/starter/playtests/cloth.playtest.json +0 -113
  578. package/templates/starter/playtests/coyote.playtest.json +0 -87
  579. package/templates/starter/playtests/gameover.playtest.json +0 -66
  580. package/templates/starter/playtests/goal.playtest.json +0 -67
  581. package/templates/starter/playtests/look.playtest.json +0 -175
  582. package/templates/starter/playtests/models-baseline.png +0 -0
  583. package/templates/starter/playtests/models.playtest.json +0 -74
  584. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  585. package/templates/starter/playtests/odometer.playtest.json +0 -54
  586. package/templates/starter/playtests/restart.playtest.json +0 -91
  587. package/templates/starter/playtests/seed.playtest.json +0 -54
  588. package/templates/starter/playtests/textures-baseline.png +0 -0
  589. package/templates/starter/playtests/textures.playtest.json +0 -74
  590. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  591. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  592. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  593. package/templates/starter/src/render/coast.ts +0 -199
  594. package/templates/starter/src/render/hero.ts +0 -88
  595. package/templates/starter/src/render/implicitSurface.ts +0 -199
  596. package/templates/starter/src/render/kuwahara.ts +0 -174
  597. package/templates/starter/src/render/outline.ts +0 -141
  598. package/templates/starter/src/render/painterly.ts +0 -86
  599. package/templates/starter/src/render/rockRidge.ts +0 -198
  600. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  601. package/templates/starter/src/render/scenery.ts +0 -40
  602. package/templates/starter/src/render/textureLifetime.ts +0 -53
  603. package/templates/starter/src/render/water.ts +0 -38
  604. package/templates/starter/src/render/watercolor.ts +0 -85
  605. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  606. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  607. /package/templates/{defense → rts}/.codex/config.toml +0 -0
  608. /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
  609. /package/templates/{defense → rts}/.gemini/settings.json +0 -0
  610. /package/templates/{defense → rts}/.mcp.json +0 -0
  611. /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
  612. /package/templates/{defense → rts}/.zed/settings.json +0 -0
  613. /package/templates/{defense → rts}/index.html +0 -0
  614. /package/templates/{defense → rts}/opencode.json +0 -0
  615. /package/templates/{defense → rts}/src/main.ts +0 -0
  616. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  617. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  618. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  619. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  620. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  621. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  622. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
@@ -1,57 +1,101 @@
1
- import type { ICtx } from "@threenative/core";
2
- import { CharacterBody3D, CollisionShape3D, type IPhysicsContext } from "@threenative/physics";
3
- import { Group, Vector3 } from "three";
4
- import { prepareVehicleConventions } from "../conventions.js";
1
+ import type { Vector3 } from "three";
5
2
  import { Boost } from "../kart/boost.js";
6
3
  import { createMaterials } from "../render/materials.js";
7
- import { vehicle } from "../render/shapes.js";
8
4
  import type { ITouchInput } from "../render/touch-controls.js";
9
- import type { GameState } from "../state.js";
5
+ import { CarBody, type CarCtx, FEEL } from "./CarBody.js";
6
+ import { LineDriver } from "./LineDriver.js";
10
7
 
11
- type GameCtx = ICtx<GameState, IPhysicsContext>;
12
-
13
- export const RACING_FEEL = {
14
- acceleration: 9.5,
15
- brake: 20,
16
- drag: 2.6,
17
- gravity: -24,
18
- maxFallSpeed: 30,
19
- maxSpeed: 9,
20
- turnRate: 2.25,
21
- } as const;
8
+ /**
9
+ * The demo driver's pace, in m/s, and the side of the road it keeps.
10
+ *
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.
15
+ */
16
+ export const AUTOPILOT_PACE = 15.5;
17
+ const AUTOPILOT_OFFSET = -1.5;
22
18
 
19
+ /**
20
+ * The player's car: input in, a `VehicleBody3D` out — or the same closed-loop driver the rival
21
+ * uses, when the autopilot is engaged.
22
+ *
23
+ * The old car was a kinematic fake: `#speed` and `#heading` as numbers, velocity rewritten every
24
+ * frame, the chassis pinned level. Everything that made a car feel like a car lived in those two
25
+ * numbers, so the same corner at the same speed always produced the same line. Here the input only
26
+ * ever writes three values: `engineForce`, `brake` and `steering`. Grip, weight transfer,
27
+ * understeer and the way a kerb lifts a wheel are the backend's, not this file's.
28
+ */
23
29
  export class RacingCar {
24
- readonly mesh = new Group();
25
- readonly body: CharacterBody3D;
26
- readonly forward = new Vector3(1, 0, 0);
27
- readonly travelDirection = new Vector3(1, 0, 0);
30
+ readonly car: CarBody;
28
31
  readonly boost = new Boost();
29
- #speed = 0;
30
- #heading = 0;
31
- #normaliseFactor: number;
32
+ /** The demo driver. Present whether or not it is engaged, so engaging is not an allocation. */
33
+ readonly autopilot = new LineDriver({ offset: AUTOPILOT_OFFSET, pace: AUTOPILOT_PACE });
34
+ #autopilotOn = false;
35
+ #speedAfterBoost = 0;
32
36
  #topSpeed = 0;
37
+ #boostWasActive = false;
38
+
39
+ constructor(ctx: CarCtx, spawn: Vector3, yaw = 0) {
40
+ this.car = new CarBody(ctx, { materials: createMaterials(), spawn, yaw });
41
+ this.car.measure(1 / 60);
42
+ }
43
+
44
+ get body(): CarBody {
45
+ return this.car;
46
+ }
47
+
48
+ get mesh(): CarBody["mesh"] {
49
+ return this.car.mesh;
50
+ }
51
+
52
+ get forward(): Vector3 {
53
+ return this.car.forward;
54
+ }
55
+
56
+ /** Where the car is measured to be going. `Lap` reads this, never `forward`. */
57
+ get travelDirection(): Vector3 {
58
+ return this.car.travelDirection;
59
+ }
60
+
61
+ get normaliseFactor(): number {
62
+ return this.car.normaliseFactor;
63
+ }
64
+
65
+ get lateralLoad(): number {
66
+ return this.car.lateralLoad;
67
+ }
68
+
69
+ get speed(): number {
70
+ return this.car.speedMagnitude;
71
+ }
72
+
73
+ get topSpeed(): number {
74
+ return this.#topSpeed;
75
+ }
76
+
77
+ get boosting(): boolean {
78
+ return this.boost.active;
79
+ }
80
+
81
+ /** Whether the closed-loop driver has the wheel. Published, so a scenario can prove it drove. */
82
+ get autopilotEngaged(): boolean {
83
+ return this.#autopilotOn;
84
+ }
85
+
86
+ /** The speed measured on the frame a boost ran out, which is what the boost playtest reads. */
87
+ speedAfterBoost(): number {
88
+ return this.#speedAfterBoost;
89
+ }
33
90
 
34
- constructor(ctx: GameCtx, spawn: Vector3) {
35
- this.mesh.position.copy(spawn);
36
- this.mesh.castShadow = true;
37
- const visual = vehicle(createMaterials());
38
- this.#normaliseFactor = prepareVehicleConventions(visual);
39
- this.mesh.add(visual);
40
- ctx.add(this.mesh);
41
- this.body = new CharacterBody3D({
42
- autostep: { maxHeight: 0.25, minWidth: 0.2 },
43
- collisionLayer: 1,
44
- collisionMask: 6,
45
- gravity: RACING_FEEL.gravity,
46
- maxFallSpeed: RACING_FEEL.maxFallSpeed,
47
- object: this.mesh,
48
- physics: ctx.physics,
49
- shape: CollisionShape3D.box(2.7, 0.35, 1.6),
50
- snapToGround: 0.25,
51
- });
52
- }
53
-
54
- update(ctx: GameCtx, dt: number, touch?: ITouchInput): void {
91
+ /**
92
+ * One frame of driving: the input becomes an engine force, a brake and a steering angle.
93
+ *
94
+ * Reverse engages below half a metre per second, so holding back is a brake while the car is
95
+ * rolling and a gear once it has stopped — the same rule every arcade racer uses, and the reason
96
+ * a car can be backed out of a barrier rather than trapped against it.
97
+ */
98
+ update(ctx: CarCtx, dt: number, touch?: ITouchInput): void {
55
99
  this.boost.update(dt);
56
100
  if (ctx.input.justPressed("boost") || touch?.boostPressed === true) this.boost.activate();
57
101
  const move = ctx.input.vector("move");
@@ -60,67 +104,84 @@ export class RacingCar {
60
104
  move.y += touch.move.y;
61
105
  move.clampLength(0, 1);
62
106
  }
63
- const throttle = move.y;
64
- const target =
65
- throttle * RACING_FEEL.maxSpeed * (this.boost.active ? this.boost.multiplier : 1);
66
- const rate =
67
- Math.abs(target) > Math.abs(this.#speed) ? RACING_FEEL.acceleration : RACING_FEEL.drag;
68
- this.#speed = approach(this.#speed, target, rate * dt);
69
- if (ctx.input.pressed("brake") || touch?.brakePressed === true)
70
- this.#speed = approach(this.#speed, 0, RACING_FEEL.brake * dt);
71
- const steering =
72
- move.x * (Math.min(1, Math.abs(this.#speed) / RACING_FEEL.maxSpeed) * 0.65 + 0.35);
73
- this.#heading += steering * RACING_FEEL.turnRate * dt * (this.#speed < 0 ? -1 : 1);
74
- this.forward.set(Math.cos(this.#heading), 0, Math.sin(this.#heading));
75
- this.travelDirection.copy(this.forward).multiplyScalar(this.#speed < -0.05 ? -1 : 1);
76
- this.mesh.rotation.y = this.#heading;
77
- this.body.velocity.x = this.forward.x * this.#speed;
78
- this.body.velocity.z = this.forward.z * this.#speed;
79
- this.body.moveAndSlide(dt);
80
- this.#topSpeed = Math.max(this.#topSpeed, Math.abs(this.#speed));
107
+ if (ctx.input.justPressed("autopilot")) this.#autopilotOn = !this.#autopilotOn;
108
+ // Touching the wheel takes it back, the way a driving game's demo lap does. A scenario that
109
+ // wants to hand the car over presses a key; a player who grabs the stick gets their car.
110
+ if (this.#autopilotOn && move.lengthSq() > 0.02) this.#autopilotOn = false;
111
+ if (this.#autopilotOn) {
112
+ this.autopilot.update(this.car, dt);
113
+ } else {
114
+ this.drive(move);
115
+ this.car.measure(dt);
116
+ }
117
+ if (this.boost.active) {
118
+ this.#boostWasActive = true;
119
+ } else if (this.#boostWasActive) {
120
+ this.#boostWasActive = false;
121
+ this.#speedAfterBoost = this.speed;
122
+ }
123
+ this.#topSpeed = Math.max(this.#topSpeed, this.speed);
124
+ }
125
+
126
+ private drive(move: { x: number; y: number }): void {
127
+ const body = this.car.body;
128
+ const speed = body.speed;
129
+ // The sign: `move.x` is +1 to the right, and a positive Rapier steering angle turns toward the
130
+ // chassis's -z, which is the driver's left. Flipping here keeps "right means right" for the
131
+ // physics and for the visual front wheels, which take the same angle.
132
+ body.steering = -move.x * this.car.lockAt(speed);
133
+ if (move.y > 0) {
134
+ const top = this.boost.active ? FEEL.boostTopSpeed : FEEL.topSpeed;
135
+ body.engineForce =
136
+ move.y *
137
+ FEEL.engineForce *
138
+ (this.boost.active ? FEEL.boostForce : 1) *
139
+ Math.max(0, 1 - speed / top);
140
+ body.brake = 0;
141
+ } else if (speed > FEEL.reverseEnterSpeed) {
142
+ body.engineForce = 0;
143
+ body.brake = FEEL.brake;
144
+ } else if (move.y === 0) {
145
+ // **Handbrake at a standstill.** The main straight climbs at 1.6% and a ray-cast vehicle has no
146
+ // rolling resistance, so a car left on the grid with no input freewheels backwards down the
147
+ // hill: measured, 75 m of it before the race began, which put the grid slot 862 m around the
148
+ // lap and made the ranking scenario's baseline a car that had already been rescued.
149
+ body.engineForce = 0;
150
+ body.brake = FEEL.brake * 0.5;
151
+ } else {
152
+ body.engineForce =
153
+ move.y * FEEL.engineForce * Math.max(0, 1 - Math.abs(speed) / FEEL.reverseTopSpeed);
154
+ body.brake = 0;
155
+ }
81
156
  }
82
157
 
158
+ /** Places the car back on the road facing `heading`, which is what a rescue does. */
83
159
  setHeading(heading: Vector3): void {
84
160
  const flat = heading.clone().setY(0);
85
161
  if (flat.lengthSq() < 0.0001) return;
86
162
  flat.normalize();
87
- this.#heading = Math.atan2(flat.z, flat.x);
88
- this.forward.copy(flat);
89
- this.travelDirection.copy(flat);
90
- this.mesh.rotation.y = this.#heading;
91
- }
92
-
93
- speedAfterBoost(): number {
94
- return this.boost.active ? 0 : Math.abs(this.#speed);
95
- }
96
-
97
- get speed(): number {
98
- return Math.abs(this.#speed);
99
- }
100
-
101
- get topSpeed(): number {
102
- return this.#topSpeed;
163
+ this.car.teleport(
164
+ { x: this.car.position.x, y: this.car.position.y, z: this.car.position.z },
165
+ Math.atan2(flat.z, flat.x),
166
+ );
103
167
  }
104
168
 
105
169
  debug(): Record<string, unknown> {
106
170
  return {
171
+ autopilot: this.#autopilotOn,
107
172
  boostActive: this.boost.active,
108
- heading: this.#heading,
109
- normaliseFactor: this.#normaliseFactor,
110
- position: this.mesh.position.toArray(),
173
+ boostUses: this.boost.uses,
174
+ lateralLoad: Math.round(this.lateralLoad * 100) / 100,
175
+ normaliseFactor: this.car.normaliseFactor,
176
+ position: this.car.position.toArray(),
111
177
  speed: this.speed,
112
178
  topSpeed: this.#topSpeed,
113
179
  travelDirection: this.travelDirection.toArray(),
180
+ wheelsInContact: this.car.wheels.map((_wheel, index) => this.car.body.wheelContact(index)),
114
181
  };
115
182
  }
116
183
 
117
184
  dispose(): void {
118
- this.body.dispose();
119
- this.mesh.removeFromParent();
185
+ this.car.dispose();
120
186
  }
121
187
  }
122
-
123
- function approach(current: number, target: number, delta: number): number {
124
- const difference = target - current;
125
- return Math.abs(difference) <= delta ? target : current + Math.sign(difference) * delta;
126
- }
@@ -1,49 +1,86 @@
1
- import type { PathFollow3D } from "@threenative/core";
2
- import { Group, Vector3 } from "three";
1
+ import { Vector3 } from "three";
3
2
  import { createMaterials } from "../render/materials.js";
4
- import { vehicle } from "../render/shapes.js";
3
+ import { CIRCUIT } from "../track/circuit.js";
4
+ import { CarBody, type CarCtx, RIDE } from "./CarBody.js";
5
+ import { LineDriver } from "./LineDriver.js";
5
6
 
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.
11
+ */
12
+ export const RIVAL_PACE = 17.4;
13
+
14
+ /** The side of the road the rival keeps, so it and the demo driver never share a line. */
15
+ const RIVAL_OFFSET = 1.5;
16
+
17
+ /**
18
+ * The rival: a second `VehicleBody3D` on the same chassis, driven by the same {@link LineDriver}
19
+ * the autopilot uses.
20
+ *
21
+ * It has a body, so the player cannot drive through it; it starts on its own grid slot, so the two
22
+ * cars do not spawn inside each other; and it is ranked on its own progress around the circuit, so
23
+ * the order on the HUD is two cars rather than one car and a constant.
24
+ *
25
+ * There is no steering, throttle or braking code in this file. That is the point: the rival and the
26
+ * autopilot are the *same* controller, so a playtest that presses the autopilot button is running
27
+ * the rival's driving, not a scripted approximation of it.
28
+ */
6
29
  export class Rival {
7
- readonly mesh = new Group();
8
- readonly travelDirection = new Vector3(1, 0, 0);
9
- #distance: number;
30
+ readonly car: CarBody;
31
+ readonly driver: LineDriver;
10
32
  #lap = 0;
11
33
 
12
- constructor(
13
- private readonly route: PathFollow3D,
14
- startDistance: number,
15
- ) {
16
- this.#distance = startDistance;
17
- // Same sculpt, different livery. The rival was indistinguishable from the player in the first
34
+ constructor(ctx: CarCtx, startDistance: number) {
35
+ const sample = CIRCUIT.at(startDistance, CIRCUIT.createSample());
36
+ const yaw = Math.atan2(sample.tangent.z, sample.tangent.x);
37
+ // Same sculpt, different livery: the rival was indistinguishable from the player in the first
18
38
  // frame because both cars asked for the same material set.
19
39
  const materials = createMaterials();
20
- const visual = vehicle({ ...materials, body: materials.rivalBody });
21
- visual.scale.setScalar(0.96);
22
- this.mesh.add(visual);
40
+ this.car = new CarBody(ctx, {
41
+ materials: { ...materials, body: materials.rivalBody },
42
+ // The centreline is authored on the terrain, so the spawn is its point raised to the
43
+ // chassis' ride height: dropping the car in from above reads as a jump start.
44
+ spawn: new Vector3(sample.point.x, sample.point.y + RIDE, sample.point.z),
45
+ yaw,
46
+ });
47
+ this.driver = new LineDriver({ offset: RIVAL_OFFSET, pace: RIVAL_PACE });
48
+ this.driver.reset(startDistance);
49
+ this.car.measure(1 / 60);
23
50
  }
24
51
 
25
52
  update(dt: number): void {
26
- this.#distance += 7.6 * dt;
27
- this.#lap = Math.floor(this.#distance / this.route.totalLength);
28
- const sample = this.route.pointAt(this.#distance);
29
- this.mesh.position.copy(sample.point).setY(0.48);
30
- this.travelDirection.copy(sample.tangent);
31
- this.mesh.rotation.y = Math.atan2(sample.tangent.z, sample.tangent.x);
53
+ this.driver.update(this.car, dt);
54
+ this.#lap = Math.max(0, Math.floor(this.driver.progress / CIRCUIT.totalLength));
55
+ }
56
+
57
+ get mesh(): CarBody["mesh"] {
58
+ return this.car.mesh;
32
59
  }
33
60
 
34
61
  get lap(): number {
35
62
  return this.#lap;
36
63
  }
37
64
 
65
+ /** Monotonic progress around the lap, in metres: the quantity the ranking orders cars by. */
38
66
  get distance(): number {
39
- return this.#distance;
67
+ return this.driver.progress;
68
+ }
69
+
70
+ get speed(): number {
71
+ return this.car.speedMagnitude;
40
72
  }
41
73
 
42
74
  debug(): Record<string, unknown> {
43
75
  return {
44
76
  lap: this.#lap,
45
- position: this.mesh.position.toArray(),
46
- routeProgress: this.#distance,
77
+ position: this.car.position.toArray(),
78
+ routeProgress: this.driver.progress,
79
+ speed: this.speed,
47
80
  };
48
81
  }
82
+
83
+ dispose(): void {
84
+ this.car.dispose();
85
+ }
49
86
  }
@@ -20,6 +20,11 @@ const game = defineGame<GameState, IPhysicsContext>({
20
20
  brake: { buttons: [1], keys: ["ShiftLeft", "ShiftRight"] },
21
21
  boost: { buttons: [0], keys: ["Space"] },
22
22
  restart: { keys: ["KeyR"] },
23
+ // The demo driver: the same closed-loop controller the rival uses, on the player's car. It is
24
+ // a game-owned control, not a harness hook — a player can watch a lap of the circuit, and a
25
+ // playtest that needs a car to follow the track presses the same key the rival obeys instead
26
+ // of a recorded key timing the chassis would not reproduce.
27
+ autopilot: { keys: ["KeyP"] },
23
28
  },
24
29
  plugins: [rapier({ gravity: { x: 0, y: -24, z: 0 } }), playtest({ events })],
25
30
  display: config.display,
@@ -1,9 +1,17 @@
1
1
  import { MathUtils, type PerspectiveCamera, Vector3 } from "three";
2
2
 
3
3
  // Chase height and distance. At 5.8 up and 8.5 back the camera looked down on the roof, which is
4
- // the one angle from which every car in the world reads as a rectangle; 3.3 and 7.4 put the eye
4
+ // the one angle from which every car in the world reads as a rectangle; 3.0 and 6.6 put the eye
5
5
  // near the rear wing where the wedge, the arches and the flank are all in view.
6
- const SCRATCH_UP = new Vector3(0, 3.0, 0);
6
+ const EYE_UP = 3;
7
+ const EYE_BACK = 6.6;
8
+
9
+ /** How far ahead of the car the camera looks, in metres, plus its own speed. */
10
+ const LEAD_BASE = 1.5;
11
+ const LEAD_PER_MPS = 0.42;
12
+
13
+ /** The most the camera will bank, in radians. Past this a corner reads as a barrel roll. */
14
+ const MAX_BANK = 0.055;
7
15
 
8
16
  export function setupCamera(camera: PerspectiveCamera): void {
9
17
  camera.fov = 56;
@@ -16,20 +24,54 @@ export function setupCamera(camera: PerspectiveCamera): void {
16
24
  // every racing game built from this template; three Vector clones a frame was pure garbage.
17
25
  const behind = new Vector3();
18
26
  const desired = new Vector3();
27
+ const look = new Vector3();
28
+ const velocity = new Vector3();
19
29
 
30
+ /**
31
+ * The chase camera: it sits behind the car's **velocity**, not behind its nose, and it looks at
32
+ * where the car is going.
33
+ *
34
+ * Both halves matter on a car that slides. Anchored to the nose, a car sideways in a corner puts
35
+ * the camera broadside — the driver sees a wall of tarmac and no horizon. Anchored to the
36
+ * velocity, the camera stays behind the direction of travel and the corner opens up ahead.
37
+ */
20
38
  export function chaseCamera(
21
39
  camera: PerspectiveCamera,
22
40
  target: Vector3,
23
41
  heading: Vector3,
24
42
  dt: number,
43
+ carVelocity?: { readonly x: number; y: number; z: number },
25
44
  ): void {
26
- behind.copy(heading).setY(0).normalize().multiplyScalar(-6.6);
27
- desired.copy(target).add(behind).add(SCRATCH_UP);
45
+ // The direction the car is travelling, flattened. Under half a metre per second there is no
46
+ // direction to speak of and the nose is the best available answer.
47
+ behind.copy(heading).setY(0);
48
+ if (carVelocity !== undefined) {
49
+ velocity.set(carVelocity.x, 0, carVelocity.z);
50
+ if (velocity.lengthSq() > 0.25) behind.copy(velocity).normalize();
51
+ }
52
+ if (behind.lengthSq() < 0.0001) behind.set(1, 0, 0);
53
+ behind.normalize();
54
+ desired.copy(target).addScaledVector(behind, -EYE_BACK);
55
+ desired.y += EYE_UP;
28
56
  if (dt >= 1) camera.position.copy(desired);
29
57
  else camera.position.lerp(desired, 1 - Math.exp(-dt / 0.2));
30
- camera.lookAt(target.x, target.y + 1.15, target.z);
58
+ // Look ahead along the same travel direction, so a fast car sees the corner it is entering
59
+ // rather than the road immediately under its own nose.
60
+ const speed = Math.hypot(velocity.x, velocity.z);
61
+ look.copy(target).addScaledVector(behind, LEAD_BASE + speed * LEAD_PER_MPS);
62
+ look.y = target.y + 1.15;
63
+ camera.lookAt(look);
31
64
  }
32
65
 
33
- export function cameraRoll(camera: PerspectiveCamera, heading: Vector3): void {
34
- camera.rotateZ(MathUtils.clamp(-heading.x * 0.018, -0.035, 0.035));
66
+ /**
67
+ * The camera's bank, from the car's **lateral load**.
68
+ *
69
+ * The old camera banked on world X: `clamp(-heading.x * 0.018, …)`, which is a function of which
70
+ * way the circuit happens to point rather than of what the car is doing. On a square track the
71
+ * car banks the same amount in every corner and the opposite amount on the straights, so the roll
72
+ * read as a wobble. Lateral acceleration is what a driver's inner ear banks on, and the car
73
+ * measures it, so the camera banks on that and is level on the straights.
74
+ */
75
+ export function cameraBank(lateralLoad: number, reference: number): number {
76
+ return MathUtils.clamp(lateralLoad / reference, -1, 1) * MAX_BANK;
35
77
  }
@@ -1,46 +1,45 @@
1
- import {
2
- AmbientLight,
3
- DirectionalLight,
4
- HemisphereLight,
5
- PCFSoftShadowMap,
6
- type Scene,
7
- } from "three";
8
- import { palette } from "./palette.js";
1
+ // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
+ // ThreeNative does not read this file.
3
+ //
4
+ // One sun. The sky image in `sky.ts` is the fill light — its environment reaches every face the
5
+ // sun misses — so there is no hemisphere or ambient light stacked on top to flatten the frame.
6
+ import { DirectionalLight, PCFSoftShadowMap, type Scene } from "three";
7
+ import { SUN_DIRECTION } from "./sky.js";
9
8
 
10
9
  type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
11
10
 
12
- // Returns the key light: `WorldEnvironment`'s godrays stage raymarches against a shadow map, so
13
- // the scene hands the sun to `setupPost` and a shadowless light is refused by name instead of
14
- // rendering a black pass.
15
- //
16
- // The sun is **near-white**, not the accent colour. Tinting the key light yellow was how the first
17
- // version of this file made a green infield go olive and a grey road go brown: a strongly coloured
18
- // key contaminates every surface at once, and no per-material tweak can undo it. Colour belongs in
19
- // the materials; the sun's job is direction and contrast.
20
- export function setupLighting(scene: Scene, renderer: ShadowRenderer): DirectionalLight {
11
+ export function setupLighting(
12
+ scene: Scene,
13
+ renderer: ShadowRenderer,
14
+ mobile = false,
15
+ ): { key: DirectionalLight } {
21
16
  renderer.shadowMap.enabled = true;
22
17
  renderer.shadowMap.type = PCFSoftShadowMap;
23
- // Sky above, grass bounce below. The ground term is what stops undersides going to slate.
24
- scene.add(new HemisphereLight(palette.skyLow, palette.field, 1.1));
25
- const key = new DirectionalLight(0xfff4e2, 2.9);
26
- key.position.set(-16, 26, -12);
18
+
19
+ // Warm white, matched by eye to the photographed midday sun against its own sky.
20
+ const key = new DirectionalLight(0xfff1e0, 4.5);
21
+ key.position.copy(SUN_DIRECTION).multiplyScalar(40);
27
22
  key.castShadow = true;
28
- key.shadow.mapSize.set(2048, 2048);
29
- key.shadow.camera.near = 0.5;
23
+ // One map fitted to the whole circuit rather than a cascade that follows the car: the racing line
24
+ // never leaves a 36 m square, so 30 m of extent covers the road, the kerbs and the tyre walls at
25
+ // 4096² — a centimetre a texel, which is what keeps the car's own shadow on the road readable.
26
+ // The treeline at 42 m and beyond is deliberately outside it; a tree's shadow is not what says
27
+ // where the track is.
28
+ const size = mobile ? 2048 : 4096;
29
+ key.shadow.mapSize.set(size, size);
30
+ key.shadow.radius = 2;
31
+ key.shadow.camera.near = 1;
30
32
  key.shadow.camera.far = 120;
31
- key.shadow.camera.left = -55;
32
- key.shadow.camera.right = 55;
33
- key.shadow.camera.top = 55;
34
- key.shadow.camera.bottom = -55;
35
- key.shadow.bias = -0.0004;
36
- key.shadow.normalBias = 0.03;
33
+ const extent = 30;
34
+ key.shadow.camera.left = -extent;
35
+ key.shadow.camera.right = extent;
36
+ key.shadow.camera.top = extent;
37
+ key.shadow.camera.bottom = -extent;
38
+ // Small biases: a large normal bias is what lifted the mannequin's shadow off its own feet.
39
+ key.shadow.bias = -0.0002;
40
+ key.shadow.normalBias = 0.005;
37
41
  scene.add(key);
38
- // A cool fill from the opposite side, so shadow faces separate from each other rather than all
39
- // collapsing to one flat tone.
40
- const rim = new DirectionalLight(palette.skyLow, 0.85);
41
- rim.position.set(18, 9, 22);
42
- scene.add(rim);
43
- scene.add(new AmbientLight(palette.shadow, 0.55));
44
-
45
- return key;
42
+ // The key light is returned because `WorldEnvironment`'s godrays stage raymarches against its
43
+ // shadow map, so `setupPost` needs the light itself.
44
+ return { key };
46
45
  }