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,137 @@
1
+ import { type ICtx, SoftBody3D } from "@threenative/core";
2
+ import { Area3D, CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
3
+ import { type BufferGeometry, type Material, Matrix4, Mesh } from "three";
4
+ import { tessellatePennant } from "../render/pennant.js";
5
+ import { block, tube } from "../render/shapes.js";
6
+ import type { GameState } from "../state.js";
7
+
8
+ /**
9
+ * The far side of the gap: a fixed island, a flagpole, and the pennant the packaged glTF
10
+ * proof asset is cut from. Landing anywhere on it ends the run.
11
+ *
12
+ * The island top sits below the ledge on purpose. A same-height landing has to be jumped
13
+ * within a couple of frames of the edge; dropping 0.4 m widens that window to about half
14
+ * a second, which is what makes coyote time feel generous instead of decorative. Its visual
15
+ * slab is shallow because the waterline sits just below the top, so the far island reads as
16
+ * a sandbar rather than a submerged rectangular block.
17
+ */
18
+ export const ISLAND = { depth: 2.6, height: 0.1, top: -0.4, width: 3, x: 7.9, z: 0 } as const;
19
+ const POLE = { height: 2.4, radius: 0.05, x: 8.4, z: -0.5 } as const;
20
+ const PENNANT_SCALE = 0.55;
21
+
22
+ export interface IGoalMaterials {
23
+ /** The island itself: the same ground the ledge is made of, across the gap. */
24
+ readonly floor: Material;
25
+ /** The pole. The accent role, and the only warm thing on the far side. */
26
+ readonly goal: Material;
27
+ /** The sandbar's beach rim and the flank below it. */
28
+ readonly shore: Material;
29
+ }
30
+
31
+ export class Goal {
32
+ /** The whole marker, so a playtest `visibility` row can ask whether it is on screen. */
33
+ readonly mesh: SoftBody3D;
34
+ readonly pennant: SoftBody3D;
35
+ readonly area: Area3D;
36
+ readonly #body: RigidBody3D;
37
+
38
+ constructor(ctx: ICtx<GameState, IPhysicsContext>, materials: IGoalMaterials, pennant: Mesh) {
39
+ // Children carry world coordinates and the group stays at the origin: a physics body
40
+ // reads its object's own transform, and a nested offset would silently desync them.
41
+ const island = block(ISLAND.width, ISLAND.height, ISLAND.depth, materials.floor, {
42
+ radius: 0.16,
43
+ });
44
+ island.position.set(ISLAND.x, ISLAND.top - ISLAND.height / 2, ISLAND.z);
45
+ const pole = tube(POLE.radius, POLE.radius, POLE.height, materials.goal);
46
+ pole.position.set(POLE.x, ISLAND.top + POLE.height / 2, POLE.z);
47
+ // The proof triangle points +x once it is turned on its side, which is a pennant. Its
48
+ // hoist edge lands on the pole; the rest of it flies clear.
49
+ const transform = new Matrix4()
50
+ .makeRotationZ(-Math.PI / 2)
51
+ .premultiply(new Matrix4().makeScale(PENNANT_SCALE, PENNANT_SCALE, PENNANT_SCALE))
52
+ .premultiply(
53
+ new Matrix4().makeTranslation(
54
+ POLE.x + 0.6 * PENNANT_SCALE,
55
+ ISLAND.top + POLE.height - 0.5,
56
+ POLE.z + POLE.radius,
57
+ ),
58
+ );
59
+ const geometry = tessellatePennant(pennant.geometry).applyMatrix4(transform);
60
+ this.pennant = new SoftBody3D(new Mesh(geometry, pennant.material), {
61
+ damping: 1.8,
62
+ gravity: [0, 0, 0],
63
+ pinned: pinnedHoist(geometry),
64
+ readbackEveryFrames: 2,
65
+ stiffness: 36,
66
+ wind: [0, 0, 0],
67
+ });
68
+ this.pennant.name = "finish-flag-cloth";
69
+ this.mesh = this.pennant;
70
+ // A sand rim and a flank, so the far side is a sandbar and not a green rectangle floating on
71
+ // the water. Left bare it was the one piece of the coast with a hard cut edge and no shore,
72
+ // and it read as unfinished next to the main island's beach.
73
+ const rim = block(ISLAND.width + 0.7, 0.09, ISLAND.depth + 0.7, materials.shore, {
74
+ radius: 0.3,
75
+ });
76
+ rim.position.set(ISLAND.x, ISLAND.top - ISLAND.height - 0.02, ISLAND.z);
77
+ const flank = block(ISLAND.width + 0.35, 0.5, ISLAND.depth + 0.35, materials.shore, {
78
+ radius: 0.24,
79
+ });
80
+ flank.position.set(ISLAND.x, ISLAND.top - ISLAND.height - 0.3, ISLAND.z);
81
+ this.mesh.add(island, rim, flank, pole);
82
+ ctx.add(this.mesh);
83
+
84
+ this.#body = new RigidBody3D({
85
+ object: island,
86
+ physics: ctx.physics,
87
+ shape: CollisionShape3D.fromMesh(island),
88
+ type: "fixed",
89
+ });
90
+ // Tall enough to catch a landing, shallow enough that a body still falling past the
91
+ // island's flank in the gap is metres below it and never trips the finish.
92
+ this.area = new Area3D({
93
+ physics: ctx.physics,
94
+ position: { x: ISLAND.x, y: ISLAND.top + 0.8, z: ISLAND.z },
95
+ shape: CollisionShape3D.box(ISLAND.width, 1.6, ISLAND.depth),
96
+ });
97
+ }
98
+
99
+ /** Maximum local-Z movement from the authored plane in the latest throttled GPU sample. */
100
+ flagDisplacement(): number {
101
+ const sample = this.pennant.sample;
102
+ if (sample === undefined) return 0;
103
+ let maximum = 0;
104
+ for (let index = 2; index < sample.data.length; index += 3) {
105
+ const z = sample.data[index];
106
+ if (!Number.isFinite(z)) throw new Error(`Starter flag readback was non-finite at ${index}.`);
107
+ maximum = Math.max(maximum, Math.abs((z as number) - (POLE.z + POLE.radius)));
108
+ }
109
+ return maximum;
110
+ }
111
+
112
+ readbackLands(): number {
113
+ const stats = this.pennant.debug().readbackStats;
114
+ if (typeof stats !== "object" || stats === null || !("lands" in stats)) return 0;
115
+ const lands = (stats as { lands?: unknown }).lands;
116
+ return typeof lands === "number" ? lands : 0;
117
+ }
118
+
119
+ dispose(): void {
120
+ this.area.dispose();
121
+ this.#body.dispose();
122
+ this.mesh.removeFromParent();
123
+ }
124
+ }
125
+
126
+ function pinnedHoist(geometry: BufferGeometry): number[] {
127
+ const positions = geometry.getAttribute("position");
128
+ if (positions === undefined) throw new Error("Starter flag geometry has no positions.");
129
+ let minimum = Number.POSITIVE_INFINITY;
130
+ for (let index = 0; index < positions.count; index += 1)
131
+ minimum = Math.min(minimum, positions.getX(index));
132
+ const pinned: number[] = [];
133
+ for (let index = 0; index < positions.count; index += 1)
134
+ if (Math.abs(positions.getX(index) - minimum) < 1e-6) pinned.push(index);
135
+ if (pinned.length === 0) throw new Error("Starter flag geometry has no hoist vertices.");
136
+ return pinned;
137
+ }
@@ -1,34 +1,56 @@
1
- import type { ICtx } from "@threenative/core";
1
+ import { type ICtx, mergeParts } from "@threenative/core";
2
2
  import { CharacterBody3D, CollisionShape3D, type IPhysicsContext } from "@threenative/physics";
