create-threenative 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (588) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +61 -2
  3. package/agent-docs/references/assertion-reference.md +819 -0
  4. package/agent-docs/references/capability-reference.md +4483 -0
  5. package/agent-docs/references/capture-the-frame.md +60 -0
  6. package/agent-docs/references/creating-creatures.md +215 -0
  7. package/agent-docs/references/ctx-cookbook.md +120 -0
  8. package/agent-docs/references/debug-surface.md +68 -0
  9. package/agent-docs/references/dream-loop.md +150 -0
  10. package/agent-docs/references/finding-assets.md +215 -0
  11. package/agent-docs/references/gameplay-recipes.md +54 -0
  12. package/agent-docs/references/menu-screens.md +69 -0
  13. package/agent-docs/references/mobile-memory-budget.md +87 -0
  14. package/agent-docs/references/sculpt-from-a-reference.md +40 -0
  15. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  16. package/agent-docs/references/visual-baseline.md +174 -0
  17. package/agent-docs/references/webview-ui.md +113 -0
  18. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  19. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  20. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  21. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  22. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  23. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  24. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  25. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  26. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  27. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  28. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  29. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  30. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  31. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  32. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  33. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  34. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  35. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  36. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  37. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  38. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  39. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  40. package/agent-files/.threenative/agents/builder.md +32 -0
  41. package/agent-files/.threenative/agents/verifier.md +31 -0
  42. package/agent-files/AGENT-ROLES.md +26 -0
  43. package/agent-files/scripts/reference.mjs +705 -0
  44. package/agent-files/scripts/visual-loop.mjs +382 -0
  45. package/capabilities.json +5292 -0
  46. package/dist/index.d.ts +224 -3
  47. package/dist/index.js +1972 -73
  48. package/dist/threenative.d.ts +9 -2
  49. package/dist/threenative.js +2570 -176
  50. package/package.json +55 -6
  51. package/template-assets/icon.png +0 -0
  52. package/template-assets/loading.ts +325 -0
  53. package/template-assets/patches/three@0.185.1.patch +522 -0
  54. package/template-assets/worldEnvironment.ts +758 -0
  55. package/templates/action-rpg/.codex/config.toml +19 -0
  56. package/templates/action-rpg/.cursor/mcp.json +32 -0
  57. package/templates/action-rpg/.gemini/settings.json +32 -0
  58. package/templates/action-rpg/.mcp.json +18 -2
  59. package/templates/action-rpg/.vscode/mcp.json +36 -0
  60. package/templates/action-rpg/.zed/settings.json +36 -0
  61. package/templates/action-rpg/AGENTS.md +84 -29
  62. package/templates/action-rpg/CLAUDE.md +84 -29
  63. package/templates/action-rpg/index.html +0 -1
  64. package/templates/action-rpg/opencode.json +41 -0
  65. package/templates/action-rpg/package.json +15 -11
  66. package/templates/action-rpg/playtests/combat.playtest.json +32 -9
  67. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  68. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  69. package/templates/action-rpg/playtests/performance.playtest.json +39 -0
  70. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  71. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  72. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  73. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  74. package/templates/action-rpg/src/conventions.ts +35 -0
  75. package/templates/action-rpg/src/entities/Enemy.ts +16 -7
  76. package/templates/action-rpg/src/entities/Player.ts +20 -3
  77. package/templates/action-rpg/src/game.ts +21 -0
  78. package/templates/action-rpg/src/render/camera.ts +7 -2
  79. package/templates/action-rpg/src/render/lighting.ts +11 -4
  80. package/templates/action-rpg/src/render/loading.ts +278 -43
  81. package/templates/action-rpg/src/render/materials.ts +11 -0
  82. package/templates/action-rpg/src/render/palette.ts +10 -3
  83. package/templates/action-rpg/src/render/postprocessing.ts +32 -16
  84. package/templates/action-rpg/src/render/quality.ts +170 -0
  85. package/templates/action-rpg/src/render/shapes.ts +185 -26
  86. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  87. package/templates/action-rpg/src/render/vfx.ts +257 -0
  88. package/templates/action-rpg/src/render/worldEnvironment.ts +758 -0
  89. package/templates/action-rpg/src/scenes/Play.ts +91 -24
  90. package/templates/action-rpg/src/state.ts +4 -0
  91. package/templates/action-rpg/src/style.css +65 -1
  92. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  93. package/templates/action-rpg/src/ui/App.tsx +9 -8
  94. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  95. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  96. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  97. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  98. package/templates/action-rpg/src/ui/main.tsx +14 -0
  99. package/templates/action-rpg/threenative.config.ts +28 -8
  100. package/templates/action-rpg/vite.config.ts +32 -2
  101. package/templates/defense/.codex/config.toml +19 -0
  102. package/templates/defense/.cursor/mcp.json +32 -0
  103. package/templates/defense/.gemini/settings.json +32 -0
  104. package/templates/defense/.mcp.json +18 -2
  105. package/templates/defense/.vscode/mcp.json +36 -0
  106. package/templates/defense/.zed/settings.json +36 -0
  107. package/templates/defense/AGENTS.md +81 -41
  108. package/templates/defense/CLAUDE.md +81 -41
  109. package/templates/defense/README.md +2 -1
  110. package/templates/defense/index.html +0 -1
  111. package/templates/defense/opencode.json +41 -0
  112. package/templates/defense/package.json +16 -12
  113. package/templates/defense/playtests/leak.playtest.json +9 -4
  114. package/templates/defense/playtests/performance.playtest.json +39 -0
  115. package/templates/defense/playtests/placement.playtest.json +5 -5
  116. package/templates/defense/playtests/pointer-placement.playtest.json +156 -0
  117. package/templates/defense/playtests/scan.playtest.json +4 -4
  118. package/templates/defense/playtests/survive.playtest.json +25 -6
  119. package/templates/defense/src/attackers/Attacker.ts +32 -16
  120. package/templates/defense/src/board/Route.ts +22 -8
  121. package/templates/defense/src/conventions.ts +18 -0
  122. package/templates/defense/src/entities/Player.ts +11 -3
  123. package/templates/defense/src/game.ts +25 -4
  124. package/templates/defense/src/physics.ts +9 -39
  125. package/templates/defense/src/placement/Buildable.ts +4 -4
  126. package/templates/defense/src/render/camera.ts +9 -3
  127. package/templates/defense/src/render/lighting.ts +6 -1
  128. package/templates/defense/src/render/loading.ts +274 -38
  129. package/templates/defense/src/render/materials.ts +9 -0
  130. package/templates/defense/src/render/palette.ts +12 -5
  131. package/templates/defense/src/render/postprocessing.ts +32 -12
  132. package/templates/defense/src/render/quality.ts +170 -0
  133. package/templates/defense/src/render/shapes.ts +180 -23
  134. package/templates/defense/src/render/sky.ts +2 -2
  135. package/templates/defense/src/render/worldEnvironment.ts +758 -0
  136. package/templates/defense/src/scenes/Boot.ts +2 -2
  137. package/templates/defense/src/scenes/Defense.ts +122 -56
  138. package/templates/defense/src/state.ts +6 -0
  139. package/templates/defense/src/style.css +65 -1
  140. package/templates/defense/src/towers/Tower.ts +11 -12
  141. package/templates/defense/src/towers/targeting.ts +1 -1
  142. package/templates/defense/src/ui/App.tsx +11 -6
  143. package/templates/defense/src/ui/GameUi.tsx +20 -0
  144. package/templates/defense/src/ui/Hud.tsx +6 -5
  145. package/templates/defense/src/ui/main.tsx +14 -0
  146. package/templates/defense/threenative.config.ts +28 -8
  147. package/templates/defense/vite.config.ts +34 -1
  148. package/templates/minimal/.codex/config.toml +19 -0
  149. package/templates/minimal/.cursor/mcp.json +32 -0
  150. package/templates/minimal/.gemini/settings.json +32 -0
  151. package/templates/minimal/.mcp.json +18 -2
  152. package/templates/minimal/.vscode/mcp.json +36 -0
  153. package/templates/minimal/.zed/settings.json +36 -0
  154. package/templates/minimal/AGENTS.md +78 -382
  155. package/templates/minimal/CLAUDE.md +78 -382
  156. package/templates/minimal/index.html +0 -1
  157. package/templates/minimal/opencode.json +41 -0
  158. package/templates/minimal/package.json +14 -11
  159. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  160. package/templates/minimal/playtests/play.playtest.json +18 -5
  161. package/templates/minimal/playtests/survives.playtest.json +48 -4
  162. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  163. package/templates/minimal/src/conventions.ts +18 -0
  164. package/templates/minimal/src/entities/Player.ts +39 -6
  165. package/templates/minimal/src/game.ts +1 -0
  166. package/templates/minimal/src/main.ts +14 -4
  167. package/templates/minimal/src/render/camera.ts +1 -1
  168. package/templates/minimal/src/render/hud.ts +24 -8
  169. package/templates/minimal/src/render/lighting.ts +23 -2
  170. package/templates/minimal/src/render/loading.ts +23 -103
  171. package/templates/minimal/src/render/materials.ts +7 -0
  172. package/templates/minimal/src/render/palette.ts +3 -3
  173. package/templates/minimal/src/render/postprocessing.ts +55 -16
  174. package/templates/minimal/src/render/quality.ts +162 -0
  175. package/templates/minimal/src/render/sky.ts +51 -32
  176. package/templates/minimal/src/render/touch-controls.ts +165 -0
  177. package/templates/minimal/src/render/worldEnvironment.ts +758 -0
  178. package/templates/minimal/src/scenes/Play.ts +128 -14
  179. package/templates/minimal/src/state.ts +8 -1
  180. package/templates/minimal/src/style.css +20 -0
  181. package/templates/minimal/threenative.config.ts +22 -10
  182. package/templates/minimal/vite.config.ts +28 -1
  183. package/templates/platformer/.codex/config.toml +19 -0
  184. package/templates/platformer/.cursor/mcp.json +32 -0
  185. package/templates/platformer/.gemini/settings.json +32 -0
  186. package/templates/platformer/.mcp.json +18 -2
  187. package/templates/platformer/.vscode/mcp.json +36 -0
  188. package/templates/platformer/.zed/settings.json +36 -0
  189. package/templates/platformer/AGENTS.md +81 -186
  190. package/templates/platformer/CLAUDE.md +81 -186
  191. package/templates/platformer/index.html +0 -1
  192. package/templates/platformer/opencode.json +41 -0
  193. package/templates/platformer/package.json +17 -14
  194. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  195. package/templates/platformer/playtests/branding.playtest.json +29 -0
  196. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  197. package/templates/platformer/playtests/collect.playtest.json +1 -1
  198. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  199. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  200. package/templates/platformer/playtests/damage.playtest.json +4 -1
  201. package/templates/platformer/playtests/dash.playtest.json +2 -2
  202. package/templates/platformer/playtests/jump.playtest.json +2 -3
  203. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  204. package/templates/platformer/playtests/oneway.playtest.json +30 -3
  205. package/templates/platformer/playtests/performance.playtest.json +7 -5
  206. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  207. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  208. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  209. package/templates/platformer/playtests/survives.playtest.json +31 -0
  210. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +16 -4
  211. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  212. package/templates/platformer/playtests/touch-controls-web.playtest.json +57 -0
  213. package/templates/platformer/src/conventions.ts +18 -0
  214. package/templates/platformer/src/entities/Character.ts +79 -11
  215. package/templates/platformer/src/entities/Patrol.ts +5 -0
  216. package/templates/platformer/src/game.ts +27 -2
  217. package/templates/platformer/src/level/Platform.ts +13 -1
  218. package/templates/platformer/src/render/lighting.ts +13 -5
  219. package/templates/platformer/src/render/loading.ts +281 -62
  220. package/templates/platformer/src/render/palette.ts +4 -1
  221. package/templates/platformer/src/render/postprocessing.ts +42 -14
  222. package/templates/platformer/src/render/quality.ts +170 -0
  223. package/templates/platformer/src/render/touch-controls.ts +54 -36
  224. package/templates/platformer/src/render/worldEnvironment.ts +758 -0
  225. package/templates/platformer/src/scenes/Level.ts +97 -32
  226. package/templates/platformer/src/state.ts +4 -0
  227. package/templates/platformer/src/style.css +65 -1
  228. package/templates/platformer/src/ui/App.tsx +9 -4
  229. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  230. package/templates/platformer/src/ui/Hud.tsx +6 -5
  231. package/templates/platformer/src/ui/main.tsx +14 -0
  232. package/templates/platformer/threenative.config.ts +27 -10
  233. package/templates/platformer/vite.config.ts +34 -1
  234. package/templates/puzzle/.codex/config.toml +19 -0
  235. package/templates/puzzle/.cursor/mcp.json +32 -0
  236. package/templates/puzzle/.gemini/settings.json +32 -0
  237. package/templates/puzzle/.mcp.json +32 -0
  238. package/templates/puzzle/.vscode/mcp.json +36 -0
  239. package/templates/puzzle/.zed/settings.json +36 -0
  240. package/templates/puzzle/AGENTS.md +96 -0
  241. package/templates/puzzle/CLAUDE.md +98 -0
  242. package/templates/puzzle/README.md +43 -0
  243. package/templates/puzzle/index.html +12 -0
  244. package/templates/puzzle/kit.json +7 -0
  245. package/templates/puzzle/opencode.json +41 -0
  246. package/templates/puzzle/package.json +50 -0
  247. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  248. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  249. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  250. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  251. package/templates/puzzle/public/favicon.svg +5 -0
  252. package/templates/puzzle/src/conventions.ts +25 -0
  253. package/templates/puzzle/src/entities/Ball.ts +70 -0
  254. package/templates/puzzle/src/entities/Crate.ts +76 -0
  255. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  256. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  257. package/templates/puzzle/src/game.ts +48 -0
  258. package/templates/puzzle/src/main.ts +15 -0
  259. package/templates/puzzle/src/physics.ts +19 -0
  260. package/templates/puzzle/src/render/camera.ts +37 -0
  261. package/templates/puzzle/src/render/lighting.ts +55 -0
  262. package/templates/puzzle/src/render/loading.ts +325 -0
  263. package/templates/puzzle/src/render/materials.ts +28 -0
  264. package/templates/puzzle/src/render/palette.ts +31 -0
  265. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  266. package/templates/puzzle/src/render/quality.ts +170 -0
  267. package/templates/puzzle/src/render/shapes.ts +134 -0
  268. package/templates/puzzle/src/render/sky.ts +16 -0
  269. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  270. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  271. package/templates/puzzle/src/room.ts +83 -0
  272. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  273. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  274. package/templates/puzzle/src/state.ts +30 -0
  275. package/templates/puzzle/src/style.css +96 -0
  276. package/templates/puzzle/src/ui/App.tsx +22 -0
  277. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  278. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  279. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  280. package/templates/puzzle/src/ui/main.tsx +14 -0
  281. package/templates/puzzle/tailwind.config.ts +1 -0
  282. package/templates/puzzle/threenative.config.ts +49 -0
  283. package/templates/puzzle/tsconfig.json +17 -0
  284. package/templates/puzzle/vite.config.ts +38 -0
  285. package/templates/racing/.codex/config.toml +19 -0
  286. package/templates/racing/.cursor/mcp.json +32 -0
  287. package/templates/racing/.gemini/settings.json +32 -0
  288. package/templates/racing/.mcp.json +18 -2
  289. package/templates/racing/.vscode/mcp.json +36 -0
  290. package/templates/racing/.zed/settings.json +36 -0
  291. package/templates/racing/AGENTS.md +84 -36
  292. package/templates/racing/CLAUDE.md +84 -36
  293. package/templates/racing/index.html +0 -1
  294. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  295. package/templates/racing/opencode.json +41 -0
  296. package/templates/racing/package.json +17 -12
  297. package/templates/racing/playtests/boost.playtest.json +5 -5
  298. package/templates/racing/playtests/outcome.playtest.json +14 -4
  299. package/templates/racing/playtests/performance.playtest.json +39 -0
  300. package/templates/racing/playtests/ranking.playtest.json +2 -2
  301. package/templates/racing/playtests/rescue.playtest.json +12 -6
  302. package/templates/racing/playtests/reverse.playtest.json +3 -3
  303. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  304. package/templates/racing/playtests/survives.playtest.json +36 -4
  305. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  306. package/templates/racing/src/conventions.ts +6 -0
  307. package/templates/racing/src/entities/RacingCar.ts +16 -4
  308. package/templates/racing/src/entities/Rival.ts +5 -2
  309. package/templates/racing/src/game.ts +24 -1
  310. package/templates/racing/src/render/camera.ts +15 -8
  311. package/templates/racing/src/render/lighting.ts +28 -14
  312. package/templates/racing/src/render/loading.ts +302 -35
  313. package/templates/racing/src/render/materials.ts +54 -4
  314. package/templates/racing/src/render/palette.ts +23 -6
  315. package/templates/racing/src/render/postprocessing.ts +32 -12
  316. package/templates/racing/src/render/quality.ts +170 -0
  317. package/templates/racing/src/render/shapes.ts +537 -26
  318. package/templates/racing/src/render/sky.ts +5 -2
  319. package/templates/racing/src/render/touch-controls.ts +185 -0
  320. package/templates/racing/src/render/worldEnvironment.ts +758 -0
  321. package/templates/racing/src/scenes/Race.ts +84 -37
  322. package/templates/racing/src/state.ts +4 -0
  323. package/templates/racing/src/style.css +65 -1
  324. package/templates/racing/src/track/Lap.ts +20 -9
  325. package/templates/racing/src/track/Ranking.ts +53 -14
  326. package/templates/racing/src/track/Track.ts +284 -32
  327. package/templates/racing/src/track/TrackSector.ts +14 -4
  328. package/templates/racing/src/ui/App.tsx +9 -4
  329. package/templates/racing/src/ui/GameUi.tsx +20 -0
  330. package/templates/racing/src/ui/Hud.tsx +6 -5
  331. package/templates/racing/src/ui/main.tsx +14 -0
  332. package/templates/racing/threenative.config.ts +28 -8
  333. package/templates/racing/vite.config.ts +34 -1
  334. package/templates/runner/.codex/config.toml +19 -0
  335. package/templates/runner/.cursor/mcp.json +32 -0
  336. package/templates/runner/.gemini/settings.json +32 -0
  337. package/templates/runner/.mcp.json +32 -0
  338. package/templates/runner/.vscode/mcp.json +36 -0
  339. package/templates/runner/.zed/settings.json +36 -0
  340. package/templates/runner/AGENTS.md +96 -0
  341. package/templates/runner/CLAUDE.md +98 -0
  342. package/templates/runner/README.md +43 -0
  343. package/templates/runner/index.html +12 -0
  344. package/templates/runner/kit.json +7 -0
  345. package/templates/runner/opencode.json +41 -0
  346. package/templates/runner/package.json +50 -0
  347. package/templates/runner/playtests/performance.playtest.json +23 -0
  348. package/templates/runner/playtests/streams.playtest.json +38 -0
  349. package/templates/runner/playtests/survives.playtest.json +51 -0
  350. package/templates/runner/public/favicon.svg +5 -0
  351. package/templates/runner/src/conventions.ts +24 -0
  352. package/templates/runner/src/entities/Runner.ts +135 -0
  353. package/templates/runner/src/game.ts +50 -0
  354. package/templates/runner/src/main.ts +15 -0
  355. package/templates/runner/src/physics.ts +13 -0
  356. package/templates/runner/src/render/camera.ts +39 -0
  357. package/templates/runner/src/render/dust.ts +131 -0
  358. package/templates/runner/src/render/lighting.ts +57 -0
  359. package/templates/runner/src/render/loading.ts +325 -0
  360. package/templates/runner/src/render/materials.ts +27 -0
  361. package/templates/runner/src/render/palette.ts +30 -0
  362. package/templates/runner/src/render/postprocessing.ts +34 -0
  363. package/templates/runner/src/render/quality.ts +170 -0
  364. package/templates/runner/src/render/shapes.ts +68 -0
  365. package/templates/runner/src/render/sky.ts +51 -0
  366. package/templates/runner/src/render/touch-controls.ts +185 -0
  367. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  368. package/templates/runner/src/scenes/Boot.ts +12 -0
  369. package/templates/runner/src/scenes/Run.ts +142 -0
  370. package/templates/runner/src/state.ts +29 -0
  371. package/templates/runner/src/style.css +96 -0
  372. package/templates/runner/src/track.ts +176 -0
  373. package/templates/runner/src/ui/App.tsx +22 -0
  374. package/templates/runner/src/ui/GameUi.tsx +20 -0
  375. package/templates/runner/src/ui/Hud.tsx +55 -0
  376. package/templates/runner/src/ui/Menu.tsx +7 -0
  377. package/templates/runner/src/ui/main.tsx +14 -0
  378. package/templates/runner/tailwind.config.ts +1 -0
  379. package/templates/runner/threenative.config.ts +49 -0
  380. package/templates/runner/tsconfig.json +17 -0
  381. package/templates/runner/vite.config.ts +38 -0
  382. package/templates/sailing/.codex/config.toml +19 -0
  383. package/templates/sailing/.cursor/mcp.json +32 -0
  384. package/templates/sailing/.gemini/settings.json +32 -0
  385. package/templates/sailing/.mcp.json +32 -0
  386. package/templates/sailing/.vscode/mcp.json +36 -0
  387. package/templates/sailing/.zed/settings.json +36 -0
  388. package/templates/sailing/AGENTS.md +95 -0
  389. package/templates/sailing/CLAUDE.md +97 -0
  390. package/templates/sailing/README.md +28 -0
  391. package/templates/sailing/index.html +12 -0
  392. package/templates/sailing/kit.json +7 -0
  393. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  394. package/templates/sailing/native-playtests/survives.playtest.json +38 -0
  395. package/templates/sailing/opencode.json +41 -0
  396. package/templates/sailing/package.json +52 -0
  397. package/templates/sailing/playtests/fail.playtest.json +24 -0
  398. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  399. package/templates/sailing/playtests/float.playtest.json +59 -0
  400. package/templates/sailing/playtests/performance.playtest.json +36 -0
  401. package/templates/sailing/playtests/survives.playtest.json +46 -0
  402. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  403. package/templates/sailing/playtests/win.playtest.json +31 -0
  404. package/templates/sailing/public/favicon.svg +5 -0
  405. package/templates/sailing/src/conventions.ts +8 -0
  406. package/templates/sailing/src/entities/Ship.ts +233 -0
  407. package/templates/sailing/src/game.ts +40 -0
  408. package/templates/sailing/src/main.ts +15 -0
  409. package/templates/sailing/src/render/camera.ts +28 -0
  410. package/templates/sailing/src/render/lighting.ts +41 -0
  411. package/templates/sailing/src/render/loading.ts +325 -0
  412. package/templates/sailing/src/render/materials.ts +44 -0
  413. package/templates/sailing/src/render/ocean.ts +179 -0
  414. package/templates/sailing/src/render/palette.ts +17 -0
  415. package/templates/sailing/src/render/postprocessing.ts +34 -0
  416. package/templates/sailing/src/render/props.ts +602 -0
  417. package/templates/sailing/src/render/quality.ts +140 -0
  418. package/templates/sailing/src/render/sky.ts +37 -0
  419. package/templates/sailing/src/render/touch-controls.ts +142 -0
  420. package/templates/sailing/src/render/worldEnvironment.ts +758 -0
  421. package/templates/sailing/src/scenes/Boot.ts +12 -0
  422. package/templates/sailing/src/scenes/Sailing.ts +133 -0
  423. package/templates/sailing/src/state.ts +10 -0
  424. package/templates/sailing/src/style.css +81 -0
  425. package/templates/sailing/src/ui/App.tsx +15 -0
  426. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  427. package/templates/sailing/src/ui/Hud.tsx +55 -0
  428. package/templates/sailing/src/ui/Menu.tsx +30 -0
  429. package/templates/sailing/src/ui/main.tsx +7 -0
  430. package/templates/sailing/tailwind.config.ts +2 -0
  431. package/templates/sailing/threenative.config.ts +40 -0
  432. package/templates/sailing/tsconfig.json +17 -0
  433. package/templates/sailing/vite.config.ts +34 -0
  434. package/templates/shooter/.codex/config.toml +19 -0
  435. package/templates/shooter/.cursor/mcp.json +32 -0
  436. package/templates/shooter/.gemini/settings.json +32 -0
  437. package/templates/shooter/.mcp.json +18 -2
  438. package/templates/shooter/.vscode/mcp.json +36 -0
  439. package/templates/shooter/.zed/settings.json +36 -0
  440. package/templates/shooter/AGENTS.md +81 -54
  441. package/templates/shooter/CLAUDE.md +81 -54
  442. package/templates/shooter/index.html +0 -1
  443. package/templates/shooter/kit.json +2 -2
  444. package/templates/shooter/opencode.json +41 -0
  445. package/templates/shooter/package.json +16 -11
  446. package/templates/shooter/playtests/combat.playtest.json +48 -0
  447. package/templates/shooter/playtests/fail.playtest.json +5 -4
  448. package/templates/shooter/playtests/input-control.playtest.json +261 -0
  449. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  450. package/templates/shooter/playtests/performance.playtest.json +39 -0
  451. package/templates/shooter/playtests/shooter.playtest.json +31 -21
  452. package/templates/shooter/playtests/survives.playtest.json +28 -1
  453. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  454. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  455. package/templates/shooter/public/favicon.svg +1 -1
  456. package/templates/shooter/src/combat/damage.ts +1 -2
  457. package/templates/shooter/src/conventions.ts +51 -0
  458. package/templates/shooter/src/entities/Player.ts +235 -18
  459. package/templates/shooter/src/entities/Target.ts +2 -2
  460. package/templates/shooter/src/game.ts +35 -3
  461. package/templates/shooter/src/main.ts +3 -13
  462. package/templates/shooter/src/render/camera.ts +78 -18
  463. package/templates/shooter/src/render/decals.ts +211 -0
  464. package/templates/shooter/src/render/lighting.ts +13 -4
  465. package/templates/shooter/src/render/loading.ts +274 -35
  466. package/templates/shooter/src/render/materials.ts +56 -3
  467. package/templates/shooter/src/render/palette.ts +6 -3
  468. package/templates/shooter/src/render/postprocessing.ts +32 -17
  469. package/templates/shooter/src/render/quality.ts +170 -0
  470. package/templates/shooter/src/render/scale.ts +22 -0
  471. package/templates/shooter/src/render/shapes.ts +519 -60
  472. package/templates/shooter/src/render/sky.ts +5 -1
  473. package/templates/shooter/src/render/touch-controls.ts +305 -0
  474. package/templates/shooter/src/render/ui.css +119 -1
  475. package/templates/shooter/src/render/ui.ts +19 -3
  476. package/templates/shooter/src/render/vfx.ts +215 -0
  477. package/templates/shooter/src/render/worldEnvironment.ts +758 -0
  478. package/templates/shooter/src/scenes/Play.ts +385 -97
  479. package/templates/shooter/src/state.ts +18 -0
  480. package/templates/shooter/src/style.css +46 -0
  481. package/templates/shooter/src/ui/App.tsx +10 -12
  482. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  483. package/templates/shooter/src/ui/GameUi.tsx +22 -0
  484. package/templates/shooter/src/ui/Hud.tsx +14 -10
  485. package/templates/shooter/src/ui/Menu.tsx +24 -9
  486. package/templates/shooter/src/ui/main.tsx +15 -0
  487. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  488. package/templates/shooter/src/weapons/Projectile.ts +29 -13
  489. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  490. package/templates/shooter/threenative.config.ts +28 -8
  491. package/templates/shooter/vite.config.ts +32 -2
  492. package/templates/starter/.codex/config.toml +19 -0
  493. package/templates/starter/.cursor/mcp.json +32 -0
  494. package/templates/starter/.gemini/settings.json +32 -0
  495. package/templates/starter/.mcp.json +18 -2
  496. package/templates/starter/.vscode/mcp.json +36 -0
  497. package/templates/starter/.zed/settings.json +36 -0
  498. package/templates/starter/AGENTS.md +72 -426
  499. package/templates/starter/CLAUDE.md +72 -426
  500. package/templates/starter/assets/pickup.wav +0 -0
  501. package/templates/starter/gitignore +4 -0
  502. package/templates/starter/index.html +0 -1
  503. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  504. package/templates/starter/native-playtests/render-chain.playtest.json +81 -0
  505. package/templates/starter/opencode.json +41 -0
  506. package/templates/starter/package.json +16 -12
  507. package/templates/starter/playtests/assets.playtest.json +65 -0
  508. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  509. package/templates/starter/playtests/buffer.playtest.json +59 -9
  510. package/templates/starter/playtests/cloth.playtest.json +113 -0
  511. package/templates/starter/playtests/coyote.playtest.json +60 -8
  512. package/templates/starter/playtests/forward.playtest.json +29 -4
  513. package/templates/starter/playtests/gameover.playtest.json +66 -0
  514. package/templates/starter/playtests/goal.playtest.json +67 -0
  515. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  516. package/templates/starter/playtests/look.playtest.json +142 -10
  517. package/templates/starter/playtests/models-baseline.png +0 -0
  518. package/templates/starter/playtests/models.playtest.json +74 -0
  519. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  520. package/templates/starter/playtests/odometer.playtest.json +54 -0
  521. package/templates/starter/playtests/pause.playtest.json +27 -4
  522. package/templates/starter/playtests/play.playtest.json +44 -7
  523. package/templates/starter/playtests/respawn.playtest.json +46 -6
  524. package/templates/starter/playtests/restart.playtest.json +65 -10
  525. package/templates/starter/playtests/seed.playtest.json +44 -8
  526. package/templates/starter/playtests/survives.playtest.json +48 -4
  527. package/templates/starter/playtests/textures-baseline.png +0 -0
  528. package/templates/starter/playtests/textures.playtest.json +74 -0
  529. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  530. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  531. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  532. package/templates/starter/src/conventions.ts +18 -0
  533. package/templates/starter/src/entities/Goal.ts +137 -0
  534. package/templates/starter/src/entities/Player.ts +111 -10
  535. package/templates/starter/src/game.ts +27 -0
  536. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  537. package/templates/starter/src/render/camera.ts +31 -5
  538. package/templates/starter/src/render/coast.ts +199 -0
  539. package/templates/starter/src/render/easing.ts +5 -0
  540. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  541. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  542. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  543. package/templates/starter/src/render/hero.ts +88 -0
  544. package/templates/starter/src/render/implicitSurface.ts +199 -0
  545. package/templates/starter/src/render/kuwahara.ts +174 -0
  546. package/templates/starter/src/render/lighting.ts +10 -5
  547. package/templates/starter/src/render/loading.ts +325 -0
  548. package/templates/starter/src/render/materials.ts +39 -4
  549. package/templates/starter/src/render/outline.ts +141 -0
  550. package/templates/starter/src/render/painterly.ts +86 -0
  551. package/templates/starter/src/render/palette.ts +15 -6
  552. package/templates/starter/src/render/pennant.ts +54 -0
  553. package/templates/starter/src/render/postprocessing.ts +97 -15
  554. package/templates/starter/src/render/quality.ts +185 -0
  555. package/templates/starter/src/render/rockRidge.ts +198 -0
  556. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  557. package/templates/starter/src/render/scenery.ts +40 -0
  558. package/templates/starter/src/render/shapes.ts +9 -21
  559. package/templates/starter/src/render/textureLifetime.ts +53 -0
  560. package/templates/starter/src/render/touch-controls.ts +165 -0
  561. package/templates/starter/src/render/water.ts +38 -0
  562. package/templates/starter/src/render/watercolor.ts +85 -0
  563. package/templates/starter/src/render/worldEnvironment.ts +758 -0
  564. package/templates/starter/src/scenes/Play.ts +243 -46
  565. package/templates/starter/src/state.ts +12 -0
  566. package/templates/starter/src/style.css +72 -8
  567. package/templates/starter/src/ui/App.tsx +9 -6
  568. package/templates/starter/src/ui/GameUi.tsx +20 -0
  569. package/templates/starter/src/ui/Hud.tsx +52 -29
  570. package/templates/starter/src/ui/Menu.tsx +25 -23
  571. package/templates/starter/src/ui/main.tsx +14 -0
  572. package/templates/starter/threenative.config.ts +27 -9
  573. package/templates/starter/tools/look.mjs +109 -0
  574. package/templates/starter/vite.config.ts +32 -2
  575. package/templates/action-rpg/src/physics.ts +0 -40
  576. package/templates/minimal/assets/.gitkeep +0 -0
  577. package/templates/minimal/public/.gitkeep +0 -0
  578. package/templates/minimal/public/icon.png +0 -0
  579. package/templates/platformer/assets/.gitkeep +0 -0
  580. package/templates/platformer/public/.gitkeep +0 -0
  581. package/templates/platformer/public/icon.png +0 -0
  582. package/templates/shooter/src/physics.ts +0 -49
  583. package/templates/starter/assets/.gitkeep +0 -0
  584. package/templates/starter/public/.gitkeep +0 -0
  585. package/templates/starter/public/icon.png +0 -0
  586. package/templates/starter/public/pickup.ogg +0 -0
  587. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  588. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -1,452 +1,98 @@
