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
@@ -2,13 +2,19 @@
2
2
  "name": "defense-pointer-placement",
3
3
  "schemaVersion": 1,
4
4
  "target": "web",
5
- "viewport": { "width": 1280, "height": 720 },
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
6
9
  "warmupFrames": 40,
7
10
  "steps": [
8
11
  {
9
12
  "kind": "input",
10
13
  "label": "hover",
11
- "pointerPosition": { "x": 0.31678, "y": 0.41783 },
14
+ "pointerPosition": {
15
+ "x": 0.32462,
16
+ "y": 0.49184
17
+ },
12
18
  "waitTicks": 5,
13
19
  "release": true,
14
20
  "screenshot": "hovered"
@@ -16,14 +22,24 @@
16
22
  {
17
23
  "kind": "input",
18
24
  "label": "clear-hover",
19
- "pointerPosition": { "x": 0.01, "y": 0.01 },
25
+ "pointerPosition": {
26
+ "x": 0.01,
27
+ "y": 0.01
28
+ },
20
29
  "waitTicks": 2,
21
30
  "release": true
22
31
  },
23
32
  {
24
33
  "kind": "input",
25
34
  "label": "touch-held",
26
- "pointers": [{ "buttons": 1, "id": 1, "x": 0.31678, "y": 0.41783 }],
35
+ "pointers": [
36
+ {
37
+ "buttons": 1,
38
+ "id": 1,
39
+ "x": 0.32462,
40
+ "y": 0.49184
41
+ }
42
+ ],
27
43
  "waitTicks": 2,
28
44
  "release": false,
29
45
  "screenshot": "touch-held"
@@ -35,27 +51,53 @@
35
51
  "waitTicks": 1,
36
52
  "release": false
37
53
  },
38
- { "kind": "wait", "label": "placed", "waitTicks": 2, "release": true }
54
+ {
55
+ "kind": "wait",
56
+ "label": "placed",
57
+ "waitTicks": 2,
58
+ "release": true
59
+ }
39
60
  ],
40
61
  "assert": {
41
- "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
62
+ "diagnostics": {
63
+ "noConsoleErrors": true,
64
+ "runtimeReady": true
65
+ },
42
66
  "resources": [
43
67
  {
44
68
  "id": "state",
45
69
  "path": "spent",
46
70
  "atSteps": [
47
- { "label": "hover", "equals": 0 },
48
- { "label": "touch-held", "equals": 0 },
49
- { "label": "placed", "equals": 40 }
71
+ {
72
+ "label": "hover",
73
+ "equals": 0
74
+ },
75
+ {
76
+ "label": "touch-held",
77
+ "equals": 0
78
+ },
79
+ {
80
+ "label": "placed",
81
+ "equals": 40
82
+ }
50
83
  ]
51
84
  },
52
85
  {
53
86
  "id": "state",
54
87
  "path": "towers",
55
88
  "atSteps": [
56
- { "label": "hover", "equals": 0 },
57
- { "label": "touch-held", "equals": 0 },
58
- { "label": "placed", "equals": 1 }
89
+ {
90
+ "label": "hover",
91
+ "equals": 0
92
+ },
93
+ {
94
+ "label": "touch-held",
95
+ "equals": 0
96
+ },
97
+ {
98
+ "label": "placed",
99
+ "equals": 1
100
+ }
59
101
  ]
60
102
  }
61
103
  ],
@@ -64,26 +106,51 @@
64
106
  "entity": "build-preview",
65
107
  "component": "hovered",
66
108
  "atSteps": [
67
- { "label": "hover", "equals": true },
68
- { "label": "clear-hover", "equals": false },
69
- { "label": "touch-held", "equals": true }
109
+ {
110
+ "label": "hover",
111
+ "equals": true
112
+ },
113
+ {
114
+ "label": "clear-hover",
115
+ "equals": false
116
+ },
117
+ {
118
+ "label": "touch-held",
119
+ "equals": true
120
+ }
70
121
  ]
71
122
  },
72
123
  {
73
124
  "entity": "build-preview",
74
125
  "component": "tile",
75
126
  "atSteps": [
76
- { "label": "hover", "equals": "build-tile-2-3" },
77
- { "label": "touch-held", "equals": "build-tile-2-3" },
78
- { "label": "placed", "equals": "build-tile-2-3" }
127
+ {
128
+ "label": "hover",
129
+ "equals": "build-tile-2-3"
130
+ },
131
+ {
132
+ "label": "touch-held",
133
+ "equals": "build-tile-2-3"
134
+ },
135
+ {
136
+ "label": "placed",
137
+ "equals": "build-tile-2-3"
138
+ }
79
139
  ]
80
140
  },
81
141
  {
82
142
  "entity": "build-preview",
83
143
  "component": "placedTile",
84
- "atSteps": [{ "label": "placed", "equals": "build-tile-2-3" }]
144
+ "atSteps": [
145
+ {
146
+ "label": "placed",
147
+ "equals": "build-tile-2-3"
148
+ }
149
+ ]
85
150
  }
86
151
  ]