3
- import { type Material, Mesh } from "three";
4
- import { roundedBox } from "../render/shapes.js";
3
+ import { Group, type Mesh, Vector3 } from "three";
4
+ import { type IStarterConventions, preparePlayerConventions } from "../conventions.js";
5
+ import { type IHeroMaterials, hero } from "../render/hero.js";
6
+ import type { ITouchInput } from "../render/touch-controls.js";
5
7
  import type { GameState } from "../state.js";
6
8
 
7
9
  type GameCtx = ICtx<GameState, IPhysicsContext>;
8
10
 
9
11
  // Tune these two timers for jump feel; they forgive a late or early button press.
12
+ // 0.12s is 7.2 ticks at the 1/60 step, and `playtests/coyote.playtest.json` is written against
13
+ // that: 3 ticks walking off the ledge, 5 more airborne, then the jump — the jump lands about 5
14
+ // ticks after the player actually leaves the ground, inside the window. Change this and those two
15
+ // step lengths move with it. Tightening the airborne hold does NOT make the scenario safer: with
16
+ // 2 the player has not left the ledge yet, and the jump is counted as an ordinary one
17
+ // (`jumps: 1, coyoteJumps: 0`), which is what it measured when I tried.
10
18
  const COYOTE_TIME = 0.12;
11
19
  const JUMP_BUFFER = 0.14;
