create-threenative 0.2.3 → 0.2.5

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 (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -1,13 +1,22 @@
1
1
  import {
2
2
  Billboard3D,
3
3
  CameraShake,
4
+ GPUParticles3D,
4
5
  type ICtx,
5
6
  Scene,
6
7
  type SceneFrame,
7
8
  SpriteAnimator3D,
9
+ afterPhysics,
8
10
  isMobile,
11
+ isTouchscreenAvailable,
9
12
  } from "@threenative/core";
10
- import { CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
13
+ import {
14
+ CollisionShape3D,
15
+ type IPhysicsContext,
16
+ type IRayHit,
17
+ RigidBody3D,
18
+ buildStaticColliders,
19
+ } from "@threenative/physics";
11
20
  import { Mesh, MeshBasicMaterial, type PerspectiveCamera, Quaternion, Vector3 } from "three";
12
21
  import { applyDirectDamage, applyRadiusDamage } from "../combat/damage.js";
13
22
  import { Pickup } from "../entities/Pickup.js";
@@ -21,9 +30,9 @@ import {
21
30
  } from "../entities/Player.js";
22
31
  import { Target } from "../entities/Target.js";
23
32
  import { SpawnPoints } from "../level/SpawnPoints.js";
24
- import type { IRayHit } from "../physics.js";
25
33
  import { emitPlaytestEvent } from "../playtest-events.js";
26
- import { createArenaCamera, createArenaShakeOptions } from "../render/camera.js";
34
+ import { createArenaShakeOptions, createFirstPersonRig } from "../render/camera.js";
35
+ import { DecalField } from "../render/decals.js";
27
36
  import { setupLighting } from "../render/lighting.js";
28
37
  import { createLoadingScreen } from "../render/loading.js";
29
38
  import { createMaterials } from "../render/materials.js";
@@ -35,18 +44,17 @@ import {
35
44
  createWallVisual,
36
45
  } from "../render/shapes.js";
37
46
  import { setupSky } from "../render/sky.js";
47
+ import { TouchControls } from "../render/touch-controls.js";
48
+ import type { ITouchInput } from "../render/touch-controls.js";
49
+ import { createImpactDust, createImpactSparks, createMuzzleFlash } from "../render/vfx.js";
38
50
  import type { GameState } from "../state.js";
39
51
  import { WaveDirector } from "../waves.js";
40
52
  import { Hitscan } from "../weapons/Hitscan.js";
41
53
  import { Projectile } from "../weapons/Projectile.js";
54
+ import { MAGAZINE, RESERVE, Viewmodel } from "../weapons/Viewmodel.js";
42
55
 
43
56
  export type GameCtx = ICtx<GameState, IPhysicsContext>;
44
57
 
45
- const AIM = new Vector3(0, 0, -1);
46
- const UP = new Vector3(0, 1, 0);
47
- // Relative mouse pixels to radians. Mouse look is applied per pixel moved, not per second —
48
- // the delta is already frame-rate independent, so no dt scaling.
49
- const LOOK_RADIANS_PER_PIXEL = 0.005;
50
58
  const DEMO_POSITION = new Vector3(0, 0.85, -4);
51
59
  const WAVE_POSITION = new Vector3(0, 0.9, -9);
52
60
  const SCAN_POSITION = new Vector3(3, 0.9, 0);
@@ -70,6 +78,9 @@ export class Play extends Scene<GameState, IPhysicsContext> {
70
78
  uiReady: false,
71
79
  aimedShots: 0,
72
80
  aiming: 0,
81
+ ammo: MAGAZINE,
82
+ reserve: RESERVE,
83
+ reloading: 0,
73
84
  armor: 0,
74
85
  cameraShakes: 0,
75
86
  deaths: 0,
@@ -88,6 +99,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
88
99
  pickupFrame: 0,
89
100
  pickupFrameChanges: 0,
90
101
  pickups: 0,
102
+ pitchDegrees: 0,
91
103
  radiusInsideDeaths: 0,
92
104
  radiusMidAlive: 1,
93
105
  radiusNearAlive: 1,
@@ -114,8 +126,12 @@ export class Play extends Scene<GameState, IPhysicsContext> {
114
126
  setupPost(ctx.renderer, ctx.scene, camera, { godraysLight: sun, mobile: isMobile() });
115
127
  const loading = createLoadingScreen(ctx);
116
128
  ctx.add(camera);
129
+ const showTouchControls = isMobile() && isTouchscreenAvailable();
130
+ const touchControls = showTouchControls
131
+ ? ctx.entities.add("touch-controls", new TouchControls(camera))
132
+ : undefined;
117
133
  const shake = new CameraShake(createArenaShakeOptions());
118
- const rig = createArenaCamera(camera, shake);
134
+ const rig = createFirstPersonRig(camera, shake);
119
135
  const billboards: Billboard3D[] = [];
120
136
  const billboardFront = new Vector3(0, 0, 1);
121
137
  const billboardExpected = new Vector3();
@@ -130,17 +146,11 @@ export class Play extends Scene<GameState, IPhysicsContext> {
130
146
 
131
147
  const arena = createArena(materials);
132
148
  ctx.add(arena.group);
133
- const arenaBody = (object: Mesh, shape: CollisionShape3D): RigidBody3D =>
134
- new RigidBody3D({
135
- collisionLayer: WORLD_LAYER,
136
- collisionMask: PLAYER_LAYER | HOSTILE_LAYER | FRIENDLY_LAYER,
137
- object,
138
- physics: ctx.physics,
139
- shape,
140
- type: "fixed",
141
- });
142
- arenaBody(arena.floor, CollisionShape3D.box(22, 0.4, 20));
143
- for (const wall of arena.walls) arenaBody(wall, CollisionShape3D.fromMesh(wall));
149
+ buildStaticColliders(ctx, arena.group, {
150
+ collisionLayer: WORLD_LAYER,
151
+ collisionMask: PLAYER_LAYER | HOSTILE_LAYER | FRIENDLY_LAYER,
152
+ predicate: (object) => object.name === "arena-floor" || object.name.startsWith("arena-wall-"),
153
+ });
144
154
 
145
155
  const playerRef: { value?: Player } = {};
146
156
  const getPlayer = (): Player => {
@@ -156,23 +166,22 @@ export class Play extends Scene<GameState, IPhysicsContext> {
156
166
  const hitscan = new Hitscan();
157
167
  const spawnPoints = SPAWN_POINTS;
158
168
  const elapsed = { value: 0 };
159
- // Look state: relative mouse pixels accumulate here, the camera rig orbits by it, and the
160
- // aim direction rotates with it. Reported through ctx.state so a playtest can observe the
161
- // rotation after the real input path.
162
- const lookState = { yaw: 0 };
163
- const aimDirection = new Vector3();
164
169
  const enemyDirection = new Vector3();
165
- const aimForward = (): Vector3 => aimDirection.copy(AIM).applyAxisAngle(UP, -lookState.yaw);
170
+ const decalPoint = new Vector3();
171
+ const decalNormal = new Vector3();
166
172
 
167
173
  const onEnemyProjectileHit = (hit: IRayHit): void => {
168
174
  if (hit.body.id === getPlayer().body.body.id) {
169
175
  getPlayer().takeDamage(20);
176
+ burst(impactDustVfx, hit.position, "vfx-impact");
170
177
  emitPlaytestEvent({ entity: "player", name: "projectile-hit" });
171
178
  }
172
179
  };
173
180
  const onPlayerProjectileHit = (hit: IRayHit): void => {
174
- if (applyDirectDamage(targets, hit.body.id, 22))
181
+ if (applyDirectDamage(targets, hit.body.id, 22)) {
182
+ burst(impactVfx, hit.position, "vfx-impact");
175
183
  emitPlaytestEvent({ entity: "player", name: "projectile-defeated" });
184
+ }
176
185
  };
177
186
 
178
187
  const acquireProjectile = (
@@ -257,9 +266,38 @@ export class Play extends Scene<GameState, IPhysicsContext> {
257
266
  });
258
267
  };
259
268
 
260
- const player = new Player(ctx, materials, SPAWN.clone(), onDamage, onDeath);
269
+ const player = new Player(ctx, camera, materials, SPAWN.clone(), onDamage, onDeath);
261
270
  playerRef.value = player;
262
271
  ctx.entities.add("player", player);
272
+ const viewmodel = new Viewmodel(player.visual);
273
+ ctx.entities.add("viewmodel", viewmodel);
274
+ // Marks live on the scene root, not on what they hit: a hole is stuck to the world, and a
275
+ // target that dies should not take the holes in the wall behind it with it.
276
+ const decals = new DecalField(ctx.scene, { count: 24 });
277
+ ctx.entities.add("decals", decals);
278
+ // Two seconds in, every material this pool needs has been compiled; stop drawing the slots
279
+ // nobody has used.
280
+ ctx.after(2, () => decals.settle());
281
+
282
+ const muzzleVfx = ctx.add(new GPUParticles3D(createMuzzleFlash()));
283
+ const impactVfx = ctx.add(new GPUParticles3D(createImpactSparks()));
284
+ const impactDustVfx = ctx.add(new GPUParticles3D(createImpactDust()));
285
+ muzzleVfx.visible = false;
286
+ impactVfx.visible = false;
287
+ impactDustVfx.visible = false;
288
+ const burst = (
289
+ particles: GPUParticles3D,
290
+ position: { readonly x: number; readonly y: number; readonly z: number },
291
+ name: string,
292
+ ): void => {
293
+ particles.position.copy(position);
294
+ particles.visible = true;
295
+ particles.restart();
296
+ ctx.after(0.45, () => {
297
+ particles.visible = false;
298
+ });
299
+ emitPlaytestEvent({ entity: "player", name });
300
+ };
263
301
 
264
302
  const demo = registerTarget(
265
303
  "demo-target",
@@ -270,14 +308,14 @@ export class Play extends Scene<GameState, IPhysicsContext> {
270
308
  registerTarget("scan-target", SCAN_POSITION, { health: 20, onFire: () => undefined });
271
309
  const friendly = createFriendlyVisual(materials);
272
310
  friendly.name = "friendly-drone";
273
- friendly.position.set(0, 1, 2.2);
311
+ friendly.position.set(0, 1, 1.4);
274
312
  ctx.add(friendly);
275
313
  const friendlyBody = new RigidBody3D({
276
314
  collisionLayer: FRIENDLY_LAYER,
277
315
  collisionMask: 0,
278
316
  object: friendly,
279
317
  physics: ctx.physics,
280
- shape: CollisionShape3D.box(0.9, 1.4, 0.9),
318
+ shape: CollisionShape3D.box(0.34, 1.5, 0.34),
281
319
  type: "fixed",
282
320
  });
283
321
 
@@ -313,10 +351,13 @@ export class Play extends Scene<GameState, IPhysicsContext> {
313
351
  false,
314
352
  );
315
353
 
354
+ // Well clear of every respawn point. At 1.2 m the player landed inside the pack's trigger the
355
+ // instant they respawned, which handed back a full bar for dying — the opposite of what a
356
+ // health pickup is for.
316
357
  const pickup = new Pickup(
317
358
  ctx,
318
359
  materials,
319
- new Vector3(-1.2, SPAWN.y, SPAWN.z),
360
+ new Vector3(-2.6, SPAWN.y, SPAWN.z),
320
361
  player.body.body.id,
321
362
  () => {
322
363
  player.health = Math.min(player.maxHealth, player.health + 60);
@@ -353,7 +394,10 @@ export class Play extends Scene<GameState, IPhysicsContext> {
353
394
  emitPlaytestEvent({ entity: "wave", name: "started", wave });
354
395
  };
355
396
  waveDirector.start(spawnWave);
356
- rig.snap(player.mesh.position);
397
+ rig.snap(player);
398
+ // The eye is placed here, after the solver wrote the step, and never inside the frame
399
+ // callback. Placing it from `update` leaves the camera one physics step behind the body.
400
+ afterPhysics(ctx, (dt) => rig.follow(player, dt));
357
401
 
358
402
  const resolveHitscanImpact = (
359
403
  hit: NonNullable<ReturnType<typeof hitscan.fire>>,
@@ -361,6 +405,12 @@ export class Play extends Scene<GameState, IPhysicsContext> {
361
405
  ): void => {
362
406
  const target = targets.get(hit.body.id);
363
407
  if (target !== undefined) applyDirectDamage(targets, hit.body.id, 40);
408
+ burst(impactVfx, hit.position, "vfx-impact");
409
+ burst(impactDustVfx, hit.position, "vfx-impact-dust");
410
+ // A round that leaves nothing behind teaches the player their shots land nowhere.
411
+ decalPoint.set(hit.position.x, hit.position.y, hit.position.z);
412
+ decalNormal.set(hit.normal.x, hit.normal.y, hit.normal.z);
413
+ decals.place(decalPoint, decalNormal, target === undefined ? 1 : 0.7);
364
414
  const demoHit = hit.body.id === demo.body.body.id;
365
415
  shake.trigger();
366
416
  ctx.state.set({
@@ -385,32 +435,49 @@ export class Play extends Scene<GameState, IPhysicsContext> {
385
435
  if (target?.alive === false) emitPlaytestEvent({ entity: "target", name: "defeated" });
386
436
  };
387
437
 
438
+ /**
439
+ * One round.
440
+ *
441
+ * The ray starts at the camera and runs down the camera's own forward axis, because that is
442
+ * where the crosshair is drawn. Starting it at the muzzle instead puts the round a hand's
443
+ * width to the right of where the player aimed, which is invisible at range and infuriating
444
+ * up close. The muzzle is where the *flash* goes, and the weapon leans to meet this ray.
445
+ */
388
446
  const fireHitscan = (whileAiming: boolean): void => {
447
+ if (!viewmodel.fire()) return;
389
448
  const state = ctx.state.getState();
390
- const originOffset = player
391
- .aimOrigin()
392
- .sub(player.mesh.position)
393
- .applyAxisAngle(UP, -lookState.yaw)
394
- .add(player.mesh.position);
395
- const hit = hitscan.fire(ctx.physics, originOffset, aimForward(), HOSTILE_LAYER);
449
+ const ray = player.aimRay();
450
+ const hit = hitscan.fire(ctx.physics, ray.origin, ray.direction, HOSTILE_LAYER | WORLD_LAYER);
451
+ burst(muzzleVfx, viewmodel.muzzlePoint(), "vfx-muzzle");
396
452
  ctx.state.set({
397
453
  aimedShots: whileAiming ? state.aimedShots + 1 : state.aimedShots,
454
+ ammo: viewmodel.ammo,
398
455
  shotsFired: state.shotsFired + 1,
399
456
  });
400
457
  emitPlaytestEvent({ entity: "player", name: "fired", aimed: whileAiming ? 1 : 0 });
401
458
  if (hit !== undefined) resolveHitscanImpact(hit, state);
402
459
  };
403
460
 
461
+ const reload = (): void => {
462
+ if (viewmodel.reloading || viewmodel.ammo >= MAGAZINE || viewmodel.reserve <= 0) return;
463
+ viewmodel.reload(ctx);
464
+ ctx.state.set({ reloading: 1 });
465
+ emitPlaytestEvent({ entity: "player", name: "reload-started" });
466
+ };
467
+
404
468
  const fireProjectile = (): void => {
469
+ const ray = player.aimRay();
470
+ burst(muzzleVfx, viewmodel.muzzlePoint(), "vfx-muzzle");
405
471
  acquireProjectile(
406
- player.aimOrigin(),
407
- AIM,
472
+ ray.origin,
473
+ ray.direction,
408
474
  HOSTILE_LAYER | WORLD_LAYER,
409
475
  onPlayerProjectileHit,
410
476
  );
411
477
  };
412
478
 
413
479
  const fireRadius = (): void => {
480
+ burst(impactDustVfx, BLAST_CENTRE, "vfx-blast");
414
481
  applyRadiusDamage(ctx.physics, BLAST_CENTRE, 3.5, 80, targets);
415
482
  let insideDeaths = 0;
416
483
  if (!radiusNear.alive) insideDeaths += 1;
@@ -425,7 +492,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
425
492
  };
426
493
 
427
494
  const probeWall = (): void => {
428
- const from = player.mesh.position.clone().add(new Vector3(0, 0.75, 0));
495
+ const from = player.mesh.position.clone().add(new Vector3(0, player.eyeHeight, 0));
429
496
  const to = from.clone().add(new Vector3(10, 0, 0));
430
497
  const hit = hitscan.probe(ctx.physics, from, to, WORLD_LAYER | FRIENDLY_LAYER);
431
498
  if (hit?.body.id !== wallBody.body.id) return;
@@ -466,9 +533,18 @@ export class Play extends Scene<GameState, IPhysicsContext> {
466
533
  }
467
534
  };
468
535
 
469
- const handleInput = (frameCtx: GameCtx): void => {
536
+ const handleInput = (frameCtx: GameCtx, touch?: ITouchInput): void => {
470
537
  handleAimEdges(frameCtx);
471
- if (frameCtx.input.justPressed("fire")) fireHitscan(frameCtx.input.pressed("aim"));
538
+ // Held *or* just pressed, and the weapon's cyclic cooldown decides which of those frames
539
+ // sends a round — so a tap and a held trigger run exactly the same path. The edge is not
540
+ // redundant: a mouse button that goes down and up between two fixed-step ticks leaves a
541
+ // latched edge and no held state, which is how a click can otherwise fire nothing at all.
542
+ const trigger =
543
+ frameCtx.input.pressed("fire") ||
544
+ frameCtx.input.justPressed("fire") ||
545
+ touch?.firePressed === true;
546
+ if (trigger) fireHitscan(player.aiming);
547
+ if (frameCtx.input.justPressed("reload") || touch?.reloadPressed === true) reload();
472
548
  if (frameCtx.input.justPressed("projectile")) fireProjectile();
473
549
  if (frameCtx.input.justPressed("blast")) fireRadius();
474
550
  if (frameCtx.input.justPressed("probe")) probeWall();
@@ -491,6 +567,29 @@ export class Play extends Scene<GameState, IPhysicsContext> {
491
567
  if (waveDirector.won) frameCtx.state.set({ gameWon: 1, phase: "won" });
492
568
  };
493
569
 
570
+ let lastAmmo = -1;
571
+ let lastReserve = -1;
572
+ let lastReloading = -1;
573
+ const weaponPatch: Partial<GameState> = {};
574
+ const publishWeapon = (frameCtx: GameCtx): void => {
575
+ const reloading = viewmodel.reloading ? 1 : 0;
576
+ if (
577
+ viewmodel.ammo === lastAmmo &&
578
+ viewmodel.reserve === lastReserve &&
579
+ reloading === lastReloading
580
+ )
581
+ return;
582
+ if (lastReloading === 1 && reloading === 0)
583
+ emitPlaytestEvent({ entity: "player", name: "reloaded" });
584
+ lastAmmo = viewmodel.ammo;
585
+ lastReserve = viewmodel.reserve;
586
+ lastReloading = reloading;
587
+ weaponPatch.ammo = viewmodel.ammo;
588
+ weaponPatch.reserve = viewmodel.reserve;
589
+ weaponPatch.reloading = reloading;
590
+ frameCtx.state.set(weaponPatch);
591
+ };
592
+
494
593
  const hudPatch: Partial<GameState> = {};
495
594
  const lookPatch: Partial<GameState> = {};
496
595
  let lastHealth = -1;
@@ -559,24 +658,41 @@ export class Play extends Scene<GameState, IPhysicsContext> {
559
658
  frameCtx.state.set(hudPatch);
560
659
  };
561
660
 
562
- // Relative mouse pixels accumulate here once per frame; the same yaw drives both the
563
- // camera orbit and the aim direction, and the total is published for playtests.
564
- const applyLook = (frameCtx: GameCtx): void => {
565
- const look = frameCtx.input.vector("look");
566
- if (look.x === 0) return;
567
- lookState.yaw += look.x * LOOK_RADIANS_PER_PIXEL;
568
- lookPatch.yawDegrees = Math.round((lookState.yaw * 180) / Math.PI);
569
- ctx.state.set(lookPatch);
661
+ /**
662
+ * Publish where the player is looking.
663
+ *
664
+ * The player integrates the look deltas itself, inside `update`, on the same path a native
665
+ * build takes. This only reports the result, and only when it changed — a state write every
666
+ * frame would flush the bridge for nothing on a still mouse.
667
+ */
668
+ let lastYawDegrees = Number.NaN;
669
+ let lastPitchDegrees = Number.NaN;
670
+ const publishLook = (frameCtx: GameCtx): void => {
671
+ const yawDegrees = Math.round(player.yawDegrees);
672
+ const pitchDegrees = Math.round(player.pitchDegrees);
673
+ if (yawDegrees === lastYawDegrees && pitchDegrees === lastPitchDegrees) return;
674
+ lastYawDegrees = yawDegrees;
675
+ lastPitchDegrees = pitchDegrees;
676
+ lookPatch.yawDegrees = yawDegrees;
677
+ lookPatch.pitchDegrees = pitchDegrees;
678
+ frameCtx.state.set(lookPatch);
570
679
  };
571
680
 
572
681
  return (frameCtx, dt) => {
573
682
  loading.update();
574
683
  elapsed.value += dt;
575
684
  if (restart(frameCtx)) return;
576
- handleInput(frameCtx);
577
- applyLook(frameCtx);
578
-
579
- player.update(frameCtx, dt);
685
+ const touch = touchControls?.update(frameCtx.input.raw.pointers, frameCtx.viewport.size);
686
+ // Look and stance first: the weapon pose and the shot both read this frame's aim, so a
687
+ // round fired below would otherwise use last frame's crosshair.
688
+ player.update(frameCtx, dt, touch);
689
+ handleInput(frameCtx, touch);
690
+ publishLook(frameCtx);
691
+
692
+ const ray = player.aimRay();
693
+ viewmodel.converge(ray.origin, ray.direction);
694
+ viewmodel.update(dt, player.aiming, player.moving);
695
+ publishWeapon(frameCtx);
580
696
  hitscan.update(dt);
581
697
  updateProjectiles(frameCtx, dt);
582
698
  for (const target of targets.values()) target.update(dt);
@@ -593,7 +709,6 @@ export class Play extends Scene<GameState, IPhysicsContext> {
593
709
  removeDeadTargets();
594
710
  updateWaves(frameCtx);
595
711
  syncStateAndHud(frameCtx);
596
- rig.follow(player.mesh.position, dt, lookState.yaw);
597
712
  for (const billboard of billboards) billboard.update();
598
713
  syncNameplateFacingCamera(frameCtx);
599
714
  };
@@ -7,6 +7,10 @@ export type GameState = {
7
7
  uiReady: boolean;
8
8
  aimedShots: number;
9
9
  aiming: number;
10
+ /** Rounds in the magazine, and in reserve. The HUD reads both; a scenario asserts them. */
11
+ ammo: number;
12
+ reserve: number;
13
+ reloading: number;
10
14
  armor: number;
11
15
  cameraShakes: number;
12
16
  deaths: number;
@@ -25,6 +29,7 @@ export type GameState = {
25
29
  pickupFrame: number;
26
30
  pickupFrameChanges: number;
27
31
  pickups: number;
32
+ pitchDegrees: number;
28
33
  radiusInsideDeaths: number;
29
34
  radiusMidAlive: number;
30
35
  radiusNearAlive: number;
@@ -24,3 +24,23 @@ body {
24
24
  #root {
25
25
  background: #263449;
26
26
  }
27
+
28
+ /* Boot failures are a page state, so the generated game owns their presentation. */
29
+ [data-threenative-canvas-error="true"] {
30
+ position: fixed;
31
+ inset: 0;
32
+ z-index: 1000;
33
+ display: grid;
34
+ place-items: center;
35
+ box-sizing: border-box;
36
+ padding: clamp(1.5rem, 8vw, 6rem);
37
+ overflow: auto;
38
+ background: #fff7ed;
39
+ color: #263449;
40
+ font-family: inherit;
41
+ font-size: clamp(1rem, 2vw, 1.5rem);
42
+ line-height: 1.5;
43
+ text-align: center;
44
+ white-space: pre-wrap;
45
+ overflow-wrap: anywhere;
46
+ }
@@ -0,0 +1,25 @@
1
+ import { useUiState } from "@threenative/ui";
2
+ import { shooterUi } from "../render/ui.js";
3
+ import type { GameState } from "../state.js";
4
+
5
+ /**
6
+ * The reticle.
7
+ *
8
+ * Two bars with a gap, not a dot: the gap is where the round goes, and it is the only part of a
9
+ * first-person HUD the player actually looks at. It disappears down the sights, because the optic
10
+ * on the weapon is the sight at that point and two reticles read as a bug.
11
+ *
12
+ * It is DOM rather than a mesh because it must sit at the exact centre of the *window*, which is
13
+ * where a viewport-space element already is. A world-space quad in front of the camera moves with
14
+ * the field of view and drifts off centre the moment ADS changes it.
15
+ */
16
+ export function Crosshair() {
17
+ const state = useUiState<GameState>();
18
+ if (state === undefined || state.phase !== "playing") return null;
19
+ return (
20
+ <div className={state.aiming === 1 ? shooterUi.crosshair.rootAiming : shooterUi.crosshair.root}>
21
+ <i className={shooterUi.crosshair.vertical} />
22
+ <i className={shooterUi.crosshair.horizontal} />
23
+ </div>
24
+ );
25
+ }
@@ -1,4 +1,5 @@
1
1
  import { UiLayer } from "@threenative/ui";
2
+ import { Crosshair } from "./Crosshair.js";
2
3
  import { Hud } from "./Hud.js";
3
4
  import { Menu } from "./Menu.js";
4
5
 
@@ -13,6 +14,7 @@ import { Menu } from "./Menu.js";
13
14
  export function GameUi() {
14
15
  return (
15
16
  <UiLayer>
17
+ <Crosshair />
16
18
  <Hud />
17
19
  <Menu />
18
20
  </UiLayer>
@@ -26,7 +26,7 @@ export function Hud() {
26
26
  // Nothing to draw until the game publishes its first snapshot, a few milliseconds in. Rendering
27
27
  // zeroes instead would put wrong numbers on screen and then correct them.
28
28
  if (state === undefined) return null;
29
- const { health, lives, wave, wavesCleared, phase } = state;
29
+ const { ammo, health, lives, reloading, reserve, wave, wavesCleared, phase } = state;
30
30
  const targets = state.targetsRemaining;
31
31
  return (
32
32
  <section className={shooterUi.hud.root}>
@@ -39,6 +39,12 @@ export function Hud() {
39
39
  <span>{shooterUi.hud.copy.targets(targets)}</span>
40
40
  <span>{shooterUi.hud.copy.clear(wavesCleared)}</span>
41
41
  </div>
42
+ <div className={shooterUi.hud.ammo.root}>
43
+ <b className={shooterUi.hud.ammo.count}>{shooterUi.hud.copy.ammo(ammo, reserve)}</b>
44
+ {reloading === 1 && (
45
+ <span className={shooterUi.hud.ammo.reloading}>{shooterUi.hud.copy.reloading}</span>
46
+ )}
47
+ </div>
42
48
  {phase !== "playing" && (
43
49
  <div className={shooterUi.hud.phase[phase]}>{shooterUi.hud.phaseCopy[phase]}</div>
44
50
  )}
@@ -1,6 +1,5 @@
1
- import type { IPhysicsContext } from "@threenative/physics";
1
+ import type { IPhysicsContext, IRayHit } from "@threenative/physics";
2
2
  import type { Vector3 } from "three";
3
- import { type IRayHit, directSpaceState } from "../physics.js";
4
3
 
5
4
  export class Hitscan {
6
5
  readonly range: number;
@@ -25,7 +24,7 @@ export class Hitscan {
25
24
  if (this.#cooldown > 0) return undefined;
26
25
  this.#cooldown = this.cooldown;
27
26
  const to = from.clone().add(direction.clone().normalize().multiplyScalar(this.range));
28
- return directSpaceState(physics).intersectRay({
27
+ return physics.directSpaceState.intersectRay({
29
28
  collisionMask,
30
29
  from,
31
30
  to,
@@ -38,6 +37,6 @@ export class Hitscan {
38
37
  to: Vector3,
39
38
  collisionMask: number,
40
39
  ): IRayHit | undefined {
41
- return directSpaceState(physics).intersectRay({ collisionMask, from, to });
40
+ return physics.directSpaceState.intersectRay({ collisionMask, from, to });
42
41
  }
43
42
  }
@@ -1,8 +1,13 @@
1
1
  import type { ICtx } from "@threenative/core";
2
- import { CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
2
+ import {
3
+ CollisionShape3D,
4
+ type IPhysicsContext,
5
+ type IRayHit,
6
+ RigidBody3D,
7
+ } from "@threenative/physics";
3
8
  import { type Mesh, Vector3 } from "three";
4
9
  import { PROJECTILE_LAYER } from "../entities/Player.js";
5
- import { type IRayHit, directSpaceState } from "../physics.js";
10
+
6
11
  import { createProjectileVisual } from "../render/shapes.js";
7
12
  import type { GameState } from "../state.js";
8
13
 
@@ -66,7 +71,7 @@ export class Projectile {
66
71
  }
67
72
  const from = this.#from.copy(this.mesh.position);
68
73
  const to = this.#to.copy(from).addScaledVector(this.#direction, this.#speed * dt);
69
- const hit = directSpaceState(ctx.physics).intersectRay({
74
+ const hit = ctx.physics.directSpaceState.intersectRay({
70
75
  collisionMask: this.#collisionMask,
71
76
  from,
72
77
  to,