1
1
  <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
2
 
3
- # AGENTS.md — __PROJECT_NAME__
3
+ # AGENTS.md — __PROJECT_NAME__ starter
4
4
 
5
- Instructions for the AI agent working in this game. This project was scaffolded with
6
- `create-threenative`. `CLAUDE.md` is a copy of this file; edit this one.
5
+ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
7
6
 
8
- ## What the framework owns, and what you own
7
+ ## Ownership
9
8
 
10
- ThreeNative owns the plumbing: renderer bootstrap and WebGPU fallback, the fixed-step loop,
11
- scene lifecycle, input mapping, asset loading, the physics binding, and the state bridge to
12
- React.
9
+ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
10
+ `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`.
13
11
 
14
- **You own everything a player sees.** `src/render/`, `src/entities/`, `src/scenes/`, and
15
- `src/ui/` are ordinary code in this repository. Nothing in `@threenative/*` reads them.
16
- Rewrite or delete any of it.
12
+ ## Start every change
17
13
 
18
- ## Commands
14
+ 1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
+ `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan.
17
+ 2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
+ direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
+ 3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
20
+ use returned subpaths and `attachToBone` rather than rebuilding installed systems.
21
+ 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` enables continuous collision by default; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
19
22
 
20
- ```sh
21
- pnpm dev # Vite dev server
22
- pnpm studio # chat, preview and proof in one page; needs claude or codex
23
- pnpm build # web build; identical to vite build
24
- pnpm build --target desktop # native executable; Linux is the only verified host
25
- pnpm test # build, start the dev server, and run the committed playtest
26
- ```
27
-
28
- The normal `@threenative/physics` API selects native Rapier on Android; its source-workspace
29
- APK and emulator scenario are proven without Rapier WASM. A published scaffold still cannot
30
- ship Android or iOS until signed prebuilt runtime assets and their checksum manifest exist,
31
- so those targets fail closed for consumers. Linux desktop is source-machine evidence, not a
32
- clean-machine distribution proof; macOS, Windows, iOS, and physical hardware remain OPEN.
33
-
34
- ## Keep the game portable to native
35
-
36
- `pnpm build --target desktop` runs this same source on a native host with **no browser**.
37
- Four things break there, and none of them fail on the web build:
38
-
39
- 1. **The native host has no DOM and does not run React.** The starter's single HUD is the
40
- web-only `src/ui/Hud.tsx`; native builds ship `src/scenes/` and `src/render/` without
41
- `src/ui/`. Gameplay, scoring and state transitions live in the scene; add a native HUD in
42
- your game-owned render code only if your game needs one.
43
- 2. **No `document`, `window`, or `localStorage` reach outside the canvas.** Use `ctx` and
44
- Three.js. Save games go through your own JSON, not `window.localStorage` directly.
45
- 3. **No dynamic `import()`.** The native build is one bundled file.
46
- 4. **`.raw` is web-only.** `ctx.physics.world.raw` is a Rapier object in the browser and
47
- opaque on native. Anything reading it is a web-only code path by contract.
48
-
49
- Writing against `ctx`, `three`, and the Godot-named physics nodes keeps all four correct
50
- without thinking about it. If you only ever ship to the web, ignore this section.
51
-
52
- ## The layout
53
-
54
- ```mermaid
55
- flowchart TD
56
- project["generated project"]
57
- src["src/"]
58
- main["main.ts<br/>defineGame(...) + React mount"]
59
- play["scenes/Play.ts<br/>gameplay: load, enter, update, exit"]
60
- entities["entities/<br/>Player.ts, Crate.ts — plain classes, not an ECS"]
61
- render["render/<br/>palette, camera, sky, lighting,<br/>materials, post — YOURS"]
62
- ui["ui/<br/>App.tsx, Hud.tsx, Menu.tsx — React 19 + Tailwind 4"]
63
- state["state.ts<br/>state shape the HUD subscribes to"]
64
- scenarios["playtests/*.playtest.json<br/>committed browser scenarios, run by pnpm test"]
65
- config["threenative.config.ts<br/>app identity, icon, display, desktop window, renderer"]
66
-
67
- project --> src
68
- src --> main
69
- src --> play
70
- src --> entities
71
- src --> render
72
- src --> ui
73
- src --> state
74
- project --> scenarios
75
- project --> config
76
- ```
77
-
78
- `threenative.config.ts` is the one game-owned app-shape file. Set the launcher identity and
79
- icon, mobile orientation and display flags, desktop window, renderer preference, and native
80
- entry there. `package.json` may retain only `threenative.nativeEntry` as a compatibility
81
- fallback for older projects.
82
-
83
- `src/ui/Hud.tsx` is the starter's single HUD. It reads `game.state` through `useGameState`; keep
84
- gameplay and state transitions in the portable scene rather than in the React component.
85
- Touch controls are not generated yet: add the small pointer-action mapping after the core
86
- multitouch surface from PRD-053 lands.
87
-
88
- ## How to write gameplay here
89
-
90
- A scene is a class with optional `load`, `enter`, `update`, `exit`, and `render`. That is
91
- the whole lifecycle — there is nothing else to register.
92
-
93
- `ctx` hands you real Three.js objects and backend-neutral physics handles:
94
-
95
- ```ts
96
- ctx.scene // THREE.Scene
97
- ctx.camera // THREE.PerspectiveCamera
98
- ctx.renderer // the renderer
99
- ctx.physics.world // PhysicsWorldHandle
100
- player.body // PhysicsBodyHandle (via CharacterBody3D)
101
- player.mesh // THREE.Mesh
102
- ```
103
-
104
- The physics handles expose `.raw` as an explicitly backend-specific escape hatch: Rapier on
105
- web, opaque on native. Code that reads `.raw` is not portable between those targets.
106
-
107
- Any Three.js tutorial, StackOverflow answer, or snippet you already know works unchanged
108
- inside a scene. Prefer that over hunting for a framework wrapper — **for anything Three.js
109
- itself does (geometry, materials, lights, math), there is no wrapper and you should write
110
- the Three.js.** The exception is the loop: scene changes, timers and tweens are on `ctx`,
111
- not in an import, so grepping the imports of an existing file will not find them. The
112
- table below is the complete list.
113
-
114
- Physics uses Godot's names: `RigidBody3D`, `Area3D`, `CharacterBody3D`, `CollisionShape3D`.
115
- Every node has `dispose()`. Register disposable entities with `ctx.entities`; the framework
116
- clears registered entities, scene objects, and physics nodes when a scene exits. Dispose a
117
- node explicitly only when removing it during play. **The id is the name a scenario resolves.** A playtest `subject`, and every `movement` or
118
- `visibility` assertion, looks the entity up by that string — an unregistered player fails
119
- `TN_PLAYTEST_VISIBILITY_FAILED` however visible it is on screen.
120
-
121
- `input.vector("move").y` is +up; map it to world-space -z for forward with one explicit
122
- `-move.y` conversion in the player movement code.
123
-
124
- `CharacterBody3D.moveAndSlide(dt)` owns gravity through `body.velocity`; the player keeps
125
- the coyote-time and jump-buffer timers in the entity so jump feel stays game-owned.
126
-
127
- ## The `ctx` surface — you already have these, do not rebuild them
128
-
129
- `ctx` carries six things that get reimplemented by hand in almost every project, because
130
- they are **properties on `ctx`, never imports** — grepping an existing file's imports will
131
- never surface them. This table is the complete list.
132
-
133
- | You already have | Rather than | Signature |
134
- |---|---|---|
135
- | `ctx.goto("play")` | a hand-written `#reset()` | `(name: string) => Promise<void>` |
136
- | `ctx.tween(obj, { y: 2 }, 0.4)` | a `Math.sin` / `lerp` accumulator | `(target, props, seconds) => Promise<void>` |
137
- | `ctx.after(0.8, fn)` | `elapsed += dt; if (elapsed > 0.8)` | `(seconds, cb) => ScheduleHandle` |
138
- | `ctx.every(fn)` | a per-frame branch in `update` | `(cb: (dt: number) => void) => ScheduleHandle` |
139
- | `ctx.random.range(-1, 1)` | `Math.random()` | seeded — a replay produces identical results |
140
- | `ctx.raycast()` | `new Raycaster()` + `intersectObject` | `(options?: { screen?, targets? }) => Intersection \| undefined` |
141
-
142
- **`ctx.raycast()` is how you pick geometry under the pointer.** It defaults to the current
143
- pointer position and the whole scene, returns the nearest `THREE.Intersection`, and stays
144
- under a millisecond on meshes large enough that a plain `Raycaster` visibly stutters — it
145
- keeps an acceleration structure per geometry and rebuilds it when that geometry's positions
146
- change. Pass `{ targets }` to narrow it, `{ screen }` to test a point that is not the
147
- pointer. Skinned, instanced and morphed meshes fall back
148
- to the stock Three.js path automatically, so the result always matches
149
- `Raycaster.intersectObject`.
150
-
151
- **`ctx.goto(name)` restarts the current scene.** Calling `ctx.goto("play")` from inside
152
- `Play` tears the scene down and rebuilds it: `exit()` runs, scheduled callbacks are cleared,
153
- registered entities are cleared, the Three scene is emptied, then a fresh instance runs
154
- `load()` and `enter()`. That is your entire restart button, and your entire death-and-retry.
155
-
156
- Do **not** write a `#reset()` that walks your entities putting them back. It is ~15 lines
157
- that look right and quietly miss the scheduler and anything you spawned after `enter()`, so
158
- the second playthrough behaves differently from the first — and no gate in this project will
159
- catch that.
160
-
161
- **One rule when calling it from a frame function: `goto` and then `return`, immediately.**
162
-
163
- ```ts
164
- if (player.dead) {
165
- void ctx.goto("play");
166
- return; // ← required. Everything below now runs against a torn-down scene.
167
- }
168
- ```
169
-
170
- From React, the same call is `game.goto("play")` — use that for a restart button instead of
171
- routing a counter through game state.
172
-
173
- **`ctx.tween` is for timing, not for looks.** Use it for the *when* — a pickup rising over
174
- 0.4s, a door opening, a hit flash — and keep the *what* (colour, shape, easing feel) in
175
- `src/render/`. Motion driven by a persistent `Math.sin(elapsed)` in `update()` is still the
176
- right tool for a continuous idle bob; `tween` is for anything that starts, runs once, and
177
- finishes.
178
-
179
- **`ctx.random` is seeded from `defineGame({ seed })`.** Use it for anything a playtest needs
180
- to reproduce — spawn positions, patrol offsets, level variation. `Math.random()` makes a
181
- scenario that passes once and fails on replay for no visible reason.
182
-
183
- ## Save and load
184
-
185
- Save only the state you declare. The framework does not serialize entities, scene graphs, or
186
- physics handles, and it never will; save those fields in your own object literal:
187
-
188
- ```ts
189
- const save = JSON.stringify({ state: ctx.state.getState(), playerX: player.mesh.position.x });
190
- const loaded = JSON.parse(save) as { state: GameState; playerX: number };
191
- ctx.state.set(loaded.state);
192
- player.body.teleport({ x: loaded.playerX, y: player.mesh.position.y, z: player.mesh.position.z });
193
- ```
194
-
195
- ## Assets and animation
23
+ ## When the framework blocks you, write plain Three.js
196
24
 
