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,174 @@
1
+ # Visual baseline — what each `src/render/` file ships, and the traps
2
+
3
+ Companion to the `Visuals` section in this project's `AGENTS.md`. Everything here is ordinary
4
+ Three.js source in this project, yours to rewrite or delete.
5
+
6
+ ## What is already there, so you do not rebuild it
7
+
8
+ - `shapes.ts` — `roundedBox`, `block`, `ball`, `tube`, `spike`. **Build props out of these,
9
+ not raw `BoxGeometry`.** A sharp box reads as Minecraft; the same box with a 0.14 corner
10
+ radius reads as a toy, and that is most of the difference between a scene that looks
11
+ designed and one that looks like a test harness. For the seeded randomness that varies a
12
+ run of meshes, the scene builds `createRandom(seed)` and passes it down — nothing in
13
+ `src/render/` may import a framework package, which is what keeps this folder portable.
14
+ - `lighting.ts` — key, sky/ground bounce, **rim**, ambient, with soft shadows and a
15
+ `normalBias` tuned for rounded geometry. The rim is what stops silhouettes reading as
16
+ flat cut-outs; do not delete it while "simplifying".
17
+ - `camera.ts` — `createSpringArm`, a frame-rate-independent follow camera. Its offset and its
18
+ **lead** are the framing: the default aims ahead of the character rather than centring it,
19
+ because a level that runs one way puts half the picture behind the player otherwise.
20
+ - `postprocessing.ts` — the editable presets and `setupPost` delegation.
21
+ - `worldEnvironment.ts` — the editable Godot-named render chain: tone mapping/exposure and
22
+ optional TSL stages, with `createRenderChain` reporting applied or refused stages.
23
+ - `scenery.ts` — `createScenery`, the collider-free half of the world: columns under ledges,
24
+ spires in the middle distance, an unlit ridge on the horizon. **Keep something in all three
25
+ bands.** A lit floor alone in black reads as a test fixture no matter how good the floor
26
+ is, and it is the single cheapest thing to fix in a first screenshot.
27
+
28
+ ## Traps
29
+
30
+ Each of these has cost real debugging time. All of them fail *silently* — nothing in
31
+ typecheck, lint, or a playtest catches one, and several look exactly like "the effect is on
32
+ and does nothing".
33
+
34
+ 1. **`CanvasTexture` samples black under `WebGPURenderer`.** Procedurally painting a canvas
35
+ and using it as a `map` produces a black surface, silently. Get variety from alternating
36
+ material colours across a run of meshes instead, or from `softCircleDataTexture`, which
37
+ writes sprite pixels straight into a `DataTexture` and is the framework's way around this.
38
+ 2. **`flatShading` fights `roundedBox`,** which welds its seams precisely so normals
39
+ interpolate across them. Do not set both.
40
+ 3. **Import a render module and then call it.** `setupPost` and `setupLighting` are inert
41
+ if the scene only imports them.
42
+
43
+ ### TSL post-processing stages that install and then do nothing
44
+
45
+ 4. **`SSRNode.maxDistance` defaults to `1` — one world unit.** On any scene larger than a
46
+ tabletop every reflection ray dies after a metre and returns nothing, on every pixel. This
47
+ reads as "screen-space reflections are on and have no effect". Set it to the distance across
48
+ the scene you actually want reflected.
49
+ 5. **`reflectNonMetals` defaults to `false`.** A polished stone, wood, or painted floor is not
50
+ metal, so by default it never reflects — only metals do. A polished floor is the usual
51
+ reason to reach for SSR at all, so this default silently removes the effect you wanted.
52
+ `roughnessNode` left `null` is the mirror-image mistake: every surface is then treated as a
53
+ perfect mirror.
54
+ 6. **Do not swizzle the normal you hand a pass.** `ssr()` calls `.sample()` on that node, so it
55
+ needs the whole `TextureNode` from the MRT target; `normal.xyz` produces a plain vec3 and the
56
+ pass dies at shader build with `this.normalNode.sample is not a function`. `@types/three`
57
+ declares the parameter as `Node<"vec3">`, which is exactly what makes the swizzle look
58
+ correct — the types are wrong here and the runtime is right.
59
+ 7. **A dangling graph branch renders a blank frame.** When a pass needs a *texture* rather than
60
+ an expression, materialise the chain **once** with `convertToTexture` and reuse that texture
61
+ on both sides of the composite. Passing `convertToTexture(lit)` into the pass while adding
62
+ its result back onto the unconverted `lit` builds two parallel copies of the same graph, one
63
+ rendered into a target and one not — and whether the frame appears then depends on whether
64
+ some *other* stage happens to re-materialise the second copy. Measured on a real scene: it
65
+ rendered with bloom on, rendered with SSR off, rendered with godrays off, and came back as
66
+ the bare background colour only when all three conditions lined up. That is what a dangling
67
+ branch looks like from the outside, and it is not a driver bug.
68
+
69
+ Nothing in the toolchain can see your game. `pnpm test` proves behaviour, never the look —
70
+ so when you change something visual, actually look at it before reporting it done.
71
+
72
+ ## The chain, in order — and what each stage costs
73
+
74
+ `postprocessing.ts` builds a `WorldEnvironment` and hands its stages to the engine's render
75
+ chain, which sorts them into one canonical order. The order is not a preference:
76
+
77
+ 1. **ambient occlusion** and **SSGI** gather, because both read the depth and normal buffers the
78
+ scene pass wrote and neither can read a composited image.
79
+ 2. **denoise** runs inside the gather stage on its AO and GI terms, before they are added to the
80
+ beauty pass — denoising the composite instead smears the geometry it was meant to preserve.
81
+ 3. **godrays**, then **SSR**, which add light rather than remove it, so they see the frame the
82
+ gather has already occluded and lit.
83
+ 4. **sharpen**, because RCAS is defined on the finished picture and sharpening before bloom
84
+ sharpens edges that bloom then spreads back out.
85
+ 5. **bloom**, then **vignette**, then the tone curve — the last thing the frame meets.
86
+
87
+ Exposure is applied as a multiply on the scene pass, ahead of every stage, so the gather, the
88
+ reflections and the bloom threshold all see the same exposed image. `renderer.toneMappingExposure`
89
+ is live too and reaches the frame at the same point, but only when no output node is installed;
90
+ with any stage running, the multiply is the shutter.
91
+
92
+ ### Cost
93
+
94
+ Measured on a dense interior (a sandbox cathedral, not one of these templates) at 1600x900 on a
95
+ desktop RTX 2080, browser WebGPU, as GPU time per frame — `gpuMs` in `TN_FRAME_BUDGET`, not the
96
+ CPU `render` phase, which reads ~5.5 ms while the GPU frame is 14.7 ms and therefore cannot see
97
+ this at all:
98
+
99
+ | configuration | gpuMs | fps |
100
+ | --- | --- | --- |
101
+ | every stage on | 14.7 | 56.8 |
102
+ | minus SSGI + denoise | 5.5 | 126.3 |
103
+ | minus SSR | 10.6 | 77.0 |
104
+ | minus bloom | 10.1 | 72.4 |
105
+ | minus denoise only | 12.8 | 60.3 |
106
+ | every stage off | 2.2 | 333.3 |
107
+
108
+ The scene, its shadow map and the overlay together cost 2.2 ms of that frame; the chain costs the
109
+ other 12.5. **SSGI is the expensive one by a wide margin** — the gather is ~7.3 ms and its two
110
+ full-resolution denoise passes ~1.9 ms at `medium` — which is why `ssgiQuality: "high"` (3 slices
111
+ x 16 steps) and full-resolution SSR are the two knobs to reach for first when a frame is late.
112
+ Godrays measured ~0.0 ms here and are off by default for a different reason: a shaft needs a sun,
113
+ an occluder and interior air to read at all, and none of these templates is an interior.
114
+
115
+ Your scene is not this one. Read your own numbers out of `TN_FRAME_BUDGET` before believing any
116
+ row above applies to it.
117
+
118
+ ### Turning a stage on
119
+
120
+ Every stage that ships off is one property in the preset object in `postprocessing.ts`:
121
+
122
+ ```ts
123
+ gtaoEnabled: true, // contact occlusion in the crevices SSGI's room-scale gather misses
124
+ godraysEnabled: true, // needs the shadow-casting light setupLighting returns; interiors only
125
+ vignetteAmount: 0.25, // corner darkening, as the fraction removed at the extreme corner
126
+ ssgiEnabled: true, // also for mobile: add it to mobilePreset and measure the result
127
+ ```
128
+
129
+ `TN_WORLD_ENVIRONMENT` prints every run and names each stage as applied, or refused **with a
130
+ reason** — `godraysEnabled is false`, `light 'sun' does not cast shadows`, `renderer:webgl2`. A
131
+ stage you turned on that is not in that line as `applied: true` did not run, and the reason says
132
+ why. An unknown `ssgiQuality` or `tonemapMode` throws at construction rather than quietly
133
+ becoming the default.
134
+
135
+ ## Shafts of light — the one recipe that is easy to get wrong
136
+
137
+ You want the beam a cathedral window or a hole in a cave roof throws. **Do not build cone
138
+ geometry for it.** A hand-authored additive cone draws its own silhouette, stacks two layers where
139
+ you see through both walls, and reads as a plastic tube; the `godRays` stage is the supported
140
+ route and it is already wired.
141
+
142
+ Four things have to be true, and three of them fail silently:
143
+
144
+ 1. **`renderer.shadowMap.enabled = true`.** The stage raymarches the sun's shadow map, and three
145
+ does not allocate one until something asks for it. With no shadow map the stage refuses — and
146
+ because it refuses at build time it takes the *whole chain* with it, so SSGI, SSR and your
147
+ tonemap all quietly stop too. The symptom is a flat, ungraded frame, not a missing beam.
148
+ `ctx.renderer` is the framework's wrapper; `ctx.renderer.raw` is the three renderer that has
149
+ `shadowMap`. Setting it on the wrong one throws `Cannot set properties of undefined`.
150
+ 2. **The light casts shadows and reaches the room.** `castShadow = true`, and a shadow-camera
151
+ frustum wide enough to contain the space — the default 10 m ortho extent shadows nothing in a
152
+ 50 m hall, and a shaft is only visible where the map says the air is lit.
153
+ 3. **The beam has to pass through the opening.** Position the light so the line from it through
154
+ the hole lands where you want the pool of light; a sun placed for a pleasing angle usually
155
+ misses the hole entirely and lights the far wall instead.
156
+ 4. **`godraysFloor` is the dial that separates beams from fog.** This is the one people miss. The
157
+ pass adds haze to every pixel, not only to the beams. `godraysFloor` subtracts that out-of-beam
158
+ scatter *before* `godraysIntensity` multiplies, so with the floor near zero, raising intensity
159
+ scales the veil over the whole room and the frame just gets milkier. Raise the floor first,
160
+ then the intensity.
161
+
162
+ Measured band on an interior (lumen-hall, across many captures):
163
+
164
+ ```ts
165
+ godraysDensity: 0.7, // above ~0.8 the haze stops being confined to the beams
166
+ godraysFloor: 0.08, // subtracts the veil; raise this before raising intensity
167
+ godraysIntensity: 3.0, // only scales what survives the floor
168
+ godraysMaxDensity: 0.6, // clamp; a no-op at this density, louder at higher ones
169
+ godraysSteps: 56, // below ~24 leaves visible slabs at each step boundary
170
+ ```
171
+
172
+ A useful check that costs nothing: if turning godrays off moves the **median** brightness of the
173
+ frame by more than a few points, the stage is fogging the room rather than drawing shafts. Beams
174
+ change the bright end of the histogram, not the middle.
@@ -0,0 +1,113 @@
1
+ # The UI layer — one `src/ui/` in a web view, on every platform
2
+
3
+ `src/ui/` is the whole UI and the same source on every target. On web it is a React tree beside
4
+ the canvas. On native it is the same React tree, loaded by **the platform's own browser-class
5
+ renderer** into a transparent surface composited over the game — not a browser the framework
6
+ ships, and never the game itself. The scene stays in the native runtime; only the UI crosses.
7
+
8
+ | target | what loads `src/ui/main.tsx` | status |
9
+ | --- | --- | --- |
10
+ | web | the page itself, beside `GameCanvas` | shipped |
11
+ | Android | a transparent `WebView` over the SDL surface | shipped, proven on a Pixel 8 |
12
+ | desktop (Linux) | a transparent WebKitGTK window over the game window | shipped |
13
+ | desktop (Windows, macOS) | — | no host yet; use `ui: { renderer: "native" }` |
14
+ | iOS | a transparent `WKWebView` over the Metal layer | written, **unproven on hardware** |
15
+
16
+ Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
17
+ and no extra process, and draws `View`/`Text` quads inside the rendered frame instead.
18
+
19
+ ## Two things cross the boundary, and nothing else
20
+
21
+ On native the UI is a different process from the game. It cannot hold the game object, call
22
+ `game.pause()`, or import a scene. It reads **published state** and sends **intents**.
23
+
24
+ ```tsx
25
+ import { UiLayer, useUiIntent, useUiState } from "@threenative/ui";
26
+
27
+ function Hud() {
28
+ const state = useUiState<GameState>();
29
+ const send = useUiIntent();
30
+ // The web view loads this page before the game has run a tick, so this is the normal first
31
+ // paint rather than an error path.
32
+ if (state === undefined) return null;
33
+ return (
34
+ <button data-tn-interactive onClick={() => send("restart")}>
35
+ restart · {state.score}
36
+ </button>
37
+ );
38
+ }
39
+ ```
40
+
41
+ `src/game.ts` decides what an intent means. This is the whole of the game side:
42
+
43
+ ```ts
44
+ game.ui.onIntent((intent, payload) => {
45
+ if (intent === "restart") void game.goto("play");
46
+ if (intent === "pause") game.pause();
47
+ });
48
+ ```
49
+
50
+ State flows the other way by itself: whatever the scene writes with `ctx.state.set(...)` is
51
+ published to the UI. It is serialised to compare frames, so keep it small — live numbers, not
52
+ level geometry. Static data the UI needs (a minimap's layout, a weapon table) belongs in a module
53
+ both sides import, and that module must not import `three`, or the renderer lands in the UI
54
+ bundle. If a value only the game can compute must reach the UI, publish it as state.
55
+
56
+ ## `data-tn-interactive` is how a press finds its owner
57
+
58
+ Mark every element the player presses. The page publishes those rectangles, normalised to the
59
+ viewport, and the **host** decides on pointer-down whether the press belongs to the UI or falls
60
+ through to the game.
61
+
62
+ ```tsx
63
+ <button data-tn-interactive onClick={fire}>fire</button> // takes the press
64
+ <div className="score">{score}</div> // scenery; the press reaches the game
65
+ ```
66
+
67
+ `pointer-events: none` is **not** the mechanism and cannot be. The platform hands the gesture to
68
+ the web view before any CSS runs; by the time the page could refuse it, the game has already
69
+ missed it.
70
+
71
+ Rectangles are republished while anything moves — a CSS transition, a resize, an element
72
+ appearing — so a button is hit where it is *drawn*, not where it started. You do not call
73
+ anything to make that happen; `UiLayer` observes the tree.
74
+
75
+ ## What breaks, and what it looks like
76
+
77
+ Every one of these shipped at least once here, and none of them failed a build.
78
+
79
+ - **A `body` background.** `src/ui/main.tsx` imports your stylesheet, and on native that page is
80
+ composited over the game. `body { background: … }` is an opaque sheet over the frame the game
81
+ just rendered — the HUD looks right and the game is gone. Put the page backdrop on `#root`,
82
+ which exists only in the web document.
83
+ - **Absolute asset URLs.** The UI is served from a subdirectory. A `/assets/app.js` resolves
84
+ outside it and 404s, and the page renders nothing at all — no error, no HUD.
85
+ - **Importing game code.** It works on web and drags the renderer into the UI bundle on native.
86
+ The rule that keeps you honest: `src/ui/` may import types and plain data, never a scene, an
87
+ entity, or anything that imports `three`.
88
+ - **Assuming the first render has state.** It does not. Return `null` until it arrives.
89
+
90
+ ## Watching it work
91
+
92
+ Markers, all greppable from the game's output (`adb logcat` on Android):
93
+
94
+ | marker | means |
95
+ | --- | --- |
96
+ | `TN_UI_OVERLAY:{"attached":true}` | the host brought the web view up and the page reached it |
97
+ | `TN_UI_OVERLAY:{"attached":false,…}` | it did not, and `reason` says why |
98
+ | `TN_UI_HIT_REGIONS:{"count":N}` | the page published N interactive rectangles |
99
+
100
+ `attached` stays false until the page sends its first message, so a false here means the page
101
+ never loaded — look at the page, not at the host.
102
+
103
+ **The page's console does not reach the game's stdout on desktop.** A `console.log` in a UI
104
+ component is invisible there. Report through an intent when you need to see something, or open the
105
+ same `src/ui/` in a browser, where it is an ordinary page with ordinary devtools.
106
+
107
+ ## Proving it
108
+
109
+ A `--target android` playtest drives the real build and asserts what the game received: a press on
110
+ empty HUD space must reach the game, a press on a published rectangle must not, and a drag that
111
+ starts on the game and crosses a button must stay with the game. Assert the game's own counters —
112
+ `pointerDowns`, the intents it handled — rather than what the UI shows, which is the half that can
113
+ lie about the half you care about.
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: file-engine-bug
3
+ description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session. Use when doctor and a minimal repro separate an engine bug from a game or machine problem, and you have pasted output proving it.
4
+ ---
5
+
6
+ # Filing an engine bug
7
+
8
+ A confirmed engine bug is filed upstream in the same turn you proved it — on the user's behalf,
9
+ under the user's own `gh` session. Never create an account, never request a token, never open a
10
+ browser flow: `gh` is already authenticated as the user, and that is the identity the report
11
+ carries. Keep the report factual; it goes out in their name.
12
+
13
+ ## 1. Confirm it is an engine bug
14
+
15
+ `npx threenative doctor` and `npx @threenative/playtest doctor` separate project, machine, and
16
+ engine failures. It is an engine bug when an `@threenative/*` API is broken, missing, or acts
17
+ against its contract (capability detail or `AGENTS.md`), and a minimal repro shows it — not a
18
+ fix that lives in this game's source, and not a machine problem doctor names.
19
+
20
+ Implement the workaround first and continue the game (`AGENTS.md`: never stall on a framework
21
+ bug). Filing does not wait for the workaround to be clean.
22
+
23
+ ## 2. Search before filing
24
+
25
+ ```sh
26
+ gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or three keywords>"
27
+ ```
28
+
29
+ An open issue already covering it: add your repro and output as a comment
30
+ (`gh issue comment <number> --body-file <file>`) instead of a new report.
31
+
32
+ ## 3. File it
33
+
34
+ Write the body to a file first; quoting goes through `--body-file`, never inline:
35
+
36
+ ```sh
37
+ gh issue create --repo ThreeNativeHQ/threenative \
38
+ --title "<area>: <what is wrong, stated as behaviour>" \
39
+ --body-file bug-report.md
40
+ ```
41
+
42
+ The body carries, in this order:
43
+
44
+ - **Expected** — what the capability's contract says happens.
45
+ - **Actual** — what happened, with the exact error id (`TN_*`) and the output you ran (doctor,
46
+ playtest, perf) pasted, not summarised.
47
+ - **Repro** — the smallest game code that shows it, and which template it reproduces in.
48
+ - **Environment** — platform and target, browser and adapter for web, `@threenative/*` versions
49
+ from the project's `package.json`.
50
+ - **Workaround** — what the game shipped with to keep moving.
51
+
52
+ ## 4. When not to file
53
+
54
+ - `gh auth status` fails or `gh` is missing: do not authenticate for the user and do not stall —
55
+ hand them the drafted title and body file and name the one command that files it.
56
+ - The bug is real but you cannot prove it with pasted output yet: file nothing. Report it to the
57
+ user as suspected, with the repro to run.
58
+
59
+ The final summary to the user names the issue URL, or the reason no issue exists.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: prd-creator
3
+ description: Turn a ThreeNative game idea or change into an approved game plan and implementation tasks before authoring code. Use after threenative-capabilities has recorded a capability or no-match for every mechanic, and before any game source is written.
4
+ ---
5
+
6
+ # ThreeNative game PRD
7
+
8
+ Use this after `threenative-capabilities` has recorded a capability or no-match for the full request
9
+ and every concrete mechanic. The outcome is a small, distinctive, playable plan grounded in the
10
+ engine surface and explicitly approved by the user, not a generic genre template.
11
+
12
+ ## Plan
13
+
14
+ 1. Inspect the existing game, its instructions, and the capability discovery record. If discovery
15
+ is missing or the requested mechanics changed, invoke `threenative-capabilities` before drafting.
16
+ 2. Preserve the request's fantasy. Define the smallest playable loop that depends on its setting,
17
+ traversal, combat, or simulation rather than reskinning a generic character game.
18
+ 3. Specify controls, camera, core mechanics, win/loss states, game state, progression, visual and
19
+ audio direction, asset needs and licences, target platforms, performance risks, and non-goals.
20
+ 4. Define fail-closed playtest acceptance criteria for the loop, including observable state and a
21
+ real capture for visible changes. Unexecuted platforms remain unverified.
22
+ 5. Record prerequisites: required tools/MCPs, service access, test users, and environment variable
23
+ names. Use placeholders only; never read or write real secrets into planning artifacts.
24
+
25
+ Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
26
+ `.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
27
+ bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
28
+ The first task verifies prerequisites; later tasks include implementation, playtest proof, and
29
+ visual inspection. Preserve the pre-planning capability decisions in the relevant task checks.
30
+
31
+ ## Approval gate
32
+
33
+ Present the plan and direct the user to approve it or request changes. Do not edit game source,
34
+ download assets, authenticate services, or begin implementation while planning. Revise the plan
35
+ when the user gives feedback.
36
+
37
+ Start implementation only after explicit approval and a clear execution instruction such as
38
+ "execute", "implement", "build it", or an equivalent phrase. One message may contain both. After
39
+ that handoff, execute the approved tasks without silently expanding the scope; repeat capability
40
+ discovery only when the requested mechanics or target platforms change.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: threenative-assets
3
+ description: Find, import, license, or sculpt assets for a portable ThreeNative game. Use when the game needs textures, materials, HDRIs, sounds, or models, when importing an owned Fab or Unreal pack, or when sculpting bespoke geometry from a reference image.
4
+ ---
5
+
6
+ # ThreeNative assets and sculpting
7
+
8
+ Use tools for conventional textures, materials, HDRIs, sounds, and models; write bespoke visuals
9
+ in `src/render/`. Start the session from the game root so the project-scoped MCP config is read.
10
+
11
+ 1. Run `asset_search_sources` to learn what is reachable, then search with
12
+ `polyhaven_search_assets`, `ambientcg_search_assets`, or `audio_search_assets`.
13
+ 2. List files with `polyhaven_list_files`/`ambientcg_list_files` before downloading; read the
14
+ license and choose a sane resolution.
15
+ 3. Download with `asset_download_file`/`audio_download_asset` and `acceptLicense: true`; tools
16
+ write to the configured project directory.
17
+ 4. Add file, source, license, and URL to `CREDITS.md`. Never state a license not returned by a tool.
18
+
19
+ Many Fab listings are Unreal-only rather than ready-to-load GLBs. Search with `fab_search_assets`,
20
+ check owned listings with `fab_list_owned`, then use `fab_import_asset` to download and convert an
21
+ owned listing; use `asset_import_unreal` for an already-downloaded local pack. Both write textured
22
+ `.glb` files under `assets/`. If they report `UNREAL_SOURCE_UNCOOKED`, stop: source editor assets
23
+ need Unreal Editor export and cannot be recovered by retrying the converter.
24
+
25
+ If FabCLI needs a session, proactively run `fabcli auth login`. Use Claude browser, or Codex's
26
+ `chrome:control-chrome`, to complete the login with the user's active browser session, then retry
27
+ the MCP call. Never read, copy, print, or persist browser cookies or tokens. The MCP checks
28
+ entitlement and accepts only Fab Standard or CC-BY; it never claims or buys. Full arguments:
29
+ `agent-docs/finding-assets.md`.
30
+
31
+ For a bespoke animated creature, follow `agent-docs/creating-creatures.md`. Call the five
32
+ `creature_*` tools through the project asset server, keep the editable spec and claims in
33
+ `.threenative/creatures/`, compile into the configured `assets/` source, and get independent
34
+ visual review before delivery. `creature_status` distinguishes compile-only availability from
35
+ optional preview/check dependencies; an unavailable renderer is not approval.
36
+
37
+ Choose the sculpt branch before coding: conventional → asset tools; trivial → portable geometry;
38
+ bespoke with a reference → `sculpt_plan`, `sculpt_spec_gate` until every region passes, one
39
+ factory per pass in `src/render/`, then `sculpt_compare` and `sculpt_pass_gate` against a real
40
+ capture; bespoke without a reference → read `agent-docs/dream-loop.md` and acquire a
41
+ user-supplied or explicitly authorized target before sculpting. Use `node scripts/reference.mjs`
42
+ only when the user selected its provider/model; never invent a reference or hide a missing key.
43
+ `sculpt_grimoire` supplies techniques. `threenative-sculpt-mcp` guides source and never launches
44
+ a browser. A missing/blank capture fails; credit the reference before the turn ends. See
45
+ `agent-docs/sculpt-from-a-reference.md`.
@@ -0,0 +1,7 @@
1
+ ---
2
+ name: threenative-builder
3
+ description: Build one bounded ThreeNative change and report its evidence. Use when dispatched as the builder against a single task; the complete role and framework contract is `.threenative/agents/builder.md`.
4
+ ---
5
+
6
+ Read `.threenative/agents/builder.md` and `AGENTS.md` before acting. Follow those files as the
7
+ complete role and framework contract.
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: threenative-capabilities
3
+ description: Discover and use the ThreeNative capability surface before writing a game system. Use before prd-creator drafts a plan, and before building or replacing any world, traversal, interaction, simulation, combat, camera, audio, UI, entity, movement, navigation, attachment, particle, terrain, or measurement system.
4
+ ---
5
+
6
+ # ThreeNative capabilities
7
+
8
+ This is a critical planning prerequisite. Use it before `prd-creator` drafts a plan, and before
9
+ replacing any world, traversal, interaction, simulation, combat, camera, audio, UI, entity,
10
+ movement, navigation, attachment, particle, terrain, or measurement system.
11
+
12
+ 1. Infer the concrete mechanics from the request. Preserve its distinctive fantasy with the
13
+ smallest characteristic loop; ask one short question only when two core loops remain equally
14
+ plausible.
15
+ 2. Search the full request with `engine_search_capabilities` using `scope: "request"`, then search
16
+ every mechanic with `scope: "mechanic"`. Check each returned `matchedSituation`.
17
+ 3. Record a capability or no-match for every mechanic before writing a replacement. Describe
18
+ situations plainly, such as *"enemy walks around a wall"*.
19
+ 4. Hand the recorded matches, inspected constraints, and no-matches to `prd-creator`; the PRD must
20
+ plan against this actual engine surface.
21
+
22
+ The manifest is the complete public surface; grep misses subpath exports such as
23
+ `@threenative/physics/navigation`. If MCP is unavailable after `npx threenative doctor`, use
24
+ `agent-docs/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
25
+ Returned constraints are binding: import navigation from its returned subpath, use `attachToBone`
26
+ for held weapons (add a portable `Bone` named `RightHand` when needed), and never invent platform
27
+ support. One game rewrote 446 installed lines and ran at 9 FPS; discovery prevents that.
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: threenative-context
3
+ description: Use the portable ThreeNative ctx lifecycle, scheduling, randomness, pointer, and raycast APIs. Use when writing scene changes, timers, tweens, randomness, pointer or drag handling, raycasts, or startup gating rather than hand-rolling them, and when `pnpm budgets` rejects a raw construct.
4
+ ---
5
+
6
+ # ThreeNative context surface
7
+
8
+ These are properties on `ctx`, never imports; use them before writing equivalent game plumbing.
9
+ The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
10
+ `engine_search_capabilities`.
11
+
12
+ | Use | Instead of | Contract |
13
+ |---|---|---|
14
+ | `ctx.goto("<scene-name>")` | hand reset | async scene rebuild |
15
+ | `ctx.tween(...)` | `Math.sin`/`lerp` accumulator | timed interpolation with optional `ease` |
16
+ | `ctx.after(...)` / `ctx.every(...)` | timer branches in `update` | disposable schedules |
17
+ | `ctx.random.range(-1, 1)` | `Math.random()` | reproducible when `seed` is configured |
18
+ | `ctx.pointer.on(...)` / `ctx.pointer.drag(...)` | hover/press/drag bookkeeping | web/native pointer-id stream |
19
+ | `ctx.raycast()` / `ctx.raycastAll()` | `new Raycaster()` | backend-neutral intersections |
20
+ | `ctx.startup.hold(label, work)` | a loading screen that waits past `whenReady()` | the game's own launch work joins the readiness gate |
21
+
22
+ `ctx.pointer` dispatches entered, exited, pressed, released, tapped, drag-started, dragged, and
23
+ drag-ended events. Register a mesh/model root; only registered objects are raycast and events bubble
24
+ through parents.
25
+
26
+ `ctx.goto(name)` rebuilds the scene without resetting state; values in `ctx.state` survive. From a
27
+ frame function, `goto` and then `return` immediately because the old scene is torn down. For a full
28
+ restart, `game.goto("<scene-name>")` from React resets declared initial state first. A state reset
29
+ uses `ctx.state.set({ /* copy this game's initial-state shape */ })` before the goto. `ctx.random` is
30
+ deterministic only when `defineGame({ seed })` is configured.
31
+
32
+ `pnpm budgets` rejects superseded raw constructs such as `new Audio(`, `Math.random(`,
33
+ `new Raycaster(`, `.visible = false`, and `new Box3().setFromObject(`; use the named capability or
34
+ annotate a genuinely necessary line with a non-empty `// engine-override: reason`.
35
+
36
+ <!-- generated: superseded-constructs -->
37
+
38
+ **Reinvention fails CI.** `pnpm budgets` scans this project's `src/` for these raw
39
+ constructs and fails, naming the capability instead. The list and the gate are generated
40
+ from the capabilities' own doc tags, so they cannot disagree:
41
+
42
+ | Rather than write | Use instead | Import from |
43
+ |---|---|---|
44
+ | `new Audio(` | `AudioBus` | `@threenative/core` |
45
+ | `Math.random(` | `createRandom` | `@threenative/core` |
46
+ | `new Box3().setFromObject(` | `normaliseToMetres` | `@threenative/core` |
47
+ | `.visible = false` | `prewarm` | `@threenative/core` |
48
+ | `new Raycaster(` | `ScenePicker` | `@threenative/core` |
49
+
50
+ When the raw construct is genuinely right, annotate that exact line with a non-empty
51
+ reason — a bare `// engine-override:` still fails:
52
+
53
+ ```ts
54
+ const bounds = new Box3().setFromObject(viewmodel); // engine-override: measuring, not scaling
55
+ ```
56
+
57
+ <!-- /generated -->
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: threenative-performance
3
+ description: Measure ThreeNative frame budgets and report platform evidence without guessing. Use when a frame budget, FPS floor, or platform performance claim is in question, when reading `TN_FRAME_BUDGET`, or when writing a bounded performance assertion.
4
+ ---
5
+
6
+ # ThreeNative performance evidence
7
+
8
+ Refill scratch and pool objects. Static GLBs may use `assets.models.lightmap:{atlasSize,padding}`;
9
+ load through `ctx.assets.model()`, remove it to roll back, and never claim Android/iOS from a
10
+ web/desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`, and
11
+ `residual`; `defineGame({ frameBudget: false })` silences output, never measurement.
12
+
13
+ Unexecuted platforms stay unverified; never invent numbers. Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. The bounded proof shape is
14
+ `{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12}}}` and its
15
+ fields are defined in `agent-docs/assertion-reference.md#performance`.
16
+
17
+ |Tier|Measure|Floor|Target|
18
+ |---|---|---:|---:|
19
+ |1|Starter/browser-desktop|60fps|display-refresh|
20
+ |1|Starter/browser-Android|30fps|58fps|
21
+ |1|Starter/native-desktop|60fps|display-refresh|
22
+ |1|Starter/native-Android|55fps|58fps|
23
+ |1|Starter/native-iOS|unverified|no-number|
24
+ |1|All-platform/hostGap-p95|—|≤4ms|
25
+ |1|All-platform/update-p95|—|≤2ms|
26
+ |1|All-platform/residual-p95|—|≤0.5ms|
27
+ |1|All-platform/overlay-p95|—|≤1ms|
28
+ |2|Same-device-fps-parity|.85|.95|
29
+ |2|Inverted-render-p95-parity|.80|.95|
30
+ |3|Light|55fps|58fps|
31
+ |3|Medium|30fps|58fps|
32
+ |3|Heavy|30fps|58fps|
33
+ |4|Sustained-duration|10min|10min|
34
+ |4|Final/opening-fps|.75|.90|
35
+ |4|Last-minute-heavy|25fps|50fps|
36
+ |4|Peak-battery-temperature|≤45C|≤40C|
37
+ |4|Thermal-status|≤2|≤1|
38
+ |4|Whole-device-current|—|report;not-gated|
39
+
40
+ On Android, budget roughly a 500 MiB driver floor before your own textures; a dual-use
41
+ equirectangular environment adds about 48 MiB. Fix it with `agent-docs/mobile-memory-budget.md`,
42
+ which carries the measurement conditions behind both numbers.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: threenative-playtest
3
+ description: Diagnose a ThreeNative game, prove behavior, and keep playtests fail-closed. Use for a blank, black, or washed-out frame, a browser, device, or import failure, or when writing or repairing a playtest scenario and its assertions.
4
+ ---
5
+
6
+ # ThreeNative diagnosis and playtests
7
+
8
+ For browser, blank-frame, device, or import failures, run `npx threenative doctor` and
9
+ `npx @threenative/playtest doctor` first. For a running game, use:
10
+
11
+ ```sh
12
+ npx @threenative/playtest doctor --url http://127.0.0.1:5173 --text
13
+ npx @threenative/playtest playtests/<name>.playtest.json --browser-recipe webgpu --headed
14
+ ```
15
+
16
+ Read visibility, scale, draw cost, frame rate, advancing state, and errors. Missing output means
17
+ unobserved, never zero.
18
+
19
+ **Read the room before you reach for a screenshot.** `doctor --url` also reports three lines named
20
+ lighting, materials and camera — how many lights the renderer can see, what materials are mounted,
21
+ the background, the fog, and the camera's position and clip planes — and it names the three ways a
22
+ frame dies while every other number looks healthy: lit materials with no visible light, a fog far
23
+ plane in front of the scene it fogs, and a camera far plane that clips it. A black or washed-out
24
+ frame is a question those lines answer and a screenshot cannot.
25
+
26
+ Bound the same things in a scenario so the check outlives the session:
27
+ `assert.scene` takes `minVisibleLights`, `litMaterialsAreLit`, `fogClearsScene` and
28
+ `cameraClearsScene`; `assert.animation[]` takes `maxFootSlide` and `strideSynced`, which catch a
29
+ character skating across the floor when the clip and the ground disagree. Both fail closed — a
30
+ bridge that reports no scene has not reported a well-lit one. For a relative-placement question, publish a scene probe with derived
31
+ `checks`, drive it with Playwright, sweep candidates in one run, and turn the winning check into a
32
+ playtest assertion.
33
+
34
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
35
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, entity registry, and bridge;
36
+ avoid `document`, `window`, `localStorage`, dynamic `import()`, and raw physics handles. **Report
37
+ what blocked you**: API, expectation, result, and replacement. Never stall on a framework bug.
38
+
39
+ Playtests fail closed: a missing entity, absent observation, or empty assertion set fails. Every
40
+ `allowTrivial` waiver needs a 20-character reason; `true` alone is invalid, and all-waived
41
+ triviality fails `TN_PLAYTEST_SCENARIO_ASSERTS_NOTHING`. Use `holdTicks`/`waitTicks` for fixed-step
42
+ time (`holdFrames`/`waitFrames` are compatibility aliases); `warmupFrames` means RAF warmup.
43
+ Read `agent-docs/assertion-reference.md` for assertion fields and `agent-docs/debug-surface.md`
44
+ for bridge globals. The JSON-safe bridge resource is `state`; `GameState` is a deprecated alias.
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: threenative-ui
3
+ description: Build a native-safe ThreeNative React UI that communicates through state and intents. Use when adding or changing a HUD, menu, or any React UI that must also run on native, where the layout key set is fixed and CSS does not exist.
4
+ ---
5
+
6
+ # ThreeNative UI
7
+
8
+ Use `View` and `Text` from `@threenative/core/react` for native UI; `react-dom` is web-only.
9
+ Native layout is pixel-based and absolute unless `direction` is `row` or `column`. Supported keys
10
+ are `left`, `right`, `top`, `bottom`, `centerX`, `centerY`, `width`, `height`, `padding`,
11
+ `direction`, `gap`, `align`, `background`, `color`, `opacity`, `fontSize`, `letterSpacing`,
12
+ `textAlign`, and `zIndex`; CSS, Tailwind, flex grow/wrap, borders, radius, transforms, images, SVG,
13
+ and events do not exist in the native renderer.
14
+
15
+ On native, game and UI are separate processes. The UI reads published JSON-safe state and sends
16
+ intents; `src/game.ts` decides their meaning. `useUiState<GameState>()` is undefined until the first
17
+ snapshot, and `useUiIntent()` sends commands. Mark every touch target `data-tn-interactive`; the
18
+ host routes marked pointer-down events to UI and unmarked touches to the game. Share state and
19
+ components, but keep appearance in `src/ui/`. The full state, hit-region, and renderer contract is
20
+ `agent-docs/webview-ui.md`.
@@ -0,0 +1,7 @@
1
+ ---
2
+ name: threenative-verifier
3
+ description: Independently verify a ThreeNative change without editing it. Use when a change needs a fresh read-only check that its evidence actually holds; the complete role and framework contract is `.threenative/agents/verifier.md`.
4
+ ---
5
+
6
+ Read `.threenative/agents/verifier.md` and `AGENTS.md` before acting. Follow those files as the
7
+ complete role and framework contract.