create-threenative 0.2.2 → 0.2.3

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 (343) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +10 -2
  3. package/agent-docs/asset-mcp-loop.md +33 -0
  4. package/agent-docs/ctx-surface.md +69 -0
  5. package/agent-docs/engine-capabilities.md +4 -0
  6. package/agent-docs/framework-blocks-you.md +60 -0
  7. package/agent-docs/look-at-it-and-budget-the-look.md +27 -0
  8. package/agent-docs/performance-default.md +42 -0
  9. package/agent-docs/pixel-budget.md +20 -0
  10. package/agent-docs/playtest-fail-closed.md +23 -0
  11. package/agent-docs/references/assertion-reference.md +652 -0
  12. package/agent-docs/references/capability-reference.md +3279 -0
  13. package/agent-docs/references/capture-the-frame.md +53 -0
  14. package/agent-docs/references/ctx-cookbook.md +51 -0
  15. package/agent-docs/references/debug-surface.md +63 -0
  16. package/agent-docs/references/finding-assets.md +147 -0
  17. package/agent-docs/references/gameplay-recipes.md +54 -0
  18. package/agent-docs/references/menu-screens.md +69 -0
  19. package/agent-docs/references/mobile-memory-budget.md +87 -0
  20. package/agent-docs/references/sculpt-from-a-reference.md +39 -0
  21. package/agent-docs/references/visual-baseline.md +133 -0
  22. package/agent-docs/references/webview-ui.md +113 -0
  23. package/agent-docs/sculpt-loop.md +16 -0
  24. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  25. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  26. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  27. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  28. package/agent-files/.threenative/agents/builder.md +32 -0
  29. package/agent-files/.threenative/agents/verifier.md +31 -0
  30. package/agent-files/AGENT-ROLES.md +26 -0
  31. package/capabilities.json +3542 -0
  32. package/dist/index.d.ts +191 -3
  33. package/dist/index.js +1707 -73
  34. package/dist/threenative.d.ts +9 -2
  35. package/dist/threenative.js +1825 -148
  36. package/package.json +30 -6
  37. package/template-assets/loading.ts +315 -0
  38. package/template-assets/patches/three@0.185.1.patch +287 -0
  39. package/templates/action-rpg/.codex/config.toml +15 -0
  40. package/templates/action-rpg/.mcp.json +6 -2
  41. package/templates/action-rpg/AGENTS.md +370 -6
  42. package/templates/action-rpg/CLAUDE.md +370 -6
  43. package/templates/action-rpg/index.html +0 -1
  44. package/templates/action-rpg/package.json +15 -11
  45. package/templates/action-rpg/playtests/combat.playtest.json +23 -9
  46. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  47. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  48. package/templates/action-rpg/playtests/performance.playtest.json +22 -0
  49. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  50. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  51. package/templates/action-rpg/public/icon.png +0 -0
  52. package/templates/action-rpg/src/entities/Enemy.ts +14 -4
  53. package/templates/action-rpg/src/game.ts +21 -0
  54. package/templates/action-rpg/src/render/lighting.ts +6 -1
  55. package/templates/action-rpg/src/render/loading.ts +267 -42
  56. package/templates/action-rpg/src/render/postprocessing.ts +68 -15
  57. package/templates/action-rpg/src/render/worldEnvironment.ts +583 -0
  58. package/templates/action-rpg/src/scenes/Play.ts +49 -19
  59. package/templates/action-rpg/src/state.ts +4 -0
  60. package/templates/action-rpg/src/style.css +45 -1
  61. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  62. package/templates/action-rpg/src/ui/App.tsx +9 -8
  63. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  64. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  65. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  66. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  67. package/templates/action-rpg/src/ui/main.tsx +14 -0
  68. package/templates/action-rpg/threenative.config.ts +21 -8
  69. package/templates/action-rpg/vite.config.ts +32 -2
  70. package/templates/defense/.codex/config.toml +15 -0
  71. package/templates/defense/.mcp.json +6 -2
  72. package/templates/defense/AGENTS.md +371 -8
  73. package/templates/defense/CLAUDE.md +371 -8
  74. package/templates/defense/README.md +2 -1
  75. package/templates/defense/index.html +0 -1
  76. package/templates/defense/package.json +16 -12
  77. package/templates/defense/playtests/leak.playtest.json +9 -4
  78. package/templates/defense/playtests/performance.playtest.json +22 -0
  79. package/templates/defense/playtests/placement.playtest.json +5 -5
  80. package/templates/defense/playtests/pointer-placement.playtest.json +89 -0
  81. package/templates/defense/playtests/scan.playtest.json +3 -3
  82. package/templates/defense/playtests/survive.playtest.json +11 -6
  83. package/templates/defense/public/icon.png +0 -0
  84. package/templates/defense/src/attackers/Attacker.ts +28 -12
  85. package/templates/defense/src/game.ts +24 -2
  86. package/templates/defense/src/render/lighting.ts +6 -1
  87. package/templates/defense/src/render/loading.ts +263 -37
  88. package/templates/defense/src/render/postprocessing.ts +70 -13
  89. package/templates/defense/src/render/shapes.ts +38 -0
  90. package/templates/defense/src/render/worldEnvironment.ts +583 -0
  91. package/templates/defense/src/scenes/Defense.ts +109 -50
  92. package/templates/defense/src/state.ts +6 -0
  93. package/templates/defense/src/style.css +45 -1
  94. package/templates/defense/src/ui/App.tsx +9 -4
  95. package/templates/defense/src/ui/GameUi.tsx +20 -0
  96. package/templates/defense/src/ui/Hud.tsx +6 -5
  97. package/templates/defense/src/ui/main.tsx +14 -0
  98. package/templates/defense/threenative.config.ts +21 -8
  99. package/templates/defense/vite.config.ts +34 -1
  100. package/templates/minimal/.codex/config.toml +15 -0
  101. package/templates/minimal/.mcp.json +6 -2
  102. package/templates/minimal/AGENTS.md +360 -255
  103. package/templates/minimal/CLAUDE.md +360 -255
  104. package/templates/minimal/index.html +0 -1
  105. package/templates/minimal/package.json +14 -11
  106. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  107. package/templates/minimal/playtests/play.playtest.json +17 -5
  108. package/templates/minimal/public/icon.png +0 -0
  109. package/templates/minimal/src/game.ts +1 -0
  110. package/templates/minimal/src/render/camera.ts +1 -1
  111. package/templates/minimal/src/render/hud.ts +24 -8
  112. package/templates/minimal/src/render/lighting.ts +23 -2
  113. package/templates/minimal/src/render/loading.ts +23 -103
  114. package/templates/minimal/src/render/postprocessing.ts +92 -14
  115. package/templates/minimal/src/render/sky.ts +37 -32
  116. package/templates/minimal/src/render/worldEnvironment.ts +583 -0
  117. package/templates/minimal/src/scenes/Play.ts +91 -13
  118. package/templates/minimal/src/state.ts +8 -1
  119. package/templates/minimal/threenative.config.ts +15 -10
  120. package/templates/minimal/vite.config.ts +28 -1
  121. package/templates/platformer/.codex/config.toml +15 -0
  122. package/templates/platformer/.mcp.json +6 -2
  123. package/templates/platformer/AGENTS.md +385 -130
  124. package/templates/platformer/CLAUDE.md +385 -130
  125. package/templates/platformer/index.html +0 -1
  126. package/templates/platformer/package.json +17 -14
  127. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  128. package/templates/platformer/playtests/branding.playtest.json +29 -0
  129. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  130. package/templates/platformer/playtests/collect.playtest.json +1 -1
  131. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  132. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  133. package/templates/platformer/playtests/damage.playtest.json +4 -1
  134. package/templates/platformer/playtests/dash.playtest.json +2 -2
  135. package/templates/platformer/playtests/jump.playtest.json +2 -3
  136. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  137. package/templates/platformer/playtests/oneway.playtest.json +1 -1
  138. package/templates/platformer/playtests/performance.playtest.json +6 -5
  139. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  140. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  141. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  142. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +13 -4
  143. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  144. package/templates/platformer/playtests/touch-controls-web.playtest.json +46 -0
  145. package/templates/platformer/public/icon.png +0 -0
  146. package/templates/platformer/src/entities/Character.ts +16 -10
  147. package/templates/platformer/src/entities/Patrol.ts +5 -0
  148. package/templates/platformer/src/game.ts +24 -1
  149. package/templates/platformer/src/render/lighting.ts +6 -1
  150. package/templates/platformer/src/render/loading.ts +270 -61
  151. package/templates/platformer/src/render/postprocessing.ts +68 -15
  152. package/templates/platformer/src/render/touch-controls.ts +54 -36
  153. package/templates/platformer/src/render/worldEnvironment.ts +583 -0
  154. package/templates/platformer/src/scenes/Level.ts +47 -22
  155. package/templates/platformer/src/state.ts +4 -0
  156. package/templates/platformer/src/style.css +45 -1
  157. package/templates/platformer/src/ui/App.tsx +9 -4
  158. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  159. package/templates/platformer/src/ui/Hud.tsx +6 -5
  160. package/templates/platformer/src/ui/main.tsx +14 -0
  161. package/templates/platformer/threenative.config.ts +20 -10
  162. package/templates/platformer/vite.config.ts +34 -1
  163. package/templates/racing/.codex/config.toml +15 -0
  164. package/templates/racing/.mcp.json +6 -2
  165. package/templates/racing/AGENTS.md +370 -6
  166. package/templates/racing/CLAUDE.md +370 -6
  167. package/templates/racing/index.html +0 -1
  168. package/templates/racing/package.json +16 -12
  169. package/templates/racing/playtests/boost.playtest.json +5 -5
  170. package/templates/racing/playtests/outcome.playtest.json +14 -4
  171. package/templates/racing/playtests/performance.playtest.json +22 -0
  172. package/templates/racing/playtests/ranking.playtest.json +2 -2
  173. package/templates/racing/playtests/rescue.playtest.json +12 -6
  174. package/templates/racing/playtests/reverse.playtest.json +3 -3
  175. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  176. package/templates/racing/public/icon.png +0 -0
  177. package/templates/racing/src/game.ts +24 -1
  178. package/templates/racing/src/render/camera.ts +10 -6
  179. package/templates/racing/src/render/lighting.ts +6 -1
  180. package/templates/racing/src/render/loading.ts +291 -34
  181. package/templates/racing/src/render/postprocessing.ts +70 -13
  182. package/templates/racing/src/render/worldEnvironment.ts +583 -0
  183. package/templates/racing/src/scenes/Race.ts +68 -36
  184. package/templates/racing/src/state.ts +4 -0
  185. package/templates/racing/src/style.css +45 -1
  186. package/templates/racing/src/track/Lap.ts +20 -9
  187. package/templates/racing/src/track/Ranking.ts +53 -14
  188. package/templates/racing/src/track/Track.ts +29 -16
  189. package/templates/racing/src/track/TrackSector.ts +14 -4
  190. package/templates/racing/src/ui/App.tsx +9 -4
  191. package/templates/racing/src/ui/GameUi.tsx +20 -0
  192. package/templates/racing/src/ui/Hud.tsx +6 -5
  193. package/templates/racing/src/ui/main.tsx +14 -0
  194. package/templates/racing/threenative.config.ts +21 -8
  195. package/templates/racing/vite.config.ts +34 -1
  196. package/templates/sailing/.codex/config.toml +15 -0
  197. package/templates/sailing/.mcp.json +20 -0
  198. package/templates/sailing/AGENTS.md +388 -0
  199. package/templates/sailing/CLAUDE.md +390 -0
  200. package/templates/sailing/README.md +25 -0
  201. package/templates/sailing/index.html +12 -0
  202. package/templates/sailing/kit.json +7 -0
  203. package/templates/sailing/native-playtests/survives.playtest.json +21 -0
  204. package/templates/sailing/package.json +52 -0
  205. package/templates/sailing/playtests/fail.playtest.json +24 -0
  206. package/templates/sailing/playtests/performance.playtest.json +21 -0
  207. package/templates/sailing/playtests/survives.playtest.json +38 -0
  208. package/templates/sailing/playtests/win.playtest.json +31 -0
  209. package/templates/sailing/public/favicon.svg +5 -0
  210. package/templates/sailing/public/icon.png +0 -0
  211. package/templates/sailing/src/entities/Ship.ts +96 -0
  212. package/templates/sailing/src/game.ts +40 -0
  213. package/templates/sailing/src/main.ts +15 -0
  214. package/templates/sailing/src/render/camera.ts +21 -0
  215. package/templates/sailing/src/render/lighting.ts +36 -0
  216. package/templates/sailing/src/render/loading.ts +315 -0
  217. package/templates/sailing/src/render/materials.ts +28 -0
  218. package/templates/sailing/src/render/palette.ts +24 -0
  219. package/templates/sailing/src/render/postprocessing.ts +33 -0
  220. package/templates/sailing/src/render/props.ts +52 -0
  221. package/templates/sailing/src/render/sky.ts +32 -0
  222. package/templates/sailing/src/render/water-material.ts +14 -0
  223. package/templates/sailing/src/render/water-shaders.ts +12 -0
  224. package/templates/sailing/src/render/wave-nodes.ts +10 -0
  225. package/templates/sailing/src/render/worldEnvironment.ts +590 -0
  226. package/templates/sailing/src/scenes/Boot.ts +12 -0
  227. package/templates/sailing/src/scenes/Sailing.ts +106 -0
  228. package/templates/sailing/src/state.ts +10 -0
  229. package/templates/sailing/src/style.css +61 -0
  230. package/templates/sailing/src/ui/App.tsx +15 -0
  231. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  232. package/templates/sailing/src/ui/Hud.tsx +55 -0
  233. package/templates/sailing/src/ui/Menu.tsx +30 -0
  234. package/templates/sailing/src/ui/main.tsx +7 -0
  235. package/templates/sailing/tailwind.config.ts +2 -0
  236. package/templates/sailing/threenative.config.ts +34 -0
  237. package/templates/sailing/tsconfig.json +17 -0
  238. package/templates/sailing/vite.config.ts +34 -0
  239. package/templates/shooter/.codex/config.toml +15 -0
  240. package/templates/shooter/.mcp.json +6 -2
  241. package/templates/shooter/AGENTS.md +373 -7
  242. package/templates/shooter/CLAUDE.md +373 -7
  243. package/templates/shooter/index.html +0 -1
  244. package/templates/shooter/package.json +16 -11
  245. package/templates/shooter/playtests/fail.playtest.json +5 -4
  246. package/templates/shooter/playtests/input-control.playtest.json +131 -0
  247. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  248. package/templates/shooter/playtests/performance.playtest.json +22 -0
  249. package/templates/shooter/playtests/shooter.playtest.json +22 -18
  250. package/templates/shooter/playtests/survives.playtest.json +1 -1
  251. package/templates/shooter/public/favicon.svg +1 -1
  252. package/templates/shooter/public/icon.png +0 -0
  253. package/templates/shooter/src/game.ts +24 -1
  254. package/templates/shooter/src/main.ts +3 -13
  255. package/templates/shooter/src/render/camera.ts +62 -12
  256. package/templates/shooter/src/render/lighting.ts +6 -1
  257. package/templates/shooter/src/render/loading.ts +262 -33
  258. package/templates/shooter/src/render/palette.ts +1 -1
  259. package/templates/shooter/src/render/postprocessing.ts +68 -16
  260. package/templates/shooter/src/render/shapes.ts +178 -0
  261. package/templates/shooter/src/render/ui.css +34 -1
  262. package/templates/shooter/src/render/worldEnvironment.ts +583 -0
  263. package/templates/shooter/src/scenes/Play.ts +246 -73
  264. package/templates/shooter/src/state.ts +13 -0
  265. package/templates/shooter/src/style.css +26 -0
  266. package/templates/shooter/src/ui/App.tsx +10 -12
  267. package/templates/shooter/src/ui/GameUi.tsx +20 -0
  268. package/templates/shooter/src/ui/Hud.tsx +8 -10
  269. package/templates/shooter/src/ui/Menu.tsx +24 -9
  270. package/templates/shooter/src/ui/main.tsx +15 -0
  271. package/templates/shooter/src/weapons/Projectile.ts +21 -10
  272. package/templates/shooter/threenative.config.ts +21 -8
  273. package/templates/shooter/vite.config.ts +32 -2
  274. package/templates/starter/.codex/config.toml +15 -0
  275. package/templates/starter/.mcp.json +6 -2
  276. package/templates/starter/AGENTS.md +429 -326
  277. package/templates/starter/CLAUDE.md +429 -326
  278. package/templates/starter/assets/pickup.wav +0 -0
  279. package/templates/starter/gitignore +4 -0
  280. package/templates/starter/index.html +0 -1
  281. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  282. package/templates/starter/native-playtests/render-chain.playtest.json +12 -0
  283. package/templates/starter/package.json +16 -12
  284. package/templates/starter/playtests/assets.playtest.json +65 -0
  285. package/templates/starter/playtests/buffer.playtest.json +59 -9
  286. package/templates/starter/playtests/cloth.playtest.json +113 -0
  287. package/templates/starter/playtests/coyote.playtest.json +60 -8
  288. package/templates/starter/playtests/forward.playtest.json +29 -4
  289. package/templates/starter/playtests/gameover.playtest.json +66 -0
  290. package/templates/starter/playtests/goal.playtest.json +67 -0
  291. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  292. package/templates/starter/playtests/look.playtest.json +34 -6
  293. package/templates/starter/playtests/models-baseline.png +0 -0
  294. package/templates/starter/playtests/models.playtest.json +74 -0
  295. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  296. package/templates/starter/playtests/odometer.playtest.json +54 -0
  297. package/templates/starter/playtests/pause.playtest.json +27 -4
  298. package/templates/starter/playtests/play.playtest.json +43 -7
  299. package/templates/starter/playtests/respawn.playtest.json +46 -6
  300. package/templates/starter/playtests/restart.playtest.json +65 -10
  301. package/templates/starter/playtests/seed.playtest.json +44 -8
  302. package/templates/starter/playtests/survives.playtest.json +27 -4
  303. package/templates/starter/playtests/textures-baseline.png +0 -0
  304. package/templates/starter/playtests/textures.playtest.json +74 -0
  305. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  306. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  307. package/templates/starter/public/icon.png +0 -0
  308. package/templates/starter/src/entities/Goal.ts +122 -0
  309. package/templates/starter/src/entities/Player.ts +40 -2
  310. package/templates/starter/src/game.ts +25 -0
  311. package/templates/starter/src/render/camera.ts +31 -5
  312. package/templates/starter/src/render/easing.ts +5 -0
  313. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  314. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  315. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  316. package/templates/starter/src/render/lighting.ts +6 -1
  317. package/templates/starter/src/render/loading.ts +315 -0
  318. package/templates/starter/src/render/materials.ts +17 -1
  319. package/templates/starter/src/render/pennant.ts +54 -0
  320. package/templates/starter/src/render/postprocessing.ts +46 -15
  321. package/templates/starter/src/render/scenery.ts +83 -0
  322. package/templates/starter/src/render/shapes.ts +9 -21
  323. package/templates/starter/src/render/worldEnvironment.ts +583 -0
  324. package/templates/starter/src/scenes/Play.ts +146 -36
  325. package/templates/starter/src/state.ts +12 -0
  326. package/templates/starter/src/style.css +45 -1
  327. package/templates/starter/src/ui/App.tsx +9 -6
  328. package/templates/starter/src/ui/GameUi.tsx +20 -0
  329. package/templates/starter/src/ui/Hud.tsx +52 -29
  330. package/templates/starter/src/ui/Menu.tsx +25 -23
  331. package/templates/starter/src/ui/main.tsx +14 -0
  332. package/templates/starter/threenative.config.ts +27 -9
  333. package/templates/starter/tools/look.mjs +109 -0
  334. package/templates/starter/vite.config.ts +32 -2
  335. package/templates/minimal/assets/.gitkeep +0 -0
  336. package/templates/minimal/public/.gitkeep +0 -0
  337. package/templates/platformer/assets/.gitkeep +0 -0
  338. package/templates/platformer/public/.gitkeep +0 -0
  339. package/templates/starter/assets/.gitkeep +0 -0
  340. package/templates/starter/public/.gitkeep +0 -0
  341. package/templates/starter/public/pickup.ogg +0 -0
  342. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  343. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -0,0 +1,53 @@
