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
@@ -6,11 +6,38 @@
6
6
  "warmupFrames": 10,
7
7
  "subject": "player",
8
8
  "steps": [
9
- { "kind": "input", "press": "Space", "holdTicks": 4, "release": true },
10
- { "kind": "wait", "waitTicks": 100, "release": true }
9
+ { "kind": "input", "label": "jump", "press": "Space", "holdTicks": 4, "release": true },
10
+ { "kind": "wait", "label": "airborne-visual", "waitTicks": 8, "release": true },
11
+ { "kind": "wait", "label": "elevated-landing", "waitTicks": 100, "release": true }
11
12
  ],
12
13
  "assert": {
13
14
  "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
15
+ "components": [
16
+ {
17
+ "entity": "player",
18
+ "component": "groundCorrectionEnabled",
19
+ "atSteps": [
20
+ { "label": "airborne-visual", "equals": false },
21
+ { "label": "elevated-landing", "equals": true }
22
+ ]
23
+ },
24
+ {
25
+ "entity": "player",
26
+ "component": "groundSurfaceY",
27
+ "gte": 2.55,
28
+ "lte": 2.65,
29
+ "changed": true,
30
+ "atSteps": [{ "label": "elevated-landing", "equals": 2.6 }]
31
+ },
32
+ {
33
+ "entity": "player",
34
+ "component": "visualAttached",
35
+ "atSteps": [
36
+ { "label": "airborne-visual", "equals": true },
37
+ { "label": "elevated-landing", "equals": true }
38
+ ]
39
+ }
40
+ ],
14
41
  "movement": { "entity": "player", "minAxisDelta": { "axis": "+y", "min": 1.5 } },
15
42
  "resources": [{ "id": "state", "path": "peakRise", "gte": 1.5, "changed": true }]
16
43
  }
@@ -5,7 +5,8 @@
5
5
  "performance": {
6
6
  "maxDrawCalls": 200,
7
7
  "maxFrameMsP95": 33,
8
- "maxTriangles": 7700
8
+ "maxTriangles": 7700,
9
+ "minFps": 30
9
10
  },
10
11
  "renderChain": { "tier": "high" }
11
12
  },
@@ -16,7 +16,28 @@
16
16
  "noRuntimeDiagnostics": true,
17
17
  "runtimeReady": true
18
18
  },
19
+ "components": [
20
+ {
21
+ "allowTrivial": "GroundSnap settles the procedural character before this movement observation; the finite near-zero clearance is the generated call-site proof.",
22
+ "component": "groundClearance",
23
+ "entity": "player",
24
+ "lte": 0.01
25
+ },
26
+ {
27
+ "allowTrivial": "The procedural rig has an authored non-unit height; this retained factor proves normaliseToMetres ran in the generated character.",
28
+ "component": "normaliseFactor",
29
+ "entity": "player",
30
+ "gte": 1.01
31
+ }
32
+ ],
19
33
  "movement": { "entity": "player", "minDistance": 0.5 },
34
+ "visibility": [
35
+ {
36
+ "entity": "touch-controls",
37
+ "present": false,
38
+ "allowTrivial": "Desktop keyboard lanes intentionally omit touch controls while movement proves the scene is active."
39
+ }
40
+ ],
20
41
  "visual": [
21
42
  {
22
43
  "region": {
@@ -26,6 +47,16 @@
26
47
  "height": 720,
27
48
  "minNonblankPixelRatio": 0.01
28
49
  }
50
+ },
51
+ {
52
+ "region": {
53
+ "x": 1172,
54
+ "y": 552,
55
+ "width": 16,
56
+ "height": 20,
57
+ "maxLuminance": 0.4,
58
+ "maxDarkPixelRatio": 0.05
59
+ }
29
60
  }
30
61
  ]
31
62
  }
@@ -5,6 +5,9 @@
5
5
  "viewport": { "width": 1280, "height": 720 },
6
6
  "warmupFrames": 10,
7
7
  "subject": "player",
