create-threenative 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (588) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +61 -2
  3. package/agent-docs/references/assertion-reference.md +819 -0
  4. package/agent-docs/references/capability-reference.md +4483 -0
  5. package/agent-docs/references/capture-the-frame.md +60 -0
  6. package/agent-docs/references/creating-creatures.md +215 -0
  7. package/agent-docs/references/ctx-cookbook.md +120 -0
  8. package/agent-docs/references/debug-surface.md +68 -0
  9. package/agent-docs/references/dream-loop.md +150 -0
  10. package/agent-docs/references/finding-assets.md +215 -0
  11. package/agent-docs/references/gameplay-recipes.md +54 -0
  12. package/agent-docs/references/menu-screens.md +69 -0
  13. package/agent-docs/references/mobile-memory-budget.md +87 -0
  14. package/agent-docs/references/sculpt-from-a-reference.md +40 -0
  15. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  16. package/agent-docs/references/visual-baseline.md +174 -0
  17. package/agent-docs/references/webview-ui.md +113 -0
  18. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  19. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  20. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  21. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  22. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  23. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  24. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  25. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  26. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  27. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  28. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  29. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  30. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  31. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  32. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  33. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  34. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  35. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  36. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  37. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  38. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  39. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  40. package/agent-files/.threenative/agents/builder.md +32 -0
  41. package/agent-files/.threenative/agents/verifier.md +31 -0
  42. package/agent-files/AGENT-ROLES.md +26 -0
  43. package/agent-files/scripts/reference.mjs +705 -0
  44. package/agent-files/scripts/visual-loop.mjs +382 -0
  45. package/capabilities.json +5292 -0
  46. package/dist/index.d.ts +224 -3
  47. package/dist/index.js +1972 -73
  48. package/dist/threenative.d.ts +9 -2
  49. package/dist/threenative.js +2570 -176
  50. package/package.json +55 -6
  51. package/template-assets/icon.png +0 -0
  52. package/template-assets/loading.ts +325 -0
  53. package/template-assets/patches/three@0.185.1.patch +522 -0
  54. package/template-assets/worldEnvironment.ts +758 -0
  55. package/templates/action-rpg/.codex/config.toml +19 -0
  56. package/templates/action-rpg/.cursor/mcp.json +32 -0
  57. package/templates/action-rpg/.gemini/settings.json +32 -0
  58. package/templates/action-rpg/.mcp.json +18 -2
  59. package/templates/action-rpg/.vscode/mcp.json +36 -0
  60. package/templates/action-rpg/.zed/settings.json +36 -0
  61. package/templates/action-rpg/AGENTS.md +84 -29
  62. package/templates/action-rpg/CLAUDE.md +84 -29
  63. package/templates/action-rpg/index.html +0 -1
  64. package/templates/action-rpg/opencode.json +41 -0
  65. package/templates/action-rpg/package.json +15 -11
  66. package/templates/action-rpg/playtests/combat.playtest.json +32 -9
  67. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  68. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  69. package/templates/action-rpg/playtests/performance.playtest.json +39 -0
  70. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  71. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  72. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  73. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  74. package/templates/action-rpg/src/conventions.ts +35 -0
  75. package/templates/action-rpg/src/entities/Enemy.ts +16 -7
  76. package/templates/action-rpg/src/entities/Player.ts +20 -3
  77. package/templates/action-rpg/src/game.ts +21 -0
  78. package/templates/action-rpg/src/render/camera.ts +7 -2
  79. package/templates/action-rpg/src/render/lighting.ts +11 -4
  80. package/templates/action-rpg/src/render/loading.ts +278 -43
  81. package/templates/action-rpg/src/render/materials.ts +11 -0
  82. package/templates/action-rpg/src/render/palette.ts +10 -3
  83. package/templates/action-rpg/src/render/postprocessing.ts +32 -16
  84. package/templates/action-rpg/src/render/quality.ts +170 -0
  85. package/templates/action-rpg/src/render/shapes.ts +185 -26
  86. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  87. package/templates/action-rpg/src/render/vfx.ts +257 -0
  88. package/templates/action-rpg/src/render/worldEnvironment.ts +758 -0
  89. package/templates/action-rpg/src/scenes/Play.ts +91 -24
  90. package/templates/action-rpg/src/state.ts +4 -0
  91. package/templates/action-rpg/src/style.css +65 -1
  92. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  93. package/templates/action-rpg/src/ui/App.tsx +9 -8
  94. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  95. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  96. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  97. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  98. package/templates/action-rpg/src/ui/main.tsx +14 -0
  99. package/templates/action-rpg/threenative.config.ts +28 -8
  100. package/templates/action-rpg/vite.config.ts +32 -2
  101. package/templates/defense/.codex/config.toml +19 -0
  102. package/templates/defense/.cursor/mcp.json +32 -0
  103. package/templates/defense/.gemini/settings.json +32 -0
  104. package/templates/defense/.mcp.json +18 -2
  105. package/templates/defense/.vscode/mcp.json +36 -0
  106. package/templates/defense/.zed/settings.json +36 -0
  107. package/templates/defense/AGENTS.md +81 -41
  108. package/templates/defense/CLAUDE.md +81 -41
  109. package/templates/defense/README.md +2 -1
  110. package/templates/defense/index.html +0 -1
  111. package/templates/defense/opencode.json +41 -0
  112. package/templates/defense/package.json +16 -12
  113. package/templates/defense/playtests/leak.playtest.json +9 -4
  114. package/templates/defense/playtests/performance.playtest.json +39 -0
  115. package/templates/defense/playtests/placement.playtest.json +5 -5
  116. package/templates/defense/playtests/pointer-placement.playtest.json +156 -0
  117. package/templates/defense/playtests/scan.playtest.json +4 -4
  118. package/templates/defense/playtests/survive.playtest.json +25 -6
  119. package/templates/defense/src/attackers/Attacker.ts +32 -16
  120. package/templates/defense/src/board/Route.ts +22 -8
  121. package/templates/defense/src/conventions.ts +18 -0
  122. package/templates/defense/src/entities/Player.ts +11 -3
  123. package/templates/defense/src/game.ts +25 -4
  124. package/templates/defense/src/physics.ts +9 -39
  125. package/templates/defense/src/placement/Buildable.ts +4 -4
  126. package/templates/defense/src/render/camera.ts +9 -3
  127. package/templates/defense/src/render/lighting.ts +6 -1
  128. package/templates/defense/src/render/loading.ts +274 -38
  129. package/templates/defense/src/render/materials.ts +9 -0
  130. package/templates/defense/src/render/palette.ts +12 -5
  131. package/templates/defense/src/render/postprocessing.ts +32 -12
  132. package/templates/defense/src/render/quality.ts +170 -0
  133. package/templates/defense/src/render/shapes.ts +180 -23
  134. package/templates/defense/src/render/sky.ts +2 -2
  135. package/templates/defense/src/render/worldEnvironment.ts +758 -0
  136. package/templates/defense/src/scenes/Boot.ts +2 -2
  137. package/templates/defense/src/scenes/Defense.ts +122 -56
  138. package/templates/defense/src/state.ts +6 -0
  139. package/templates/defense/src/style.css +65 -1
  140. package/templates/defense/src/towers/Tower.ts +11 -12
  141. package/templates/defense/src/towers/targeting.ts +1 -1
  142. package/templates/defense/src/ui/App.tsx +11 -6
  143. package/templates/defense/src/ui/GameUi.tsx +20 -0
  144. package/templates/defense/src/ui/Hud.tsx +6 -5
  145. package/templates/defense/src/ui/main.tsx +14 -0
  146. package/templates/defense/threenative.config.ts +28 -8
  147. package/templates/defense/vite.config.ts +34 -1
  148. package/templates/minimal/.codex/config.toml +19 -0
  149. package/templates/minimal/.cursor/mcp.json +32 -0
  150. package/templates/minimal/.gemini/settings.json +32 -0
  151. package/templates/minimal/.mcp.json +18 -2
  152. package/templates/minimal/.vscode/mcp.json +36 -0
  153. package/templates/minimal/.zed/settings.json +36 -0
  154. package/templates/minimal/AGENTS.md +78 -382
  155. package/templates/minimal/CLAUDE.md +78 -382
  156. package/templates/minimal/index.html +0 -1
  157. package/templates/minimal/opencode.json +41 -0
  158. package/templates/minimal/package.json +14 -11
  159. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  160. package/templates/minimal/playtests/play.playtest.json +18 -5
  161. package/templates/minimal/playtests/survives.playtest.json +48 -4
  162. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  163. package/templates/minimal/src/conventions.ts +18 -0
  164. package/templates/minimal/src/entities/Player.ts +39 -6
  165. package/templates/minimal/src/game.ts +1 -0
  166. package/templates/minimal/src/main.ts +14 -4
  167. package/templates/minimal/src/render/camera.ts +1 -1
  168. package/templates/minimal/src/render/hud.ts +24 -8
  169. package/templates/minimal/src/render/lighting.ts +23 -2
  170. package/templates/minimal/src/render/loading.ts +23 -103
  171. package/templates/minimal/src/render/materials.ts +7 -0
  172. package/templates/minimal/src/render/palette.ts +3 -3
  173. package/templates/minimal/src/render/postprocessing.ts +55 -16
  174. package/templates/minimal/src/render/quality.ts +162 -0
  175. package/templates/minimal/src/render/sky.ts +51 -32
  176. package/templates/minimal/src/render/touch-controls.ts +165 -0
  177. package/templates/minimal/src/render/worldEnvironment.ts +758 -0
  178. package/templates/minimal/src/scenes/Play.ts +128 -14
  179. package/templates/minimal/src/state.ts +8 -1
  180. package/templates/minimal/src/style.css +20 -0
  181. package/templates/minimal/threenative.config.ts +22 -10
  182. package/templates/minimal/vite.config.ts +28 -1
  183. package/templates/platformer/.codex/config.toml +19 -0
  184. package/templates/platformer/.cursor/mcp.json +32 -0
  185. package/templates/platformer/.gemini/settings.json +32 -0
  186. package/templates/platformer/.mcp.json +18 -2
  187. package/templates/platformer/.vscode/mcp.json +36 -0
  188. package/templates/platformer/.zed/settings.json +36 -0
  189. package/templates/platformer/AGENTS.md +81 -186
  190. package/templates/platformer/CLAUDE.md +81 -186
  191. package/templates/platformer/index.html +0 -1
  192. package/templates/platformer/opencode.json +41 -0
  193. package/templates/platformer/package.json +17 -14
  194. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  195. package/templates/platformer/playtests/branding.playtest.json +29 -0
  196. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  197. package/templates/platformer/playtests/collect.playtest.json +1 -1
  198. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  199. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  200. package/templates/platformer/playtests/damage.playtest.json +4 -1
  201. package/templates/platformer/playtests/dash.playtest.json +2 -2
  202. package/templates/platformer/playtests/jump.playtest.json +2 -3
  203. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  204. package/templates/platformer/playtests/oneway.playtest.json +30 -3
  205. package/templates/platformer/playtests/performance.playtest.json +7 -5
  206. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  207. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  208. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  209. package/templates/platformer/playtests/survives.playtest.json +31 -0
  210. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +16 -4
  211. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  212. package/templates/platformer/playtests/touch-controls-web.playtest.json +57 -0
  213. package/templates/platformer/src/conventions.ts +18 -0
  214. package/templates/platformer/src/entities/Character.ts +79 -11
  215. package/templates/platformer/src/entities/Patrol.ts +5 -0
  216. package/templates/platformer/src/game.ts +27 -2
  217. package/templates/platformer/src/level/Platform.ts +13 -1
  218. package/templates/platformer/src/render/lighting.ts +13 -5
  219. package/templates/platformer/src/render/loading.ts +281 -62
  220. package/templates/platformer/src/render/palette.ts +4 -1
  221. package/templates/platformer/src/render/postprocessing.ts +42 -14
  222. package/templates/platformer/src/render/quality.ts +170 -0
  223. package/templates/platformer/src/render/touch-controls.ts +54 -36
  224. package/templates/platformer/src/render/worldEnvironment.ts +758 -0
  225. package/templates/platformer/src/scenes/Level.ts +97 -32
  226. package/templates/platformer/src/state.ts +4 -0
  227. package/templates/platformer/src/style.css +65 -1
  228. package/templates/platformer/src/ui/App.tsx +9 -4
  229. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  230. package/templates/platformer/src/ui/Hud.tsx +6 -5
  231. package/templates/platformer/src/ui/main.tsx +14 -0
  232. package/templates/platformer/threenative.config.ts +27 -10
  233. package/templates/platformer/vite.config.ts +34 -1
  234. package/templates/puzzle/.codex/config.toml +19 -0
  235. package/templates/puzzle/.cursor/mcp.json +32 -0
  236. package/templates/puzzle/.gemini/settings.json +32 -0
  237. package/templates/puzzle/.mcp.json +32 -0
  238. package/templates/puzzle/.vscode/mcp.json +36 -0
  239. package/templates/puzzle/.zed/settings.json +36 -0
  240. package/templates/puzzle/AGENTS.md +96 -0
  241. package/templates/puzzle/CLAUDE.md +98 -0
  242. package/templates/puzzle/README.md +43 -0
  243. package/templates/puzzle/index.html +12 -0
  244. package/templates/puzzle/kit.json +7 -0
  245. package/templates/puzzle/opencode.json +41 -0
  246. package/templates/puzzle/package.json +50 -0
  247. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  248. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  249. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  250. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  251. package/templates/puzzle/public/favicon.svg +5 -0
  252. package/templates/puzzle/src/conventions.ts +25 -0
  253. package/templates/puzzle/src/entities/Ball.ts +70 -0
  254. package/templates/puzzle/src/entities/Crate.ts +76 -0
  255. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  256. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  257. package/templates/puzzle/src/game.ts +48 -0
  258. package/templates/puzzle/src/main.ts +15 -0
  259. package/templates/puzzle/src/physics.ts +19 -0
  260. package/templates/puzzle/src/render/camera.ts +37 -0
  261. package/templates/puzzle/src/render/lighting.ts +55 -0
  262. package/templates/puzzle/src/render/loading.ts +325 -0
  263. package/templates/puzzle/src/render/materials.ts +28 -0
  264. package/templates/puzzle/src/render/palette.ts +31 -0
  265. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  266. package/templates/puzzle/src/render/quality.ts +170 -0
  267. package/templates/puzzle/src/render/shapes.ts +134 -0
  268. package/templates/puzzle/src/render/sky.ts +16 -0
  269. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  270. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  271. package/templates/puzzle/src/room.ts +83 -0
  272. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  273. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  274. package/templates/puzzle/src/state.ts +30 -0
  275. package/templates/puzzle/src/style.css +96 -0
  276. package/templates/puzzle/src/ui/App.tsx +22 -0
  277. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  278. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  279. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  280. package/templates/puzzle/src/ui/main.tsx +14 -0
  281. package/templates/puzzle/tailwind.config.ts +1 -0
  282. package/templates/puzzle/threenative.config.ts +49 -0
  283. package/templates/puzzle/tsconfig.json +17 -0
  284. package/templates/puzzle/vite.config.ts +38 -0
  285. package/templates/racing/.codex/config.toml +19 -0
  286. package/templates/racing/.cursor/mcp.json +32 -0
  287. package/templates/racing/.gemini/settings.json +32 -0
  288. package/templates/racing/.mcp.json +18 -2
  289. package/templates/racing/.vscode/mcp.json +36 -0
  290. package/templates/racing/.zed/settings.json +36 -0
  291. package/templates/racing/AGENTS.md +84 -36
  292. package/templates/racing/CLAUDE.md +84 -36
  293. package/templates/racing/index.html +0 -1
  294. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  295. package/templates/racing/opencode.json +41 -0
  296. package/templates/racing/package.json +17 -12
  297. package/templates/racing/playtests/boost.playtest.json +5 -5
  298. package/templates/racing/playtests/outcome.playtest.json +14 -4
  299. package/templates/racing/playtests/performance.playtest.json +39 -0
  300. package/templates/racing/playtests/ranking.playtest.json +2 -2
  301. package/templates/racing/playtests/rescue.playtest.json +12 -6
  302. package/templates/racing/playtests/reverse.playtest.json +3 -3
  303. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  304. package/templates/racing/playtests/survives.playtest.json +36 -4
  305. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  306. package/templates/racing/src/conventions.ts +6 -0
  307. package/templates/racing/src/entities/RacingCar.ts +16 -4
  308. package/templates/racing/src/entities/Rival.ts +5 -2
  309. package/templates/racing/src/game.ts +24 -1
  310. package/templates/racing/src/render/camera.ts +15 -8
  311. package/templates/racing/src/render/lighting.ts +28 -14
  312. package/templates/racing/src/render/loading.ts +302 -35
  313. package/templates/racing/src/render/materials.ts +54 -4
  314. package/templates/racing/src/render/palette.ts +23 -6
  315. package/templates/racing/src/render/postprocessing.ts +32 -12
  316. package/templates/racing/src/render/quality.ts +170 -0
  317. package/templates/racing/src/render/shapes.ts +537 -26
  318. package/templates/racing/src/render/sky.ts +5 -2
  319. package/templates/racing/src/render/touch-controls.ts +185 -0
  320. package/templates/racing/src/render/worldEnvironment.ts +758 -0
  321. package/templates/racing/src/scenes/Race.ts +84 -37
  322. package/templates/racing/src/state.ts +4 -0
  323. package/templates/racing/src/style.css +65 -1
  324. package/templates/racing/src/track/Lap.ts +20 -9
  325. package/templates/racing/src/track/Ranking.ts +53 -14
  326. package/templates/racing/src/track/Track.ts +284 -32
  327. package/templates/racing/src/track/TrackSector.ts +14 -4
  328. package/templates/racing/src/ui/App.tsx +9 -4
  329. package/templates/racing/src/ui/GameUi.tsx +20 -0
  330. package/templates/racing/src/ui/Hud.tsx +6 -5
  331. package/templates/racing/src/ui/main.tsx +14 -0
  332. package/templates/racing/threenative.config.ts +28 -8
  333. package/templates/racing/vite.config.ts +34 -1
  334. package/templates/runner/.codex/config.toml +19 -0
  335. package/templates/runner/.cursor/mcp.json +32 -0
  336. package/templates/runner/.gemini/settings.json +32 -0
  337. package/templates/runner/.mcp.json +32 -0
  338. package/templates/runner/.vscode/mcp.json +36 -0
  339. package/templates/runner/.zed/settings.json +36 -0
  340. package/templates/runner/AGENTS.md +96 -0
  341. package/templates/runner/CLAUDE.md +98 -0
  342. package/templates/runner/README.md +43 -0
  343. package/templates/runner/index.html +12 -0
  344. package/templates/runner/kit.json +7 -0
  345. package/templates/runner/opencode.json +41 -0
  346. package/templates/runner/package.json +50 -0
  347. package/templates/runner/playtests/performance.playtest.json +23 -0
  348. package/templates/runner/playtests/streams.playtest.json +38 -0
  349. package/templates/runner/playtests/survives.playtest.json +51 -0
  350. package/templates/runner/public/favicon.svg +5 -0
  351. package/templates/runner/src/conventions.ts +24 -0
  352. package/templates/runner/src/entities/Runner.ts +135 -0
  353. package/templates/runner/src/game.ts +50 -0
  354. package/templates/runner/src/main.ts +15 -0
  355. package/templates/runner/src/physics.ts +13 -0
  356. package/templates/runner/src/render/camera.ts +39 -0
  357. package/templates/runner/src/render/dust.ts +131 -0
  358. package/templates/runner/src/render/lighting.ts +57 -0
  359. package/templates/runner/src/render/loading.ts +325 -0
  360. package/templates/runner/src/render/materials.ts +27 -0
  361. package/templates/runner/src/render/palette.ts +30 -0
  362. package/templates/runner/src/render/postprocessing.ts +34 -0
  363. package/templates/runner/src/render/quality.ts +170 -0
  364. package/templates/runner/src/render/shapes.ts +68 -0
  365. package/templates/runner/src/render/sky.ts +51 -0
  366. package/templates/runner/src/render/touch-controls.ts +185 -0
  367. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  368. package/templates/runner/src/scenes/Boot.ts +12 -0
  369. package/templates/runner/src/scenes/Run.ts +142 -0
  370. package/templates/runner/src/state.ts +29 -0
  371. package/templates/runner/src/style.css +96 -0
  372. package/templates/runner/src/track.ts +176 -0
  373. package/templates/runner/src/ui/App.tsx +22 -0
  374. package/templates/runner/src/ui/GameUi.tsx +20 -0
  375. package/templates/runner/src/ui/Hud.tsx +55 -0
  376. package/templates/runner/src/ui/Menu.tsx +7 -0
  377. package/templates/runner/src/ui/main.tsx +14 -0
  378. package/templates/runner/tailwind.config.ts +1 -0
  379. package/templates/runner/threenative.config.ts +49 -0
  380. package/templates/runner/tsconfig.json +17 -0
  381. package/templates/runner/vite.config.ts +38 -0
  382. package/templates/sailing/.codex/config.toml +19 -0
  383. package/templates/sailing/.cursor/mcp.json +32 -0
  384. package/templates/sailing/.gemini/settings.json +32 -0
  385. package/templates/sailing/.mcp.json +32 -0
  386. package/templates/sailing/.vscode/mcp.json +36 -0
  387. package/templates/sailing/.zed/settings.json +36 -0
  388. package/templates/sailing/AGENTS.md +95 -0
  389. package/templates/sailing/CLAUDE.md +97 -0
  390. package/templates/sailing/README.md +28 -0
  391. package/templates/sailing/index.html +12 -0
  392. package/templates/sailing/kit.json +7 -0
  393. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  394. package/templates/sailing/native-playtests/survives.playtest.json +38 -0
  395. package/templates/sailing/opencode.json +41 -0
  396. package/templates/sailing/package.json +52 -0
  397. package/templates/sailing/playtests/fail.playtest.json +24 -0
  398. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  399. package/templates/sailing/playtests/float.playtest.json +59 -0
  400. package/templates/sailing/playtests/performance.playtest.json +36 -0
  401. package/templates/sailing/playtests/survives.playtest.json +46 -0
  402. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  403. package/templates/sailing/playtests/win.playtest.json +31 -0
  404. package/templates/sailing/public/favicon.svg +5 -0
  405. package/templates/sailing/src/conventions.ts +8 -0
  406. package/templates/sailing/src/entities/Ship.ts +233 -0
  407. package/templates/sailing/src/game.ts +40 -0
  408. package/templates/sailing/src/main.ts +15 -0
  409. package/templates/sailing/src/render/camera.ts +28 -0
  410. package/templates/sailing/src/render/lighting.ts +41 -0
  411. package/templates/sailing/src/render/loading.ts +325 -0
  412. package/templates/sailing/src/render/materials.ts +44 -0
  413. package/templates/sailing/src/render/ocean.ts +179 -0
  414. package/templates/sailing/src/render/palette.ts +17 -0
  415. package/templates/sailing/src/render/postprocessing.ts +34 -0
  416. package/templates/sailing/src/render/props.ts +602 -0
  417. package/templates/sailing/src/render/quality.ts +140 -0
  418. package/templates/sailing/src/render/sky.ts +37 -0
  419. package/templates/sailing/src/render/touch-controls.ts +142 -0
  420. package/templates/sailing/src/render/worldEnvironment.ts +758 -0
  421. package/templates/sailing/src/scenes/Boot.ts +12 -0
  422. package/templates/sailing/src/scenes/Sailing.ts +133 -0
  423. package/templates/sailing/src/state.ts +10 -0
  424. package/templates/sailing/src/style.css +81 -0
  425. package/templates/sailing/src/ui/App.tsx +15 -0
  426. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  427. package/templates/sailing/src/ui/Hud.tsx +55 -0
  428. package/templates/sailing/src/ui/Menu.tsx +30 -0
  429. package/templates/sailing/src/ui/main.tsx +7 -0
  430. package/templates/sailing/tailwind.config.ts +2 -0
  431. package/templates/sailing/threenative.config.ts +40 -0
  432. package/templates/sailing/tsconfig.json +17 -0
  433. package/templates/sailing/vite.config.ts +34 -0
  434. package/templates/shooter/.codex/config.toml +19 -0
  435. package/templates/shooter/.cursor/mcp.json +32 -0
  436. package/templates/shooter/.gemini/settings.json +32 -0
  437. package/templates/shooter/.mcp.json +18 -2
  438. package/templates/shooter/.vscode/mcp.json +36 -0
  439. package/templates/shooter/.zed/settings.json +36 -0
  440. package/templates/shooter/AGENTS.md +81 -54
  441. package/templates/shooter/CLAUDE.md +81 -54
  442. package/templates/shooter/index.html +0 -1
  443. package/templates/shooter/kit.json +2 -2
  444. package/templates/shooter/opencode.json +41 -0
  445. package/templates/shooter/package.json +16 -11
  446. package/templates/shooter/playtests/combat.playtest.json +48 -0
  447. package/templates/shooter/playtests/fail.playtest.json +5 -4
  448. package/templates/shooter/playtests/input-control.playtest.json +261 -0
  449. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  450. package/templates/shooter/playtests/performance.playtest.json +39 -0
  451. package/templates/shooter/playtests/shooter.playtest.json +31 -21
  452. package/templates/shooter/playtests/survives.playtest.json +28 -1
  453. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  454. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  455. package/templates/shooter/public/favicon.svg +1 -1
  456. package/templates/shooter/src/combat/damage.ts +1 -2
  457. package/templates/shooter/src/conventions.ts +51 -0
  458. package/templates/shooter/src/entities/Player.ts +235 -18
  459. package/templates/shooter/src/entities/Target.ts +2 -2
  460. package/templates/shooter/src/game.ts +35 -3
  461. package/templates/shooter/src/main.ts +3 -13
  462. package/templates/shooter/src/render/camera.ts +78 -18
  463. package/templates/shooter/src/render/decals.ts +211 -0
  464. package/templates/shooter/src/render/lighting.ts +13 -4
  465. package/templates/shooter/src/render/loading.ts +274 -35
  466. package/templates/shooter/src/render/materials.ts +56 -3
  467. package/templates/shooter/src/render/palette.ts +6 -3
  468. package/templates/shooter/src/render/postprocessing.ts +32 -17
  469. package/templates/shooter/src/render/quality.ts +170 -0
  470. package/templates/shooter/src/render/scale.ts +22 -0
  471. package/templates/shooter/src/render/shapes.ts +519 -60
  472. package/templates/shooter/src/render/sky.ts +5 -1
  473. package/templates/shooter/src/render/touch-controls.ts +305 -0
  474. package/templates/shooter/src/render/ui.css +119 -1
  475. package/templates/shooter/src/render/ui.ts +19 -3
  476. package/templates/shooter/src/render/vfx.ts +215 -0
  477. package/templates/shooter/src/render/worldEnvironment.ts +758 -0
  478. package/templates/shooter/src/scenes/Play.ts +385 -97
  479. package/templates/shooter/src/state.ts +18 -0
  480. package/templates/shooter/src/style.css +46 -0
  481. package/templates/shooter/src/ui/App.tsx +10 -12
  482. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  483. package/templates/shooter/src/ui/GameUi.tsx +22 -0
  484. package/templates/shooter/src/ui/Hud.tsx +14 -10
  485. package/templates/shooter/src/ui/Menu.tsx +24 -9
  486. package/templates/shooter/src/ui/main.tsx +15 -0
  487. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  488. package/templates/shooter/src/weapons/Projectile.ts +29 -13
  489. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  490. package/templates/shooter/threenative.config.ts +28 -8
  491. package/templates/shooter/vite.config.ts +32 -2
  492. package/templates/starter/.codex/config.toml +19 -0
  493. package/templates/starter/.cursor/mcp.json +32 -0
  494. package/templates/starter/.gemini/settings.json +32 -0
  495. package/templates/starter/.mcp.json +18 -2
  496. package/templates/starter/.vscode/mcp.json +36 -0
  497. package/templates/starter/.zed/settings.json +36 -0
  498. package/templates/starter/AGENTS.md +72 -426
  499. package/templates/starter/CLAUDE.md +72 -426
  500. package/templates/starter/assets/pickup.wav +0 -0
  501. package/templates/starter/gitignore +4 -0
  502. package/templates/starter/index.html +0 -1
  503. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  504. package/templates/starter/native-playtests/render-chain.playtest.json +81 -0
  505. package/templates/starter/opencode.json +41 -0
  506. package/templates/starter/package.json +16 -12
  507. package/templates/starter/playtests/assets.playtest.json +65 -0
  508. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  509. package/templates/starter/playtests/buffer.playtest.json +59 -9
  510. package/templates/starter/playtests/cloth.playtest.json +113 -0
  511. package/templates/starter/playtests/coyote.playtest.json +60 -8
  512. package/templates/starter/playtests/forward.playtest.json +29 -4
  513. package/templates/starter/playtests/gameover.playtest.json +66 -0
  514. package/templates/starter/playtests/goal.playtest.json +67 -0
  515. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  516. package/templates/starter/playtests/look.playtest.json +142 -10
  517. package/templates/starter/playtests/models-baseline.png +0 -0
  518. package/templates/starter/playtests/models.playtest.json +74 -0
  519. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  520. package/templates/starter/playtests/odometer.playtest.json +54 -0
  521. package/templates/starter/playtests/pause.playtest.json +27 -4
  522. package/templates/starter/playtests/play.playtest.json +44 -7
  523. package/templates/starter/playtests/respawn.playtest.json +46 -6
  524. package/templates/starter/playtests/restart.playtest.json +65 -10
  525. package/templates/starter/playtests/seed.playtest.json +44 -8
  526. package/templates/starter/playtests/survives.playtest.json +48 -4
  527. package/templates/starter/playtests/textures-baseline.png +0 -0
  528. package/templates/starter/playtests/textures.playtest.json +74 -0
  529. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  530. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  531. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  532. package/templates/starter/src/conventions.ts +18 -0
  533. package/templates/starter/src/entities/Goal.ts +137 -0
  534. package/templates/starter/src/entities/Player.ts +111 -10
  535. package/templates/starter/src/game.ts +27 -0
  536. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  537. package/templates/starter/src/render/camera.ts +31 -5
  538. package/templates/starter/src/render/coast.ts +199 -0
  539. package/templates/starter/src/render/easing.ts +5 -0
  540. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  541. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  542. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  543. package/templates/starter/src/render/hero.ts +88 -0
  544. package/templates/starter/src/render/implicitSurface.ts +199 -0
  545. package/templates/starter/src/render/kuwahara.ts +174 -0
  546. package/templates/starter/src/render/lighting.ts +10 -5
  547. package/templates/starter/src/render/loading.ts +325 -0
  548. package/templates/starter/src/render/materials.ts +39 -4
  549. package/templates/starter/src/render/outline.ts +141 -0
  550. package/templates/starter/src/render/painterly.ts +86 -0
  551. package/templates/starter/src/render/palette.ts +15 -6
  552. package/templates/starter/src/render/pennant.ts +54 -0
  553. package/templates/starter/src/render/postprocessing.ts +97 -15
  554. package/templates/starter/src/render/quality.ts +185 -0
  555. package/templates/starter/src/render/rockRidge.ts +198 -0
  556. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  557. package/templates/starter/src/render/scenery.ts +40 -0
  558. package/templates/starter/src/render/shapes.ts +9 -21
  559. package/templates/starter/src/render/textureLifetime.ts +53 -0
  560. package/templates/starter/src/render/touch-controls.ts +165 -0
  561. package/templates/starter/src/render/water.ts +38 -0
  562. package/templates/starter/src/render/watercolor.ts +85 -0
  563. package/templates/starter/src/render/worldEnvironment.ts +758 -0
  564. package/templates/starter/src/scenes/Play.ts +243 -46
  565. package/templates/starter/src/state.ts +12 -0
  566. package/templates/starter/src/style.css +72 -8
  567. package/templates/starter/src/ui/App.tsx +9 -6
  568. package/templates/starter/src/ui/GameUi.tsx +20 -0
  569. package/templates/starter/src/ui/Hud.tsx +52 -29
  570. package/templates/starter/src/ui/Menu.tsx +25 -23
  571. package/templates/starter/src/ui/main.tsx +14 -0
  572. package/templates/starter/threenative.config.ts +27 -9
  573. package/templates/starter/tools/look.mjs +109 -0
  574. package/templates/starter/vite.config.ts +32 -2
  575. package/templates/action-rpg/src/physics.ts +0 -40
  576. package/templates/minimal/assets/.gitkeep +0 -0
  577. package/templates/minimal/public/.gitkeep +0 -0
  578. package/templates/minimal/public/icon.png +0 -0
  579. package/templates/platformer/assets/.gitkeep +0 -0
  580. package/templates/platformer/public/.gitkeep +0 -0
  581. package/templates/platformer/public/icon.png +0 -0
  582. package/templates/shooter/src/physics.ts +0 -49
  583. package/templates/starter/assets/.gitkeep +0 -0
  584. package/templates/starter/public/.gitkeep +0 -0
  585. package/templates/starter/public/icon.png +0 -0
  586. package/templates/starter/public/pickup.ogg +0 -0
  587. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  588. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -1,82 +1,299 @@
