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
@@ -0,0 +1,215 @@
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 40; these 8
10
+ are the loop you will use for nearly everything:
11
+
12
+ For a bespoke animated creature, use the complete [`creating-creatures.md`](creating-creatures.md)
13
+ recipe. It keeps the editable spec and claims under `.threenative/creatures/`, compiles the GLB
14
+ into the configured `assets/` source, and requires independent preview review before game
15
+ delivery. The five creature tools are `creature_status`, `creature_guide`, `creature_compile`,
16
+ `creature_preview` and `creature_check`; call `creature_status` first because compile can work
17
+ without optional preview dependencies while a complete preview/check loop may not.
18
+
19
+ 1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
20
+ source with its license summary, attribution requirement, browse URL, and whether an agent
21
+ can complete a download from it. **That output is the authority on what is reachable** —
22
+ not your memory of some other project.
23
+ 2. `polyhaven_search_assets` (CC0 models, textures, HDRIs), `ambientcg_search_assets` (CC0
24
+ materials and textures), or `audio_search_assets` (Kenney, Sonniss).
25
+ 3. `polyhaven_list_files` / `ambientcg_list_files` — the license, official URL, byte size and
26
+ md5 of every resolution and format. **Read this before downloading, not after**, and pick a
27
+ sane one: Poly Haven lists 16k PNGs over 1 GB beside 8k JPEGs at 28 MB. A game does not
28
+ need the 16k.
29
+ 4. `asset_download_file` for textures and models, `audio_download_asset` for audio. Both take
30
+ `acceptLicense: true` — you are asserting you read step 3. **They ignore any path you pass
31
+ and write to the directories `.mcp.json` sets** (`public/assets/<provider>/<sha>/` and
32
+ `public/audio/<source>/<pack>/`); without that config they would write to `~/Downloads` and
33
+ never reach the game.
34
+ 5. Append the file, its source, its license and its URL to `CREDITS.md` **before the turn
35
+ ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
36
+ CC0 per asset page, and audio and bundle licenses are per pack.
37
+
38
+ **For a Poly Haven *model*, steps 3-4 collapse into `polyhaven_import_model`.** Poly Haven
39
+ publishes models as a `.gltf` beside a `.bin` and loose texture files and **never as a `.glb`**, so
40
+ doing it by hand means fetching five to eight URLs and rebuilding the directory layout the glTF's
41
+ relative URIs expect before anything will load. Pass `assetId`, an `outputPath` ending in `.glb`,
42
+ a `resolution` (it defaults to `1k`, which is what a game floor wants), and `acceptLicense: true`;
43
+ it downloads through the same guarded path, packs one self-contained GLB that
44
+ `ctx.assets.model()` loads directly, and returns **triangle count and per-texture dimensions** —
45
+ the two numbers `create-threenative inspect` does not report and that every triangle and texture
46
+ budget is written in. Ask for a resolution the asset does not publish and it names the ones that
47
+ exist. Textures and HDRIs still use `asset_download_file`.
48
+
49
+ **Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
50
+ `ambientcg_search_assets` did not tell you, you do not know it.
51
+
52
+ ## What arrives is usually a ZIP, not a texture
53
+
54
+ ambientCG and Kenney ship archives: unpack one, keep only the maps you actually use (`_Color`,
55
+ `_NormalGL`, `_Roughness` — not the `.blend`, `.usdc` or displacement), and put those beside
56
+ your code under `public/`. A 1K JPEG set is right for a game; the 8K set of the same material
57
+ is 200 MB.
58
+
59
+ ## Two argument shapes that bite
60
+
61
+ Both learned the hard way: `ambientcg_search_assets` takes lowercase `type` values (`material`,
62
+ `hdri`, `3d-model`), and the audio catalog is **pack-level** — `audio_search_assets` matches
63
+ pack names, so `query: "pickup coin"` returns nothing while `kind: "sfx"` returns the packs
64
+ that exist. Pick a pack, download it, unzip it, and choose a file yourself.
65
+
66
+ ## Fab: searching, and importing an Unreal asset you own
67
+
68
+ Most Fab listings ship Unreal-only — 272 `.uasset` files and no `.glb` anywhere — so Fab is two
69
+ steps, not one: find the listing, then convert it.
70
+
71
+ **1. Search free first.** `fab_search_assets` talks to Fab's public API anonymously; no account is
72
+ involved. Its default `priceMode: "free"` is the right default and should stay your first query —
73
+ a free asset is one anybody who clones this project can fetch too.
74
+
75
+ ```jsonc
76
+ // fab_search_assets
77
+ {
78
+ "query": "cave rocks",
79
+ "formats": ["unreal-engine"], // "gltf", "fbx", "obj", "unity" ... omit for every format
80
+ "priceMode": "any", // SEE BELOW — the default is "free"
81
+ "sort": "relevance", // or rating, newest, price_asc, recently_updated
82
+ "limit": 24
83
+ }
84
+ ```
85
+
86
+ **Then look at what the account already owns.** A paid listing sitting in the library costs
87
+ nothing further to use, and it will never appear in a free search — `priceMode: "free"` returns a
88
+ different result set than `"any"` does. `fab_list_owned` answers that directly, without guessing
89
+ at search terms:
90
+
91
+ ```jsonc
92
+ // fab_list_owned
93
+ { "unrealOnly": true, "query": "vegetation" } // both optional; unrealOnly drops engine installs
94
+ // and plugins the importer cannot take
95
+ // -> [{ listingId, title, url, categories, engineVersions, hasUnrealArtifact }]
96
+ ```
97
+
98
+ Reach for `priceMode: "any"` in `fab_search_assets` only when you mean to look at paid listings
99
+ the account does *not* own yet — buying is not something these tools can do for you.
100
+
101
+ Each item carries a `title` and an `id` — that `id` is the listing UID the next two tools take.
102
+ `fab_list_filters` returns the usable `formats`, `categories` and `tags` slugs; guessing them
103
+ silently narrows the search instead of erroring.
104
+
105
+ **2. Check the licence.** Search results carry **no licence** — Fab's search endpoint omits it, so
106
+ every item comes back with an empty `licenses` array. `fab_get_asset` is where the slugs live:
107
+
108
+ ```jsonc
109
+ { "listingIdOrUrl": "75f42402-40bb-4a1b-b557-18e2c9604273" }
110
+ // -> licenses: [{ slug: "personal" }, { slug: "professional" }], freeLicenseSlugs: [...]
111
+ ```
112
+
113
+ **3. Import.** `fab_import_asset` verifies the entitlement itself, downloads through the FabCLI
114
+ session, converts every static mesh, and writes source GLBs into your `assets/`:
115
+
116
+ ```jsonc
117
+ // fab_import_asset
118
+ {
119
+ "listingIdOrUrl": "https://www.fab.com/listings/<uid>",
120
+ "outputDir": "assets/fab/soul-cave",
121
+ "packages": ["SM_S_Soul_Statue"], // omit to convert every static mesh — packs run to gigabytes
122
+ "maxTextureSize": 2048, // omit to keep Unreal's own resolution
123
+ "acceptFabEula": true
124
+ }
125
+ ```
126
+
127
+ Then load the returned path the ordinary way:
128
+ `ctx.assets.model("fab/soul-cave/.../SM_S_Soul_Statue.glb")`. The normal asset compiler picks the
129
+ GLBs up from `assets/` with no extra configuration.
130
+
131
+ What the import will and will not do:
132
+
133
+ - **A pack of uncooked editor assets cannot be converted at all**, and this is the common case for
134
+ marketplace packs, which ship as Unreal *source* projects. Cooking is what writes the renderable
135
+ vertex and index buffers into the file; an uncooked package keeps only the editable source mesh
136
+ and lets the editor derive the rest, so there is no geometry for UE Viewer to read. The import
137
+ detects this and fails `UNREAL_SOURCE_UNCOOKED` naming the evidence it found —
138
+ `/Script/UnrealEd`, `AssetImportData`, `SourceModels`. **Believe it and stop.** No engine
139
+ version, `packages` filter or flag changes the answer, and the download is gigabytes each time
140
+ you try. The only route to those meshes is opening the pack in Unreal Editor and exporting FBX
141
+ or glTF yourself. Prefer a listing that ships a non-Unreal format, and treat one that does not as
142
+ a likely dead end before you spend the bandwidth.
143
+ - **A free listing still has to be in the library first.** `fab_import_asset` refuses with
144
+ `FABCLI_NOT_OWNED` until the listing is claimed, and it never claims — by design. Run
145
+ `fabcli claim <uid>`, which needs the interactive `fabcli auth login` session rather
146
+ than the API token `fabcli auth status` reports as authenticated. Note also that `fab_get_asset`
147
+ reports a free CC-BY offer as `isFree: false` with an empty `freeLicenseSlugs`; the listing
148
+ appearing in `fab_search_assets` with `priceMode: "free"` at `startingPrice.amount: 0` is the
149
+ reliable signal, so check the search before concluding a listing costs money.
150
+ - **Only assets you already own**, and only under **Fab Standard (Personal or Professional) or
151
+ CC-BY**. Unreal-Engine-only and legacy entitlements are refused, and a licence it cannot read is
152
+ refused too. The MCP never logs in, claims, or purchases. If FabCLI needs a session, the agent
153
+ must proactively run `fabcli auth login` and complete it through Claude browser or Codex's
154
+ `chrome:control-chrome`, reusing the user's active signed-in browser session. Never inspect,
155
+ copy, print, or persist cookies or tokens; interact with the login page instead.
156
+ Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
157
+ authenticated path it is guarding.
158
+ - **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
159
+ `THREENATIVE_TOOLCHAIN_AUTOINSTALL=0` to require you install them instead. Linux and Windows only.
160
+ - **`packages` is not optional in practice.** A marketplace pack converts to many gigabytes of
161
+ GLBs; name the handful of meshes your scene uses. Run it once without `packages` against a
162
+ scratch directory if you need to see what a pack contains, then re-run with the names.
163
+ - **Read `import-report.json` before trusting the result.** It reports `materials: "complete"` or
164
+ `"degraded"`, counts textured against total sections, and names every mesh it skipped and every
165
+ texture it could not map. Unreal shader graphs have no glTF equivalent, so some sections arrive
166
+ with a neutral grey and say so. `.umap` levels, Blueprints, Niagara and foliage placement are
167
+ reported as unsupported, never silently dropped.
168
+ - `asset_import_unreal` takes a local `sourceDir` instead of a listing, for a pack you already
169
+ downloaded by any means.
170
+
171
+ `fab_download_free_asset` is the unrelated older path: it downloads a directly-available free
172
+ `glb`/`fbx`/`obj`/`unity` file with no account at all. Use it when the listing already ships a
173
+ format you can load, and the importer only when it does not.
174
+
175
+ ## From a downloaded `.fbx` to a running character
176
+
177
+ An `.fbx`, `.blend`, `.obj` or `.dae` is not a file the runtime can load. Put it in your assets
178
+ directory anyway and the build converts it:
179
+
180
+ 1. Download it — `fab_download_free_asset`, `asset_import_unreal`, `asset_download_bundle_entry`,
181
+ or by hand.
182
+ 2. Write it into `assets/`, beside your `.glb` files. Nothing else to configure.
183
+ 3. Build. `compileAssets` classifies it as a model, converts it to GLB through Blender, then
184
+ optimizes it exactly like an authored GLB — skeleton, animation clips, materials and embedded
185
+ textures survive.
186
+ 4. Load it the ordinary way: `ctx.assets.model("hero")`.
187
+
188
+ **Blender must be installed**, and the framework never installs it for you. With no Blender the
189
+ build fails and names the install command for your platform — it does not copy the unusable file
190
+ through and report success. Ask the user before installing anything; it is roughly 350 MB.
191
+
192
+ The `threenative-blender` MCP server answers the rest:
193
+
194
+ - `blender_status` — can this machine convert at all? Never fails; with no Blender it returns
195
+ `available: false` and the install command. Call it first.
196
+ - `blender_inspect` — what is in this file? Mesh, triangle, vertex and bone counts, material
197
+ names, clip names, image names. Use it before committing a download.
198
+ - `blender_convert` — write a GLB somewhere other than the build's output. Zero meshes out is a
199
+ failure, never an empty GLB.
200
+ - `blender_recipes` — the shipped bpy recipes (`decimate`, `unwrap`, `bake_ao`, `retarget`) and
201
+ their **full source text**. Read one and adapt it; do not write bpy cold.
202
+ - `blender_run_python` — run a bpy script of your own. It is not a sandbox and does not claim to
203
+ be; it gives you a resolved Blender and the same fail-closed handling, not extra privilege.
204
+
205
+ ## The narrower tools
206
+
207
+ The directory spells out the conditions on each. The Fab tools are covered above; the server
208
+ never purchases anything on any path. `smithsonian_search_assets` returns museum scans at scan resolution, which this project has no
209
+ pipeline to decimate — that geometry is the wrong shape for a game. When in doubt check
210
+ `asset_search_sources` first; its `caution` and license fields are the current truth for the
211
+ pinned version, and they change between versions.
212
+
213
+ Load what you downloaded the ordinary way — `ctx.assets.model("crate.glb")`,
214
+ `ctx.assets.texture(...)`, `ctx.assets.audio(...)` — and write your own material and lighting
215
+ 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,40 @@
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** — read `agent-docs/dream-loop.md` and acquire one from
16
+ the user or an explicitly selected host/provider tool. Do not invent a reference: comparison
17
+ without evidence is unguided iteration.
18
+
19
+ For a full environment, split the decision: sculpt the signature landmark or bounded scene
20
+ kit that makes the reference recognisable; use the asset tools for interchangeable trees,
21
+ rocks, textures, HDRIs, and sounds around it. Do not sculpt an entire world as one object.
22
+
23
+ ## The gate loop
24
+
25
+ `.mcp.json` launches `threenative-sculpt-mcp` beside the asset server. It does not generate
26
+ or ship runtime code; it guides the source you write:
27
+
28
+ 1. Call `sculpt_plan` with the image path and a one-line intent, then read the returned
29
+ grimoire resources.
30
+ 2. Write the returned object contract and loop on `sculpt_spec_gate` until every named
31
+ region and depth requirement passes. Do not write geometry before this gate is green.
32
+ 3. For each ordered pass, write or extend one factory in `src/render/`. Capture the real
33
+ frame with `npx @threenative/playtest`; the sculpt server never launches a browser.
34
+ 4. Call `sculpt_compare` with the reference and captured frame, then give that evidence to
35
+ `sculpt_pass_gate`. Advance only when it says advance; ambiguity means retry.
36
+ 5. Use `sculpt_grimoire` for a named technique topic. It rejects pages containing concrete
37
+ paste-ready material or shader recipes so the tool never owns this game's look.
38
+
39
+ A missing or blank capture is a failed run, never a finished model. Add the reference image,
40
+ its creator, license, and source URL to `CREDITS.md` before the turn ends.
@@ -0,0 +1,99 @@
1
+ # Trace a slow frame — finding the function, not the percentile
2
+
3
+ `TN_FRAME_BUDGET` and `npx @threenative/playtest perf` tell you a frame was slow. They cannot tell
4
+ you what ran inside it. **A percentile says a frame was slow; a trace says which function.** This
5
+ page is the second half.
6
+
7
+ ## The rule
8
+
9
+ **Before you attribute a frame-rate or stutter complaint to any cause — and before you change one
10
+ line to fix one — run `npx @threenative/playtest trace --url <url> --text` and name the function
11
+ the trace blames.** Not "when performance looks bad": every time, before the first fix. If you
12
+ skipped it, you are guessing, and the report below is what guessing costs.
13
+
14
+ ## Why the rule exists
15
+
16
+ A game came in as "performance is not good, and after a while everything becomes blurry". Two
17
+ hypotheses were formed from the frame meters and both were wrong. One trace overturned them:
18
+
19
+ - **96 frames per second on average, frame-interval p50 8.2 ms.** The game was never slow on
20
+ average. Every statistic that reports a mean was hiding the complaint.
21
+ - **p99 50.3 ms, worst frame 267.9 ms, 28 main-thread tasks over 40 ms.** The pain was entirely in
22
+ the tail. Optimising the median would have moved nothing a player could feel.
23
+ - **GPU 31.5% busy, main thread 46.9% idle.** Neither triangle-bound nor CPU-saturated. An hour of
24
+ draw-call and triangle reduction was already underway and would have changed nothing.
25
+ - **Sampling inside the worst tasks named them**: TSL graph `build`, `analyze`, `_getChildren`,
26
+ plus two stalls at 86% and 97% *idle* where the main thread sat waiting on GPU pipeline
27
+ creation. That is shader compilation arriving during play — a completely different bug from any
28
+ of the three the numbers above had been read as.
29
+
30
+ ## Running it
31
+
32
+ ```sh
33
+ npx @threenative/playtest trace --url http://127.0.0.1:5173 --text
34
+ npx @threenative/playtest trace --url http://127.0.0.1:5173 --seconds 45 --key KeyW --key KeyD
35
+ ```
36
+
37
+ It launches the game headed with the WebGPU recipe, waits for the engine's startup-ready signal,
38
+ records for `--seconds` while holding the movement keys, writes the raw trace to disk, and prints
39
+ the summary. Defaults worth knowing:
40
+
41
+ | Flag | Default | Why it is there |
42
+ | --- | --- | --- |
43
+ | `--seconds <n>` | 20 | The traced window. Tail statistics need frames; under about 10 s a p99 is one sample. |
44
+ | `--key <KeyName>` | `KeyW` | Held for the whole window. Repeat for more keys. |
45
+ | `--no-input` | off | Traces a standing camera and warns. A parked viewpoint re-uses everything it drew last frame, which is how the first frame-rate number in this project came back nearly twice the truth. |
46
+ | `--wait-for <js>` | `globalThis.__TN_STARTUP_READY__ === true` | Trace the game, not the load. Point it at your own global if your game reveals its world later; `--no-wait` traces the load too and says so. |
47
+ | `--stall-ms <n>` | 40 | What counts as a blown frame in the task count. |
48
+ | `--out <path>` | `artifacts/traces/trace-<timestamp>.json` | Open this in Chrome DevTools' Performance panel when the summary points somewhere specific. |
49
+
50
+ Exit codes: **0** traced and quotable, **1** traced but part of the answer is missing or
51
+ untrustworthy (the reason is printed with a `TN_TRACE_` code), **2** no trace was recorded at all.
52
+
53
+ ## Reading the summary
54
+
55
+ Read it in this order, because each line rules out a whole class of fix:
56
+
57
+ 1. **Frame interval p50 / p90 / p99 / max.** If p50 is fine and p99 is not, the problem is hitches,
58
+ not throughput — and nothing that lowers average cost will fix it.
59
+ 2. **GPU busy %.** Low means the GPU is not the wall, so fewer triangles, fewer draws and cheaper
60
+ materials are all the wrong lane.
61
+ 3. **Main thread idle %.** High *and* a low GPU busy means the frame is waiting on something —
62
+ pipeline creation, a texture upload, a network read — not computing.
63
+ 4. **Tasks over the threshold.** The count and the worst few. This is the complaint, quantified.
64
+ 5. **Top self time.** The functions. This is the answer; everything above it narrows which answer
65
+ is plausible.
66
+
67
+ Only then open the raw trace file, and only if the summary points somewhere specific.
68
+
69
+ ## The trap that produces a confident wrong number
70
+
71
+ **A frame rate measured on a virtual display is wrong, not missing.** Under a private Xvfb there
72
+ is no vsync and no compositor, so the present wait lands inside the engine's `update` phase.
73
+ Measured on one build, same 12 s window, only `DISPLAY` differing:
74
+
75
+ | | Xvfb | real display |
76
+ | --- | ---: | ---: |
77
+ | fps | 13.3 | 57.7 |
78
+ | frame p50 | 68.5 ms | 8.5 ms |
79
+ | `update` p50 | **66.1 ms** | 1.0 ms |
80
+ | `render` p50 | 2.0 ms | 7.3 ms |
81
+
82
+ Read as a report, that is 66 ms of game CPU per frame, and it sends you looking for an expensive
83
+ loop in a frame callback. There is not one: a CPU profile over the same window came back **84%
84
+ idle**.
85
+
86
+ So `trace` refuses to print a frame rate when it detects a virtual display, and exits 1 saying so.
87
+ Set `TN_PLAYTEST_HOST_DISPLAY=1` to run on the real display and get a quotable one; pass
88
+ `--allow-virtual-display` to accept the function attribution alone and exit 0. The frame rate stays
89
+ suppressed either way — acknowledging the trap does not give the display a vsync.
90
+
91
+ The same command also refuses when WebGPU came from SwiftShader, Chromium's CPU rasteriser
92
+ (`TN_TRACE_SOFTWARE_ADAPTER`): a trace of software rendering names software rendering's functions.
93
+ `agent-docs/capture-the-frame.md` covers that adapter trap in full.
94
+
95
+ ## After the trace
96
+
97
+ Say what the trace blamed, in the report, with the number beside it. "Tail, not throughput: p50
98
+ 8.2 ms, p99 50.3 ms, 28 tasks over 40 ms; top self time is pipeline creation inside `build`" is a
99
+ finding. "Performance is better now" is not, and neither is a fix whose evidence is a mean.