create-threenative 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -1,6 +1,5 @@
1
1
  // Generated for you. Camera framing is game-owned source; edit it to change the feel.
2
- import type { PerspectiveCamera, Vector3 } from "three";
3
- import { Vector3 as Vec3 } from "three";
2
+ import { type PerspectiveCamera, Vector3 as Vec3, type Vector3 } from "three";
4
3
 
5
4
  export interface ICameraShakeOffset {
6
5
  readonly position: Vector3;
@@ -19,61 +18,72 @@ export interface ICameraShakeOptions {
19
18
  readonly curve: (phase: number) => number;
20
19
  }
21
20
 
21
+ /** Anything that can put the camera at its own eye. `Player` is the one that does. */
22
+ export interface IEyeSource {
23
+ readonly syncCamera: () => void;
24
+ }
25
+
22
26
  export interface ICameraRig {
23
- readonly follow: (target: Vector3, dt: number, yaw?: number) => void;
24
- readonly snap: (target: Vector3, yaw?: number) => void;
27
+ /** Place the eye for this frame, then add whatever the shake is currently worth. */
28
+ readonly follow: (eye: IEyeSource, dt: number) => void;
29
+ /** Place the eye with no smoothing and no shake — use on spawn and respawn. */
30
+ readonly snap: (eye: IEyeSource) => void;
25
31
  }
26
32
 
27
- const UP = new Vec3(0, 1, 0);
33
+ /**
34
+ * These are game-owned feel decisions. `CameraShake` only applies the values and never chooses
35
+ * them. First-person amplitudes are much smaller than a third-person rig's: the whole frame is
36
+ * the shake, so a centimetre reads as a punch where a third-person camera needs ten.
37
+ */
38
+ export function createArenaShakeOptions(): ICameraShakeOptions {
39
+ return {
40
+ amplitude: new Vec3(0.022, 0.016, 0.01),
41
+ rotationAmplitude: new Vec3(0.012, 0.016, 0.02),
42
+ frequency: 21,
43
+ decay: 8.5,
44
+ curve: (phase) => Math.sin(phase) * 0.72 + Math.sin(phase * 0.43) * 0.28,
45
+ };
46
+ }
28
47
 
48
+ /**
49
+ * Both halves of a shake, in one place.
50
+ *
51
+ * Position and rotation are applied together because applying only the first is the shake bug
52
+ * that reads as the camera sliding rather than being hit.
53
+ */
29
54
  function composeCameraShake(camera: PerspectiveCamera, offset: ICameraShakeOffset): void {
30
55
  camera.position.add(offset.position);
31
56
  camera.rotation.set(
32
57
  camera.rotation.x + offset.rotation.x,
33
58
  camera.rotation.y + offset.rotation.y,
34
59
  camera.rotation.z + offset.rotation.z,
60
+ camera.rotation.order,
35
61
  );
36
62
  }
37
63
 
38
- // These are game-owned feel decisions. CameraShake only applies the values and never chooses them.
39
- export function createArenaShakeOptions(): ICameraShakeOptions {
40
- return {
41
- amplitude: new Vec3(0.08, 0.05, 0.03),
42
- rotationAmplitude: new Vec3(0.025, 0.04, 0.015),
43
- frequency: 17,
44
- decay: 7,
45
- curve: (phase) => Math.sin(phase) * 0.72 + Math.sin(phase * 0.43) * 0.28,
46
- };
47
- }
48
-
49
- export function createArenaCamera(camera: PerspectiveCamera, shake?: ICameraShakeLike): ICameraRig {
50
- const offset = new Vec3(0, 5.2, 9.2);
51
- const lookAhead = new Vec3(0, 0.4, -4.6);
52
- const desired = new Vec3();
53
- const aim = new Vec3();
54
- const rotatedOffset = new Vec3();
55
- const rotatedLookAhead = new Vec3();
56
-
57
- // `yaw` is the look angle the scene accumulated from relative mouse motion: positive turns
58
- // the view right. The orbit swings offset and look-ahead around the player by the same angle,
59
- // so aim direction and camera stay one rig.
60
- const pose = (target: Vector3, dt: number, yaw = 0): void => {
61
- rotatedOffset.copy(offset).applyAxisAngle(UP, -yaw);
62
- rotatedLookAhead.copy(lookAhead).applyAxisAngle(UP, -yaw);
63
- if (dt === 0) {
64
- camera.position.copy(target).add(rotatedOffset);
65
- } else {
66
- desired.copy(target).add(rotatedOffset);
67
- camera.position.lerp(desired, 1 - Math.exp(-dt / 0.2));
68
- }
69
- camera.lookAt(aim.copy(target).add(rotatedLookAhead));
64
+ /**
65
+ * The first-person rig.
66
+ *
67
+ * There is no smoothing here on purpose. A third-person camera lerps towards its target because
68
+ * the target is something it is watching; the eye *is* the player, and easing it turns every step
69
+ * into a swim. What does get added is the hit shake, composed on top of the pose the player just
70
+ * wrote, so the shake decays back to exactly where the player is aiming.
71
+ */
72
+ export function createFirstPersonRig(
73
+ camera: PerspectiveCamera,
74
+ shake?: ICameraShakeLike,
75
+ ): ICameraRig {
76
+ const pose = (eye: IEyeSource, dt: number): void => {
77
+ eye.syncCamera();
78
+ // A snap is a respawn, and a respawn should not arrive pre-shaken.
79
+ if (dt === 0) return;
70
80
  const shakeOffset = shake?.update(dt);
71
81
  if (shakeOffset === undefined) return;
72
82
  composeCameraShake(camera, shakeOffset);
73
83
  };
74
84
 
75
85
  return {
76
- follow: (target, dt, yaw = 0) => pose(target, dt, yaw),
77
- snap: (target, yaw = 0) => pose(target, 0, yaw),
86
+ follow: (eye, dt) => pose(eye, dt),
87
+ snap: (eye) => pose(eye, 0),
78
88
  };
79
89
  }
@@ -0,0 +1,211 @@
1
+ // Generated for you. What a bullet leaves behind is a look decision; this file owns all of it.
2
+ import {
3
+ DataTexture,
4
+ DoubleSide,
5
+ type Material,
6
+ Mesh,
7
+ MeshBasicMaterial,
8
+ type Object3D,
9
+ PlaneGeometry,
10
+ Quaternion,
11
+ RGBAFormat,
12
+ type Texture,
13
+ UnsignedByteType,
14
+ Vector3,
15
+ } from "three";
16
+ import { scale } from "./scale.js";
17
+
18
+ /** Deterministic value noise, so a rebuilt texture is byte-identical between runs. */
19
+ function hash(x: number, y: number): number {
20
+ const n = Math.sin(x * 127.1 + y * 311.7) * 43758.5453;
21
+ return n - Math.floor(n);
22
+ }
23
+
24
+ /**
25
+ * One bullet hole: a punched dark core, a bright rim of powdered surface, and a few spall streaks
26
+ * running out from the edge. The streaks are what stop it reading as a sticker — a perfect circle
27
+ * on a wall is a dot, and an irregular one is damage.
28
+ */
29
+ export function bulletHoleTexture(size = 64): Texture {
30
+ const data = new Uint8Array(size * size * 4);
31
+ const centre = (size - 1) / 2;
32
+ const streaks = Array.from({ length: 8 }, (_, index) => ({
33
+ angle: (index / 8) * Math.PI * 2 + hash(index, 3) * 0.6,
34
+ reach: 0.5 + hash(index, 7) * 0.34,
35
+ width: 0.06 + hash(index, 11) * 0.09,
36
+ }));
37
+ for (let y = 0; y < size; y += 1) {
38
+ for (let x = 0; x < size; x += 1) {
39
+ const px = (x - centre) / centre;
40
+ const py = (y - centre) / centre;
41
+ const radius = Math.sqrt(px * px + py * py);
42
+ const angle = Math.atan2(py, px);
43
+ // Grain keeps the rim from reading as an airbrushed ring.
44
+ const grain = 0.82 + hash(Math.floor(x * 0.7), Math.floor(y * 0.7)) * 0.36;
45
+ const core = 0.34 * grain;
46
+ const rim = 0.56 * grain;
47
+ let alpha = 0;
48
+ let shade = 0;
49
+ if (radius < core) {
50
+ // The hole itself: opaque, and dark rather than pure black so it takes the fog.
51
+ alpha = 1;
52
+ shade = 0.05 + radius * 0.1;
53
+ } else if (radius < rim) {
54
+ // Crushed surface around the entry — the brightest part of a real bullet hole.
55
+ const t = (radius - core) / Math.max(1e-4, rim - core);
56
+ alpha = 1 - t * 0.3;
57
+ shade = 0.22 + t * 0.7;
58
+ } else if (radius < 1) {
59
+ const t = (radius - rim) / (1 - rim);
60
+ alpha = Math.max(0, (1 - t) ** 2.2) * 0.55 * grain;
61
+ shade = 0.78;
62
+ }
63
+ for (const streak of streaks) {
64
+ let delta = Math.abs(angle - streak.angle);
65
+ if (delta > Math.PI) delta = Math.PI * 2 - delta;
66
+ if (radius <= core || radius > streak.reach) continue;
67
+ const across = delta / streak.width;
68
+ if (across > 1) continue;
69
+ const along = 1 - (radius - core) / Math.max(1e-4, streak.reach - core);
70
+ const strength = (1 - across) ** 1.5 * along ** 1.1;
71
+ alpha = Math.max(alpha, strength * 0.9);
72
+ shade = Math.min(shade, 0.14 + (1 - strength) * 0.55);
73
+ }
74
+ const index = (y * size + x) * 4;
75
+ const value = Math.round(Math.min(1, shade) * 255);
76
+ data[index] = value;
77
+ data[index + 1] = value;
78
+ data[index + 2] = value;
79
+ data[index + 3] = Math.round(Math.min(1, alpha) * 255);
80
+ }
81
+ }
82
+ const texture = new DataTexture(data, size, size, RGBAFormat, UnsignedByteType);
83
+ texture.needsUpdate = true;
84
+ return texture;
85
+ }
86
+
87
+ const FORWARD = new Vector3(0, 0, 1);
88
+ // Scratch. The fire path must not allocate.
89
+ const scratchQuaternion = new Quaternion();
90
+ const scratchRoll = new Quaternion();
91
+ const scratchNormal = new Vector3();
92
+
93
+ /**
94
+ * Bullet holes that stay put.
95
+ *
96
+ * A hole that fades after half a second is worse than no hole: the player learns their rounds land
97
+ * nowhere. So the pool is fixed and recycled round-robin, and the oldest mark quietly gives up its
98
+ * slot rather than every mark expiring on a timer.
99
+ *
100
+ * Each slot gets its own cloned material, which looks wasteful and is not. The renderer batches
101
+ * renderables sharing a geometry *and* a material; a distinct material per slot keeps every mark on
102
+ * the exact draw path. A mark is also pushed `offset` metres along the surface normal — a decal
103
+ * sitting flat on a wall z-fights it into a shimmering ring that reads as a rendering bug.
104
+ */
105
+ export class DecalField {
106
+ readonly #slots: Mesh[] = [];
107
+ readonly #geometry: PlaneGeometry;
108
+ readonly #material: MeshBasicMaterial;
109
+ readonly #offset: number;
110
+ #cursor = 0;
111
+ #placed = 0;
112
+ #settled = false;
113
+
114
+ constructor(
115
+ parent: Object3D,
116
+ options: { count?: number; offset?: number; size?: number; tint?: number } = {},
117
+ ) {
118
+ this.#offset = options.offset ?? 0.014;
119
+ this.#geometry = new PlaneGeometry(
120
+ options.size ?? scale.bulletHole,
121
+ options.size ?? scale.bulletHole,
122
+ );
123
+ this.#material = new MeshBasicMaterial({
124
+ color: options.tint ?? 0xb9c4cc,
125
+ depthWrite: false,
126
+ map: bulletHoleTexture(),
127
+ // A hole punched through a thin prop should read from behind it too.
128
+ side: DoubleSide,
129
+ transparent: true,
130
+ });
131
+ for (let index = 0; index < (options.count ?? 32); index += 1) {
132
+ const mesh = new Mesh(this.#geometry, this.#material.clone());
133
+ // Present from the first frame at a size nothing can see, so this material's pipeline is
134
+ // built during loading rather than on the frame the first round lands.
135
+ mesh.scale.setScalar(0.0001);
136
+ mesh.visible = true;
137
+ mesh.frustumCulled = false;
138
+ mesh.renderOrder = 3;
139
+ parent.add(mesh);
140
+ this.#slots.push(mesh);
141
+ }
142
+ }
143
+
144
+ get placed(): number {
145
+ return this.#placed;
146
+ }
147
+
148
+ get capacity(): number {
149
+ return this.#slots.length;
150
+ }
151
+
152
+ /**
153
+ * Stop submitting the slots nobody has used yet.
154
+ *
155
+ * Every slot is resident from frame one so its pipeline compiles during loading. The cost is a
156
+ * draw call per unused slot, forever, and on a phone the draw call is the expensive part. Once
157
+ * the pipeline is compiled it stays compiled, so hiding a slot afterwards costs nothing to undo.
158
+ * Call this a second or two in — not on the first frame, or the compile this exists to force
159
+ * will not have happened yet.
160
+ */
161
+ settle(): void {
162
+ this.#settled = true;
163
+ for (const mesh of this.#slots) if (mesh.scale.x <= 0.001) mesh.visible = false;
164
+ }
165
+
166
+ /**
167
+ * Stick a mark on a surface. `normal` is expected in world space, already transformed off the
168
+ * struck object — a raycast's face normal is object-local and will send marks into walls.
169
+ */
170
+ place(point: Vector3, normal: Vector3, size = 1): void {
171
+ const mesh = this.#slots[this.#cursor % this.#slots.length];
172
+ this.#cursor += 1;
173
+ if (mesh === undefined) return;
174
+ this.#placed += 1;
175
+ scratchNormal.copy(normal).normalize();
176
+ scratchQuaternion.setFromUnitVectors(FORWARD, scratchNormal);
177
+ // Spin about the normal so a wall taking a burst is not tiled with the same mark.
178
+ scratchRoll.setFromAxisAngle(FORWARD, (this.#placed * 2.399) % (Math.PI * 2));
179
+ scratchQuaternion.multiply(scratchRoll);
180
+ mesh.quaternion.copy(scratchQuaternion);
181
+ mesh.position.copy(point).addScaledVector(scratchNormal, this.#offset);
182
+ mesh.scale.setScalar(size);
183
+ mesh.visible = true;
184
+ // The renderer reads the mark off its world matrix and this slot moved after the last scene
185
+ // update; without this the mark draws one frame behind, at its previous hit.
186
+ mesh.updateMatrixWorld(true);
187
+ }
188
+
189
+ /** Registered as an entity so a scenario can assert that a round actually left a mark. */
190
+ debug(): { capacity: number; placed: number } {
191
+ return { capacity: this.capacity, placed: this.#placed };
192
+ }
193
+
194
+ clear(): void {
195
+ for (const mesh of this.#slots) {
196
+ mesh.scale.setScalar(0.0001);
197
+ if (this.#settled) mesh.visible = false;
198
+ }
199
+ this.#cursor = 0;
200
+ }
201
+
202
+ dispose(): void {
203
+ for (const mesh of this.#slots) {
204
+ (mesh.material as Material).dispose();
205
+ mesh.removeFromParent();
206
+ }
207
+ this.#slots.length = 0;
208
+ this.#geometry.dispose();
209
+ this.#material.dispose();
210
+ }
211
+ }
@@ -16,9 +16,13 @@ type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
16
16
  export function setupLighting(scene: Scene, renderer: ShadowRenderer): DirectionalLight {
17
17
  renderer.shadowMap.enabled = true;
18
18
  renderer.shadowMap.type = PCFSoftShadowMap;
19
- scene.add(new HemisphereLight(palette.skyHigh, palette.skyLow, 1.25));
19
+ // First person puts the player inside the arena rather than above it, so the sky term does
20
+ // most of the work of making a wall read as a surface instead of a silhouette.
21
+ scene.add(new HemisphereLight(palette.skyHigh, palette.arena, 1.5));
20
22
 
21
- const key = new DirectionalLight(palette.accent, 3.1);
23
+ // Warm white, not the accent. Keyed with the accent itself, every neutral surface in the arena
24
+ // picked up the same yellow the HUD and the floor lines use, so nothing separated from anything.
25
+ const key = new DirectionalLight(0xffeccc, 2.8);
22
26
  key.name = "key-light";
23
27
  key.position.set(-6, 10, 7);
24
28
  key.castShadow = true;
@@ -37,7 +41,7 @@ export function setupLighting(scene: Scene, renderer: ShadowRenderer): Direction
37
41
  rim.name = "rim-light";
38
42
  rim.position.set(8, 5, -10);
39
43
  scene.add(rim);
40
- scene.add(new AmbientLight(palette.skyLow, 0.3));
44
+ scene.add(new AmbientLight(palette.skyHigh, 0.55));
41
45
 
42
46
  return key;
43
47
  }
@@ -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();
@@ -4,7 +4,9 @@ import { palette } from "./palette.js";
4
4
 
5
5
  export function createMaterials() {
6
6
  return {
7
- arena: new MeshStandardMaterial({ color: palette.arena, metalness: 0.35, roughness: 0.62 }),
7
+ // Matte. At 0.35 metalness the deck became a mirror under the screen-space reflection stage
8
+ // once the walls were shaded correctly, and the arena read as a polished showroom floor.
9
+ arena: new MeshStandardMaterial({ color: palette.arena, metalness: 0.06, roughness: 0.82 }),
8
10
  accent: new MeshStandardMaterial({
9
11
  color: palette.accent,
10
12
  emissive: palette.accent,
@@ -15,7 +17,7 @@ export function createMaterials() {
15
17
  hostile: new MeshStandardMaterial({
16
18
  color: palette.hostile,
17
19
  emissive: palette.hostile,
18
- emissiveIntensity: 0.7,
20
+ emissiveIntensity: 0.3,
19
21
  metalness: 0.1,
20
22
  roughness: 0.3,
21
23
  }),
@@ -26,7 +28,58 @@ export function createMaterials() {
26
28
  metalness: 0.35,
27
29
  roughness: 0.34,
28
30
  }),
29
- shadow: new MeshStandardMaterial({ color: 0x101820, metalness: 0.5, roughness: 0.7 }),
31
+ /** The arena's boundary walls and the drones' dark plating. Lifted twice now: at 0x18242f and
32
+ * again at 0x263646 the four walls photographed as one black band straight across the middle
33
+ * of the frame, which is exactly the height the targets stand at. */
34
+ shadow: new MeshStandardMaterial({ color: 0x334659, metalness: 0.1, roughness: 0.8 }),
35
+ // The weapon is the largest thing on screen in first person, so it gets its own three
36
+ // materials rather than borrowing the arena's. Parkerised steel, moulded polymer, and the
37
+ // lit dot in the sight.
38
+ // Light enough to read as a shape against a dark arena. The first pass at 0x2b3138 was
39
+ // physically reasonable and photographed as a black slab.
40
+ // The weapon hangs at the eye, out of reach of the key light, so it carries a little emissive
41
+ // of its own. This is the flat "viewmodel light" every shooter uses, spent as material rather
42
+ // than as a light the rest of the arena would also see.
43
+ gunmetal: new MeshStandardMaterial({
44
+ color: 0x7d8996,
45
+ emissive: 0x2c343d,
46
+ emissiveIntensity: 1,
47
+ metalness: 0.7,
48
+ roughness: 0.42,
49
+ }),
50
+ polymer: new MeshStandardMaterial({
51
+ color: 0x4a5561,
52
+ emissive: 0x1e242b,
53
+ emissiveIntensity: 1,
54
+ metalness: 0.08,
55
+ roughness: 0.66,
56
+ }),
57
+ glove: new MeshStandardMaterial({
58
+ color: 0x6a7986,
59
+ emissive: 0x232b33,
60
+ emissiveIntensity: 1,
61
+ metalness: 0.05,
62
+ roughness: 0.8,
63
+ }),
64
+ /** Inset floor panels: one step off the arena tone, so the deck has a surface rather than a
65
+ * colour. Cheaper and quieter than a painted grid. */
66
+ floorPanel: new MeshStandardMaterial({
67
+ color: 0x2e4257,
68
+ metalness: 0.06,
69
+ roughness: 0.84,
70
+ }),
71
+ /** Waist-high crates and pillars. A mid tone, so a box reads as a box and not as its lit lip. */
72
+ cover: new MeshStandardMaterial({ color: 0x3d5266, metalness: 0.08, roughness: 0.78 }),
73
+ sight: new MeshStandardMaterial({
74
+ color: palette.hostile,
75
+ emissive: palette.hostile,
76
+ emissiveIntensity: 2.4,
77
+ metalness: 0,
78
+ roughness: 1,
79
+ }),
80
+ // Cover edges. Same accent hue as `trim`, a fraction of its emissive: a waist-high crate lit
81
+ // like a HUD element photographs as a glowing platform rather than something to hide behind.
82
+ edge: new MeshStandardMaterial({ color: 0x9a8b55, metalness: 0.35, roughness: 0.6 }),
30
83
  trim: new MeshStandardMaterial({
31
84
  color: palette.accent,
32
85
  emissive: palette.accent,
@@ -1,8 +1,11 @@
1
1
  // Generated for you. Keep the six palette roles coherent when you repaint the arena.
2
+ // Lifted off the floor. The arena tone was `0x22303c` under a dim key, and the deck photographed
3
+ // as near-black with a yellow grid floating on it — the cover, the walls and the ground all
4
+ // collapsed into one value and only the emissive trim survived.
2
5
  export const palette = {
3
- skyHigh: 0x263449,
4
- skyLow: 0x101820,
5
- arena: 0x18232d,
6
+ skyHigh: 0x3a5578,
7
+ skyLow: 0x1b2733,
8
+ arena: 0x374d63,
6
9
  player: 0x64d8cb,
7
10
  hostile: 0xff6b7a,
8
11
  accent: 0xf6c85f,
@@ -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.12;
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.48,
28
- bloomStrength: 0.75,
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 20-unit shadow extent
38
- // `lighting.ts` lights — an interior arena, which is the case screen-space GI is best at.
39
- ssgiRadius: 14,
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: 34,
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
  }