197
- `AnimationPlayer` is exported by `@threenative/core` for clips from a rigged asset. Put a
198
- `.glb` in `public/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then construct
199
- and update the `AnimationPlayer` beside the entity that owns the loaded model. This starter
200
- does not ship a rigged asset; adding one belongs in `public/`, not in the framework.
25
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
26
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
27
+ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
28
+ (API, expectation, result, replacement); never stall the game.
201
29
 
202
- Entities are plain classes. There is no ECS, and adding one is a real decision, not a
203
- default — `pnpm add miniplex` if a game genuinely needs it.
30
+ ## Workflow skills
204
31
 
205
- ## Finding assets — you have an MCP server for this
32
+ - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
33
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
34
+ - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
35
+ - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
36
+ - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
37
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
+ - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
+ - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
206
41
 
207
- **Reach for it when the asset is conventional; build anything custom yourself.**
42
+ ## Commands and map
208
43
 
209
- - **Textures, materials, HDRIs and sound effects — prefer the tools.** Rusted metal, oak
210
- planks, a studio HDRI, a UI click: these are well-established and a CC0 one beats what you
211
- would hand-author.
212
- - **Models — only when the thing is conventional.** A car, a plane, a crate, a barrel, a
213
- tree, a chair. If this game's main character is a car, fetching a compatible `.glb` is the
214
- right call.
215
- - **Anything specific to this game — write it in `src/render/`.** A downloaded model standing
216
- in for a bespoke design reads as a weird asset dropped into the scene, and it looks worse
217
- than a clean composition of primitives. This is the failure the tools make easy.
218
-
219
- When in doubt, build it programmatically. A fetched asset has to match what the game needs,
220
- not merely exist.
221
-
222
- `.mcp.json` in this project launches `threenative-asset-mcp` from `node_modules`, so your host
223
- lists its tools alongside your own. It advertises 32; these 8 are the loop you will use for
224
- nearly everything:
225
-
226
- 1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
227
- source with its license summary, attribution requirement, browse URL, and whether an agent
228
- can complete a download from it. **That output is the authority on what is reachable** —
229
- not this file, and not your memory of some other project.
230
- 2. `polyhaven_search_assets` (CC0 models, textures, HDRIs), `ambientcg_search_assets` (CC0
231
- materials and textures), or `audio_search_assets` (Kenney, Sonniss).
232
- 3. `polyhaven_list_files` / `ambientcg_list_files` — the license, official URL, byte size and
233
- md5 of every resolution and format. **Read this before downloading, not after**, and pick a
234
- sane one: Poly Haven lists 16k PNGs over 1 GB beside 8k JPEGs at 28 MB. A game does not
235
- need the 16k.
236
- 4. `asset_download_file` for textures and models, `audio_download_asset` for audio. Both take
237
- `acceptLicense: true` — you are asserting you read step 3. **They ignore any path you pass
238
- and write to the directories `.mcp.json` sets** (`public/assets/<provider>/<sha>/` and
239
- `public/audio/<source>/<pack>/`); without that config they would write to `~/Downloads` and
240
- never reach the game.
241
- 5. Append the file, its source, its license and its URL to `CREDITS.md` **before the turn
242
- ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
243
- CC0 per asset page, and audio and bundle licenses are per pack.
244
-
245
- **Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
246
- `ambientcg_search_assets` did not tell you, you do not know it.
247
-
248
- **What arrives is usually a ZIP, not a texture.** ambientCG and Kenney ship archives: unpack
249
- one, keep only the maps you actually use (`_Color`, `_NormalGL`, `_Roughness` — not the
250
- `.blend`, `.usdc` or displacement), and put those beside your code under `public/`. A 1K JPEG
251
- set is right for a game; the 8K set of the same material is 200 MB.
252
-
253
- Two argument shapes that will bite you, both learned the hard way: `ambientcg_search_assets`
254
- takes lowercase `type` values (`material`, `hdri`, `3d-model`), and the audio catalog is
255
- **pack-level** — `audio_search_assets` matches pack names, so `query: "pickup coin"` returns
256
- nothing while `kind: "sfx"` returns the seven packs that exist. Pick a pack, download it,
257
- unzip it, and choose a file yourself.
258
-
259
- The other tools are narrower, and the directory spells out the conditions on each. The Fab
260
- tools talk to a marketplace: the server never purchases anything, and only directly-free files
261
- download. `smithsonian_search_assets` returns museum scans at scan resolution, which this
262
- project has no pipeline to decimate — that geometry is the wrong shape for a game. When in
263
- doubt check `asset_search_sources` first; its `caution` and license fields are the current
264
- truth for the pinned version, and they change between versions.
265
-
266
- Load what you downloaded the ordinary way — `ctx.assets.model("crate.glb")`,
267
- `ctx.assets.texture(...)`, `ctx.assets.audio(...)` — and write your own material and lighting
268
- around it in `src/render/`. The framework ships no asset and picks none for you.
269
-
270
- ## Building what you cannot download — sculpt from a reference
271
-
272
- Choose one branch before writing code:
273
-
274
- - **Conventional and downloadable** — a crate, an oak plank texture, a click. Use the asset
275
- tools. Sculpting one of these is slower and worse.
276
- - **Trivial** — a platform, a wall, a pickup ring. Write it. If `BoxGeometry` finishes the
277
- job in under 20 lines, that is the answer.
278
- - **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
279
- landmark, scenery composition, or environment set piece whose silhouette must match. Use
280
- the sculpt tools to turn that reference into editable `src/render/` source.
281
- - **Bespoke, without a reference image** — ask for one, or write it and accept that it will
282
- be generic. Do not invent a reference: comparison without evidence is unguided iteration.
283
-
284
- For a full environment, split the decision: sculpt the signature landmark or bounded scene
285
- kit that makes the reference recognisable; use the asset tools for interchangeable trees,
286
- rocks, textures, HDRIs, and sounds around it. Do not sculpt an entire world as one object.
287
-
288
- `.mcp.json` launches `threenative-sculpt-mcp` beside the asset server. It does not generate
289
- or ship runtime code; it guides the source you write:
290
-
291
- 1. Call `sculpt_plan` with the image path and a one-line intent, then read the returned
292
- grimoire resources.
293
- 2. Write the returned object contract and loop on `sculpt_spec_gate` until every named
294
- region and depth requirement passes. Do not write geometry before this gate is green.
295
- 3. For each ordered pass, write or extend one factory in `src/render/`. Capture the real
296
- frame with `npx @threenative/playtest`; the sculpt server never launches a browser.
297
- 4. Call `sculpt_compare` with the reference and captured frame, then give that evidence to
298
- `sculpt_pass_gate`. Advance only when it says advance; ambiguity means retry.
299
- 5. Use `sculpt_grimoire` for a named technique topic. It rejects pages containing concrete
300
- paste-ready material or shader recipes so the tool never owns this game's look.
301
-
302
- A missing or blank capture is a failed run, never a finished model. Add the reference image,
303
- its creator, license, and source URL to `CREDITS.md` before the turn ends.
304
-
305
-
306
- ## Visuals
307
-
308
- Edit everything in `src/render/` directly. The six baseline files are `palette.ts`,
309
- `camera.ts`, `sky.ts`, `lighting.ts`, `materials.ts`, and `postprocessing.ts`; `shapes.ts`
310
- is an additional helper. These are ordinary Three.js source in this project,
311
- not a framework look or a config option. Keep the palette to six named colours with one
312
- `accent`; import it from materials and sky. Set tonemapping and exposure deliberately, use a
313
- rim light with soft shadows and `normalBias`, derive fog from the sky, and route bloom through
314
- `renderer.setOutputNode()` so midtones remain readable.
315
-
316
- What is already there, so you do not rebuild it:
317
-
318
- - `shapes.ts` — `roundedBox`, `block`, `ball`, `tube`, `spike`, `makeRandom`. **Build props
319
- out of these, not raw `BoxGeometry`.** A sharp box reads as Minecraft; the same box with
320
- a 0.14 corner radius reads as a toy, and that is most of the difference between a scene
321
- that looks designed and one that looks like a test harness.
322
- - `lighting.ts` — key, sky/ground bounce, **rim**, ambient, with soft shadows and a
323
- `normalBias` tuned for rounded geometry. The rim is what stops silhouettes reading as
324
- flat cut-outs; do not delete it while "simplifying".
325
- - `camera.ts` — `createSpringArm`, a frame-rate-independent follow camera.
326
- - `postprocessing.ts` — ACES tone mapping and the WebGPU render pipeline.
327
-
328
- Three traps, all of which cost real debugging time before they were written down:
329
-
330
- 1. **`CanvasTexture` samples black under `WebGPURenderer`.** Procedurally painting a canvas
331
- and using it as a `map` produces a black surface, silently. Get variety from alternating
332
- material colours across a run of meshes instead — that is what `makeRandom` is for.
333
- 2. **`flatShading` fights `roundedBox`,** which welds its seams precisely so normals
334
- interpolate across them. Do not set both.
335
- 3. **Import a render module and then call it.** `setupPost` and `setupLighting` are inert
336
- if `Play.ts` only imports them, and nothing in typecheck, lint, or a playtest will fail.
337
-
338
- Nothing in the toolchain can see your game. `pnpm test` proves behaviour, never the look —
339
- so when you change something visual, actually look at it before reporting it done.
340
-
341
- ## UI
342
-
343
- React renders the HUD, menus, and overlays. **React never touches the scene graph** — no
344
- JSX for meshes, lights, or cameras.
345
-
346
- The bridge is a throttled store, not a per-frame render:
347
-
348
- ```ts
349
- ctx.state.set({ score }); // in update(), at loop rate — it coalesces
350
- const { score } = useGameState(); // in a component, ~10Hz
351
- ```
352
-
353
- Never subscribe a React component to per-frame data.
354
-
355
- The start scene owns the initial state in `static initialState`; omit a duplicate
356
- `initialState` literal from `defineGame`. Update only the fields that changed:
357
- `ctx.state.set({ score })`.
358
-
359
- `main.ts` calls `acceptHotUpdate(game, import.meta.hot)` for development reloads. The
360
- framework preserves only JSON-shaped store state, so `Play.enter()` must seed entities
361
- from the carried values such as `playerX`; the scene graph, physics world, audio voices,
362
- particles, and renderer are rebuilt on every update.
363
- The keyboard and React restart paths reset `Play.initialState` before rebuilding the scene.
364
-
365
- ## Register entities you want to inspect or test
366
-
367
- ```ts
368
- ctx.entities.add("player", this.player);
44
+ ```sh
45
+ pnpm dev
46
+ pnpm studio
47
+ pnpm build
48
+ pnpm build --target desktop
49
+ pnpm test
50
+ node tools/look.mjs
369
51
  ```