8
+ "setup": {
9
+ "place": [{ "entity": "patrol", "at": { "x": 6.5, "y": 0.66, "z": 0 }, "frozen": true }]
10
+ },
8
11
  "steps": [
9
12
  { "kind": "input", "press": "ArrowRight", "holdTicks": 45, "release": true },
10
13
  { "kind": "wait", "waitTicks": 80, "release": true },
@@ -9,8 +9,15 @@
9
9
  "steps": [
10
10
  {
11
11
  "kind": "input",
12
- "label": "keyboard-movement",
13
- "press": "ArrowUp",
12
+ "label": "movement-anchor",
13
+ "pointers": [{ "id": 7, "x": 0.18, "y": 0.75 }],
14
+ "holdTicks": 2,
15
+ "release": false
16
+ },
17
+ {
18
+ "kind": "input",
19
+ "label": "simultaneous-move-and-jump",
20
+ "pointers": [{ "id": 7, "x": 0.3, "y": 0.75 }, { "id": 3, "x": 0.922, "y": 0.861 }],
14
21
  "holdTicks": 45,
15
22
  "release": true
16
23
  },
@@ -24,11 +31,15 @@
24
31
  "runtimeReady": true
25
32
  },
26
33
  "movement": { "entity": "player", "minDistance": 0.5 },
34
+ "resources": [
35
+ { "id": "state", "path": "jumps", "gte": 1, "changed": true },
36
+ { "id": "state", "path": "playerX", "gte": 0.05, "changed": true }
37
+ ],
27
38
  "visibility": [
28
39
  {
29
40
  "entity": "touch-controls",
30
- "present": false,
31
- "allowTrivial": "Web targets intentionally omit the native touch-controls entity; keyboard movement proves the web path while this absence remains held."
41
+ "present": true,
42
+ "allowTrivial": "Touch-primary lanes keep the authored controls visible while state assertions prove they are live."
32
43
  }
33
44
  ],
34
45
  "visual": [
@@ -0,0 +1,18 @@
1
+ import { GroundSnap, normaliseToMetres } from "@threenative/core";
2
+ import type { Group } from "three";
3
+
4
+ export interface IPlatformerConventions {
5
+ readonly applyGrounding: (surfaceY: number, dt: number) => void;
6
+ readonly groundSnap: GroundSnap;
7
+ readonly normaliseFactor: number;
8
+ }
9
+
10
+ export function prepareCharacterConventions(model: Group): IPlatformerConventions {
11
+ const normaliseFactor = normaliseToMetres(model, { axis: "height", metres: 1.8 });
12
+ const groundSnap = new GroundSnap(model);
13
+ return {
14
+ applyGrounding: (surfaceY, dt) => groundSnap.apply(model, surfaceY, dt),
15
+ groundSnap,
16
+ normaliseFactor,
17
+ };
18
+ }
@@ -1,12 +1,14 @@
1
1
  import type { ICtx } from "@threenative/core";
2
2
  import { CharacterBody3D, CollisionShape3D, type IPhysicsContext } from "@threenative/physics";
3
3
  import { Group, Vector3 } from "three";
4
+ import { type IPlatformerConventions, prepareCharacterConventions } from "../conventions.js";
4
5
  import { ONE_WAY_LAYER } from "../level/Platform.js";
5
6
  import { animateCharacter, createCharacterRig } from "../render/rig.js";
6
7
  import type { ITouchInput } from "../render/touch-layout.js";
7
8
  import type { GameState } from "../state.js";
8
9
  type GameCtx = ICtx<GameState, IPhysicsContext>;
9
10
  export const PLAYER_LAYER = 1;
11
+ const VISUAL_ATTACHMENT_TOLERANCE = 0.1;
10
12
  export const PLATFORMER_FEEL = {
11
13
  airAcceleration: 24,
12
14
  blinkRate: 18,
@@ -54,8 +56,15 @@ export class Character {
54
56
  #dashCooldown = 0;
55
57
  #airJumpUsed = false;
56
58
  #time = 0;
59
+ #supportSurfaceY = 0;
57
60
  #dashDirection = new Vector3(1, 0, 0);
58
61
  #wants = new Vector3();
62
+ #bodyWorldPosition = new Vector3();
63
+ #visualWorldPosition = new Vector3();
64
+ #visualBodyOffsetY: number | undefined;
65
+ #visualWasGrounded = false;
66
+ #visualBaselineSupportY: number | undefined;
67
+ #conventions: IPlatformerConventions;
59
68
 
60
69
  constructor(ctx: GameCtx, spawn: Vector3) {
61
70
  this.mesh = new Group();
@@ -65,6 +74,7 @@ export class Character {
65
74
  this.visual = this.#rig.root;
66
75
  this.visual.position.y = -0.72;
67
76
  this.mesh.add(this.visual);
77
+ this.#conventions = prepareCharacterConventions(this.visual);
68
78
  this.body = new CharacterBody3D({
69
79
  autostep: { maxHeight: 0.35, minWidth: 0.2 },
70
80
  collisionLayer: PLAYER_LAYER,
@@ -80,7 +90,12 @@ export class Character {
80
90
  });
81
91
  }
82
92
 
83
- update(ctx: GameCtx, dt: number, touch?: ITouchInput): void {
93
+ update(
94
+ ctx: GameCtx,
95
+ dt: number,
96
+ touch?: ITouchInput,
97
+ supportSurfaceY?: (position: Pick<Vector3, "x" | "y" | "z">) => number | undefined,
98
+ ): void {
84
99
  this.#time += dt;
85
100
  this.#dashTimer = Math.max(0, this.#dashTimer - dt);
86
101
  this.#dashCooldown = Math.max(0, this.#dashCooldown - dt);
@@ -113,6 +128,16 @@ export class Character {
113
128
  this.#face(dt);
114
129
  this.#applyState();
115
130
  animateCharacter(this.#rig, this.state, this.#time, this.body.velocity.x);
131
+ const supportingSurfaceY = supportSurfaceY?.(this.mesh.position);
132
+ const canCorrectGrounding =
133
+ this.body.grounded && this.body.velocity.y <= 0 && supportingSurfaceY !== undefined;
134
+ // The platform resolver identifies the supporting collider and supplies the authored surface
135
+ // plane GroundSnap must use. This stays correct when a one-way controller reports the
136
+ // underside of a slab after passing through it, and keeps the visual on its body.
137
+ if (canCorrectGrounding) this.#supportSurfaceY = supportingSurfaceY;
138
+ this.#conventions.groundSnap.enabled = canCorrectGrounding;
139
+ this.#conventions.applyGrounding(this.#supportSurfaceY, dt);
140
+ this.#captureVisualBodyOffset(supportingSurfaceY);
116
141
  }
117
142
 
118
143
  bounce(): void {
@@ -128,13 +153,21 @@ export class Character {
128
153
  }
129
154
 
130
155
  debug(): Record<string, unknown> {
156
+ const visualAttachmentDrift = this.#visualAttachmentDrift();
131
157
  return {
132
158
  dashes: this.dashes,
133
159
  grounded: this.body.grounded,
160
+ groundClearance: this.#conventions.groundSnap.clearance,
161
+ groundCorrectionEnabled: this.#conventions.groundSnap.enabled,
162
+ groundSurfaceY: this.#supportSurfaceY,
134
163
  health: this.health,
135
164
  jumps: this.jumps,
165
+ normaliseFactor: this.#conventions.normaliseFactor,
136
166
  position: this.mesh.position.toArray(),
137
167
  state: this.state,
168
+ visualAttached:
169
+ visualAttachmentDrift !== null && visualAttachmentDrift <= VISUAL_ATTACHMENT_TOLERANCE,
170
+ visualAttachmentDrift,
138
171
  velocity: this.body.velocity.toArray(),
139
172
  };
140
173
  }
@@ -144,6 +177,35 @@ export class Character {
144
177
  this.mesh.removeFromParent();
145
178
  }
146
179
 
180
+ #captureVisualBodyOffset(supportingSurfaceY: number | undefined): void {
181
+ if (!this.body.grounded || this.body.velocity.y > 0) {
182
+ this.#visualWasGrounded = false;
183
+ return;
184
+ }
185
+ const supportChanged =
186
+ supportingSurfaceY !== undefined &&
187
+ this.#visualBaselineSupportY !== undefined &&
188
+ Math.abs(supportingSurfaceY - this.#visualBaselineSupportY) > VISUAL_ATTACHMENT_TOLERANCE;
189
+ if (this.#visualWasGrounded && !supportChanged) return;
190
+ // GroundSnap may move the visual relative to a one-way body's collider. Capture that offset
191
+ // once after each grounded contact, then compare only visual and body positions so a later
192
+ // visual detachment cannot be hidden by a continuously refreshed baseline.
193
+ this.mesh.getWorldPosition(this.#bodyWorldPosition);
194
+ this.visual.getWorldPosition(this.#visualWorldPosition);
195
+ this.#visualBodyOffsetY = this.#visualWorldPosition.y - this.#bodyWorldPosition.y;
196
+ this.#visualBaselineSupportY = supportingSurfaceY;
197
+ this.#visualWasGrounded = true;
198
+ }
199
+
200
+ #visualAttachmentDrift(): number | null {
201
+ if (this.#visualBodyOffsetY === undefined) return null;
202
+ this.mesh.getWorldPosition(this.#bodyWorldPosition);
203
+ this.visual.getWorldPosition(this.#visualWorldPosition);
204
+ return Math.abs(
205
+ this.#visualWorldPosition.y - this.#bodyWorldPosition.y - this.#visualBodyOffsetY,
206
+ );
207
+ }
208
+
147
209
  #tryJump(): void {
148
210
  if (this.#buffered <= 0) return;
149
211
  if (this.#coyote > 0) {
@@ -24,7 +24,9 @@ const game = defineGame<GameState, IPhysicsContext>({
24
24
  display: config.display,
25
25
  render: config.renderer,
26
26
  scenes: { boot: Boot, level: Level },
27
- start: "boot",
27
+ // Start at the playable scene so runner setup can reach Level.load() before Level.enter().
28
+ // Boot remains available as a simple transition scene for callers that want one explicitly.
29
+ start: "level",
28
30
  });
29
31
 
30
32
  export default game;
@@ -5,6 +5,14 @@ import type { GameCtx } from "../scenes/Level.js";
5
5
 
6
6
  export const ONE_WAY_LAYER = 2;
7
7
 
8
+ export interface IPlatform {
9
+ readonly body: RigidBody3D;
10
+ readonly contains: (position: Pick<Vector3, "x" | "z">) => boolean;
11
+ readonly surfaceY: number;
12
+ readonly visual: ReturnType<typeof platformMesh>;
13
+ dispose(): void;
14
+ }
15
+
8
16
  export function createPlatform(
9
17
  ctx: GameCtx,
10
18
  at: Vector3,
@@ -23,12 +31,16 @@ export function createPlatform(
23
31
  shape: CollisionShape3D.box(width, height, depth),
24
32
  type: "fixed",
25
33
  });
34
+ const center = at.clone();
26
35
  return {
27
36
  body,
37
+ contains: (position: Pick<Vector3, "x" | "z">) =>
38
+ Math.abs(position.x - center.x) <= width / 2 && Math.abs(position.z - center.z) <= depth / 2,
28
39
  dispose: () => {
29
40
  body.dispose();
30
41
  visual.removeFromParent();
31
42
  },
43
+ surfaceY: at.y,
32
44
  visual,
33
- };
45
+ } satisfies IPlatform;
34
46
  }
@@ -15,9 +15,12 @@ type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
15
15
  export function setupLighting(scene: Scene, renderer: ShadowRenderer): DirectionalLight {
16
16
  renderer.shadowMap.enabled = true;
17
17
  renderer.shadowMap.type = PCFSoftShadowMap;
18
- scene.add(new HemisphereLight(palette.skyHigh, palette.shadow, 1.4));
18
+ scene.add(new HemisphereLight(palette.skyLow, palette.ground, 0.5));
19
19
 
20
- const key = new DirectionalLight(palette.accent, 3.2);
20
+ // Warm white, not the accent. Keyed with a saturated yellow, the grass, the character and the
21
+ // stone all took the same cast and the palette collapsed towards one pale band — the same
22
+ // failure the fog note in `sky.ts` describes, arriving through the light instead.
23
+ const key = new DirectionalLight(0xfff2d8, 2.1);
21
24
  key.position.set(5, 8, 4);
22
25
  key.castShadow = true;
23
26
  // 1024² is one quarter of a 2048² map's texel storage and fill work. The
@@ -34,10 +37,10 @@ export function setupLighting(scene: Scene, renderer: ShadowRenderer): Direction
34
37
  key.shadow.normalBias = 0.04;
35
38
  scene.add(key);
36
39
 
37
- const rim = new DirectionalLight(palette.skyLow, 0.9);
40
+ const rim = new DirectionalLight(palette.skyLow, 0.45);
38
41
  rim.position.set(-5, 4, -7);
39
42
  scene.add(rim);
40
- scene.add(new AmbientLight(palette.shadow, 0.24));
43
+ scene.add(new AmbientLight(palette.skyLow, 0.42));
41
44
 
42
45
  return key;
43
46
  }
@@ -43,7 +43,11 @@ interface ILoadingHost {
43
43
  };
44
44
  readonly renderer: { compileAsync(scene: Scene, camera: Camera): Promise<void> };
45
45
  readonly scene: Scene;
46
- readonly startup: { readonly progress: number; whenReady(): Promise<void> };
46
+ readonly startup: {
47
+ readonly progress: number;
48
+ readonly warmup?: { readonly status: "complete" | "incomplete" | "unavailable" };
49
+ whenReady(): Promise<void>;
50
+ };
47
51
  readonly viewport?: {
48
52
  readonly safeArea: { height: number; width: number; x: number; y: number };
49
53
  };
@@ -238,7 +242,13 @@ export function createLoadingScreen(host: ILoadingHost): ILoadingController {
238
242
  };
239
243
 
240
244
  const updateProgress = (value: number): void => {
241
- progress = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
245
+ const bounded = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
246
+ // A missing or incomplete backend observation cannot prove that all first-use work is done.
247
+ // Keep the bar visibly indeterminate until readiness removes the cover; never turn unknown
248
+ // coverage into a false 100% claim.
249
+ const observationUnknown =
250
+ host.startup.warmup !== undefined && host.startup.warmup.status !== "complete";
251
+ progress = observationUnknown ? Math.min(0.9, bounded) : bounded;
242
252
  setFillUv(fill.geometry, progress, fillBaseU);
243
253
  status?.update(progress);
244
254
  layout();
@@ -6,7 +6,10 @@ export const palette = {
6
6
  ground: 0x55b935,
7
7
  character: 0xf29a38,
8
8
  accent: 0xffc83d,
9
- shadow: 0x241d1a,
9
+ // Stone and crates. At 0x241d1a these read as black holes in the frame — the key comes from
10
+ // behind and above, so every face the camera can see is the unlit one, and the ambient alone
11
+ // has to carry them.
12
+ shadow: 0x6b5744,
10
13
  } as const;
11
14
 
12
15
  const materialCache = new Map<number, MeshStandardMaterial>();
@@ -1,71 +1,46 @@
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.45,
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 24-unit shadow extent
38
- // `lighting.ts` lights — a bright outdoor route where GI mostly softens the shadow side of the blocks.
39
- ssgiRadius: 16,
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: 40,
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;
18
+ type ProfileGlobals = typeof globalThis & {
19
+ __THREENATIVE_PROFILE__?: { hostedSoftware?: unknown };
20
+ };
62
21
 
63
22
  export function setupPost(
64
23
  renderer: OutputRenderer,
65
24
  scene: Scene,
66
25
  camera: Camera,
67
- environment: { godraysLight?: DirectionalLight; mobile?: boolean } = {},
26
+ environment: {
27
+ godraysLight?: DirectionalLight;
28
+ mobile?: boolean;
29
+ /** Forces a tier, ignoring `mobile`. An unknown name throws rather than falling back. */
30
+ tier?: QualityTier;
31
+ } = {},
68
32
  ): void {
69
- const world = new WorldEnvironment(environment.mobile === true ? mobilePreset : desktopPreset);
33
+ // The native production collector explicitly marks a software-only hosted smoke run. This is
34
+ // a profile input, not a host fact: the normal desktop game remains high, while this run uses
35
+ // the existing low look so screenshot and lifecycle evidence can settle on a CPU adapter.
36
+ const hostedSoftware =
37
+ (globalThis as ProfileGlobals).__THREENATIVE_PROFILE__?.hostedSoftware === true;
38
+ const requestedTier: QualityTier | undefined =
39
+ environment.tier ?? (hostedSoftware ? "low" : undefined);
40
+ const tier = resolveQualityTier({ mobile: environment.mobile, tier: requestedTier });
41
+ const source =
42
+ environment.tier !== undefined ? "override" : hostedSoftware ? "hosted-software" : "platform";
43
+ console.info(`TN_QUALITY_TIER ${tier} mobile=${environment.mobile === true} source=${source}`);
44
+ const world = new WorldEnvironment(qualityPreset(tier));
70
45
  world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
71
46
  }