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,32 @@
1
+ {
2
+ "mcpServers": {
3
+ "threenative-assets": {
4
+ "command": "node",
5
+ "args": [
6
+ "./node_modules/@threenative/core/mcp/assets.mjs"
7
+ ],
8
+ "env": {
9
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
10
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
11
+ }
12
+ },
13
+ "threenative-sculpt": {
14
+ "command": "node",
15
+ "args": [
16
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
17
+ ]
18
+ },
19
+ "threenative-engine": {
20
+ "command": "node",
21
+ "args": [
22
+ "./node_modules/@threenative/core/mcp/engine.mjs"
23
+ ]
24
+ },
25
+ "threenative-blender": {
26
+ "command": "node",
27
+ "args": [
28
+ "./node_modules/@threenative/core/mcp/blender.mjs"
29
+ ]
30
+ }
31
+ }
32
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "mcpServers": {
3
+ "threenative-assets": {
4
+ "command": "node",
5
+ "args": [
6
+ "./node_modules/@threenative/core/mcp/assets.mjs"
7
+ ],
8
+ "env": {
9
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
10
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
11
+ }
12
+ },
13
+ "threenative-sculpt": {
14
+ "command": "node",
15
+ "args": [
16
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
17
+ ]
18
+ },
19
+ "threenative-engine": {
20
+ "command": "node",
21
+ "args": [
22
+ "./node_modules/@threenative/core/mcp/engine.mjs"
23
+ ]
24
+ },
25
+ "threenative-blender": {
26
+ "command": "node",
27
+ "args": [
28
+ "./node_modules/@threenative/core/mcp/blender.mjs"
29
+ ]
30
+ }
31
+ }
32
+ }
@@ -0,0 +1,36 @@
1
+ {
2
+ "servers": {
3
+ "threenative-assets": {
4
+ "type": "stdio",
5
+ "command": "node",
6
+ "args": [
7
+ "./node_modules/@threenative/core/mcp/assets.mjs"
8
+ ],
9
+ "env": {
10
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
11
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
12
+ }
13
+ },
14
+ "threenative-sculpt": {
15
+ "type": "stdio",
16
+ "command": "node",
17
+ "args": [
18
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
19
+ ]
20
+ },
21
+ "threenative-engine": {
22
+ "type": "stdio",
23
+ "command": "node",
24
+ "args": [
25
+ "./node_modules/@threenative/core/mcp/engine.mjs"
26
+ ]
27
+ },
28
+ "threenative-blender": {
29
+ "type": "stdio",
30
+ "command": "node",
31
+ "args": [
32
+ "./node_modules/@threenative/core/mcp/blender.mjs"
33
+ ]
34
+ }
35
+ }
36
+ }
@@ -0,0 +1,36 @@
1
+ {
2
+ "context_servers": {
3
+ "threenative-assets": {
4
+ "source": "custom",
5
+ "command": "node",
6
+ "args": [
7
+ "./node_modules/@threenative/core/mcp/assets.mjs"
8
+ ],
9
+ "env": {
10
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
11
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
12
+ }
13
+ },
14
+ "threenative-sculpt": {
15
+ "source": "custom",
16
+ "command": "node",
17
+ "args": [
18
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
19
+ ]
20
+ },
21
+ "threenative-engine": {
22
+ "source": "custom",
23
+ "command": "node",
24
+ "args": [
25
+ "./node_modules/@threenative/core/mcp/engine.mjs"
26
+ ]
27
+ },
28
+ "threenative-blender": {
29
+ "source": "custom",
30
+ "command": "node",
31
+ "args": [
32
+ "./node_modules/@threenative/core/mcp/blender.mjs"
33
+ ]
34
+ }
35
+ }
36
+ }
@@ -0,0 +1,96 @@
1
+ # AGENTS.md — __PROJECT_NAME__ runner
2
+
3
+ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
4
+
5
+ ## Ownership
6
+
7
+ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the track, the runner, the obstacles, the dust, the HUD and the
8
+ look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
9
+
10
+ ## Start every change
11
+
12
+ 1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
+ `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
14
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan.
15
+ 2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
+ direct the user to review it, and wait for explicit approval plus an instruction to implement it.
17
+ 3. Treat returned constraints as binding. No navmesh is imported, so this kit runs on every
18
+ target; `@threenative/physics/navigation` would make it web and desktop only. `GPUParticles3D`
19
+ is WebGPU-only and the dust depends on it.
20
+ 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
21
+ `npx @threenative/playtest doctor`; missing observations are not zero.
22
+ For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
23
+
24
+ ## When the framework blocks you, write plain Three.js
25
+
26
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
27
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
28
+ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
29
+ (API, expectation, result, replacement); never stall the game.
30
+
31
+ ## Workflow skills
32
+
33
+ - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
34
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
35
+ - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
36
+ - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
37
+ - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
38
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
39
+ - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
40
+ - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
41
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
42
+
43
+ ## Commands and map
44
+
45
+ ```sh
46
+ pnpm dev
47
+ pnpm build
48
+ pnpm build --target desktop
49
+ pnpm test
50
+ pnpm typecheck
51
+ ```
52
+
53
+ `src/track.ts` is a ring of six chunks **moved and rewritten**, never rebuilt: each chunk's
54
+ obstacle `InstancedMesh` is built once at a fixed slot count and its matrices rewritten on
55
+ recycle. The obstacle *bodies* are the exception — disposed and recreated, because `RigidBody3D`
56
+ cannot reposition a fixed body. The runner is not a rigid body — a lane snap and a jump
57
+ arc feel worse in a solver — but the collision is real: `src/entities/Runner.ts` carries an
58
+ `Area3D` masked to the obstacle layer and listens for `bodyEntered`, so a hit is an overlap the
59
+ engine reports rather than a hand-maintained distance check. Gravity is zero in `src/game.ts` on purpose;
60
+ nothing falls. The track comes from `ctx.random`, so `defineGame({ seed })` **is** the level.
61
+ Register entities with `ctx.entities`; the React HUD reads `GameState`, never an entity. Keep `playtests/survives.playtest.json` as smoke proof, and `streams` honest
62
+ when chunk recycling changes.
63
+
64
+ ## Portable authoring contracts
65
+
66
+ 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.
67
+
68
+ 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.
69
+ 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.
70
+ The camera reads the runner **after** the step through `afterPhysics` — in the frame function that
71
+ is 0.4 m of lag at 26 m/s. `CameraShake` returns an offset; `src/render/camera.ts` adds it.
72
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive
73
+ `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from
74
+ a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
75
+ is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
76
+ state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
77
+
78
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
79
+ retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
80
+ own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
81
+ caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
82
+ (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
83
+ `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
84
+ clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
85
+ 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.
86
+
87
+ ## Budget real time for the look — see `agent-docs/dream-loop.md`
88
+
89
+ Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
90
+ tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
91
+ `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
92
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture.
93
+
94
+ 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`.
95
+ ## Optional multiplayer transport
96
+ 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,98 @@
1
+ <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
+
3
+ # AGENTS.md — __PROJECT_NAME__ runner
4
+
5
+ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
6
+
7
+ ## Ownership
8
+
9
+ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the track, the runner, the obstacles, the dust, the HUD and the
10
+ look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
11
+
12
+ ## Start every change
13
+
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. No navmesh is imported, so this kit runs on every
20
+ target; `@threenative/physics/navigation` would make it web and desktop only. `GPUParticles3D`
21
+ is WebGPU-only and the dust depends on it.
22
+ 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
23
+ `npx @threenative/playtest doctor`; missing observations are not zero.
24
+ For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
25
+
26
+ ## When the framework blocks you, write plain Three.js
27
+
28
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
29
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
30
+ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
31
+ (API, expectation, result, replacement); never stall the game.
32
+
33
+ ## Workflow skills
34
+
35
+ - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
36
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
37
+ - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
38
+ - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
39
+ - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
40
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
41
+ - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
42
+ - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
43
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
44
+
45
+ ## Commands and map
46
+
47
+ ```sh
48
+ pnpm dev
49
+ pnpm build
50
+ pnpm build --target desktop
51
+ pnpm test
52
+ pnpm typecheck
53
+ ```
54
+
55
+ `src/track.ts` is a ring of six chunks **moved and rewritten**, never rebuilt: each chunk's
56
+ obstacle `InstancedMesh` is built once at a fixed slot count and its matrices rewritten on
57
+ recycle. The obstacle *bodies* are the exception — disposed and recreated, because `RigidBody3D`
58
+ cannot reposition a fixed body. The runner is not a rigid body — a lane snap and a jump
59
+ arc feel worse in a solver — but the collision is real: `src/entities/Runner.ts` carries an
60
+ `Area3D` masked to the obstacle layer and listens for `bodyEntered`, so a hit is an overlap the
61
+ engine reports rather than a hand-maintained distance check. Gravity is zero in `src/game.ts` on purpose;
62
+ nothing falls. The track comes from `ctx.random`, so `defineGame({ seed })` **is** the level.
63
+ Register entities with `ctx.entities`; the React HUD reads `GameState`, never an entity. Keep `playtests/survives.playtest.json` as smoke proof, and `streams` honest
64
+ when chunk recycling changes.
65
+
66
+ ## Portable authoring contracts
67
+
68
+ 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.
69
+
70
+ 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.
71
+ 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.
72
+ The camera reads the runner **after** the step through `afterPhysics` — in the frame function that
73
+ is 0.4 m of lag at 26 m/s. `CameraShake` returns an offset; `src/render/camera.ts` adds it.
74
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive
75
+ `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from
76
+ a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
77
+ is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
78
+ state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
79
+
80
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
81
+ retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
82
+ own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
83
+ caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
84
+ (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
85
+ `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
86
+ clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
87
+ 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.
88
+
89
+ ## Budget real time for the look — see `agent-docs/dream-loop.md`
90
+
91
+ Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
92
+ tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
93
+ `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
94
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture.
95
+
96
+ 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,43 @@
1
+ # Runner starter kit
2
+
3
+ Three lanes and a track that builds itself ahead of you. Obstacles end the run; passing one
4
+ close shakes the camera. The track is a ring of six chunks that get moved and rebuilt, so a
5
+ ten-minute run costs what a ten-second one does.
6
+
7
+ Nothing here is downloaded. Every shape is a box, capsule or cylinder built in
8
+ `src/render/shapes.ts`, and the dust is a TSL particle surface in `src/render/dust.ts` — no
9
+ texture, no asset licence, nothing to fetch.
10
+
11
+ ```sh
12
+ pnpm dev # play it
13
+ pnpm test # the committed scenarios, in a real browser
14
+ pnpm build # web
15
+ pnpm build --target desktop
16
+ ```
17
+
18
+ ## Controls
19
+
20
+ | Input | Does |
21
+ | --- | --- |
22
+ | `A` / `D`, or arrows | change lane |
23
+ | `Space` | jump |
24
+ | `R` | run again |
25
+
26
+ On a touch device two lane buttons and a thumbstick appear; flick the stick up to jump.
27
+
28
+ ## What each piece is
29
+
30
+ | File | Owns |
31
+ | --- | --- |
32
+ | `src/track.ts` | the chunk ring — build, recycle, and the obstacle bodies |
33
+ | `src/entities/Runner.ts` | the lane snap, the jump arc, and the `Area3D` that detects a hit |
34
+ | `src/render/dust.ts` | the trail: a game-authored TSL surface handed to `GPUParticles3D` |
35
+ | `src/render/camera.ts` | the chase rig, and where the shake is added |
36
+ | `src/render/` | everything that decides how it looks. Yours to rewrite. |
37
+
38
+ ## Where to take it
39
+
40
+ The track is `RESIDENT_CHUNKS` slices and one `build` method. Add a second obstacle height that
41
+ has to be jumped rather than dodged, a pickup lane, a speed gate, or a second seed that swaps the
42
+ palette every kilometre. `defineGame({ seed })` is the level — change it and the whole track
43
+ changes, deterministically.
@@ -0,0 +1,12 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>__PROJECT_NAME__</title>
7
+ </head>
8
+ <body>
9
+ <div id="root"></div>
10
+ <script type="module" src="/src/main.ts"></script>
11
+ </body>
12
+ </html>
@@ -0,0 +1,7 @@
1
+ {
2
+ "name": "runner",
3
+ "title": "Endless runner",
4
+ "blurb": "Three lanes, a track that builds itself ahead of you, and obstacles that end the run.",
5
+ "genre": "endless-runner",
6
+ "kit": true
7
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "$schema": "https://opencode.ai/config.json",
3
+ "mcp": {
4
+ "threenative-assets": {
5
+ "type": "local",
6
+ "command": [
7
+ "node",
8
+ "./node_modules/@threenative/core/mcp/assets.mjs"
9
+ ],
10
+ "enabled": true,
11
+ "environment": {
12
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
13
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
14
+ }
15
+ },
16
+ "threenative-sculpt": {
17
+ "type": "local",
18
+ "command": [
19
+ "node",
20
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
21
+ ],
22
+ "enabled": true
23
+ },
24
+ "threenative-engine": {
25
+ "type": "local",
26
+ "command": [
27
+ "node",
28
+ "./node_modules/@threenative/core/mcp/engine.mjs"
29
+ ],
30
+ "enabled": true
31
+ },
32
+ "threenative-blender": {
33
+ "type": "local",
34
+ "command": [
35
+ "node",
36
+ "./node_modules/@threenative/core/mcp/blender.mjs"
37
+ ],
38
+ "enabled": true
39
+ }
40
+ }
41
+ }
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "__PROJECT_NAME__",
3
+ "private": true,
4
+ "license": "MIT",
5
+ "type": "module",
6
+ "scripts": {
7
+ "dev": "vite",
8
+ "build": "threenative build",
9
+ "build:web": "threenative build --target web",
10
+ "build:desktop": "threenative build --target desktop",
11
+ "build:android": "threenative build --target android",
12
+ "build:ios": "threenative build --target ios",
13
+ "pretest": "playwright install chromium",
14
+ "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
15
+ "typecheck": "tsc --noEmit -p tsconfig.json"
16
+ },
17
+ "dependencies": {
18
+ "@threenative/core": "0.3.1",
19
+ "@threenative/physics": "0.3.1",
20
+ "@threenative/ui": "0.3.1",
21
+ "react": "19.2.0",
22
+ "react-dom": "19.2.0",
23
+ "three": "0.185.1"
24
+ },
25
+ "devDependencies": {
26
+ "@gltf-transform/cli": "4.4.2",
27
+ "@tailwindcss/vite": "4.3.3",
28
+ "@threenative/assets": "0.3.1",
29
+ "@threenative/playtest": "0.3.1",
30
+ "@types/react": "19.2.0",
31
+ "@types/react-dom": "19.2.0",
32
+ "@types/three": "0.185.3",
33
+ "@vitejs/plugin-react": "6.0.5",
34
+ "create-threenative": "0.2.4",
35
+ "esbuild": "0.27.0",
36
+ "playwright": "1.62.1",
37
+ "tailwindcss": "4.3.3",
38
+ "typescript": "5.9.3",
39
+ "vite": "8.2.0"
40
+ },
41
+ "optionalDependencies": {
42
+ "@threenative/runtime-native": "0.3.1"
43
+ },
44
+ "pnpm": {
45
+ "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
46
+ "patchedDependencies": {
47
+ "three@0.185.1": "patches/three@0.185.1.patch"
48
+ }
49
+ }
50
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "acceptanceId": "runner-production-performance",
3
+ "artifacts": { "screenshots": "after" },
4
+ "assert": {
5
+ "performance": {
6
+ "maxDrawCalls": 145,
7
+ "maxFrameMsP95": 33,
8
+ "maxTriangles": 26000,
9
+ "minFps": 30
10
+ },
11
+ "renderChain": { "tier": "high" }
12
+ },
13
+ "name": "production-performance",
14
+ "schemaVersion": 1,
15
+ "steps": [
16
+ { "kind": "input", "press": "KeyA", "holdTicks": 6, "release": true },
17
+ { "kind": "wait", "waitTicks": 600, "release": true }
18
+ ],
19
+ "subject": "player",
20
+ "target": "web",
21
+ "viewport": { "height": 1080, "width": 1920 },
22
+ "warmupFrames": 60
23
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "name": "streams",
3
+ "target": "web",
4
+ "schemaVersion": 1,
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 40,
7
+ "subject": "player",
8
+ "steps": [
9
+ { "kind": "wait", "label": "run-a-while", "waitTicks": 300, "release": true },
10
+ { "kind": "input", "label": "lane-left", "press": "KeyA", "holdTicks": 6, "release": true },
11
+ { "kind": "wait", "label": "settle", "waitTicks": 60, "release": true }
12
+ ],
13
+ "assert": {
14
+ "diagnostics": {
15
+ "noConsoleErrors": true,
16
+ "noNetworkErrors": true,
17
+ "noRuntimeDiagnostics": true,
18
+ "runtimeReady": true
19
+ },
20
+ "resources": [
21
+ {
22
+ "id": "GameState",
23
+ "path": "chunks",
24
+ "gte": 7
25
+ },
26
+ {
27
+ "changed": true,
28
+ "id": "GameState",
29
+ "path": "distance"
30
+ }
31
+ ],
32
+ "movement": {
33
+ "entity": "player",
34
+ "minDistance": 20,
35
+ "minAxisDelta": { "axis": "-z", "min": 20 }
36
+ }
37
+ }
38
+ }
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "survives",
3
+ "target": "web",
4
+ "schemaVersion": 1,
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 40,
7
+ "subject": "player",
8
+ "steps": [
9
+ { "kind": "input", "label": "move", "press": "ArrowUp", "holdTicks": 60, "release": true },
10
+ { "kind": "wait", "label": "settle", "waitTicks": 10, "release": true }
11
+ ],
12
+ "assert": {
13
+ "diagnostics": {
14
+ "noConsoleErrors": true,
15
+ "noNetworkErrors": true,
16
+ "noRuntimeDiagnostics": true,
17
+ "runtimeReady": true
18
+ },
19
+ "components": [
20
+ {
21
+ "allowTrivial": "GroundSnap settles the runner on the track before this observation; the finite near-zero clearance is the generated call-site proof.",
22
+ "component": "groundClearance",
23
+ "entity": "player",
24
+ "lte": 0.01
25
+ }
26
+ ],
27
+ "movement": {
28
+ "entity": "player",
29
+ "minDistance": 0.5,
30
+ "minAxisDelta": { "axis": "-z", "min": 0.5 }
31
+ },
32
+ "visibility": [
33
+ {
34
+ "entity": "touch-controls",
35
+ "present": false,
36
+ "allowTrivial": "Desktop keyboard lanes intentionally omit touch controls while movement proves the scene is active."
37
+ }
38
+ ],
39
+ "visual": [
40
+ {
41
+ "region": {
42
+ "x": 0,
43
+ "y": 0,
44
+ "width": 1280,
45
+ "height": 720,
46
+ "minNonblankPixelRatio": 0.01
47
+ }
48
+ }
49
+ ]
50
+ }
51
+ }
@@ -0,0 +1,5 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
2
+ <rect width="64" height="64" rx="12" fill="#07131d"/>
3
+ <path d="M15 49 32 12l17 37-17-8-17 8Z" fill="#f5c451"/>
4
+ <path d="M32 23v20" stroke="#07131d" stroke-width="5"/>
5
+ </svg>
@@ -0,0 +1,24 @@
1
+ import { GroundSnap, normaliseToMetres } from "@threenative/core";
2
+ import type { Group } from "three";
3
+
4
+ export interface IRunnerConventions {
5
+ readonly applyGrounding: (surfaceY: number, dt: number) => void;
6
+ readonly groundSnap: GroundSnap;
7
+ readonly normaliseFactor: number;
8
+ }
9
+
10
+ /**
11
+ * One metre is one metre, and the runner's feet meet the track — including mid-jump.
12
+ *
13
+ * `GroundSnap` takes the surface height as an argument, so a jump is a *surface that moved*
14
+ * rather than an exception to grounding. That is what keeps the landing exact at any frame rate.
15
+ */
16
+ export function prepareRunnerConventions(model: Group): IRunnerConventions {
17
+ const normaliseFactor = normaliseToMetres(model, { axis: "height", metres: 1.6 });
18
+ const groundSnap = new GroundSnap(model);
19
+ return {
20
+ applyGrounding: (surfaceY, dt) => groundSnap.apply(model, surfaceY, dt),
21
+ groundSnap,
22
+ normaliseFactor,
23
+ };
24
+ }