370
52
 
371
- A registered entity's `debug()` shows up in the dev overlay, in `window.__THREENATIVE__`,
372
- and in playtest assertions. That is how a scenario checks the game state rather than
373
- guessing from pixels.
374
-
375
- ## Playtests
376
-
377
- `playtests/survives.playtest.json` is the durable smoke proof. Keep it when replacing the
378
- starter gameplay: it checks boot, diagnostics, a nonblank frame, and player movement without
379
- depending on pickups, score, coyote time, or respawns. `playtests/play.playtest.json` and the
380
- other scenarios are starter-game examples that you may delete or rewrite. Steps count frames,
381
- not milliseconds — `holdFrames`, `waitFrames` — because the harness drives the fixed-step clock
382
- instead of racing it.
383
-
384
- A scenario fails closed: a missing entity, an absent observation, or a scenario with no
385
- assertions is a failure, never a quiet pass. When you add a feature, add the assertion that
386
- would catch its absence, and run the scenario before reporting the feature works.
387
-
388
- ## Budget real time for the look
389
-
390
- Read this as an instruction about **where your effort goes**, not as a style tip.
391
-
392
- Every automated gate in this project — `typecheck`, `lint`, `pnpm test`, every playtest
393
- scenario — is blind to how the game looks. All of them pass on a game that is grey boxes on
394
- a black screen. If you let the gates define "done", you will ship grey boxes on a black
395
- screen and the gates will tell you that you succeeded.
53
+ The game boots straight into `Play`: a coastal island, pickup, crate, chasm, and flag produce `won` or
54
+ `lost`; `R` and the React restart intent rebuild from `initialState`. Keep the packaged
55
+ `assets/native-proof.glb` load and its console marker for the desktop asset gate. `Play.ts` owns
56
+ gameplay, `src/render/` owns the look, `src/ui/Hud.tsx`/`Menu.tsx` own UI, and `state.ts` publishes
57
+ JSON-safe values. Keep `playtests/survives.playtest.json` as smoke proof and update outcome tests.
396
58
 