87
152
  },
88
- "artifacts": { "screenshots": "before-after" }
153
+ "artifacts": {
154
+ "screenshots": "before-after"
155
+ }
89
156
  }
@@ -7,7 +7,7 @@
7
7
  "subject": "tower.0",
8
8
  "steps": [
9
9
  { "kind": "input", "label": "build", "press": "KeyB", "holdTicks": 1, "release": true },
10
- { "kind": "wait", "label": "scan-window", "waitTicks": 300, "release": true }
10
+ { "kind": "wait", "label": "scan-window", "waitTicks": 330, "release": true }
11
11
  ],
12
12
  "assert": {
13
13
  "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
@@ -14,6 +14,20 @@
14
14
  ],
15
15
  "assert": {
16
16
  "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
17
+ "components": [
18
+ {
19
+ "allowTrivial": "GroundSnap settles the commander before this long simulation; the finite near-zero clearance is the generated call-site proof.",
20
+ "component": "groundClearance",
21
+ "entity": "player",
22
+ "lte": 0.01
23
+ },
24
+ {
25
+ "allowTrivial": "The commander mesh has an authored non-unit height; this retained factor proves normaliseToMetres ran in the generated player.",
26
+ "component": "normaliseFactor",
27
+ "entity": "player",
28
+ "gte": 1.01
29
+ }
30
+ ],
17
31
  "resources": [
18
32
  { "id": "state", "path": "status", "equals": "WON", "changed": true },
19
33
  { "id": "state", "path": "wave", "equals": 10, "changed": true },
@@ -1,7 +1,7 @@
1
1
  import { type IPathFollow3DSample, PathFollow3D } from "@threenative/core";
2
- import { CollisionShape3D } from "@threenative/physics";
2
+ import { CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
3
3
  import { type Group, Vector3 } from "three";
4
- import { ATTACKER_LAYER, type DefensePhysics, createEntityBody } from "../physics.js";
4
+ import { ATTACKER_LAYER } from "../physics.js";
5
5
  import { emitPlaytestEvent } from "../playtest-events.js";
6
6
  import { attacker as attackerMesh } from "../render/shapes.js";
7
7
 
@@ -32,7 +32,7 @@ export class Attacker {
32
32
  readonly id: string;
33
33
  readonly lateralOffset: number;
34
34
  readonly pathPoints: readonly Vector3[];
35
- readonly physics: DefensePhysics;
35
+ readonly physics: IPhysicsContext;
36
36
  readonly onDefeated: () => void;
37
37
  readonly onLeak: () => void;
38
38
  }) {
@@ -43,7 +43,7 @@ export class Attacker {
43
43
  this.#onLeak = options.onLeak;
44
44
  this.#path = new PathFollow3D({ points: options.pathPoints, speed: ATTACKER_SPEED });
45
45
  this.mesh = attackerMesh();
46
- this.#body = createEntityBody({
46
+ this.#body = new RigidBody3D({
47
47
  collisionLayer: ATTACKER_LAYER,
48
48
  collisionMask: 0,
49
49
  entity: this.entityId,
@@ -1,7 +1,7 @@
1
- import { CollisionShape3D } from "@threenative/physics";
1
+ import { CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
2
2
  import { type Object3D, Vector3 } from "three";
3
- import { type DefensePhysics, GROUND_LAYER, ROUTE_LAYER, createEntityBody } from "../physics.js";
4
- import { base, board, routeSegment } from "../render/shapes.js";
3
+ import { GROUND_LAYER, ROUTE_LAYER } from "../physics.js";
4
+ import { base, board, routeSegment, surrounds } from "../render/shapes.js";
5
5
 
6
6
  export const ROUTE_POINTS = [
7
7
  new Vector3(-11, 0, -6),
@@ -12,30 +12,44 @@ export const ROUTE_POINTS = [
12
12
  new Vector3(11, 0, 6),
13
13
  ] as const;
14
14
 
15
+ /**
16
+ * The four buildable positions, in the order the safe-build key walks them.
17
+ *
18
+ * The order is the level design. A player who buys three towers gets the first three, and those
19
+ * three have to cover the whole route: with `(-2.3, 3.8)` third, the last nine metres — the run
20
+ * along `z = 6` out to the exit — sat outside every tower's radius, so an attacker that survived
21
+ * the first twenty-seven metres walked the rest unopposed. Measured over ten waves: nineteen
22
+ * shots, nineteen kills, twenty attackers, one leak, every run.
23
+ *
24
+ * `(6.2, 3.8)` is third instead. It reaches the exit run end to end and still covers the corner
25
+ * before it, and `(-2.3, 3.8)` becomes the fourth tower a richer player adds for depth rather
26
+ * than for coverage. Slot zero stays where it is — the overlap-rejection test builds on it.
27
+ */
15
28
  export const SAFE_BUILD_SLOTS = [
16
29
  new Vector3(-8.3, 0, -3.8),
17
30
  new Vector3(-2.3, 0, -3.8),
18
- new Vector3(-2.3, 0, 3.8),
19
31
  new Vector3(6.2, 0, 3.8),
32
+ new Vector3(-2.3, 0, 3.8),
20
33
  ] as const;
21
34
 
22
35
  export const ROUTE_TEST_SLOT = new Vector3(-8, 0, -6);
23
36
 
24
37
  interface IRouteContext {
25
38
  readonly add: (object: Object3D) => Object3D;
26
- readonly physics: DefensePhysics;
39
+ readonly physics: IPhysicsContext;
27
40
  }
28
41
 
29
42
  export class RouteBoard {
30
43
  readonly points = ROUTE_POINTS.map((point) => point.clone());
31
44
  readonly surface: Object3D;
32
- readonly #bodies = [] as ReturnType<typeof createEntityBody>[];
45
+ readonly #bodies: RigidBody3D[] = [];
33
46
 
34
47
  constructor(ctx: IRouteContext) {
35
48
  this.surface = board();
49
+ ctx.add(surrounds());
36
50
  ctx.add(this.surface);
37
51
  this.#bodies.push(
38
- createEntityBody({
52
+ new RigidBody3D({
39
53
  collisionLayer: GROUND_LAYER,
40
54
  collisionMask: 0xffff,
41
55
  entity: "ground",
@@ -57,7 +71,7 @@ export class RouteBoard {
57
71
  visual.rotation.y = Math.abs(delta.z) > Math.abs(delta.x) ? Math.PI / 2 : 0;
58
72
  ctx.add(visual);
59
73
  this.#bodies.push(
60
- createEntityBody({
74
+ new RigidBody3D({
61
75
  collisionLayer: ROUTE_LAYER,
62
76
  collisionMask: 0xffff,
63
77
  entity: `route.${index}`,
@@ -0,0 +1,18 @@
1
+ import { GroundSnap, normaliseToMetres } from "@threenative/core";
2
+ import type { Group } from "three";
3
+
4
+ export interface IDefenseConventions {
5
+ readonly applyGrounding: (surfaceY: number, dt: number) => void;
6
+ readonly groundSnap: GroundSnap;
7
+ readonly normaliseFactor: number;
8
+ }
9
+
10
+ export function prepareCommanderConventions(model: Group): IDefenseConventions {
11
+ const normaliseFactor = normaliseToMetres(model, { axis: "height", metres: 1 });
12
+ const groundSnap = new GroundSnap(model);
13
+ return {
14
+ applyGrounding: (surfaceY, dt) => groundSnap.apply(model, surfaceY, dt),
15
+ groundSnap,
16
+ normaliseFactor,
17
+ };
18
+ }
@@ -1,10 +1,11 @@
1
1
  import type { ICtx } from "@threenative/core";
2
+ import type { IPhysicsContext } from "@threenative/physics";
2
3
  import { type Group, Vector3 } from "three";
3
- import type { DefensePhysics } from "../physics.js";
4
+ import { type IDefenseConventions, prepareCommanderConventions } from "../conventions.js";
4
5
  import { commander as commanderMesh } from "../render/shapes.js";
5
6
  import type { GameState } from "../state.js";
6
7
 
7
- type GameCtx = ICtx<GameState, DefensePhysics>;
8
+ type GameCtx = ICtx<GameState, IPhysicsContext>;
8
9
 
9
10
  const MOVE_SPEED = 4;
10
11
  const SPAWN = new Vector3(9, 0, 8);
@@ -13,11 +14,13 @@ const BOARD_BOUNDS = { maxX: 12, maxZ: 8, minX: -12, minZ: -8 } as const;
13
14
  export class Player {
14
15
  readonly mesh: Group;
15
16
  readonly tags = ["player", "commander"];
17
+ #conventions: IDefenseConventions;
16
18
 
17
19
  constructor(ctx: GameCtx) {
18
20
  this.mesh = commanderMesh();
19
21
  this.mesh.name = "player";
20
22
  this.mesh.position.copy(SPAWN);
23
+ this.#conventions = prepareCommanderConventions(this.mesh);
21
24
  ctx.add(this.mesh);
22
25
  }
23
26
 
@@ -32,10 +35,15 @@ export class Player {
32
35
  Math.min(BOARD_BOUNDS.maxZ, this.mesh.position.z - move.y * MOVE_SPEED * dt),
33
36
  );
34
37
  if (move.lengthSq() > 0) this.mesh.rotation.y = Math.atan2(move.x, -move.y);
38
+ this.#conventions.applyGrounding(0, dt);
35
39
  }
36
40
 
37
41
  debug(): Record<string, unknown> {
38
- return { position: this.mesh.position.toArray() };
42
+ return {
43
+ groundClearance: this.#conventions.groundSnap.clearance,
44
+ normaliseFactor: this.#conventions.normaliseFactor,
45
+ position: this.mesh.position.toArray(),
46
+ };
39
47
  }
40
48
 
41
49
  dispose(): void {
@@ -1,14 +1,13 @@
1
1
  import { defineGame } from "@threenative/core";
2
2
  import { playtest } from "@threenative/core/playtest";
3
- import { rapier } from "@threenative/physics";
3
+ import { type IPhysicsContext, rapier } from "@threenative/physics";
4
4
  import config from "../threenative.config.js";
5
- import type { DefensePhysics } from "./physics.js";
6
5
  import { drainPlaytestEvents as events } from "./playtest-events.js";
7
6
  import { Boot } from "./scenes/Boot.js";
8
7
  import { Defense } from "./scenes/Defense.js";
9
8
  import type { GameState } from "./state.js";
10
9
 
11
- const game = defineGame<GameState, DefensePhysics>({
10
+ const game = defineGame<GameState, IPhysicsContext>({
12
11
  input: {
13
12
  move: {
14
13
  down: ["ArrowDown", "KeyS"],
@@ -1,43 +1,13 @@
1
- import { type IPhysicsContext, RigidBody3D } from "@threenative/physics";
2
- import type { CollisionShape3D } from "@threenative/physics";
3
- import type { Vector3 } from "three";
4
-
1
+ /**
2
+ * Collision layers, and only collision layers.
3
+ *
4
+ * Which bit means what is a game decision — the framework never names your layers — so the four
5
+ * live here where a scene, a tower and an attacker all read the same numbers. Everything else
6
+ * this file used to hold (a `directSpaceState` accessor, a `RigidBody3D` wrapper that only added
7
+ * `entity`) is now first-class on `@threenative/physics`: query through `ctx.physics.directSpaceState`
8
+ * and pass `entity` straight to `RigidBody3D`.
9
+ */
5
10
  export const GROUND_LAYER = 1;
6
11
  export const ROUTE_LAYER = 2;
7
12
  export const TOWER_LAYER = 4;
8
13
  export const ATTACKER_LAYER = 8;
9
-
10
- export interface IShapeHit {
11
- readonly body: unknown;
12
- readonly entity?: string;
13
- readonly position?: Vector3;
14
- }
15
-
16
- export interface IPhysicsDirectSpaceState {
17
- intersectShape(options: {
18
- readonly collisionMask: number;
19
- readonly maxResults?: number;
20
- readonly position: Vector3;
21
- readonly shape: CollisionShape3D;
22
- }): readonly IShapeHit[];
23
- }
24
-
25
- export type DefensePhysics = IPhysicsContext & {
26
- readonly directSpaceState: IPhysicsDirectSpaceState;
27
- };
28
-
29
- export type EntityBodyOptions = ConstructorParameters<typeof RigidBody3D>[0] & {
30
- readonly entity?: string;
31
- };
32
-
33
- export function createEntityBody(options: EntityBodyOptions): RigidBody3D {
34
- return new RigidBody3D(options as ConstructorParameters<typeof RigidBody3D>[0]);
35
- }
36
-
37
- export function directSpaceState(physics: IPhysicsContext): IPhysicsDirectSpaceState {
38
- const state = (physics as Partial<DefensePhysics>).directSpaceState;
39
- if (state === undefined) {
40
- throw new Error("Defense requires PRD-088 directSpaceState.intersectShape.");
41
- }
42
- return state;
43
- }
@@ -1,6 +1,6 @@
1
- import { CollisionShape3D } from "@threenative/physics";
1
+ import { CollisionShape3D, type PhysicsDirectSpaceState3D } from "@threenative/physics";
2
2
  import type { Vector3 } from "three";
3
- import { type IPhysicsDirectSpaceState, ROUTE_LAYER, TOWER_LAYER } from "../physics.js";
3
+ import { ROUTE_LAYER, TOWER_LAYER } from "../physics.js";
4
4
 
5
5
  export type PlacementReason = "clear" | "overlap" | "route";
6
6
 
@@ -13,11 +13,11 @@ const BUILD_MASK = ROUTE_LAYER | TOWER_LAYER;
13
13
  const BUILD_HEIGHT = 0.6;
14
14
 
15
15
  export class Buildable {
16
- readonly #query: IPhysicsDirectSpaceState;
16
+ readonly #query: PhysicsDirectSpaceState3D;
17
17
  readonly #shape = CollisionShape3D.box(1.55, 1.2, 1.55);
18
18
  readonly #placed: Vector3[] = [];
19
19
 
20
- constructor(query: IPhysicsDirectSpaceState) {
20
+ constructor(query: PhysicsDirectSpaceState3D) {
21
21
  this.#query = query;
22
22
  }
23
23
 
@@ -3,8 +3,14 @@ import type { PerspectiveCamera } from "three";
3
3
  export function setupCamera(camera: PerspectiveCamera): void {
4
4
  camera.fov = 48;
5
5
  camera.near = 0.1;
6
- camera.far = 120;
7
- camera.position.set(0, 22, 19);
8
- camera.lookAt(0, 0, 0);
6
+ camera.far = 400;
7
+ // Lower and further back than the old 22/19, so the horizon and the hills behind the sector are
8
+ // in frame. Pitched straight down the terrain filled the picture edge to edge and the board had
9
+ // a ground but still no *place*.
10
+ camera.position.set(0, 14.5, 26);
11
+ camera.lookAt(0, 0, -2.5);
12
+ // `playtests/pointer-placement.playtest.json` clicks a screen fraction and asserts it lands on
13
+ // `build-tile-2-3` (world -9, -3). Those fractions are a projection of *this* camera: move it and
14
+ // they must be recomputed, not nudged by eye.
9
15
  camera.updateProjectionMatrix();
10
16
  }
@@ -36,7 +36,11 @@ interface ILoadingHost {
36
36
  };
37
37
  readonly renderer: { compileAsync(scene: Scene, camera: Camera): Promise<void> };
38
38
  readonly scene: Scene;
39
- readonly startup: { readonly progress: number; whenReady(): Promise<void> };
39
+ readonly startup: {
40
+ readonly progress: number;
41
+ readonly warmup?: { readonly status: "complete" | "incomplete" | "unavailable" };
42
+ whenReady(): Promise<void>;
43
+ };
40
44
  readonly viewport?: {
41
45
  readonly safeArea: { height: number; width: number; x: number; y: number };
42
46
  };
@@ -231,7 +235,13 @@ export function createLoadingScreen(host: ILoadingHost): ILoadingController {
231
235
  };
232
236
 
233
237
  const updateProgress = (value: number): void => {
234
- progress = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
238
+ const bounded = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
239
+ // A missing or incomplete backend observation cannot prove that all first-use work is done.
240
+ // Keep the bar visibly indeterminate until readiness removes the cover; never turn unknown
241
+ // coverage into a false 100% claim.
242
+ const observationUnknown =
243
+ host.startup.warmup !== undefined && host.startup.warmup.status !== "complete";
244
+ progress = observationUnknown ? Math.min(0.9, bounded) : bounded;
235
245
  setFillUv(fill.geometry, progress, fillBaseU);
236
246
  status?.update(progress);
237
247
  layout();
@@ -9,5 +9,14 @@ export function createMaterials() {
9
9
  route: toon(palette.route, 0.88),
10
10
  shadow: new MeshStandardMaterial({ color: palette.shadow, roughness: 1 }),
11
11
  tower: toon(palette.accent, 0.56),
12
+ /** The plate the board sits on, and the terrain around it. */
13
+ /** The terrain the board sits in: cooler and darker than the board itself. */
14
+ terrain: toon(0x2f4a44, 0.96),
15
+ /** Hills on the horizon. */
16
+ distant: toon(0x44636a, 0.98),
17
+ /** Tower and base plating: cool metal against the warm accent. */
18
+ plating: toon(0x5c6f7d, 0.6),
19
+ /** The one hostile colour. */
20
+ hostile: toon(0xd9584f, 0.6),
12
21
  };
13
22
  }
@@ -1,14 +1,21 @@
1
1
  import { MeshStandardMaterial } from "three";
2
2
 
3
+ // A sector at dusk. `ground` was 0x173a3b against a flat 0x2b6a76 sky, and the first frame showed
4
+ // a near-black olive rectangle floating in a teal void — the board had no ground under it, no
5
+ // horizon behind it, and no value separation from either.
3
6
  export const palette = {
4
- skyHigh: 0x0b2236,
5
- skyLow: 0x2b6a76,
6
- ground: 0x173a3b,
7
- route: 0x4b5660,
7
+ skyHigh: 0x1d3f5e,
8
+ skyLow: 0x86b3b6,
9
+ /** The buildable board. Mid, so a tower standing on it reads against it. */
10
+ ground: 0x3f5f4c,
11
+ route: 0x6b7684,
8
12
  accent: 0xf5c451,
9
- shadow: 0x07131d,
13
+ shadow: 0x1a2c38,
10
14
  } as const;
11
15
 
16
+ // Terrain and distant hills are shades of these six rather than roles of their own; `materials.ts`
17
+ // owns them, next to the surfaces that use them.
18
+
12
19
  const materials = new Map<string, MeshStandardMaterial>();
13
20
 
14
21
  export function toon(color: number, roughness = 0.8): MeshStandardMaterial {
@@ -1,71 +1,34 @@
1
- // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
- // ThreeNative does not read this file.
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file.
3
2
  //
4
- // `WorldEnvironment`, in this folder, builds the lighting chain: which stages run, in what
5
- // order, and an honest report of what happened. It prints `TN_WORLD_ENVIRONMENT` naming every
6
- // stage as applied or refused **with a reason**, so a stage that silently no-op'd is never
7
- // mistaken for one you turned off. It decides no colour and no strength — every value below is
8
- // an argument, and they are yours.
3
+ // This file wires two things together and decides nothing itself. `quality.ts`, in this folder,
4
+ // owns which stages run at which tier and records what each one measured. `WorldEnvironment`,
5
+ // also in this folder, builds them and prints `TN_WORLD_ENVIRONMENT` naming every stage as
6
+ // applied or refused **with a reason**, so a stage that silently no-op'd is never mistaken for
7
+ // one you turned off.
9
8
  //
10
- // SSGI and SSR are the expensive pair, so they ship on for desktop and off for mobile. That
11
- // split is the shipped default, not a ceiling: turn either on for mobile by adding it to
12
- // `mobilePreset` and read the frame cost back out of `TN_FRAME_BUDGET`. What each stage costs,
13
- // and the one-line enable for the ones that ship off everywhere (godrays, contact AO,
14
- // vignette), is in `agent-docs/visual-baseline.md`.
9
+ // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one
10
+ // run — a desktop that is dropping frames, a capture you want to compare — pass it:
11
+ // `setupPost(renderer, scene, camera, { tier: "low" })`. Overriding does not silence the report:
12
+ // `TN_QUALITY_TIER` names the tier that ran either way.
15
13
  import type { Camera, DirectionalLight, Scene } from "three";
14
+ import { type QualityTier, qualityPreset, resolveQualityTier } from "./quality.js";
16
15
  import type { OutputRenderer } from "./worldEnvironment.js";
17
16
  import { WorldEnvironment } from "./worldEnvironment.js";
18
17
 
19
- // Scene-referred exposure: multiplied into the pass before the tone curve, so the gather, the
20
- // reflections and the bloom threshold all see the same exposed image.
21
- const exposure = 1.15;
22
-
23
- // Unchanged from this template's previous chain — strength, radius and threshold are a look
24
- // decision that was already tuned to this scene's palette.
25
- const glow = {
26
- bloomEnabled: true,
27
- bloomRadius: 0.5,
28
- bloomStrength: 0.42,
29
- bloomThreshold: 0.2,
30
- } as const;
31
-
32
- const desktopPreset = {
33
- ...glow,
34
- denoiseEnabled: true,
35
- exposure,
36
- ssgiEnabled: true,
37
- // Room scale, not contact scale: about two thirds of the 26-unit shadow extent
38
- // `lighting.ts` lights — a lit board seen from above, where the bounce off the ground plane is most of the effect.
39
- ssgiRadius: 18,
40
- ssgiQuality: "medium",
41
- ssrEnabled: true,
42
- // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as
43
- // "reflections are on and do nothing" — the ray dies a metre from where it started.
44
- ssrMaxDistance: 44,
45
- // A reflection carries almost no high-frequency detail, so half resolution costs a quarter
46
- // of the rays and is very hard to see in the result.
47
- ssrResolutionScale: 0.5,
48
- // RCAS puts back the micro-detail the half-resolution reflection and the denoiser take out.
49
- // The same cause everywhere, so the same value everywhere: **0 is maximum sharpening and 2
50
- // is none** — it is a radius, not a gain.
51
- sharpenEnabled: true,
52
- sharpenStrength: 0.3,
53
- tonemapMode: "aces",
54
- } as const;
55
-
56
- // No SSGI, no SSR, and therefore nothing for the sharpener to put back.
57
- const mobilePreset = {
58
- ...glow,
59
- exposure,
60
- tonemapMode: "aces",
61
- } as const;
62
-
63
18
  export function setupPost(
64
19
  renderer: OutputRenderer,
65
20
  scene: Scene,
66
21
  camera: Camera,
67
- environment: { godraysLight?: DirectionalLight; mobile?: boolean } = {},
22
+ environment: {
23
+ godraysLight?: DirectionalLight;
24
+ mobile?: boolean;
25
+ /** Forces a tier, ignoring `mobile`. An unknown name throws rather than falling back. */
26
+ tier?: QualityTier;
27
+ } = {},
68
28
  ): void {
69
- const world = new WorldEnvironment(environment.mobile === true ? mobilePreset : desktopPreset);
29
+ const tier = resolveQualityTier({ mobile: environment.mobile, tier: environment.tier });
30
+ const source = environment.tier === undefined ? "platform" : "override";
31
+ console.info(`TN_QUALITY_TIER ${tier} mobile=${environment.mobile === true} source=${source}`);
32
+ const world = new WorldEnvironment(qualityPreset(tier));
70
33
  world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
71
34
  }