create-threenative 0.2.3 → 0.2.4

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
@@ -0,0 +1,170 @@
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or rewrite
2
+ // it freely — the tiers below are a starting point, not a framework look.
3
+ //
4
+ // This is the one place this game decides how expensive it looks. `postprocessing.ts` reads
5
+ // `qualityPreset(resolveQualityTier(...))` and nothing else, so "make it run on a phone" is one
6
+ // file to edit rather than a hunt through anonymous literals.
7
+ //
8
+ // **Where the numbers come from.** Every millisecond below is GPU time from the per-stage
9
+ // ablation recorded in the engine repository's `docs/verification/runtime-perf-state.md`: Chrome
10
+ // on an RTX 2080, 1600x900, static build, `gpuMs` read from three's `timestamp-query`. In that
11
+ // scene the whole five-stage chain costs **12.5 ms of a 14.7 ms GPU frame**, and the same frame
12
+ // with every stage off costs **2.2 ms**. The per-stage figures oversum — removing SSGI also
13
+ // removes the denoise passes the later stages sample — so read each as *what turning this one off
14
+ // gave back*, not as a share of a partition. A stage nobody has ablated on its own says
15
+ // `unmeasured` rather than guessing, and your scene is not that scene: read `TN_FRAME_BUDGET`
16
+ // back after you change a tier.
17
+ //
18
+ // One cost that is **not** a stage here and outweighs most of them: the prefiltered reflection
19
+ // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
+ // in `sky.ts`, not in this file.
21
+ //
22
+ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
23
+
24
+ /**
25
+ * The three names this game's look comes in.
26
+ *
27
+ * `low` is what a phone gets and `high` what a desktop gets — those two are this template's
28
+ * shipped looks, unchanged. `medium` is the rung in between for a machine that is neither: a
29
+ * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
30
+ * what any of them mean.
31
+ */
32
+ export type QualityTier = "low" | "medium" | "high";
33
+
34
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
35
+
36
+ /**
37
+ * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
38
+ * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
39
+ */
40
+ function isQualityTier(value: string): value is QualityTier {
41
+ return (QUALITY_TIERS as readonly string[]).includes(value);
42
+ }
43
+
44
+ /**
45
+ * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
46
+ *
47
+ * Fails closed. An unrecognised tier name throws with the value it was handed rather than
48
+ * quietly rendering the default, because a silent fallback here looks exactly like a tier that
49
+ * turned out to have no effect.
50
+ */
51
+ export function resolveQualityTier(
52
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
53
+ ): QualityTier {
54
+ const requested = request.tier;
55
+ if (requested !== undefined) {
56
+ if (!isQualityTier(requested)) {
57
+ throw new Error(
58
+ `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
59
+ );
60
+ }
61
+ return requested;
62
+ }
63
+ return request.mobile === true ? "low" : "high";
64
+ }
65
+
66
+ /**
67
+ * What a desktop gets: this template's shipped desktop look, unchanged.
68
+ *
69
+ * The whole chain measured 12.5 ms of a 14.7 ms GPU frame in the reference ablation, and SSGI
70
+ * with its denoiser is ~9.2 ms of that.
71
+ */
72
+ const high: IWorldEnvironmentOptions = {
73
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
74
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
75
+ // to be.
76
+ bloomEnabled: true,
77
+ bloomRadius: 0.48,
78
+ bloomStrength: 0.75,
79
+ bloomThreshold: 0.2,
80
+ exposure: 1.12,
81
+ // The two full-resolution denoise passes over the AO and GI terms: ~1.9 ms. Only worth running
82
+ // when SSGI is on — its noise is what they clean up.
83
+ denoiseEnabled: true,
84
+ // SSGI, the screen-space indirect-light gather: ~7.3 ms alone, ~9.2 ms with the two denoise
85
+ // passes it feeds. The largest stage in the chain by a factor of two, of a 14.7 ms frame.
86
+ // Dropping this pair is what `medium` is.
87
+ ssgiEnabled: true,
88
+ ssgiRadius: 14,
89
+ ssgiQuality: "medium",
90
+ // Half the frame in each axis, so a quarter of the pixels. Full-res SSGI cost 14.4 ms
91
+ // of a 39.7 ms frame on an RTX 2080; this is the same gather over a quarter of the work,
92
+ // and it measured *sharper* because the scaler spends what it hands back on resolution.
93
+ // `worldEnvironment.ts` explains why it takes a wrapper instead of a property.
94
+ ssgiResolutionScale: 0.5,
95
+ // Screen-space reflections: ~4.1 ms.
96
+ ssrEnabled: true,
97
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
98
+ // are on and do nothing" — the ray dies a metre from where it started.
99
+ ssrMaxDistance: 34,
100
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
101
+ // the rays and is very hard to see in the result.
102
+ ssrResolutionScale: 0.5,
103
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
104
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
105
+ // that runs one of them.
106
+ sharpenEnabled: true,
107
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
108
+ sharpenStrength: 0.3,
109
+ tonemapMode: "aces",
110
+ };
111
+
112
+ /**
113
+ * `high` minus the gather and its denoiser — the single change in this chain measured to give
114
+ * back most of the frame: **14.7 ms -> 5.5 ms of GPU** in the reference ablation. Reflections,
115
+ * bloom and the sharpener stay, so it is recognisably the same look.
116
+ */
117
+ const medium: IWorldEnvironmentOptions = {
118
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
119
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
120
+ // to be.
121
+ bloomEnabled: true,
122
+ bloomRadius: 0.48,
123
+ bloomStrength: 0.75,
124
+ bloomThreshold: 0.2,
125
+ exposure: 1.12,
126
+ // Screen-space reflections: ~4.1 ms.
127
+ ssrEnabled: true,
128
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
129
+ // are on and do nothing" — the ray dies a metre from where it started.
130
+ ssrMaxDistance: 34,
131
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
132
+ // the rays and is very hard to see in the result.
133
+ ssrResolutionScale: 0.5,
134
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
135
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
136
+ // that runs one of them.
137
+ sharpenEnabled: true,
138
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
139
+ sharpenStrength: 0.3,
140
+ tonemapMode: "aces",
141
+ };
142
+
143
+ /**
144
+ * What a phone gets: this template's shipped mobile look, unchanged. Bloom and the tone curve,
145
+ * nothing screen-space. The ablation's floor — every stage off — was 2.2 ms.
146
+ */
147
+ const low: IWorldEnvironmentOptions = {
148
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
149
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
150
+ // to be.
151
+ bloomEnabled: true,
152
+ bloomRadius: 0.48,
153
+ bloomStrength: 0.75,
154
+ bloomThreshold: 0.2,
155
+ exposure: 1.12,
156
+ tonemapMode: "aces",
157
+ };
158
+
159
+ const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
160
+
161
+ /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
162
+ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
163
+ const preset = QUALITY_PRESETS[tier as QualityTier];
164
+ if (preset === undefined) {
165
+ throw new Error(
166
+ `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
167
+ );
168
+ }
169
+ return preset;
170
+ }
@@ -0,0 +1,22 @@
1
+ // Generated for you. The one place this game writes a real-world size.
2
+ //
3
+ // One metre is one metre. Every silhouette, every collider and every weapon reads its size from
4
+ // here, so a thing that comes out wrong is fixed once rather than nudged at each site. A model
5
+ // that arrives in centimetres is normalised on load with `normaliseToMetres` — never accommodated
6
+ // by tuning a literal beside it.
7
+ export const scale = {
8
+ /** Adult figure, boots to head-top. Sets the target silhouettes and the player capsule. */
9
+ humanHeight: 1.78,
10
+ /** Eye above the floor, standing. The camera sits here, not at an invented "camera height". */
11
+ eyeHeight: 1.66,
12
+ /** Shoulder width. Sets the capsule radius and therefore what fits through a gap. */
13
+ shoulderWidth: 0.5,
14
+ /** How far the eye drops crouched. A crouch that only slows you reads as a bug. */
15
+ crouchDrop: 0.56,
16
+ /** Carbine, muzzle to stock. The viewmodel is normalised to this. */
17
+ rifleLength: 0.78,
18
+ /** Visible muzzle flame. Anything larger reads as a bug rather than a flash. */
19
+ muzzleFlash: 0.3,
20
+ /** Bullet hole edge length. */
21
+ bulletHole: 0.14,
22
+ } as const;
@@ -1,5 +1,6 @@
1
1
  // Generated for you. All arena silhouettes and gameplay visuals start here.
2
2
  import {
3
+ BoxGeometry,
3
4
  BufferAttribute,
4
5
  BufferGeometry,
5
6
  ClampToEdgeWrapping,
@@ -17,6 +18,7 @@ import {
17
18
  UnsignedByteType,
18
19
  } from "three";
19
20
 
21
+ import { mergeGeometries } from "three/addons/utils/BufferGeometryUtils.js";
20
22
  import type { ReturnTypeOfMaterials } from "./types.js";
21
23
 
22
24
  const roundedCache = new Map<string, BufferGeometry>();
@@ -162,7 +164,7 @@ function createTargetNameplate(): Group {
162
164
  const group = new Group();
163
165
  group.name = "target-nameplate";
164
166
  const mesh = new Mesh(
165
- new PlaneGeometry(2.4, 0.6),
167
+ new PlaneGeometry(1.05, 0.26),
166
168
  new MeshBasicMaterial({
167
169
  depthWrite: false,
168
170
  map: createNameplateTexture(),
@@ -225,21 +227,67 @@ function compactBox(width: number, height: number, depth: number): BufferGeometr
225
227
  return geometry;
226
228
  }
227
229
 
228
- function roundedBox(
229
- width: number,
230
- height: number,
231
- depth: number,
232
- radius = 0.12,
233
- segments = 1,
234
- ): BufferGeometry {
235
- const key = `${width},${height},${depth},${radius},${segments}`;
230
+ /**
231
+ * A box with **face** normals, cached by size.
232
+ *
233
+ * `compactBox` above shares eight vertices between all six faces and derives each normal by
234
+ * normalising the vertex position. That is fine for something roughly cubic, and wrong for
235
+ * anything long and thin: for the arena's 22 x 4.2 x 0.4 back wall every normal comes out pointing
236
+ * along +/-X, so the inner face is shaded as though it faced sideways and an overhead key misses
237
+ * it completely. The wall rendered as a black band straight across the middle of the frame at
238
+ * exactly the height the targets stand — and no palette or light change could lift it, because the
239
+ * surface was not facing the light.
240
+ *
241
+ * A `BoxGeometry` has twenty-four vertices and the **same twelve triangles**, so this costs
242
+ * nothing against the triangle budget. `compactBox` stays for the flat trim strips and decals,
243
+ * where the geometry really is a thin quad and the shading does not matter.
244
+ */
245
+ function roundedBox(width: number, height: number, depth: number): BufferGeometry {
246
+ const key = `${width},${height},${depth}`;
236
247
  const cached = roundedCache.get(key);
237
248
  if (cached !== undefined) return cached;
238
- const geometry = compactBox(width, height, depth);
249
+ const geometry = new BoxGeometry(width, height, depth);
239
250
  roundedCache.set(key, geometry);
240
251
  return geometry;
241
252
  }
242
253
 
254
+ /**
255
+ * Bake a group of rigid meshes down to one mesh per material.
256
+ *
257
+ * The arena's floor panels, its skirting and each drone are all static relative to their parent,
258
+ * and authored one mesh at a time they cost one draw each. With five hostiles on the field that
259
+ * put `production-performance` at five hundred draws. Merging keeps every material separate and
260
+ * separately editable and costs no triangles at all.
261
+ */
262
+ function bakeByMaterial(parts: readonly Mesh[], root: Group): void {
263
+ const byMaterial = new Map<Material, Mesh[]>();
264
+ for (const mesh of parts) {
265
+ const bucket = byMaterial.get(mesh.material as Material);
266
+ if (bucket === undefined) byMaterial.set(mesh.material as Material, [mesh]);
267
+ else bucket.push(mesh);
268
+ }
269
+ for (const [material, meshes] of byMaterial) {
270
+ const geometry = mergeGeometries(
271
+ meshes.map((mesh) => {
272
+ mesh.updateMatrix();
273
+ const placed = mesh.geometry.clone().applyMatrix4(mesh.matrix);
274
+ const cloned = placed.index === null ? placed : placed.toNonIndexed();
275
+ for (const name of Object.keys(cloned.attributes)) {
276
+ if (name !== "position") cloned.deleteAttribute(name);
277
+ }
278
+ return cloned;
279
+ }),
280
+ false,
281
+ );
282
+ if (geometry === null) throw new Error("mergeGeometries returned null baking a visual.");
283
+ geometry.computeVertexNormals();
284
+ const merged = new Mesh(geometry, material);
285
+ merged.castShadow = meshes[0]?.castShadow ?? true;
286
+ merged.receiveShadow = true;
287
+ root.add(merged);
288
+ }
289
+ }
290
+
243
291
  function shadowed(mesh: Mesh, cast = true): Mesh {
244
292
  mesh.castShadow = cast;
245
293
  mesh.receiveShadow = true;
@@ -253,89 +301,322 @@ function block(width: number, height: number, depth: number, material: Material)
253
301
  export function createArena(materials: ShooterMaterials) {
254
302
  const group = new Group();
255
303
  group.name = "arena";
256
- const floor = block(22, 0.4, 20, materials.arena);
304
+ // Everything static and non-interactive: floor panels, skirting, boundary lines, cover lips.
305
+ // Baked into one mesh per material at the end of this function.
306
+ const decoration: Mesh[] = [];
307
+ const floor = block(22, 0.4, 24, materials.arena);
257
308
  floor.name = "arena-floor";
258
- floor.position.set(0, -0.2, -2);
309
+ floor.position.set(0, -0.2, -1);
259
310
  group.add(floor);
311
+ // Four walls, not three. In first person the player turns around, and an arena open at the back
312
+ // shows the void the third-person camera never pointed at.
260
313
  const walls = [
261
- { depth: 20, position: [-11, 1.7, -2] as const, width: 0.4 },
262
- { depth: 20, position: [11, 1.7, -2] as const, width: 0.4 },
263
- { depth: 0.4, position: [0, 1.7, -12] as const, width: 22 },
314
+ { depth: 24, position: [-11, 1.9, -1] as const, width: 0.4 },
315
+ { depth: 24, position: [11, 1.9, -1] as const, width: 0.4 },
316
+ { depth: 0.4, position: [0, 1.9, -13] as const, width: 22 },
317
+ { depth: 0.4, position: [0, 1.9, 11] as const, width: 22 },
264
318
  ].map(({ depth, position, width }, index) => {
265
- const wall = block(width, 3.8, depth, materials.shadow);
319
+ const wall = block(width, 4.2, depth, materials.shadow);
266
320
  wall.name = `arena-wall-${index}`;
267
321
  wall.position.set(position[0], position[1], position[2]);
268
322
  group.add(wall);
323
+ // A lit skirting strip where the wall meets the deck. Without one the join is the darkest
324
+ // value in the arena and reads as a black band cut across the middle of the frame, which is
325
+ // exactly where the targets stand.
326
+ const skirting = new Mesh(
327
+ compactBox(width < 1 ? width + 0.12 : width, 0.14, depth < 1 ? depth + 0.12 : depth),
328
+ materials.trim,
329
+ );
330
+ skirting.position.set(position[0], 0.12, position[2]);
331
+ skirting.castShadow = false;
332
+ decoration.push(skirting);
269
333
  return wall;
270
334
  });
271
- for (let x = -9; x <= 9; x += 3) {
272
- const strip = new Mesh(compactBox(0.035, 0.012, 19), materials.trim);
273
- strip.position.set(x, 0.012, -2);
274
- strip.castShadow = false;
275
- strip.receiveShadow = false;
276
- group.add(strip);
335
+ // Cover. An arena with a flat floor is a shooting gallery: these are what turns "walk forward
336
+ // and hold fire" into peeking, and they are what the crouch is for.
337
+ const cover = [
338
+ { height: 1.15, position: [-4.6, 0, -3.2] as const, size: [2.4, 1.2] as const },
339
+ { height: 1.15, position: [4.6, 0, -3.2] as const, size: [2.4, 1.2] as const },
340
+ { height: 0.95, position: [0, 0, -7.4] as const, size: [3.6, 1.1] as const },
341
+ { height: 2.6, position: [-7.4, 0, -8.6] as const, size: [1.5, 1.5] as const },
342
+ { height: 2.6, position: [7.4, 0, -8.6] as const, size: [1.5, 1.5] as const },
343
+ { height: 0.9, position: [-2.4, 0, 2.4] as const, size: [1.4, 1.4] as const },
344
+ { height: 0.9, position: [2.4, 0, 2.4] as const, size: [1.4, 1.4] as const },
345
+ ].map(({ height, position, size }, index) => {
346
+ const crate = block(size[0], height, size[1], materials.cover);
347
+ crate.name = `arena-wall-cover-${index}`;
348
+ crate.position.set(position[0], height / 2, position[2]);
349
+ group.add(crate);
350
+ // A lit lip along the top edge, so cover reads as cover at a glance in a dim arena.
351
+ const lip = new Mesh(compactBox(size[0] + 0.06, 0.05, size[1] + 0.06), materials.edge);
352
+ lip.position.set(position[0], height + 0.02, position[2]);
353
+ lip.castShadow = false;
354
+ lip.receiveShadow = false;
355
+ decoration.push(lip);
356
+ return crate;
357
+ });
358
+ // Floor panels, then a boundary line. A full accent grid every three metres across the whole
359
+ // floor is what shipped, and it photographed as a debug overlay switched on by mistake: bright
360
+ // yellow rules over everything, drawing the eye away from the targets standing on them.
361
+ for (let x = -8; x <= 8; x += 5.4) {
362
+ for (let z = -11; z <= 9; z += 5) {
363
+ const panel = new Mesh(compactBox(4.9, 0.02, 4.5), materials.floorPanel);
364
+ panel.position.set(x, 0.011, z);
365
+ panel.castShadow = false;
366
+ panel.receiveShadow = true;
367
+ decoration.push(panel);
368
+ }
369
+ }
370
+ for (const [width, depth, z] of [
371
+ [21.4, 0.06, -12.6],
372
+ [21.4, 0.06, 10.6],
373
+ ] as const) {
374
+ const line = new Mesh(compactBox(width, 0.014, depth), materials.trim);
375
+ line.position.set(0, 0.02, z);
376
+ line.castShadow = false;
377
+ decoration.push(line);
277
378
  }
278
- for (let z = -11; z <= 7; z += 3) {
279
- const strip = new Mesh(compactBox(21, 0.012, 0.035), materials.trim);
280
- strip.position.set(0, 0.014, z);
281
- strip.castShadow = false;
282
- strip.receiveShadow = false;
283
- group.add(strip);
379
+ for (const side of [-1, 1]) {
380
+ const line = new Mesh(compactBox(0.06, 0.014, 23.2), materials.trim);
381
+ line.position.set(side * 10.6, 0.02, -1);
382
+ line.castShadow = false;
383
+ decoration.push(line);
284
384
  }
285
- return { floor, group, walls };
385
+ bakeByMaterial(decoration, group);
386
+ return { cover, floor, group, walls };
286
387
  }
287
388
 
288
- export function createPlayerVisual(materials: ShooterMaterials): Group {
389
+ /**
390
+ * The carbine and the hands that hold it, authored pointing -z.
391
+ *
392
+ * Deliberately built from primitives rather than loaded from a `.glb`: a kit that ships a
393
+ * 12 MB weapon model teaches an agent to reach for one, and this reads as a weapon at a
394
+ * fraction of the download. Swap it for a real model by loading a `.glb` in `Scene.load()` and
395
+ * handing it to `preparePlayerConventions` instead — `normaliseToMetres` sizes either one.
396
+ *
397
+ * It is authored at roughly 0.55 m so `normaliseToMetres` has real work to do: the size that
398
+ * ships is the one in `render/scale.ts`, never the one that happened to be convenient here.
399
+ */
400
+ export function createViewmodelVisual(materials: ShooterMaterials): Group {
289
401
  const group = new Group();
290
- group.name = "player-visual";
291
- const body = block(0.76, 1.35, 0.76, materials.player);
292
- body.position.y = 0.62;
293
- group.add(body);
294
- const visor = new Mesh(compactBox(0.56, 0.22, 0.08), materials.trim);
295
- visor.position.set(0, 0.88, -0.4);
296
- visor.castShadow = true;
297
- group.add(visor);
298
- const muzzle = new Mesh(
299
- new CylinderGeometry(0.08, 0.1, 0.5, 6).rotateX(Math.PI / 2),
300
- materials.shadow,
402
+ group.name = "viewmodel";
403
+
404
+ const rifle = new Group();
405
+ rifle.name = "held-rifle";
406
+
407
+ const part = (
408
+ geometry: BufferGeometry,
409
+ material: Material,
410
+ x: number,
411
+ y: number,
412
+ z: number,
413
+ ): Mesh => {
414
+ const mesh = new Mesh(geometry, material);
415
+ mesh.position.set(x, y, z);
416
+ // The viewmodel is drawn over the arena and never casts into it: a weapon held at the eye
417
+ // throws a shadow the size of the room.
418
+ mesh.castShadow = false;
419
+ mesh.receiveShadow = false;
420
+ mesh.frustumCulled = false;
421
+ rifle.add(mesh);
422
+ return mesh;
423
+ };
424
+
425
+ part(compactBox(0.062, 0.072, 0.24), materials.gunmetal, 0, 0, -0.02);
426
+ part(compactBox(0.05, 0.052, 0.15), materials.polymer, 0, -0.002, -0.2);
427
+ part(
428
+ new CylinderGeometry(0.011, 0.011, 0.2, 6).rotateX(Math.PI / 2),
429
+ materials.gunmetal,
430
+ 0,
431
+ 0.012,
432
+ -0.31,
433
+ );
434
+ part(
435
+ new CylinderGeometry(0.021, 0.019, 0.07, 6).rotateX(Math.PI / 2),
436
+ materials.gunmetal,
437
+ 0,
438
+ 0.012,
439
+ -0.43,
301
440
  );
302
- muzzle.position.set(0, 0.52, -0.55);
303
- muzzle.castShadow = true;
304
- group.add(muzzle);
441
+ // Magazine and pistol grip, both raked back the way a real one sits in the hand.
442
+ const magazine = part(compactBox(0.04, 0.13, 0.062), materials.polymer, 0, -0.09, -0.04);
443
+ magazine.rotation.x = -0.16;
444
+ const grip = part(compactBox(0.038, 0.1, 0.05), materials.polymer, 0, -0.075, 0.07);
445
+ grip.rotation.x = 0.3;
446
+ part(compactBox(0.055, 0.062, 0.13), materials.polymer, 0, -0.006, 0.13);
447
+ // The optic. `preparePlayerConventions` does not look for it by name, but a rigged replacement
448
+ // usually ships one called this, and the aiming pose is authored against its position.
449
+ const optic = part(compactBox(0.036, 0.038, 0.07), materials.gunmetal, 0, 0.057, -0.01);
450
+ optic.name = "optic";
451
+ part(compactBox(0.008, 0.008, 0.008), materials.sight, 0, 0.058, -0.045);
452
+ part(compactBox(0.044, 0.012, 0.09), materials.gunmetal, 0, 0.04, -0.02);
453
+
454
+ group.add(rifle);
455
+
456
+ // Two gloved forearms. They live outside `held-rifle` so `normaliseToMetres` measures the
457
+ // weapon and not the person carrying it.
458
+ const arms = new Group();
459
+ arms.name = "viewmodel-arms";
460
+ const forearm = (x: number, y: number, z: number, pitch: number, yaw: number): void => {
461
+ const mesh = new Mesh(compactBox(0.048, 0.046, 0.3), materials.glove);
462
+ mesh.position.set(x, y, z);
463
+ mesh.rotation.set(pitch, yaw, 0);
464
+ mesh.castShadow = false;
465
+ mesh.receiveShadow = false;
466
+ mesh.frustumCulled = false;
467
+ arms.add(mesh);
468
+ };
469
+ forearm(0.075, -0.15, 0.02, 0.5, -0.26);
470
+ forearm(-0.055, -0.12, -0.2, 0.36, 0.32);
471
+ group.add(arms);
305
472
  return group;
306
473
  }
307
474
 
475
+ /**
476
+ * What the player sees when they look down: hips, thighs, shins, boots.
477
+ *
478
+ * Nothing above the waist, because a chest at eye height fills the frame and clips through the
479
+ * near plane. `GroundSnap` measures this group, so the boots are what meets the floor.
480
+ */
481
+ export function createLegsVisual(materials: ShooterMaterials): Group {
482
+ const group = new Group();
483
+ group.name = "player-legs";
484
+ const leg = (side: number): void => {
485
+ const thigh = block(0.19, 0.44, 0.21, materials.player);
486
+ thigh.position.set(side * 0.13, -0.24, 0);
487
+ group.add(thigh);
488
+ const shin = block(0.15, 0.4, 0.17, materials.shadow);
489
+ shin.position.set(side * 0.13, -0.64, 0.01);
490
+ group.add(shin);
491
+ const boot = block(0.17, 0.11, 0.3, materials.trim);
492
+ boot.position.set(side * 0.13, -0.855, -0.04);
493
+ group.add(boot);
494
+ };
495
+ leg(-1);
496
+ leg(1);
497
+ const hips = block(0.42, 0.2, 0.24, materials.player);
498
+ hips.position.y = -0.02;
499
+ group.add(hips);
500
+ return group;
501
+ }
502
+
503
+ /**
504
+ * The hostile: a hovering combat drone.
505
+ *
506
+ * What shipped here was a 1.2 x 1.8 box in hostile pink with two thin bars crossed over it, and
507
+ * the first frame read exactly like that — a sheet of pink card with a plus drawn on it, in
508
+ * triplicate. A drone made of nine boxes is barely more geometry (this template's `compactBox` is
509
+ * twelve triangles) and it has a front, a top and a silhouette, which is what tells the player
510
+ * which way a thing is facing and whether they have hit it.
511
+ *
512
+ * The collision box in `Target.ts` is unchanged at 1.2 x 1.8 x 1: this fills that volume rather
513
+ * than redefining it.
514
+ */
308
515
  export function createTargetVisual(materials: ShooterMaterials): Group {
309
516
  const group = new Group();
310
517
  group.name = "target-visual";
311
518
  // Keep a non-zero parent rotation in the stock scene so the nameplate demonstrates world-space
312
519
  // billboarding instead of accidentally passing only in the unparented case.
313
520
  group.rotation.y = 0.22;
314
- const body = block(1.2, 1.8, 1, materials.hostile);
315
- body.position.y = 0.9;
316
- group.add(body);
317
- const ring = new Mesh(compactBox(1.4, 0.08, 0.08), materials.trim);
318
- ring.position.y = 0.9;
319
- ring.castShadow = true;
320
- group.add(ring);
321
- const crossbar = new Mesh(compactBox(0.08, 0.08, 1.4), materials.trim);
322
- crossbar.position.y = 0.9;
323
- crossbar.castShadow = true;
324
- group.add(crossbar);
521
+ const parts: Mesh[] = [];
522
+
523
+ // Core: a chest that tapers to a narrower waist, so the thing has a top and a bottom.
524
+ const chest = block(0.94, 0.72, 0.62, materials.hostile);
525
+ chest.position.y = 1.24;
526
+ parts.push(chest);
527
+ const waist = block(0.6, 0.44, 0.46, materials.shadow);
528
+ waist.position.y = 0.78;
529
+ parts.push(waist);
530
+ const skirt = block(0.78, 0.26, 0.56, materials.hostile);
531
+ skirt.position.y = 0.5;
532
+ parts.push(skirt);
533
+
534
+ // Head and the single lit eye: the read that says which way it is looking.
535
+ const head = block(0.4, 0.3, 0.34, materials.shadow);
536
+ head.position.y = 1.72;
537
+ parts.push(head);
538
+ const eye = new Mesh(compactBox(0.26, 0.09, 0.06), materials.sight);
539
+ eye.position.set(0, 1.74, -0.2);
540
+ eye.castShadow = false;
541
+ parts.push(eye);
542
+
543
+ // Shoulder pods, canted outward. Most of the silhouette at range comes from these.
544
+ for (const side of [-1, 1]) {
545
+ const pod = block(0.28, 0.34, 0.46, materials.shadow);
546
+ pod.position.set(side * 0.62, 1.32, 0);
547
+ pod.rotation.z = side * -0.22;
548
+ parts.push(pod);
549
+ const muzzle = new Mesh(compactBox(0.1, 0.1, 0.34), materials.trim);
550
+ muzzle.position.set(side * 0.66, 1.28, -0.34);
551
+ muzzle.castShadow = false;
552
+ parts.push(muzzle);
553
+ // Trailing legs. A hovering thing with nothing below it reads as a floating box.
554
+ const leg = block(0.1, 0.5, 0.12, materials.shadow);
555
+ leg.position.set(side * 0.24, 0.2, 0.06);
556
+ leg.rotation.x = -0.24;
557
+ parts.push(leg);
558
+ }
559
+
560
+ // A lit band around the chest, so a hit registers against something bright.
561
+ const band = new Mesh(compactBox(0.98, 0.07, 0.66), materials.trim);
562
+ band.position.y = 1.44;
563
+ band.castShadow = false;
564
+ parts.push(band);
565
+
566
+ bakeByMaterial(parts, group);
325
567
  const nameplate = createTargetNameplate();
326
- nameplate.position.y = 2.1;
568
+ nameplate.position.y = 2.2;
327
569
  group.add(nameplate);
328
570
  return group;
329
571
  }
330
572
 
573
+ /**
574
+ * The friendly: a hovering escort drone.
575
+ *
576
+ * `Play.ts` places this at y = 1 — it is a *drone*, and it hovers. Authored as an upright figure
577
+ * it read as a teal fencepost standing in mid-air right down the player's sightline, which is the
578
+ * worst possible shape for the one object in the arena they must not shoot. Wider than it is tall,
579
+ * with a lit ring, it reads as friendly kit at a glance.
580
+ *
581
+ * It stays narrow across the beam: it has to stand in the player's line of fire for the
582
+ * friendly-layer proof to mean anything, and at 0.9 m across that put a cyan wall two metres in
583
+ * front of the eye.
584
+ */
331
585
  export function createFriendlyVisual(materials: ShooterMaterials): Group {
332
586
  const group = new Group();
333
- const body = block(0.9, 1.4, 0.9, materials.player);
334
- body.position.y = 0.7;
335
- group.add(body);
336
- const antenna = new Mesh(new CylinderGeometry(0.04, 0.04, 0.5, 8), materials.trim);
337
- antenna.position.y = 1.65;
338
- group.add(antenna);
587
+ const parts: Mesh[] = [];
588
+ const hull = block(0.42, 0.24, 0.36, materials.player);
589
+ parts.push(hull);
590
+ const belly = block(0.26, 0.16, 0.22, materials.shadow);
591
+ belly.position.y = -0.18;
592
+ parts.push(belly);
593
+ const visor = new Mesh(compactBox(0.3, 0.08, 0.05), materials.trim);
594
+ visor.position.set(0, 0.02, -0.2);
595
+ visor.castShadow = false;
596
+ parts.push(visor);
597
+ // Four rotor arms and a lit ring, so it reads as a drone and not as a floating brick.
598
+ for (const [x, z] of [
599
+ [-1, -1],
600
+ [1, -1],
601
+ [-1, 1],
602
+ [1, 1],
603
+ ] as const) {
604
+ const arm = block(0.2, 0.05, 0.2, materials.shadow);
605
+ arm.position.set(x * 0.26, 0.06, z * 0.24);
606
+ parts.push(arm);
607
+ const rotor = new Mesh(compactBox(0.3, 0.02, 0.3), materials.player);
608
+ rotor.position.set(x * 0.34, 0.12, z * 0.3);
609
+ rotor.castShadow = false;
610
+ parts.push(rotor);
611
+ }
612
+ const ring = new Mesh(compactBox(0.56, 0.03, 0.5), materials.trim);
613
+ ring.position.y = -0.12;
614
+ ring.castShadow = false;
615
+ parts.push(ring);
616
+ const beacon = new Mesh(new CylinderGeometry(0.02, 0.02, 0.22, 5), materials.trim);
617
+ beacon.position.y = 0.22;
618
+ parts.push(beacon);
619
+ bakeByMaterial(parts, group);
339
620
  return group;
340
621
  }
341
622