397
- So the rule here is: **a feature is not done when its assertion passes. It is done when you
398
- have looked at it and it reads well.** Plan for roughly as much work on presentation as on
399
- mechanics. That is not gold-plating; it is the majority of what a player experiences, and
400
- it is the part nothing else in this repo will catch.
59
+ On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src/render/touch-controls.ts` adds a left movement stick and right jump button; the scene passes its input to `Player`, with keyboard mapping as the desktop fallback.
401
60
 
402
- Concretely, when you add anything a player sees, do all of these before calling it done:
61
+ ## Portable authoring contracts
403
62
 
404
- 1. **Look at it.** Boot the game, get the thing on screen, take a screenshot, open the
405
- screenshot. Reading your own diff is not looking at it.
406
- 2. **Silhouette first.** Can you tell what it is from its outline alone? Break up long
407
- straight edges — overhangs, fringes, props crossing the line. A shape that reads at a
408
- glance beats a detailed shape that does not.
409
- 3. **Give it depth.** Something bright behind it, something dark under it. Contact shadows
410
- and a rim make a prop sit in the world instead of floating on top of it.
411
- 4. **Make it move.** Idle bob, a squash on impact, a particle on pickup, a screen shake on
412
- damage. A few frames of motion is the cheapest quality-per-line in the whole project.
413
- 5. **Finish the HUD too.** Spacing, hierarchy, a transition on every number that changes.
414
- An unstyled HUD makes a good-looking game look unfinished.
63
+ Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
415
64
 
416
- ### How to actually look at it
65
+ Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
66
+ Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
67
+ React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
68
+ `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then
69
+ `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch.
70
+ `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded
71
+ randomness is deterministic only when `defineGame({ seed })` is configured.
417
72
 