1
1
  import {
2
2
  type Camera,
3
+ CanvasTexture,
4
+ ClampToEdgeWrapping,
3
5
  Mesh,
4
6
  MeshBasicMaterial,
5
7
  type OrthographicCamera,
6
8
  PlaneGeometry,
7
9
  type Scene,
10
+ type Texture,
8
11
  } from "three";
9
12
  import { palette } from "./palette.js";
10
13
 
11
- /**
12
- * What the framework hands a loading screen. Structural on purpose: nothing under `src/render/`
13
- * imports the framework, and `ctx` already satisfies this shape.
14
- */
15
- export interface LoadingHost {
14
+ /* BEGIN THREENATIVE LOADING APPEARANCE */
15
+ /** The five authoring points for this screen stay in this generated file. */
16
+ export const loading = {
17
+ backgroundColor: palette.skyLow,
18
+ backgroundImage: undefined as string | undefined,
19
+ enabled: true,
20
+ fillImage: undefined as string | undefined,
21
+ logoImage: undefined as string | undefined,
22
+ progressColor: palette.accent,
23
+ showStatus: false,
24
+ trackColor: palette.skyHigh,
25
+ bar: {
26
+ anchorX: 0.5,
27
+ anchorY: 0.72,
28
+ height: 12,
29
+ maxWidth: 1200,
30
+ minWidth: 2,
31
+ width: 0.62,
32
+ },
33
+ } as const;
34
+ /* END THREENATIVE LOADING APPEARANCE */
35
+
36
+ interface ILoadingHost {
37
+ readonly assets?: { texture(path: string): Promise<Texture> };
16
38
  readonly camera: Camera;
17
- readonly scene: Scene;
18
39
  readonly canvasLayer: {
19
40
  readonly camera: OrthographicCamera;
20
41
  readonly scene: Scene;
21
42
  opaque: boolean;
22
43
  };
23
44
  readonly renderer: { compileAsync(scene: Scene, camera: Camera): Promise<void> };
24
- readonly startup: { readonly progress: number; whenReady(): Promise<void> };
45
+ readonly scene: Scene;
46
+ readonly startup: {
47
+ readonly progress: number;
48
+ readonly warmup?: { readonly status: "complete" | "incomplete" | "unavailable" };
49
+ whenReady(): Promise<void>;
50
+ };
51
+ readonly viewport?: {
52
+ readonly safeArea: { height: number; width: number; x: number; y: number };
53
+ };
25
54
  }
26
55
 
27
- /**
28
- * Draws the loading screen in the framework's pixel-sized canvas layer. Colours, layout, and the
29
- * shape of the bar live here in generated source, so they remain the game's to change or delete.
30
- */
31
- export function createLoadingScreen(host: LoadingHost) {
32
- const layer = host.canvasLayer;
33
- const camera = layer.camera;
34
- const cover = (color: number, renderOrder: number) => {
35
- const mesh = new Mesh(
36
- new PlaneGeometry(1, 1),
37
- new MeshBasicMaterial({ color, depthTest: false, depthWrite: false }),
38
- );
39
- mesh.frustumCulled = false;
40
- mesh.renderOrder = renderOrder;
41
- layer.scene.add(mesh);
42
- return mesh;
56
+ interface ILoadingController {
57
+ update(): void;
58
+ finish(): void;
59
+ }
60
+
61
+ function noOp(layer: ILoadingHost["canvasLayer"]): ILoadingController {
62
+ layer.opaque = false;
63
+ return { finish: () => undefined, update: () => undefined };
64
+ }
65
+
66
+ function meshFor(
67
+ layer: ILoadingHost["canvasLayer"],
68
+ material: MeshBasicMaterial,
69
+ renderOrder: number,
70
+ ): Mesh<PlaneGeometry, MeshBasicMaterial> {
71
+ const mesh = new Mesh(new PlaneGeometry(1, 1), material);
72
+ mesh.frustumCulled = false;
73
+ mesh.renderOrder = renderOrder;
74
+ layer.scene.add(mesh);
75
+ return mesh;
76
+ }
77
+
78
+ function imageAspect(texture: Texture | null | undefined): number {
79
+ const image = texture?.image as { height?: number; width?: number } | undefined;
80
+ const width = image?.width ?? 1;
81
+ const height = image?.height ?? 1;
82
+ return width > 0 && height > 0 ? width / height : 1;
83
+ }
84
+
85
+ function configureTexture(texture: Texture): void {
86
+ texture.wrapS = ClampToEdgeWrapping;
87
+ texture.wrapT = ClampToEdgeWrapping;
88
+ texture.needsUpdate = true;
89
+ }
90
+
91
+ function setFillUv(geometry: PlaneGeometry, progress: number, base: readonly number[]): void {
92
+ const uv = geometry.getAttribute("uv");
93
+ for (let index = 0; index < uv.count; index += 1) uv.setX(index, (base[index] ?? 0) * progress);
94
+ uv.needsUpdate = true;
95
+ }
96
+
97
+ function coverUv(
98
+ geometry: PlaneGeometry,
99
+ texture: Texture,
100
+ width: number,
101
+ height: number,
102
+ baseU: readonly number[],
103
+ baseV: readonly number[],
104
+ ): void {
105
+ const imageRatio = imageAspect(texture);
106
+ const boxRatio = width / Math.max(1, height);
107
+ const visibleU = imageRatio > boxRatio ? boxRatio / imageRatio : 1;
108
+ const visibleV = imageRatio < boxRatio ? imageRatio / boxRatio : 1;
109
+ const offsetU = (1 - visibleU) / 2;
110
+ const offsetV = (1 - visibleV) / 2;
111
+ const uv = geometry.getAttribute("uv");
112
+ for (let index = 0; index < uv.count; index += 1) {
113
+ uv.setX(index, offsetU + (baseU[index] ?? 0) * visibleU);
114
+ uv.setY(index, offsetV + (baseV[index] ?? 0) * visibleV);
115
+ }
116
+ uv.needsUpdate = true;
117
+ }
118
+
119
+ function statusMesh(
120
+ layer: ILoadingHost["canvasLayer"],
121
+ ):
122
+ | { mesh: Mesh<PlaneGeometry, MeshBasicMaterial>; texture: Texture; update(value: number): void }
123
+ | undefined {
124
+ if (!loading.showStatus || typeof document === "undefined") return undefined;
125
+ const canvas = document.createElement("canvas");
126
+ canvas.width = 180;
127
+ canvas.height = 48;
128
+ const context = canvas.getContext("2d");
129
+ if (context === null) return undefined;
130
+ const texture = new CanvasTexture(canvas);
131
+ const mesh = meshFor(
132
+ layer,
133
+ new MeshBasicMaterial({ depthTest: false, depthWrite: false, map: texture, transparent: true }),
134
+ 4,
135
+ );
136
+ const update = (value: number): void => {
137
+ context.clearRect(0, 0, canvas.width, canvas.height);
138
+ context.fillStyle = "#ffffff";
139
+ context.font = "700 20px monospace";
140
+ context.textAlign = "center";
141
+ context.textBaseline = "middle";
142
+ context.fillText(`${Math.round(value * 100)}%`, canvas.width / 2, canvas.height / 2);
143
+ texture.needsUpdate = true;
43
144
  };
44
- const backdrop = cover(palette.skyLow, 0);
45
- const track = cover(palette.skyHigh, 1);
46
- const fill = cover(palette.accent, 2);
47
- const parts = [backdrop, track, fill];
48
- layer.opaque = true;
145
+ update(0);
146
+ return { mesh, texture, update };
147
+ }
49
148
 
50
- let width = 0;
51
- let height = 0;
52
- let lastProgress = 0;
149
+ export function createLoadingScreen(host: ILoadingHost): ILoadingController {
150
+ const layer = host.canvasLayer;
151
+ if (!loading.enabled) return noOp(layer);
152
+ const camera = layer.camera;
153
+ const backdrop = meshFor(
154
+ layer,
155
+ new MeshBasicMaterial({ color: loading.backgroundColor, depthTest: false, depthWrite: false }),
156
+ 0,
157
+ );
158
+ const track = meshFor(
159
+ layer,
160
+ new MeshBasicMaterial({ color: loading.trackColor, depthTest: false, depthWrite: false }),
161
+ 1,
162
+ );
163
+ const fill = meshFor(
164
+ layer,
165
+ new MeshBasicMaterial({ color: loading.progressColor, depthTest: false, depthWrite: false }),
166
+ 2,
167
+ );
168
+ const fillBaseU = Array.from({ length: fill.geometry.getAttribute("uv").count }, (_, index) =>
169
+ fill.geometry.getAttribute("uv").getX(index),
170
+ );
171
+ const fillBaseV = Array.from({ length: fill.geometry.getAttribute("uv").count }, (_, index) =>
172
+ fill.geometry.getAttribute("uv").getY(index),
173
+ );
174
+ const logo =
175
+ loading.logoImage === undefined
176
+ ? undefined
177
+ : meshFor(
178
+ layer,
179
+ new MeshBasicMaterial({
180
+ color: 0xffffff,
181
+ depthTest: false,
182
+ depthWrite: false,
183
+ transparent: true,
184
+ }),
185
+ 3,
186
+ );
187
+ const status = statusMesh(layer);
188
+ const parts = [
189
+ backdrop,
190
+ track,
191
+ fill,
192
+ ...(logo === undefined ? [] : [logo]),
193
+ ...(status === undefined ? [] : [status.mesh]),
194
+ ];
195
+ const ownedTextures = new Set<Texture>(status === undefined ? [] : [status.texture]);
196
+ let width = 1;
197
+ let height = 1;
198
+ let barWidth = 1;
199
+ let barHeight: number = loading.bar.height;
200
+ let barX = 0;
201
+ let barY = 0;
202
+ let progress = 0;
203
+ let done = false;
204
+ let backdropTexture: Texture | undefined;
53
205
 
54
206
  const layout = (): void => {
55
- const nextWidth = camera.right - camera.left;
56
- const nextHeight = camera.top - camera.bottom;
57
- width = Number.isFinite(nextWidth) && nextWidth > 0 ? nextWidth : 1;
58
- height = Number.isFinite(nextHeight) && nextHeight > 0 ? nextHeight : 1;
207
+ width = Math.max(1, camera.right - camera.left);
208
+ height = Math.max(1, camera.top - camera.bottom);
209
+ const safe = host.viewport?.safeArea ?? { height, width, x: 0, y: 0 };
210
+ const safeWidth = Math.max(1, Math.min(width, safe.width));
211
+ const safeHeight = Math.max(1, Math.min(height, safe.height));
212
+ const safeX = Math.max(0, Math.min(width - safeWidth, safe.x));
213
+ const safeY = Math.max(0, Math.min(height - safeHeight, safe.y));
214
+ barWidth = Math.max(2, Math.min(loading.bar.maxWidth, safeWidth * loading.bar.width));
215
+ barHeight = Math.max(2, Math.min(loading.bar.height, safeHeight * 0.05));
216
+ barX = safeX + safeWidth * loading.bar.anchorX;
217
+ barY = safeY + safeHeight * loading.bar.anchorY;
218
+ const worldX = (screenX: number): number => camera.left + screenX;
219
+ const worldY = (screenY: number): number => camera.top - screenY;
220
+ const visibleWidth = Math.max(loading.bar.minWidth, barWidth * progress);
59
221
  backdrop.scale.set(width, height, 1);
60
- track.scale.set(width * 0.5, height * 0.012, 1);
61
- track.position.set(0, -height * 0.05, 0);
62
- fill.position.set(0, -height * 0.05, 0);
222
+ backdrop.position.set(worldX(width / 2), worldY(height / 2), 0);
223
+ track.scale.set(barWidth, barHeight, 1);
224
+ track.position.set(worldX(barX), worldY(barY), 0);
225
+ fill.scale.set(visibleWidth, barHeight, 1);
226
+ fill.position.set(worldX(barX - barWidth / 2 + visibleWidth / 2), worldY(barY), 0);
227
+ if (logo?.visible) {
228
+ const logoWidth = Math.min(safeWidth * 0.42, 280);
229
+ logo.scale.set(
230
+ logoWidth,
231
+ Math.min(logoWidth / imageAspect(logo.material.map), safeHeight * 0.22),
232
+ 1,
233
+ );
234
+ logo.position.set(worldX(barX), worldY(Math.max(safeY, barY - safeHeight * 0.2)), 0);
235
+ }
236
+ if (status !== undefined) {
237
+ status.mesh.scale.set(Math.min(180, safeWidth * 0.32), 48, 1);
238
+ status.mesh.position.set(worldX(barX), worldY(Math.min(height, barY + barHeight * 2.5)), 0);
239
+ }
240
+ if (backdropTexture !== undefined)
241
+ coverUv(backdrop.geometry, backdropTexture, width, height, fillBaseU, fillBaseV);
242
+ };
243
+
244
+ const updateProgress = (value: number): void => {
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;
252
+ setFillUv(fill.geometry, progress, fillBaseU);
253
+ status?.update(progress);
254
+ layout();
255
+ };
256
+
257
+ const attachTexture = (mesh: Mesh<PlaneGeometry, MeshBasicMaterial>, texture: Texture): void => {
258
+ if (done) return;
259
+ configureTexture(texture);
260
+ mesh.material.map = texture;
261
+ mesh.material.color.set(0xffffff);
262
+ mesh.material.needsUpdate = true;
263
+ ownedTextures.add(texture);
264
+ if (mesh === backdrop) backdropTexture = texture;
265
+ layout();
266
+ updateProgress(progress);
63
267
  };
64
268
 
65
- const setProgress = (progress: number): void => {
66
- // `Math.max(0, Math.min(1, NaN))` is NaN, so non-finite progress means no progress.
67
- lastProgress = Number.isFinite(progress) ? Math.max(0, Math.min(1, progress)) : 0;
68
- const full = width * 0.5;
69
- const barWidth = Math.max(full * 0.002, full * lastProgress);
70
- fill.scale.set(barWidth, height * 0.012, 1);
71
- fill.position.x = -full / 2 + barWidth / 2;
269
+ const load = (source: string | undefined, mesh: Mesh<PlaneGeometry, MeshBasicMaterial>): void => {
270
+ if (source === undefined || host.assets === undefined) return;
271
+ void host.assets
272
+ .texture(source)
273
+ .then((texture) => attachTexture(mesh, texture))
274
+ .catch(() => undefined);
72
275
  };
276
+ load(loading.backgroundImage, backdrop);
277
+ load(loading.fillImage, fill);
278
+ if (logo !== undefined && loading.logoImage !== undefined && host.assets !== undefined) {
279
+ void host.assets
280
+ .texture(loading.logoImage)
281
+ .then((texture) => {
282
+ if (done) return;
283
+ configureTexture(texture);
284
+ logo.material.map = texture;
285
+ logo.material.needsUpdate = true;
286
+ logo.visible = true;
287
+ ownedTextures.add(texture);
288
+ layout();
289
+ })
290
+ .catch(() => undefined);
291
+ }
73
292
 
74
- let laidOutWidth = camera.right - camera.left;
75
- let laidOutHeight = camera.top - camera.bottom;
293
+ layer.opaque = true;
76
294
  layout();
77
- setProgress(0);
295
+ updateProgress(0);
78
296
 
79
- let done = false;
80
297
  const finish = (): void => {
81
298
  if (done) return;
82
299
  done = true;
@@ -85,29 +302,31 @@ export function createLoadingScreen(host: LoadingHost) {
85
302
  mesh.geometry.dispose();
86
303
  mesh.material.dispose();
87
304
  }
305
+ for (const texture of ownedTextures) texture.dispose();
88
306
  layer.opaque = false;
89
307
  };
90
308
 
91
309
  void (async () => {
92
310
  await host.startup.whenReady();
93
- // Compile the collapsed world's pipelines while the opaque canvas layer still covers it.
94
- await host.renderer.compileAsync(host.scene, host.camera).catch(() => undefined);
311
+ if (done) return;
312
+ // Prewarm the world's shaders, but do not wait for them here. `whenReady()` already means the
313
+ // world is safe to show, and compiling a lit, post-processed scene takes far longer than the
314
+ // launch window: hold the screen for it and a playtest — which advances a fixed step as fast
315
+ // as the machine allows — runs an entire scenario behind the launch screen, so every capture
316
+ // photographs the loading bar instead of the game. The prewarm still happens; it no longer
317
+ // decides when the player sees the world.
318
+ try {
319
+ void host.renderer.compileAsync(host.scene, host.camera).catch(() => undefined);
320
+ } catch {
321
+ // A renderer without compileAsync is not a reason to keep the world hidden.
322
+ }
95
323
  finish();
96
324
  })();
97
325
 
98
326
  return {
327
+ finish,
99
328
  update(): void {
100
- if (done) return;
101
- const nextWidth = camera.right - camera.left;
102
- const nextHeight = camera.top - camera.bottom;
103
- if (nextWidth !== laidOutWidth || nextHeight !== laidOutHeight) {
104
- laidOutWidth = nextWidth;
105
- laidOutHeight = nextHeight;
106
- layout();
107
- setProgress(lastProgress);
108
- }
109
- setProgress(host.startup.progress);
329
+ if (!done) updateProgress(host.startup.progress);
110
330
  },
111
- finish,
112
331
  };
113
332
  }
@@ -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,18 +1,46 @@
1
- import { ACESFilmicToneMapping, type Camera, type Scene } from "three";
2
- import { bloom } from "three/addons/tsl/display/BloomNode.js";
3
- import { pass } from "three/tsl";
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file.
2
+ //
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.
8
+ //
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.
13
+ import type { Camera, DirectionalLight, Scene } from "three";
14
+ import { type QualityTier, qualityPreset, resolveQualityTier } from "./quality.js";
15
+ import type { OutputRenderer } from "./worldEnvironment.js";
16
+ import { WorldEnvironment } from "./worldEnvironment.js";
4
17
 
5
- type OutputRenderer = {
6
- kind: string;
7
- raw: unknown;
8
- setOutputNode(node: unknown): void;
18
+ type ProfileGlobals = typeof globalThis & {
19
+ __THREENATIVE_PROFILE__?: { hostedSoftware?: unknown };
9
20
  };
10
21
 
11
- export function setupPost(renderer: OutputRenderer, scene: Scene, camera: Camera): void {
12
- const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
13
- raw.toneMapping = ACESFilmicToneMapping;
14
- raw.toneMappingExposure = 1.15;
15
- if (renderer.kind !== "webgpu") return;
16
- const colour = pass(scene, camera).getTextureNode();
17
- renderer.setOutputNode(colour.add(bloom(colour, 0.45, 0.5, 0.2)));
22
+ export function setupPost(
23
+ renderer: OutputRenderer,
24
+ scene: Scene,
25
+ camera: Camera,
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
+ } = {},
32
+ ): void {
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));
45
+ world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
18
46
  }
@@ -0,0 +1,170 @@
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or rewrite
2
+ // it freely — the tiers below are a starting point, not a framework look.
3
+ //
4
+ // This is the one place this game decides how expensive it looks. `postprocessing.ts` reads
5
+ // `qualityPreset(resolveQualityTier(...))` and nothing else, so "make it run on a phone" is one
6
+ // file to edit rather than a hunt through anonymous literals.
7
+ //
8
+ // **Where the numbers come from.** Every millisecond below is GPU time from the per-stage
9
+ // ablation recorded in the engine repository's `docs/verification/runtime-perf-state.md`: Chrome
10
+ // on an RTX 2080, 1600x900, static build, `gpuMs` read from three's `timestamp-query`. In that
11
+ // scene the whole five-stage chain costs **12.5 ms of a 14.7 ms GPU frame**, and the same frame
12
+ // with every stage off costs **2.2 ms**. The per-stage figures oversum — removing SSGI also
13
+ // removes the denoise passes the later stages sample — so read each as *what turning this one off
14
+ // gave back*, not as a share of a partition. A stage nobody has ablated on its own says
15
+ // `unmeasured` rather than guessing, and your scene is not that scene: read `TN_FRAME_BUDGET`
16
+ // back after you change a tier.
17
+ //
18
+ // One cost that is **not** a stage here and outweighs most of them: the prefiltered reflection
19
+ // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
+ // in `sky.ts`, not in this file.
21
+ //
22
+ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
23
+
24
+ /**
25
+ * The three names this game's look comes in.
26
+ *
27
+ * `low` is what a phone gets and `high` what a desktop gets — those two are this template's
28
+ * shipped looks, unchanged. `medium` is the rung in between for a machine that is neither: a
29
+ * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
30
+ * what any of them mean.
31
+ */
32
+ export type QualityTier = "low" | "medium" | "high";
33
+
34
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
35
+
36
+ /**
37
+ * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
38
+ * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
39
+ */
40
+ function isQualityTier(value: string): value is QualityTier {
41
+ return (QUALITY_TIERS as readonly string[]).includes(value);
42
+ }
43
+
44
+ /**
45
+ * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
46
+ *
47
+ * Fails closed. An unrecognised tier name throws with the value it was handed rather than
48
+ * quietly rendering the default, because a silent fallback here looks exactly like a tier that
49
+ * turned out to have no effect.
50
+ */
51
+ export function resolveQualityTier(
52
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
53
+ ): QualityTier {
54
+ const requested = request.tier;
55
+ if (requested !== undefined) {
56
+ if (!isQualityTier(requested)) {
57
+ throw new Error(
58
+ `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
59
+ );
60
+ }
61
+ return requested;
62
+ }
63
+ return request.mobile === true ? "low" : "high";
64
+ }
65
+
66
+ /**
67
+ * What a desktop gets: this template's shipped desktop look, unchanged.
68
+ *
69
+ * The whole chain measured 12.5 ms of a 14.7 ms GPU frame in the reference ablation, and SSGI
70
+ * with its denoiser is ~9.2 ms of that.
71
+ */
72
+ const high: IWorldEnvironmentOptions = {
73
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
74
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
75
+ // to be.
76
+ bloomEnabled: true,
77
+ bloomRadius: 0.5,
78
+ bloomStrength: 0.3,
79
+ bloomThreshold: 0.62,
80
+ exposure: 1.02,
81
+ // The two full-resolution denoise passes over the AO and GI terms: ~1.9 ms. Only worth running
82
+ // when SSGI is on — its noise is what they clean up.
83
+ denoiseEnabled: true,
84
+ // SSGI, the screen-space indirect-light gather: ~7.3 ms alone, ~9.2 ms with the two denoise
85
+ // passes it feeds. The largest stage in the chain by a factor of two, of a 14.7 ms frame.
86
+ // Dropping this pair is what `medium` is.
87
+ ssgiEnabled: true,
88
+ ssgiRadius: 16,
89
+ ssgiQuality: "medium",
90
+ // Half the frame in each axis, so a quarter of the pixels. Full-res SSGI cost 14.4 ms
91
+ // of a 39.7 ms frame on an RTX 2080; this is the same gather over a quarter of the work,
92
+ // and it measured *sharper* because the scaler spends what it hands back on resolution.
93
+ // `worldEnvironment.ts` explains why it takes a wrapper instead of a property.
94
+ ssgiResolutionScale: 0.5,
95
+ // Screen-space reflections: ~4.1 ms.
96
+ ssrEnabled: true,
97
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
98
+ // are on and do nothing" — the ray dies a metre from where it started.
99
+ ssrMaxDistance: 40,
100
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
101
+ // the rays and is very hard to see in the result.
102
+ ssrResolutionScale: 0.5,
103
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
104
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
105
+ // that runs one of them.
106
+ sharpenEnabled: true,
107
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
108
+ sharpenStrength: 0.3,
109
+ tonemapMode: "aces",
110
+ };
111
+
112
+ /**
113
+ * `high` minus the gather and its denoiser — the single change in this chain measured to give
114
+ * back most of the frame: **14.7 ms -> 5.5 ms of GPU** in the reference ablation. Reflections,
115
+ * bloom and the sharpener stay, so it is recognisably the same look.
116
+ */
117
+ const medium: IWorldEnvironmentOptions = {
118
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
119
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
120
+ // to be.
121
+ bloomEnabled: true,
122
+ bloomRadius: 0.5,
123
+ bloomStrength: 0.3,
124
+ bloomThreshold: 0.62,
125
+ exposure: 1.02,
126
+ // Screen-space reflections: ~4.1 ms.
127
+ ssrEnabled: true,
128
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
129
+ // are on and do nothing" — the ray dies a metre from where it started.
130
+ ssrMaxDistance: 40,
131
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
132
+ // the rays and is very hard to see in the result.
133
+ ssrResolutionScale: 0.5,
134
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
135
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
136
+ // that runs one of them.
137
+ sharpenEnabled: true,
138
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
139
+ sharpenStrength: 0.3,
140
+ tonemapMode: "aces",
141
+ };
142
+
143
+ /**
144
+ * What a phone gets: this template's shipped mobile look, unchanged. Bloom and the tone curve,
145
+ * nothing screen-space. The ablation's floor — every stage off — was 2.2 ms.
146
+ */
147
+ const low: IWorldEnvironmentOptions = {
148
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
149
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
150
+ // to be.
151
+ bloomEnabled: true,
152
+ bloomRadius: 0.5,
153
+ bloomStrength: 0.3,
154
+ bloomThreshold: 0.62,
155
+ exposure: 1.02,
156
+ tonemapMode: "aces",
157
+ };
158
+
159
+ const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
160
+
161
+ /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
162
+ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
163
+ const preset = QUALITY_PRESETS[tier as QualityTier];
164
+ if (preset === undefined) {
165
+ throw new Error(
166
+ `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
167
+ );
168
+ }
169
+ return preset;
170
+ }