12
20
  const JUMP_SPEED = 5;
13
21
  const MOVE_SPEED = 2;
22
+ const PLAYER_FOOT_OFFSET = 0.51;
23
+ const VISUAL_ATTACHMENT_TOLERANCE = 0.1;
14
24
  const SPAWN = { x: -2, y: 0.5, z: 0 } as const;
15
25
 
16
26
  export class Player {
17
- readonly mesh: Mesh;
27
+ readonly mesh: Group;
28
+ readonly visual: Mesh;
18
29
  readonly body: CharacterBody3D;
19
30
  #coyoteTime = 0;
20
31
  #jumpBuffer = 0;
21
32
  #jumps = 0;
22
33
  #coyoteJumps = 0;
34
+ #odometer = 0;
35
+ #supportSurfaceY = 0;
36
+ #previousPosition = new Vector3();
37
+ #bodyWorldPosition = new Vector3();
38
+ #visualWorldPosition = new Vector3();
39
+ #visualBodyOffsetY: number | undefined;
40
+ #hasPreviousPosition = false;
41
+ #conventions: IStarterConventions;
23
42
 
24
43
  constructor(
25
44
  ctx: GameCtx,
26
- material: Material,
45
+ materials: IHeroMaterials,
27
46
  spawn: { readonly x: number; readonly y: number; readonly z: number } = SPAWN,
28
47
  ) {
29
- this.mesh = new Mesh(roundedBox(0.6, 1, 0.6), material);
48
+ this.mesh = new Group();
49
+ this.visual = hero(materials, mergeParts);
50
+ this.visual.castShadow = true;
51
+ this.mesh.add(this.visual);
30
52
  this.mesh.position.set(spawn.x, spawn.y, spawn.z);
31
- this.mesh.castShadow = true;
53
+ this.#conventions = preparePlayerConventions(this.visual);
32
54
  ctx.add(this.mesh);
33
55
  this.body = new CharacterBody3D({
34
56
  autostep: { maxHeight: 0.4, minWidth: 0.2 },
@@ -38,12 +60,21 @@ export class Player {
38
60
  });
39
61
  }
40
62
 
41
- update(ctx: GameCtx, dt: number): void {
63
+ update(
64
+ ctx: GameCtx,
65
+ dt: number,
66
+ supportSurfaceY?: (position: Pick<Vector3, "x" | "y" | "z">) => number | undefined,
67
+ touch?: ITouchInput,
68
+ ): void {
69
+ if (this.#hasPreviousPosition) {
70
+ this.#odometer += this.mesh.position.distanceTo(this.#previousPosition);
71
+ }
42
72
  const grounded = this.body.grounded;
43
73
  this.#coyoteTime = Math.max(0, this.#coyoteTime - dt);
44
74
  this.#jumpBuffer = Math.max(0, this.#jumpBuffer - dt);
45
75
  if (grounded) this.#coyoteTime = COYOTE_TIME;
46
- if (ctx.input.justPressed("jump")) this.#jumpBuffer = JUMP_BUFFER;
76
+ if (ctx.input.justPressed("jump") || touch?.jumpPressed === true)
77
+ this.#jumpBuffer = JUMP_BUFFER;
47
78
  if (this.#jumpBuffer > 0 && this.#coyoteTime > 0) {
48
79
  this.body.velocity.y = JUMP_SPEED;
49
80
  this.#jumpBuffer = 0;
@@ -52,29 +83,99 @@ export class Player {
52
83
  if (!grounded) this.#coyoteJumps += 1;
53
84
  }
54
85
  const move = ctx.input.vector("move");
86
+ if (touch !== undefined) {
87
+ move.x += touch.move.x;
88
+ move.y += touch.move.y;
89
+ move.clampLength(0, 1);
90
+ }
55
91
  this.body.velocity.x = move.x * MOVE_SPEED;
56
92
  this.body.velocity.z = -move.y * MOVE_SPEED;
93
+ this.#previousPosition.copy(this.mesh.position);
57
94
  this.body.moveAndSlide(dt);
95
+ this.#hasPreviousPosition = true;
58
96
  if (this.body.grounded) this.#coyoteTime = COYOTE_TIME;
97
+ const supportingSurfaceY = supportSurfaceY?.(this.mesh.position);
98
+ const canCorrectGrounding =
99
+ this.body.grounded && this.body.velocity.y <= 0 && supportingSurfaceY !== undefined;
100
+ // The resolver identifies the supporting collider; derive the contact plane from the
101
+ // grounded character so a changed platform height never pulls the visual from its body.
102
+ if (canCorrectGrounding) this.#supportSurfaceY = this.mesh.position.y - PLAYER_FOOT_OFFSET;
103
+ this.#conventions.groundSnap.enabled = canCorrectGrounding;
104
+ this.#conventions.applyGrounding(this.#supportSurfaceY, dt);
105
+ this.#captureVisualBodyOffset();
59
106
  }
60
107
 
61
108
  respawn(): void {
62
109
  this.body.teleport(SPAWN);
63
110
  this.#coyoteTime = 0;
64
111
  this.#jumpBuffer = 0;
112
+ this.#hasPreviousPosition = false;
65
113
  }
66
114
 
67
- debug(): { coyoteJumps: number; grounded: boolean; jumps: number; position: number[] } {
115
+ debug(): {
116
+ coyoteJumps: number;
117
+ grounded: boolean;
118
+ groundClearance: number | null;
119
+ groundCorrectionEnabled: boolean;
120
+ groundSurfaceY: number;
121
+ jumps: number;
122
+ normaliseFactor: number;
123
+ odometer: number;
124
+ position: number[];
125
+ visualAttached: boolean;
126
+ visualAttachmentDrift: number;
127
+ } {
128
+ const visualAttachmentDrift = this.#visualAttachmentDrift();
68
129
  return {
69
130
  coyoteJumps: this.#coyoteJumps,
70
131
  grounded: this.body.grounded,
132
+ groundClearance: this.#conventions.groundSnap.clearance,
133
+ groundCorrectionEnabled: this.#conventions.groundSnap.enabled,
134
+ groundSurfaceY: this.#supportSurfaceY,
71
135
  jumps: this.#jumps,
136
+ normaliseFactor: this.#conventions.normaliseFactor,
137
+ odometer: this.#odometer,
72
138
  position: this.mesh.position.toArray(),
139
+ visualAttached: visualAttachmentDrift <= VISUAL_ATTACHMENT_TOLERANCE,
140
+ visualAttachmentDrift,
73
141
  };
74
142
  }
75
143
 
144
+ get coyoteJumps(): number {
145
+ return this.#coyoteJumps;
146
+ }
147
+
148
+ get grounded(): boolean {
149
+ return this.body.grounded;
150
+ }
151
+
152
+ get jumps(): number {
153
+ return this.#jumps;
154
+ }
155
+
156
+ get odometer(): number {
157
+ return this.#odometer;
158
+ }
159
+
76
160
  dispose(): void {
77
161
  this.body.dispose();
78
162
  this.mesh.removeFromParent();
79
163
  }
164
+
165
+ #captureVisualBodyOffset(): void {
166
+ if (this.#visualBodyOffsetY !== undefined || !this.body.grounded || this.body.velocity.y > 0)
167
+ return;
168
+ this.mesh.getWorldPosition(this.#bodyWorldPosition);
169
+ this.visual.getWorldPosition(this.#visualWorldPosition);
170
+ this.#visualBodyOffsetY = this.#visualWorldPosition.y - this.#bodyWorldPosition.y;
171
+ }
172
+
173
+ #visualAttachmentDrift(): number {
174
+ if (this.#visualBodyOffsetY === undefined) return 0;
175
+ this.mesh.getWorldPosition(this.#bodyWorldPosition);
176
+ this.visual.getWorldPosition(this.#visualWorldPosition);
177
+ return Math.abs(
178
+ this.#visualWorldPosition.y - this.#bodyWorldPosition.y - this.#visualBodyOffsetY,
179
+ );
180
+ }
80
181
  }
@@ -3,11 +3,13 @@ import { playtest } from "@threenative/core/playtest";
3
3
  import type { IPhysicsContext } from "@threenative/physics";
4
4
  import { rapier } from "@threenative/physics";
5
5
  import config from "../threenative.config.js";
6
+ import { observeQualityWindow } from "./render/postprocessing.js";
6
7
  import { Play } from "./scenes/Play.js";
7
8
  import type { GameState } from "./state.js";
8
9
 
9
10
  // game.state is the single store: the fixed-step loop writes it, and React/playtests read it.
10
11
  const game = defineGame<GameState, IPhysicsContext>({
12
+ frameBudget: { onWindow: (window) => observeQualityWindow(window) },
11
13
  input: {
12
14
  // The four directions of `input.vector("move")`. Declared rather than inherited from the
13
15
  // default binding, so the axis every scene reads is visible where the game is defined.
@@ -18,9 +20,14 @@ const game = defineGame<GameState, IPhysicsContext>({
18
20
  up: ["ArrowUp", "KeyW"],
19
21
  },
20
22
  jump: { buttons: [0], keys: ["Space"] },
23
+ flagGust: { keys: ["KeyG"] },
21
24
  restart: { keys: ["KeyR"] },
25
+ // Wheel, pinch and the right stick share one portable camera intent. Negative DOM deltaY
26
+ // (toward-user) is positive scroll intent on browser and native; the scene owns the framing.
27
+ zoom: { gamepadAxes: [3], pinch: true, scroll: true },
22
28
  },
23
29
  plugins: [rapier(), replay(), playtest()],
30
+ display: config.display,
24
31
  render: config.renderer,
25
32
  scenes: { play: Play },
26
33
  seed: 90210,
@@ -28,3 +35,23 @@ const game = defineGame<GameState, IPhysicsContext>({
28
35
  });
29
36
 
30
37
  export default game;
38
+
39
+ /**
40
+ * What the UI can ask the game to do.
41
+ *
42
+ * Intents are one-way and named by the game: the UI sends `restart`, `pause` or `resume` and the
43
+ * game decides what each means. Nothing comes back this way — the UI reads the game's published
44
+ * state instead, which keeps one source of truth on the side that owns the simulation.
45
+ */
46
+ game.ui.onIntent((intent) => {
47
+ if (intent === "restart") void game.goto("play");
48
+ if (intent === "pause") game.pause();
49
+ if (intent === "resume") game.resume();
50
+ game.state.set({
51
+ // `game.ui.connected` is true only once the UI announced itself, which is what tells an
52
+ // overlay that never came up apart from a game whose HUD is simply empty.
53
+ uiReady: game.ui.connected,
54
+ ...(intent === "pause" || intent === "resume" ? { paused: intent === "pause" } : {}),
55
+ });
56
+ game.state.flush();
57
+ });
@@ -0,0 +1,195 @@
1
+ import { type QualityTier, resolveQualityTier } from "./quality.js";
2
+
3
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
4
+
5
+ /** Structural subset of the engine's completed frame window; rendering source stays portable. */
6
+ export interface IQualityWindow {
7
+ readonly window: number;
8
+ readonly frames: number;
9
+ readonly fps: number;
10
+ readonly presented: { readonly p95: number };
11
+ readonly frame: { readonly p95: number };
12
+ readonly gpuMs?: number;
13
+ readonly gpuAgeFrames?: number;
14
+ readonly surface?: { readonly compiling?: boolean };
15
+ }
16
+
17
+ export interface IQualityDecision {
18
+ readonly tier: QualityTier;
19
+ readonly source: "auto" | "pinned";
20
+ readonly changed: boolean;
21
+ readonly meter: "gpu" | "presented";
22
+ readonly fallback?: "gpu-unavailable" | "gpu-invalid" | "gpu-age-unavailable" | "gpu-stale";
23
+ readonly reason: string;
24
+ readonly budgetMs: number;
25
+ readonly overloadBudgetMs: number;
26
+ readonly gpuMs?: number;
27
+ readonly cpuMs?: number;
28
+ readonly costMs?: number;
29
+ }
30
+
31
+ export interface IAdaptiveQualityOptions {
32
+ readonly targetFps?: number;
33
+ readonly overloadedWindows?: number;
34
+ readonly healthyWindows?: number;
35
+ readonly headroom?: number;
36
+ readonly presentationTolerance?: number;
37
+ readonly cooldownMs?: number;
38
+ readonly startupWindows?: number;
39
+ readonly minFrames?: number;
40
+ readonly maxGpuAgeFrames?: number;
41
+ readonly now?: () => number;
42
+ /** The scene passes its actual loading state; elapsed time cannot establish readiness. */
43
+ readonly ready?: () => boolean;
44
+ }
45
+
46
+ /** The game owns this policy. Platform selects the first look; measured load selects later ones. */
47
+ export function createAdaptiveQuality(
48
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
49
+ options: IAdaptiveQualityOptions = {},
50
+ ) {
51
+ const policy = {
52
+ targetFps: 60,
53
+ overloadedWindows: 2,
54
+ healthyWindows: 5,
55
+ headroom: 0.2,
56
+ presentationTolerance: 0.05,
57
+ cooldownMs: 5000,
58
+ startupWindows: 1,
59
+ minFrames: 30,
60
+ maxGpuAgeFrames: 4,
61
+ ...options,
62
+ };
63
+ for (const key of ["targetFps", "overloadedWindows", "healthyWindows", "minFrames"] as const) {
64
+ if (!Number.isFinite(policy[key]) || policy[key] <= 0)
65
+ throw new Error(`quality ${key} must be positive.`);
66
+ }
67
+ for (const key of ["cooldownMs", "startupWindows", "maxGpuAgeFrames"] as const) {
68
+ if (!Number.isFinite(policy[key]) || policy[key] < 0)
69
+ throw new Error(`quality ${key} must be non-negative.`);
70
+ }
71
+ for (const key of [
72
+ "overloadedWindows",
73
+ "healthyWindows",
74
+ "startupWindows",
75
+ "minFrames",
76
+ "maxGpuAgeFrames",
77
+ ] as const) {
78
+ if (!Number.isInteger(policy[key])) throw new Error(`quality ${key} must be an integer.`);
79
+ }
80
+ if (!Number.isFinite(policy.headroom) || policy.headroom <= 0 || policy.headroom >= 1)
81
+ throw new Error("quality headroom must be between zero and one.");
82
+ if (
83
+ !Number.isFinite(policy.presentationTolerance) ||
84
+ policy.presentationTolerance < 0 ||
85
+ policy.presentationTolerance >= 1
86
+ )
87
+ throw new Error("quality presentationTolerance must be between zero and one.");
88
+ const now = options.now ?? (() => performance.now());
89
+ const ready = options.ready ?? (() => true);
90
+ let tier = resolveQualityTier(request);
91
+ const pinned = request.tier !== undefined;
92
+ const budgetMs = 1000 / policy.targetFps;
93
+ let startup = policy.startupWindows;
94
+ let lastWindow = 0;
95
+ let lastChange = Number.NEGATIVE_INFINITY;
96
+ let overloaded = 0;
97
+ let healthy = 0;
98
+ const finite = (value: number | undefined): value is number =>
99
+ value !== undefined && Number.isFinite(value);
100
+ return {
101
+ get tier() {
102
+ return tier;
103
+ },
104
+ pinned,
105
+ observe(window: IQualityWindow): IQualityDecision {
106
+ const gpu = window.gpuMs;
107
+ const age = window.gpuAgeFrames;
108
+ const fallback: IQualityDecision["fallback"] =
109
+ gpu === undefined
110
+ ? "gpu-unavailable"
111
+ : !Number.isFinite(gpu) || gpu <= 0
112
+ ? "gpu-invalid"
113
+ : age === undefined || !Number.isInteger(age) || age < 0
114
+ ? "gpu-age-unavailable"
115
+ : age > policy.maxGpuAgeFrames
116
+ ? "gpu-stale"
117
+ : undefined;
118
+ const costMs = fallback === undefined ? (gpu as number) : window.presented.p95;
119
+ // Presented intervals include vsync jitter, so fallback overload gets a small tolerance.
120
+ const overloadBudgetMs =
121
+ fallback === undefined ? budgetMs : budgetMs * (1 + policy.presentationTolerance);
122
+ const reportFields: Pick<IQualityDecision, "fallback" | "gpuMs" | "cpuMs" | "costMs"> = {
123
+ ...(fallback === undefined ? {} : { fallback }),
124
+ ...(finite(gpu) ? { gpuMs: gpu } : {}),
125
+ ...(finite(window.frame.p95) ? { cpuMs: window.frame.p95 } : {}),
126
+ ...(finite(costMs) ? { costMs } : {}),
127
+ };
128
+ const report = (reason: string, changed = false): IQualityDecision => ({
129
+ tier,
130
+ source: pinned ? "pinned" : "auto",
131
+ changed,
132
+ reason,
133
+ budgetMs,
134
+ overloadBudgetMs,
135
+ meter: fallback === undefined ? "gpu" : "presented",
136
+ ...reportFields,
137
+ });
138
+ let skip: string | undefined;
139
+ if (
140
+ !Number.isInteger(window.window) ||
141
+ window.window <= lastWindow ||
142
+ !Number.isInteger(window.frames) ||
143
+ window.frames < policy.minFrames ||
144
+ !Number.isFinite(window.fps) ||
145
+ window.fps <= 0 ||
146
+ !Number.isFinite(costMs) ||
147
+ costMs <= 0
148
+ )
149
+ skip = "invalid";
150
+ if (Number.isInteger(window.window) && window.window > lastWindow) lastWindow = window.window;
151
+ if (!ready()) {
152
+ startup = policy.startupWindows;
153
+ skip = "startup";
154
+ } else if (window.surface?.compiling) skip = "compiling";
155
+ else if (skip === undefined && startup > 0) {
156
+ startup -= 1;
157
+ skip = "startup";
158
+ }
159
+ if (skip !== undefined) {
160
+ overloaded = 0;
161
+ healthy = 0;
162
+ return report(skip);
163
+ }
164
+ if (pinned) return report("pinned");
165
+ overloaded = costMs > overloadBudgetMs ? overloaded + 1 : 0;
166
+ healthy = costMs <= budgetMs * (1 - policy.headroom) ? healthy + 1 : 0;
167
+ const direction =
168
+ overloaded >= policy.overloadedWindows ? -1 : healthy >= policy.healthyWindows ? 1 : 0;
169
+ if (direction === 0) return report("steady");
170
+ const next = QUALITY_TIERS[QUALITY_TIERS.indexOf(tier) + direction];
171
+ if (next === undefined) return report(direction < 0 ? "at-floor" : "at-ceiling");
172
+ const time = now();
173
+ if (!Number.isFinite(time)) throw new Error("quality clock must return finite milliseconds.");
174
+ if (time - lastChange < policy.cooldownMs) {
175
+ overloaded = 0;
176
+ healthy = 0;
177
+ return report("cooldown");
178
+ }
179
+ tier = next;
180
+ lastChange = time;
181
+ overloaded = 0;
182
+ healthy = 0;
183
+ return report(direction < 0 ? "overloaded" : "headroom", true);
184
+ },
185
+ };
186
+ }
187
+
188
+ export function formatQualityAdaptation(decision: IQualityDecision): string {
189
+ return (
190
+ `TN_QUALITY_TIER ${decision.tier} source=${decision.source} meter=${decision.meter}` +
191
+ ` reason=${decision.reason} fallback=${decision.fallback ?? "none"}` +
192
+ ` budgetMs=${decision.budgetMs} overloadBudgetMs=${decision.overloadBudgetMs}` +
193
+ ` costMs=${decision.costMs ?? "unavailable"}`
194
+ );
195
+ }
@@ -18,6 +18,12 @@ export interface ISpringArmOptions {
18
18
  readonly lookAhead?: Vector3;
19
19
  /** Seconds for the arm to close most of the distance. Higher trails more. */
20
20
  readonly damping?: number;
21
+ /** Closest target-relative distance allowed by the game's framing. */
22
+ readonly minDistance?: number;
23
+ /** Farthest target-relative distance allowed by the game's framing. */
24
+ readonly maxDistance?: number;
25
+ /** Target-relative distance units moved by one full zoom axis unit per second. */
26
+ readonly dollySpeed?: number;
21
27
  }
22
28
 
23
29
  export interface ISpringArm {
@@ -25,6 +31,8 @@ export interface ISpringArm {
25
31
  readonly follow: (target: Vector3, dt: number) => void;
26
32
  /** Jump the camera to its resting pose — use on spawn and respawn. */
27
33
  readonly snap: (target: Vector3) => void;
34
+ /** Move toward or away from the target; positive intent moves the camera closer. */
35
+ readonly dolly: (amount: number, dt: number) => void;
28
36
  }
29
37
 
30
38
  export function createSpringArm(
@@ -33,25 +41,43 @@ export function createSpringArm(
33
41
  ): ISpringArm {
34
42
  // Keep the starter's target-relative distance below the 9.5-unit look budget
35
43
  // so the player and nearby route stay readable after the camera settles.
36
- const offset = options.offset ?? new Vec3(0, 4.2, 8.45);
37
- const lookAhead = options.lookAhead ?? new Vec3(0, 1, 0);
44
+ const offset = (options.offset ?? new Vec3(-1, 4.2, 8.2)).clone();
45
+ // Lead the route rather than centring the character. The level runs left to right, so
46
+ // aiming ahead of the player puts the gap and the flag in frame from the first tick
47
+ // instead of leaving half the picture empty behind them.
48
+ const lookAhead = options.lookAhead ?? new Vec3(1.8, 0.35, -1.15);
38
49
  const damping = options.damping ?? 0.18;
50
+ const startingDistance = offset.length();
51
+ const offsetDirection =
52
+ startingDistance > 0 ? offset.clone().multiplyScalar(1 / startingDistance) : new Vec3(0, 0, 1);
53
+ const minDistance = Math.max(0.1, options.minDistance ?? startingDistance * 0.55);
54
+ const maxDistance = Math.max(minDistance, options.maxDistance ?? startingDistance * 1.35);
55
+ const dollySpeed = Math.max(0, options.dollySpeed ?? 10);
56
+ let distance = Math.min(Math.max(startingDistance, minDistance), maxDistance);
39
57
 
40
58
  const desired = new Vec3();
41
59
  const aim = new Vec3();
60
+ const currentOffset = new Vec3();
61
+
62
+ const dolly = (amount: number, dt: number): void => {
63
+ if (!Number.isFinite(amount) || !Number.isFinite(dt) || dt <= 0) return;
64
+ distance = Math.min(maxDistance, Math.max(minDistance, distance - amount * dollySpeed * dt));
65
+ };
66
+
67
+ const targetOffset = (): Vector3 => currentOffset.copy(offsetDirection).multiplyScalar(distance);
42
68
 
43
69
  const snap = (target: Vector3): void => {
44
- camera.position.copy(target).add(offset);
70
+ camera.position.copy(target).add(targetOffset());
45
71
  camera.lookAt(aim.copy(target).add(lookAhead));
46
72
  };
47
73
 
48
74
  const follow = (target: Vector3, dt: number): void => {
49
- desired.copy(target).add(offset);
75
+ desired.copy(target).add(targetOffset());
50
76
  // 1 - e^(-dt/damping): the frame-rate-independent form of a lerp. At 30fps
51
77
  // and 120fps the camera ends up in the same place after the same second.
52
78
  camera.position.lerp(desired, 1 - Math.exp(-dt / damping));
53
79
  camera.lookAt(aim.copy(target).add(lookAhead));
54
80
  };
55
81
 
56
- return { follow, snap };
82
+ return { dolly, follow, snap };
57
83
  }