418
- Run `pnpm dev`, then get eyes on it. In rough order of preference:
73
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each
74
+ rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names
75
+ tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which
76
+ therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches 256 per presented frame so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
419
77
 
420
- 1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
421
- or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
422
- a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
423
- console in the same loop you are already coding in. Drive the game, do not just load the
424
- menu.
425
- 2. **`npx @threenative/playtest <scenario> --browser-recipe webgpu --headed`.** The recipe
426
- carries the Chromium flags a WebGPU capture needs, including `--enable-features=Vulkan`.
427
- Do not hand-roll the flag list: without that one flag Chromium never reaches the Linux
428
- Vulkan driver and serves WebGPU from SwiftShader, its CPU rasteriser — no error, healthy
429
- limits, and a software renderer's picture. The runner now fails such a run with
430
- `TN_PLAYTEST_SOFTWARE_ADAPTER` and prints the adapter it got; `--allow-software` accepts
431
- the fallback if you truly want it.
432
- 3. **Ask the user to look**, and say specifically what you want them to check.
78
+ ## Fused rock authoring
79
+ `src/render/rockRidge.ts` owns the granite field, seed, bounds, ridge material handoff, and quality choice; `src/render/implicitSurface.ts` is the local renderer-independent extractor and final-array topology audit. A fused mass is one implicit field; separate debris may be instanced.
80
+ After changing bounds, field, or resolution, run three fixed seeds and require the audit to report zero boundary edges, degenerate triangles, and winding conflicts with positive signed volume. Never hide holes with `DoubleSide` or a normal map.
81
+ `Play.enter` attaches Preview immediately, then the classic Worker refinement swaps atomically; do not add a main-thread showcase fallback.
433
82
 