1
+ # Capture the frame — screenshots that actually render WebGPU
2
+
3
+ Companion to the `Budget real time for the look` section in this project's `AGENTS.md`. Run
4
+ `pnpm dev`, then get eyes on the game. In rough order of preference:
5
+
6
+ 1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
7
+ or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
8
+ a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
9
+ console in the same loop you are already coding in. Drive the game, do not just load the
10
+ menu.
11
+ 2. **`npx @threenative/playtest <scenario> --browser-recipe webgpu --headed`.** The recipe
12
+ carries the Chromium flags a WebGPU capture needs, including `--enable-features=Vulkan`.
13
+ Do not hand-roll the flag list: without that one flag Chromium never reaches the Linux
14
+ Vulkan driver and serves WebGPU from SwiftShader, its CPU rasteriser — no error, healthy
15
+ limits, and a software renderer's picture. The runner fails such a run with
16
+ `TN_PLAYTEST_SOFTWARE_ADAPTER` and prints the adapter it got; `--allow-software` accepts
17
+ the fallback if you truly want it.
18
+ 3. **Ask the user to look**, and say specifically what you want them to check.
19
+
20
+ ## Virtual displays
21
+
22
+ On a machine with no screen, run any of those under a virtual display. **Do not use
23
+ `xvfb-run`:** on `xorg-server-xvfb` 21.1.x its cleanup `kill` fails after Xvfb has already
24
+ exited and that failing kill's status replaces the real one, so
25
+ `xvfb-run -a -s '-screen 0 1600x900x24' true` exits `1`. Every gate wrapped in it reports
26
+ failure whether it passed or not. Start `Xvfb` yourself on a free display and export
27
+ `DISPLAY`, or check the command's own exit code separately.
28
+
29
+ ## Headless Chromium usually cannot render WebGPU
30
+
31
+ The page loads, the HUD paints, and the 3D canvas comes out blank or black. That looks
32
+ exactly like a bug in your scene, and it is not. Symptoms are `Instance dropped in
33
+ popErrorScope` and `createBuffer failed, size (N) is too large for the implementation` in
34
+ the console.
35
+
36
+ So: if a screenshot comes back black or empty, suspect the capture before you rewrite the
37
+ scene. Confirm the renderer works at all before you go debugging your materials.
38
+
39
+ ## The silhouette checklist
40
+
41
+ 1. **Look at it.** Boot the game, get the thing on screen, take a screenshot, open the
42
+ screenshot. Reading your own diff is not looking at it.
43
+ 2. **Silhouette first.** Can you tell what it is from its outline alone? Break up long
44
+ straight edges — overhangs, fringes, props crossing the line.
45
+ 3. **Give it depth.** Something bright behind it, something dark under it. Contact shadows
46
+ and a rim make a prop sit in the world instead of floating on top of it.
47
+ 4. **Make it move.** Idle bob, a squash on impact, a particle on pickup, a screen shake on
48
+ damage. A few frames of motion is the cheapest quality-per-line in the whole project.
49
+ 5. **Finish the HUD too.** Spacing, hierarchy, a transition on every number that changes.
50
+
51
+ When you think you are done, ask yourself, honestly: *would a player screenshot this?* If
52
+ the answer is no, you are not finished — and no command in this project is going to tell
53
+ you that.
@@ -0,0 +1,51 @@
1
+ # The ctx cookbook — recipes behind the `ctx` surface table
2
+
3
+ Companion to the `The ctx surface` section in this project's `AGENTS.md`. The table there is
4
+ the contract; this page is the how and the why.
5
+
6
+ ## Pointer picking with `ctx.raycast()`
7
+
8
+ It defaults to the current pointer position and the whole scene, returns the nearest
9
+ `THREE.Intersection`, and stays under a millisecond on meshes large enough that a plain
10
+ `Raycaster` visibly stutters — it keeps an acceleration structure per geometry and rebuilds it
11
+ when that geometry's positions change. Pass `{ origin, direction }` for a world ray, `{ far }`
12
+ to cap its distance, `{ exclude }` to remove subtrees, and `{ targets }` to narrow it. Use
13
+ `raycastAll` when occlusion or another query needs every hit; results are sorted nearest first.
14
+ `{ screen }` tests a point that is not the pointer. Skinned, instanced and morphed meshes fall
15
+ back to the stock Three.js path automatically, so the result always matches
16
+ `Raycaster.intersectObject`.
17
+
18
+ When scene collapse runs on a large static scene, a mesh with non-empty `userData` stays as the
19
+ original object in the live graph. Put the target or entity metadata you already use for picking
20
+ on the mesh; `ctx.raycast()` then still returns that mesh and its metadata. Meshes without
21
+ `userData` may be merged into fewer draws.
22
+
23
+ ## Scene rebuild semantics
24
+
25
+ Calling `ctx.goto("<scene-name>")` from inside the matching scene tears it down and rebuilds
26
+ it: `exit()` runs, scheduled callbacks are cleared, registered entities are cleared, the Three
27
+ scene is emptied, then a fresh instance runs `load()` and `enter()`. Values in `ctx.state` —
28
+ health, score, inventory, or any other game-owned state — survive this scene rebuild. When
29
+ death-and-retry should reset gameplay, reset your own state explicitly before calling
30
+ `ctx.goto()`.
31
+
32
+ Do **not** write a `#reset()` that walks your entities putting them back. It is ~15 lines that
33
+ look right and quietly miss the scheduler and anything you spawned after `enter()`, so the
34
+ second playthrough behaves differently from the first — and no gate in this project will catch
35
+ that.
36
+
37
+ ## Timing with `ctx.tween` and `ctx.after`
38
+
39
+ **`ctx.tween` is for timing, not for looks.** Use it for the *when* — a pickup rising over
40
+ 0.4s, a door opening, a hit flash — and keep the *what* (colour, shape, easing feel) in
41
+ `src/render/`. Motion driven by a persistent `Math.sin(elapsed)` in `update()` is still the
42
+ right tool for a continuous idle bob; `tween` is for anything that starts, runs once, and
43
+ finishes. `ctx.after(seconds, fn)` and `ctx.every(fn)` schedule on the same clock the scene
44
+ runs on; both handles are cleared when the scene exits.
45
+
46
+ ## Seeded randomness
47
+
48
+ **`ctx.random` is deterministic only when `defineGame({ seed })` is configured.** Check
49
+ `src/game.ts`: a declared seed gives replayable values for spawn positions, patrol offsets,
50
+ and level variation; without one, `ctx.random` falls back to `Math.random()`. Add a fixed
51
+ seed when a playtest needs replayable randomness.
@@ -0,0 +1,63 @@
1
+ # The debug surface — probing a running game
2
+
3
+ The bridge globals exist but were discovered by trial: six throwaway probe scripts in one
4
+ day, each re-finding the shapes through TypeErrors. This page lists every global a running
5
+ game exposes, what it returns, and how to read it from the browser console. All of them are
6
+ read-only observation surfaces; none exists to drive gameplay.
7
+
8
+ ## `window.__THREENATIVE__` — entity snapshot (dev builds only)
9
+
10
+ Installed by `defineGame` when the dev-server flag is on (`installDevTools`); absent in
11
+ production builds.
12
+
13
+ ```js
14
+ window.__THREENATIVE__.snapshot()
15
+ // → { entities: [{ id, kind?, ...entity debug fields }], ... }
16
+ ```
17
+
18
+ `snapshot()` prefers an entity's own `debug()` and falls back to `autoFields`. This is the
19
+ fastest "what does the game think exists" probe; playtest assertions and the dev overlay
20
+ read the same registry.
21
+
22
+ ## `window.__THREENATIVE_PLAYTEST_BRIDGE__` — the harness channel
23
+
24
+ Installed by `playtest()` (core plugin) or `installThreePlaytestBridge`
25
+ (`@threenative/playtest/three`). One object, JSON-safe in and out:
26
+
27
+ | Member | Shape | Use |
28
+ | --- | --- | --- |
29
+ | `describe()` | `{ name, protocolVersion, capabilities, limits }` | First call. Tells you what this game's bridge supports and the protocol limits. |
30
+ | `ready()` | `{ ready: true }` | Liveness check before sampling. |
31
+ | `sample(request)` | JSON-safe observation snapshot (entities, camera, renderer stats, resources, components) | The main probe. Pass `{}` for the default sample; `request.include` names optional series such as `physicsDebugSeries`. |
32
+ | `advance(ticks)` | fixed-step bridges only: advances exactly N ticks and returns `{ clock, ticks }`; throws if the step count mismatches | Deterministic stepping without wall-clock waits. Throws when the bridge is render-frame. |
33
+ | `applySetup(request)` | applies scenario `setup` placements/resources through the registry | What scenario setup uses; also usable by hand for one-off staging. |
34
+ | `drainEvents(limit)` | event-queue bridges only: returns up to `limit` queued events | Reads events shorter than one state flush. |
35
+
36
+ A console one-liner that works on any bridged game:
37
+
38
+ ```js
39
+ await window.__THREENATIVE_PLAYTEST_BRIDGE__.describe()
40
+ ```
41
+
42
+ Missing global means no bridge is installed — semantic assertions against that page fail
43
+ `TN_PLAYTEST_BRIDGE_MISSING`, which is the harness being right, not a bug to work around.
44
+
45
+ ## `window.__THREENATIVE_NATIVE__` — native host channel
46
+
47
+ Present only under the native runtime. The host injects its side; core's viewport and
48
+ `@threenative/playtest/three`'s device reporting read it (adapter identity, host snapshot).
49
+ On web this global does not exist — do not probe for it in portable code.
50
+
51
+ ## Runner-side markers
52
+
53
+ Two further globals are set by tooling, not the game, and are named here so a stray
54
+ assignment is recognisable: `__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__` (core's playtest
55
+ plugin marks the expected runner contract) and `__THREENATIVE_FRAMEBUFFER_COVERAGE_PROBE__`
56
+ (the framebufferCoverage assertion installs its sampler). Leave both alone in game code.
57
+
58
+ ## What does not exist
59
+
60
+ There is no `__THREENATIVE_SCENE__` global. Scene-graph inspection goes through
61
+ `sample()` (which reports counts, extents and visibility) or through your own
62
+ registered entities' `debug()` output — never by reaching into three.js objects from
63
+ the console and treating what you find as an observation surface.
@@ -0,0 +1,147 @@
1
+ # Finding assets — the full MCP tool loop
2
+
3
+ Companion to the short `Finding assets` section in this project's `AGENTS.md`. Reach for the
4
+ asset tools when the asset is conventional; build anything specific to this game yourself in
5
+ `src/render/`. A fetched asset has to match what the game needs, not merely exist.
6
+
7
+ Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
8
+ your host lists its tools alongside your own. Your host reads that file from the directory it was
9
+ launched in: start the session in this project, not in a parent of it. It advertises 34; these 8
10
+ are the loop you will use for nearly everything:
11
+
12
+ 1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
13
+ source with its license summary, attribution requirement, browse URL, and whether an agent
14
+ can complete a download from it. **That output is the authority on what is reachable** —
15
+ not your memory of some other project.
16
+ 2. `polyhaven_search_assets` (CC0 models, textures, HDRIs), `ambientcg_search_assets` (CC0
17
+ materials and textures), or `audio_search_assets` (Kenney, Sonniss).
18
+ 3. `polyhaven_list_files` / `ambientcg_list_files` — the license, official URL, byte size and
19
+ md5 of every resolution and format. **Read this before downloading, not after**, and pick a
20
+ sane one: Poly Haven lists 16k PNGs over 1 GB beside 8k JPEGs at 28 MB. A game does not
21
+ need the 16k.
22
+ 4. `asset_download_file` for textures and models, `audio_download_asset` for audio. Both take
23
+ `acceptLicense: true` — you are asserting you read step 3. **They ignore any path you pass
24
+ and write to the directories `.mcp.json` sets** (`public/assets/<provider>/<sha>/` and
25
+ `public/audio/<source>/<pack>/`); without that config they would write to `~/Downloads` and
26
+ never reach the game.
27
+ 5. Append the file, its source, its license and its URL to `CREDITS.md` **before the turn
28
+ ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
29
+ CC0 per asset page, and audio and bundle licenses are per pack.
30
+
31
+ **Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
32
+ `ambientcg_search_assets` did not tell you, you do not know it.
33
+
34
+ ## What arrives is usually a ZIP, not a texture
35
+
36
+ ambientCG and Kenney ship archives: unpack one, keep only the maps you actually use (`_Color`,
37
+ `_NormalGL`, `_Roughness` — not the `.blend`, `.usdc` or displacement), and put those beside
38
+ your code under `public/`. A 1K JPEG set is right for a game; the 8K set of the same material
39
+ is 200 MB.
40
+
41
+ ## Two argument shapes that bite
42
+
43
+ Both learned the hard way: `ambientcg_search_assets` takes lowercase `type` values (`material`,
44
+ `hdri`, `3d-model`), and the audio catalog is **pack-level** — `audio_search_assets` matches
45
+ pack names, so `query: "pickup coin"` returns nothing while `kind: "sfx"` returns the packs
46
+ that exist. Pick a pack, download it, unzip it, and choose a file yourself.
47
+
48
+ ## Fab: searching, and importing an Unreal asset you own
49
+
50
+ Most Fab listings ship Unreal-only — 272 `.uasset` files and no `.glb` anywhere — so Fab is two
51
+ steps, not one: find the listing, then convert it.
52
+
53
+ **1. Search free first.** `fab_search_assets` talks to Fab's public API anonymously; no account is
54
+ involved. Its default `priceMode: "free"` is the right default and should stay your first query —
55
+ a free asset is one anybody who clones this project can fetch too.
56
+
57
+ ```jsonc
58
+ // fab_search_assets
59
+ {
60
+ "query": "cave rocks",
61
+ "formats": ["unreal-engine"], // "gltf", "fbx", "obj", "unity" ... omit for every format
62
+ "priceMode": "any", // SEE BELOW — the default is "free"
63
+ "sort": "relevance", // or rating, newest, price_asc, recently_updated
64
+ "limit": 24
65
+ }
66
+ ```
67
+
68
+ **Then look at what the account already owns.** A paid listing sitting in the library costs
69
+ nothing further to use, and it will never appear in a free search — `priceMode: "free"` returns a
70
+ different result set than `"any"` does. `fab_list_owned` answers that directly, without guessing
71
+ at search terms:
72
+
73
+ ```jsonc
74
+ // fab_list_owned
75
+ { "unrealOnly": true, "query": "vegetation" } // both optional; unrealOnly drops engine installs
76
+ // and plugins the importer cannot take
77
+ // -> [{ listingId, title, url, categories, engineVersions, hasUnrealArtifact }]
78
+ ```
79
+
80
+ Reach for `priceMode: "any"` in `fab_search_assets` only when you mean to look at paid listings
81
+ the account does *not* own yet — buying is not something these tools can do for you.
82
+
83
+ Each item carries a `title` and an `id` — that `id` is the listing UID the next two tools take.
84
+ `fab_list_filters` returns the usable `formats`, `categories` and `tags` slugs; guessing them
85
+ silently narrows the search instead of erroring.
86
+
87
+ **2. Check the licence.** Search results carry **no licence** — Fab's search endpoint omits it, so
88
+ every item comes back with an empty `licenses` array. `fab_get_asset` is where the slugs live:
89
+
90
+ ```jsonc
91
+ { "listingIdOrUrl": "75f42402-40bb-4a1b-b557-18e2c9604273" }
92
+ // -> licenses: [{ slug: "personal" }, { slug: "professional" }], freeLicenseSlugs: [...]
93
+ ```
94
+
95
+ **3. Import.** `fab_import_asset` verifies the entitlement itself, downloads through the FabCLI
96
+ session, converts every static mesh, and writes source GLBs into your `assets/`:
97
+
98
+ ```jsonc
99
+ // fab_import_asset
100
+ {
101
+ "listingIdOrUrl": "https://www.fab.com/listings/<uid>",
102
+ "outputDir": "assets/fab/soul-cave",
103
+ "packages": ["SM_S_Soul_Statue"], // omit to convert every static mesh — packs run to gigabytes
104
+ "maxTextureSize": 2048, // omit to keep Unreal's own resolution
105
+ "acceptFabEula": true
106
+ }
107
+ ```
108
+
109
+ Then load the returned path the ordinary way:
110
+ `ctx.assets.model("fab/soul-cave/.../SM_S_Soul_Statue.glb")`. The normal asset compiler picks the
111
+ GLBs up from `assets/` with no extra configuration.
112
+
113
+ What the import will and will not do:
114
+
115
+ - **Only assets you already own**, and only under **Fab Standard (Personal or Professional) or
116
+ CC-BY**. Unreal-Engine-only and legacy entitlements are refused, and a licence it cannot read is
117
+ refused too. It never logs in, claims, or purchases — run `fabcli auth login` yourself once.
118
+ Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
119
+ authenticated path it is guarding.
120
+ - **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
121
+ `THREENATIVE_TOOLCHAIN_AUTOINSTALL=0` to require you install them instead. Linux and Windows only.
122
+ - **`packages` is not optional in practice.** A marketplace pack converts to many gigabytes of
123
+ GLBs; name the handful of meshes your scene uses. Run it once without `packages` against a
124
+ scratch directory if you need to see what a pack contains, then re-run with the names.
125
+ - **Read `import-report.json` before trusting the result.** It reports `materials: "complete"` or
126
+ `"degraded"`, counts textured against total sections, and names every mesh it skipped and every
127
+ texture it could not map. Unreal shader graphs have no glTF equivalent, so some sections arrive
128
+ with a neutral grey and say so. `.umap` levels, Blueprints, Niagara and foliage placement are
129
+ reported as unsupported, never silently dropped.
130
+ - `asset_import_unreal` takes a local `sourceDir` instead of a listing, for a pack you already
131
+ downloaded by any means.
132
+
133
+ `fab_download_free_asset` is the unrelated older path: it downloads a directly-available free
134
+ `glb`/`fbx`/`obj`/`unity` file with no account at all. Use it when the listing already ships a
135
+ format you can load, and the importer only when it does not.
136
+
137
+ ## The narrower tools
138
+
139
+ The directory spells out the conditions on each. The Fab tools are covered above; the server
140
+ never purchases anything on any path. `smithsonian_search_assets` returns museum scans at scan resolution, which this project has no
141
+ pipeline to decimate — that geometry is the wrong shape for a game. When in doubt check
142
+ `asset_search_sources` first; its `caution` and license fields are the current truth for the
143
+ pinned version, and they change between versions.
144
+
145
+ Load what you downloaded the ordinary way — `ctx.assets.model("crate.glb")`,
146
+ `ctx.assets.texture(...)`, `ctx.assets.audio(...)` — and write your own material and lighting
147
+ around it in `src/render/`. The framework ships no asset and picks none for you.
@@ -0,0 +1,54 @@
1
+ # Gameplay recipes — movement, input, physics-step timing, and saves
2
+
3
+ Companion to the gameplay sections in this project's `AGENTS.md`.
4
+
5
+ ## Forward is -z, and the mapping happens once
6
+
7
+ `input.vector("move").y` is +up; map it to world-space -z for forward with one explicit
8
+ `-move.y` conversion in the player movement code. One conversion site per entity — a second
9
+ one flips the controls.
10
+
11
+ ## A gamepad already drives this game
12
+
13
+ `vector` adds the left stick to the action literally named `move`, and
14
+ `jump: { buttons: [0] }` in `src/game.ts` is that pad's south face button — `buttons` is the
15
+ gamepad, `mouseButtons` is the mouse. Two consequences worth knowing before you debug either:
16
+ the stick reaches **only** an action called `move`, so renaming that action or adding a second
17
+ stick-driven one (a `look` axis, say) gets you nothing, and there is no deadzone, so a worn
18
+ stick's resting drift is added every frame and the character creeps. Subtract your own deadzone
19
+ in the entity if that shows up.
20
+
21
+ ## moveAndSlide queues motion for the shared physics step
22
+
23
+ `CharacterBody3D.moveAndSlide(dt)` owns gravity through `body.velocity` and queues motion for
24
+ the shared bulk physics step rather than moving its object immediately. Because
25
+ `THREE.Vector3` is mutable, use `const before = mesh.position.clone()` (or copy its `x`, `y`,
26
+ and `z` scalars) before the call, then compare `mesh.position.distanceTo(before)` on the next
27
+ update, after the step. Storing `mesh.position` itself aliases the live transform and reports
28
+ zero. Keep coyote-time and jump-buffer timers in the entity so jump feel stays game-owned.
29
+
30
+ ## Save only declared state
31
+
32
+ The framework does not serialize entities, scene graphs, or physics handles, and it never
33
+ will; save those fields in your own object literal:
34
+
35
+ ```ts
36
+ const save = JSON.stringify({ state: ctx.state.getState(), playerX: player.mesh.position.x });
37
+ const loaded = JSON.parse(save) as { state: GameState; playerX: number };
38
+ ctx.state.set(loaded.state);
39
+ player.body.teleport({ x: loaded.playerX, y: player.mesh.position.y, z: player.mesh.position.z });
40
+ ```
41
+
42
+ ## Hot reload carries JSON-shaped state only
43
+
44
+ `main.ts` calls `acceptHotUpdate(game, import.meta.hot)` for development reloads. The
45
+ framework preserves only store state; seed entities from the carried values such as
46
+ `playerX` in `enter()`, because the scene graph, physics world, audio voices, particles, and
47
+ renderer are rebuilt on every update.
48
+
49
+ ## The state bridge throttles
50
+
51
+ The bridge flushes every 100 ms by default: write `ctx.state.set({...})` from `update()` at
52
+ loop rate — it coalesces — and read it from HUD components at ~10 Hz. Per-frame visual
53
+ feedback belongs in scene-owned Three.js objects. If an event must appear in the HUD, give
54
+ it a decay longer than one flush interval.
@@ -0,0 +1,69 @@
1
+ # Menu screens: scenes are the screens
2
+
3
+ Use a scene for every screen that needs a world, camera, lighting, or ordinary Three.js art. Put
4
+ the chrome in `src/ui/` so the same React tree runs beside the web canvas and in the native web
5
+ view.
6
+
7
+ ## The flow
8
+
9
+ 1. Give the menu scene a static `initialState` with `screen: "menu"` and all fields the game
10
+ state needs.
11
+ 2. Render a form in a UI component with `useUiState` and `useUiIntent`. Mark every input and
12
+ button with `data-tn-interactive`.
13
+ 3. Validate the intent payload in `src/game.ts`. The game owns the transition:
14
+
15
+ ```ts
16
+ if (intent === "start-game" && name.length > 0) {
17
+ void game.goto("play", { carry: { characterName: name } });
18
+ }
19
+ ```
20
+
21
+ `game.goto()` resets to the destination scene's `initialState`, then merges the serializable
22
+ `carry` patch. `ctx.goto()` rebuilds without resetting state; use it only when the current run
23
+ should survive the rebuild.
24
+
25
+ 4. Give the played scene its own initial state with `screen: "playing"`. The carried values are
26
+ available in `enter()` through `ctx.state.getState()` and are also visible to the UI and
27
+ playtest bridge.
28
+ 5. Switch the chrome from the published `screen` value. The menu component returns `null` outside
29
+ the menu, and the HUD/menu bar return `null` outside play.
30
+
31
+ ## Add a settings screen
32
+
33
+ To insert settings between the menu and play screens, extend the state union with `"settings"`,
34
+ add a `Settings` scene whose `initialState.screen` is `"settings"`, and add a `SettingsUi` form
35
+ that follows the same `useUiState`/`useUiIntent` pattern. Register the scene, render the form
36
+ when `screen === "settings"`, and keep navigation in `src/game.ts`:
37
+
38
+ ```ts
39
+ if (intent === "open-settings") void game.goto("settings");
40
+ if (intent === "start-game") {
41
+ void game.goto("play", { carry: { characterName: name, difficulty } });
42
+ }
43
+ ```
44
+
45
+ The menu's settings button and the settings form's start button both carry
46
+ `data-tn-interactive`. Prove the complete flow with viewport-pixel clicks and assert the carried
47
+ settings resource after the final scene transition.
48
+
49
+ ## Prove it with a click scenario
50
+
51
+ `click` uses viewport pixels and emits a real pointer-down/up pair on the web target:
52
+
53
+ ```json
54
+ { "kind": "click", "at": { "x": 640, "y": 365 }, "label": "name-field" }
55
+ ```
56
+
57
+ Click the form field, use ordinary `input` steps for the text, click submit, then assert the
58
+ carried value through `resources`:
59
+
60
+ ```json
61
+ { "equals": "axo", "id": "state", "path": "characterName" }
62
+ ```
63
+
64
+ The bridge samples the state after the transition settles. A missing bridge or an unobserved
65
+ entity click target is a named failure, never a skipped step.
66
+
67
+ The native renderer draws quads and has no text input today. Form screens therefore use the shared
68
+ webview UI; `ui: { renderer: "native" }` is appropriate only when the screen does not need text
69
+ entry.
@@ -0,0 +1,87 @@
1
+ # What memory a phone actually gives you
2
+
3
+ Everything here was measured on a **physical Pixel 8** (Mali-G715, Vulkan, 2400x1080 surface) on
4
+ 2026-08-23, running a real game through this framework. No estimates, no emulator.
5
+
6
+ ## The headline
7
+
8
+ The game asked the GPU for 393 MiB of textures and buffers. Here is what that turned into:
9
+
10
+ | | |
11
+ | --- | --- |
12
+ | What the game asked `createTexture`/`createBuffer` for | 393 MiB |
13
+ | What the driver held (`dumpsys meminfo`: `GL mtrack` + `EGL mtrack`) | ~899 MiB |
14
+ | Process `VmRSS` | ~1.4 GiB |
15
+
16
+ That looks like the driver doubling everything you allocate. **It is not.** About **480 MiB was
17
+ already held at the first presented frame**, before the game had uploaded a single texture, and
18
+ across the entire asset load the driver then grew by *less* than the game requested.
19
+
20
+ So budget like this:
21
+
22
+ > **a ~500 MiB fixed floor, plus roughly the bytes you ask for.**
23
+
24
+ Not as a multiplier on your own textures. The practical consequence is that shaving 50 MiB off
25
+ your textures really does save about 50 MiB — but you start 500 MiB in the hole, and a phone
26
+ begins killing apps well under 2 GiB.
27
+
28
+ ## Your sky is charged twice, and the second charge is the expensive one
29
+
30
+ Assigning one equirect to both `scene.background` and `scene.environment` looks free. It is not.
31
+ `scene.environment` builds an image-based light, and three.js sizes that light's render targets
32
+ from the **source equirect's width** — `cubeSize = width / 4`, rounded *down* to a power of two,
33
+ then two render targets of `3 x max(cubeSize, 112)` by `4 x cubeSize` in `rgba16float`.
34
+
35
+ Measured, on a real WebGPU adapter:
36
+
37
+ | equirect width | PMREM pair allocated | cost |
38
+ | --- | --- | --- |
39
+ | 3072 | 1536x2048 rgba16float x2 | **48 MiB** |
40
+ | 2048 | 1536x2048 rgba16float x2 | **48 MiB** |
41
+ | 1024 | 768x1024 rgba16float x2 | **12 MiB** |
42
+ | 512 | 384x512 rgba16float x2 | **3 MiB** |
43
+
44
+ Two things fall out of that table.
45
+
46
+ **Halving a 3072 sky to 2048 saves nothing.** The cost moves in power-of-two steps, so only
47
+ crossing a step changes anything. Resizing an asset "a bit smaller" is wasted work.
48
+
49
+ **Split the two uses.** The background is what the player looks at and wants every pixel it has.
50
+ The light does not: PMREM immediately convolves its source into roughness mips, so everything it
51
+ contributes is low-frequency, and the only detail that survives is a mirror reflection. Give the
52
+ environment its own smaller copy of the same image:
53
+
54
+ ```ts
55
+ // One 3072-wide photograph, downsampled once to 1024 for the light.
56
+ scene.background = skyEquirect; // full resolution — this is the visible sky
57
+ scene.environment = skyEquirectSmall; // 1024x512 copy — this is only ever blurred
58
+ ```
59
+
60
+ That is 36 MiB back for a 2.7 MiB texture, with nothing visible changing. Pick 1024 over 512 if
61
+ your scene has polished metal or still water in it, since 512 halves the mirror again.
62
+
63
+ **Do this before you reach for texture compression.** It is one line, it costs nothing at
64
+ runtime, and it is larger than most compression wins on a small texture set.
65
+
66
+ ## Where the rest of your budget goes
67
+
68
+ Ordinary things that are bigger than people expect, all from the same measured run:
69
+
70
+ - **Full-screen render targets scale with your device's real resolution, not your design
71
+ resolution.** At 2400x1080 a single `rgba16float` colour target is 19 MiB and a `depth24plus`
72
+ is 9.5 MiB. Post-processing chains multiply that by how many you keep alive.
73
+ - **Mip chains add a third.** A 2048x2048 `rgba8unorm-srgb` with a full mip pyramid is 21 MiB,
74
+ not 16 MiB. Eight 1024x1024 maps with mips are 42 MiB between them.
75
+ - **Buffers are almost never the problem.** In that run, 3038 buffers came to 14 MiB total —
76
+ under 4 % of the footprint. Do not spend your optimisation budget there.
77
+ - **A cubemap conversion is not free.** Setting `scene.background` to an equirect makes the
78
+ renderer build a cubemap from it; at 3072x1536 that cubemap was 54 MiB on its own, separate
79
+ from the 23 MiB source texture and separate again from the image-based light.
80
+
81
+ ## How to check your own game
82
+
83
+ On native, the runtime prints its own accounting beside the present tick — watch `logcat` for
84
+ `TN_GPU_TEXTURES` and `TN_GPU_BUFFERS`, which bucket every texture by dimensions, format and mip
85
+ count so you can see which allocation is the big one rather than guessing. Read those numbers as
86
+ *what the game requested*; the driver's own total is a separate figure, and the floor above is why
87
+ the two never match.
@@ -0,0 +1,39 @@
1
+ # Building what you cannot download — sculpt from a reference
2
+
3
+ Companion to the short `Building what you cannot download` section in this project's
4
+ `AGENTS.md`.
5
+
6
+ ## Choose one branch before writing code
7
+
8
+ - **Conventional and downloadable** — a crate, an oak plank texture, a click. Use the asset
9
+ tools. Sculpting one of these is slower and worse.
10
+ - **Trivial** — a platform, a wall, a pickup ring. Write it. If `BoxGeometry` finishes the
11
+ job in under 20 lines, that is the answer.
12
+ - **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
13
+ landmark, scenery composition, or environment set piece whose silhouette must match. Use
14
+ the sculpt tools to turn that reference into editable `src/render/` source.
15
+ - **Bespoke, without a reference image** — ask for one, or write it and accept that it will
16
+ be generic. Do not invent a reference: comparison without evidence is unguided iteration.
17
+
18
+ For a full environment, split the decision: sculpt the signature landmark or bounded scene
19
+ kit that makes the reference recognisable; use the asset tools for interchangeable trees,
20
+ rocks, textures, HDRIs, and sounds around it. Do not sculpt an entire world as one object.
21
+
22
+ ## The gate loop
23
+
24
+ `.mcp.json` launches `threenative-sculpt-mcp` beside the asset server. It does not generate
25
+ or ship runtime code; it guides the source you write:
26
+
27
+ 1. Call `sculpt_plan` with the image path and a one-line intent, then read the returned
28
+ grimoire resources.
29
+ 2. Write the returned object contract and loop on `sculpt_spec_gate` until every named
30
+ region and depth requirement passes. Do not write geometry before this gate is green.
31
+ 3. For each ordered pass, write or extend one factory in `src/render/`. Capture the real
32
+ frame with `npx @threenative/playtest`; the sculpt server never launches a browser.
33
+ 4. Call `sculpt_compare` with the reference and captured frame, then give that evidence to
34
+ `sculpt_pass_gate`. Advance only when it says advance; ambiguity means retry.
35
+ 5. Use `sculpt_grimoire` for a named technique topic. It rejects pages containing concrete
36
+ paste-ready material or shader recipes so the tool never owns this game's look.
37
+
38
+ A missing or blank capture is a failed run, never a finished model. Add the reference image,
39
+ its creator, license, and source URL to `CREDITS.md` before the turn ends.