434
- On a machine with no screen, run any of those under a virtual display. **Do not use
435
- `xvfb-run`:** on `xorg-server-xvfb` 21.1.x its cleanup `kill` fails after Xvfb has already
436
- exited and that failing kill's status replaces the real one, so
437
- `xvfb-run -a -s '-screen 0 1600x900x24' true` exits `1`. Every gate wrapped in it reports
438
- failure whether it passed or not. Start `Xvfb` yourself on a free display and export
439
- `DISPLAY`, or check the command's own exit code separately.
83
+ ## Quality and proof
440
84
 
441
- What does *not* work: **headless Chromium usually cannot render WebGPU.** The page loads,
442
- the HUD paints, and the 3D canvas comes out blank or black. That looks exactly like a bug
443
- in your scene, and it is not. Symptoms are `Instance dropped in popErrorScope` and
444
- `createBuffer failed, size (N) is too large for the implementation` in the console.
85
+ `src/render/quality.ts` owns `low`, `medium`, `high`; platform selects the boot tier, and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
86
+ `setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit.
87
+ The starter's painterly look is generated source (`outline.ts`, `kuwahara.ts`, `watercolor.ts`) reached by `worldEnvironment.ts`; `quality.ts` owns tier, radius, resolution, and strength; `TN_RENDER_CHAIN` names each independently, and a missing stage observation is a failure.
88
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes.
445
89
 
446
- So: if a screenshot comes back black or empty, suspect the capture before you rewrite the
447
- scene. Confirm the renderer works at all before you go debugging your materials.
90
+ ## One shadow for a big outdoor level
91
+ When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. For movers call `trackCaster(object)` — tracking or untracking refreshes the cached levels once, then movement draws a per-level mover map every frame without invalidating them; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
448
92
 
449
- ### When you think you are done
93
+ ## Budget real time for the look — see `agent-docs/dream-loop.md`
450
94
 
451
- Ask yourself, honestly: *would a player screenshot this?* If the answer is no, you are not
452
- finished — and no command in this repo is going to tell you that.
95
+ The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule.
96
+ Long recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
97
+ ## Optional multiplayer transport
98
+ For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
@@ -0,0 +1,4 @@
1
+ # Generated by @threenative/assets from the sources in assets/. Hand-owned static files
2
+ # (favicon, launcher icons) stay in public/ and are committed; these outputs never are.
3
+ public/assets.manifest.json
4
+ public/*.[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f].*
@@ -3,7 +3,6 @@
3
3
  <head>
4
4
  <meta charset="UTF-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
- <link rel="icon" href="/favicon.svg" />
7
6
  <title>__PROJECT_NAME__</title>
8
7
  </head>
9
8
  <body>
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "native-react-hud",
3
+ "target": "desktop",
4
+ "schemaVersion": 1,
5
+ "warmupFrames": 0,
6
+ "steps": [
7
+ { "label": "ui-ready", "waitTicks": 180 },
8
+ { "kind": "input", "label": "move-under-live-hud", "press": "ArrowRight", "holdTicks": 20 }
9
+ ],
10
+ "assert": {
11
+ "resources": [
12
+ {
13
+ "id": "state",
14
+ "path": "uiReady",
15
+ "atSteps": [{ "label": "ui-ready", "equals": true }]
16
+ },
17
+ { "id": "state", "path": "playerX", "changed": true }
18
+ ]
19
+ }
20
+ }