create-threenative 0.2.3 → 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 (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -2,11 +2,80 @@
2
2
  "name": "native-render-chain",
3
3
  "target": "desktop",
4
4
  "schemaVersion": 1,
5
- "viewport": { "width": 1280, "height": 720 },
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
6
9
  "warmupFrames": 2,
7
- "steps": [{ "label": "chain-settled", "waitTicks": 12 }],
8
- "artifacts": { "screenshots": "after" },
10
+ "steps": [
11
+ {
12
+ "kind": "input",
13
+ "label": "move-and-start-refinement",
14
+ "press": "ArrowUp",
15
+ "holdTicks": 60,
16
+ "release": true
17
+ },
18
+ {
19
+ "label": "ridge-refined",
20
+ "waitTicks": 600
21
+ }
22
+ ],
23
+ "artifacts": {
24
+ "screenshots": "after"
25
+ },
9
26
  "assert": {
10
- "renderChain": { "tier": "high" }
27
+ "components": [
28
+ {
29
+ "entity": "scenery.ridge",
30
+ "component": "state",
31
+ "equals": "refined",
32
+ "allowTrivial": "A fast Worker may refine before the native baseline sample; the final state still proves the attached result is refined."
33
+ },
34
+ {
35
+ "entity": "scenery.ridge",
36
+ "component": "generation",
37
+ "gte": 1,
38
+ "allowTrivial": "A fast Worker may complete before the native baseline sample; generation one still proves the refinement dispatch ran."
39
+ },
40
+ {
41
+ "entity": "scenery.ridge",
42
+ "component": "topology",
43
+ "path": "boundaryEdges",
44
+ "equals": 0,
45
+ "allowTrivial": "The final-array topology report is a held invariant for the attached native ridge."
46
+ },
47
+ {
48
+ "entity": "scenery.ridge",
49
+ "component": "topology",
50
+ "path": "degenerateTriangles",
51
+ "equals": 0,
52
+ "allowTrivial": "The final-array topology report is a held invariant for the attached native ridge."
53
+ },
54
+ {
55
+ "entity": "scenery.ridge",
56
+ "component": "topology",
57
+ "path": "windingConflicts",
58
+ "equals": 0,
59
+ "allowTrivial": "The final-array topology report is a held invariant for the attached native ridge."
60
+ },
61
+ {
62
+ "entity": "scenery.ridge",
63
+ "component": "topology",
64
+ "path": "signedVolume",
65
+ "gte": 1,
66
+ "allowTrivial": "The final-array topology report is a held invariant for the attached native ridge."
67
+ }
68
+ ],
69
+ "renderChain": {
70
+ "tier": "high"
71
+ },
72
+ "resources": [
73
+ {
74
+ "id": "state",
75
+ "path": "odometer",
76
+ "gte": 1,
77
+ "changed": true
78
+ }
79
+ ]
11
80
  }
12
81
  }
@@ -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
+ }
@@ -17,9 +17,9 @@
17
17
  "typecheck": "tsc --noEmit -p tsconfig.json"
18
18
  },
19
19
  "dependencies": {
20
- "@threenative/core": "0.3.0",
21
- "@threenative/physics": "0.3.0",
22
- "@threenative/ui": "0.3.0",
20
+ "@threenative/core": "0.3.1",
21
+ "@threenative/physics": "0.3.1",
22
+ "@threenative/ui": "0.3.1",
23
23
  "react": "19.2.0",
24
24
  "react-dom": "19.2.0",
25
25
  "react-reconciler": "0.33.0",
@@ -27,13 +27,13 @@
27
27
  },
28
28
  "devDependencies": {
29
29
  "@tailwindcss/vite": "4.3.3",
30
- "@threenative/assets": "0.3.0",
31
- "@threenative/playtest": "0.3.0",
30
+ "@threenative/assets": "0.3.1",
31
+ "@threenative/playtest": "0.3.1",
32
32
  "@types/react": "19.2.0",
33
33
  "@types/react-dom": "19.2.0",
34
34
  "@types/three": "0.185.3",
35
35
  "@vitejs/plugin-react": "6.0.5",
36
- "create-threenative": "0.2.3",
36
+ "create-threenative": "0.2.4",
37
37
  "esbuild": "0.27.0",
38
38
  "playwright": "1.62.1",
39
39
  "tailwindcss": "4.3.3",
@@ -42,7 +42,7 @@
42
42
  "@gltf-transform/cli": "4.4.2"
43
43
  },
44
44
  "optionalDependencies": {
45
- "@threenative/runtime-native": "0.3.0"
45
+ "@threenative/runtime-native": "0.3.1"
46
46
  },
47
47
  "pnpm": {
48
48
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -0,0 +1,45 @@
1
+ {
2
+ "acceptanceId": "AC5",
3
+ "name": "boot-failure",
4
+ "target": "web",
5
+ "schemaVersion": 1,
6
+ "bootFailure": "renderer-no-adapter",
7
+ "awaitStartup": false,
8
+ "viewport": {
9
+ "width": 1280,
10
+ "height": 720
11
+ },
12
+ "warmupFrames": 1,
13
+ "steps": [
14
+ {
15
+ "kind": "wait",
16
+ "label": "failure-surface",
17
+ "waitFrames": 1
18
+ }
19
+ ],
20
+ "assert": {
21
+ "diagnostics": {
22
+ "consoleErrorsOptOutReason": "The scenario intentionally blocks the renderer adapter, whose expected WebGL context error is the failure message being surfaced.",
23
+ "noConsoleErrors": false
24
+ },
25
+ "hud": [
26
+ {
27
+ "allowTrivial": "The forced boot failure is present before the first step by design; this run checks that its message remains visible.",
28
+ "id": "threenative-canvas-error",
29
+ "textIncludes": "Error creating WebGL context",
30
+ "visible": true
31
+ }
32
+ ],
33
+ "visual": [
34
+ {
35
+ "region": {
36
+ "element": {
37
+ "id": "threenative-canvas-error"
38
+ },
39
+ "maxDarkPixelRatio": 0.5,
40
+ "minNonblankPixelRatio": 0.002
41
+ }
42
+ }
43
+ ]
44
+ }
45
+ }
@@ -6,7 +6,7 @@
6
6
  "width": 1280,
7
7
  "height": 720
8
8
  },
9
- "warmupFrames": 10,
9
+ "warmupFrames": 1,
10
10
  "subject": "player",
11
11
  "artifacts": {
12
12
  "screenshots": "before-after"
@@ -14,15 +14,21 @@
14
14
  "steps": [
15
15
  {
16
16
  "kind": "wait",
17
- "label": "play-scene-loads",
18
- "waitTicks": 600,
17
+ "label": "preview-pending",
18
+ "waitTicks": 1,
19
19
  "release": true
20
20
  },
21
21
  {
22
22
  "kind": "input",
23
- "label": "move-camera",
23
+ "label": "move-before-refinement",
24
24
  "press": "ArrowRight",
25
- "holdTicks": 220,
25
+ "holdTicks": 140,
26
+ "release": true
27
+ },
28
+ {
29
+ "kind": "wait",
30
+ "label": "refinement-settles",
31
+ "waitTicks": 600,
26
32
  "release": true
27
33
  }
28
34
  ],
@@ -32,6 +38,72 @@
32
38
  "noNetworkErrors": true,
33
39
  "runtimeReady": true
34
40
  },
41
+ "components": [
42
+ {
43
+ "entity": "scenery.ridge",
44
+ "component": "state",
45
+ "equals": "refined",
46
+ "atSteps": [
47
+ {
48
+ "label": "preview-pending",
49
+ "equals": "preview"
50
+ }
51
+ ]
52
+ },
53
+ {
54
+ "entity": "scenery.ridge",
55
+ "component": "generation",
56
+ "gte": 1,
57
+ "atSteps": [
58
+ {
59
+ "label": "preview-pending",
60
+ "equals": 0
61
+ }
62
+ ]
63
+ },
64
+ {
65
+ "entity": "scenery.ridge",
66
+ "component": "topology",
67
+ "path": "boundaryEdges",
68
+ "equals": 0,
69
+ "allowTrivial": "The final-array topology report is a held invariant for the attached ridge."
70
+ },
71
+ {
72
+ "entity": "scenery.ridge",
73
+ "component": "topology",
74
+ "path": "degenerateTriangles",
75
+ "equals": 0,
76
+ "allowTrivial": "The final-array topology report is a held invariant for the attached ridge."
77
+ },
78
+ {
79
+ "entity": "scenery.ridge",
80
+ "component": "topology",
81
+ "path": "windingConflicts",
82
+ "equals": 0,
83
+ "allowTrivial": "The final-array topology report is a held invariant for the attached ridge."
84
+ },
85
+ {
86
+ "entity": "scenery.ridge",
87
+ "component": "topology",
88
+ "path": "signedVolume",
89
+ "gte": 1,
90
+ "allowTrivial": "The final-array topology report is a held invariant for the attached ridge."
91
+ }
92
+ ],
93
+ "resources": [
94
+ {
95
+ "id": "state",
96
+ "path": "odometer",
97
+ "gte": 4,
98
+ "changed": true,
99
+ "atSteps": [
100
+ {
101
+ "label": "move-before-refinement",
102
+ "textIncludes": "."
103
+ }
104
+ ]
105
+ }
106
+ ],
35
107
  "camera": {
36
108
  "entity": "camera.main",
37
109
  "follows": "player",
@@ -42,6 +114,16 @@
42
114
  "entity": "player",
43
115
  "minDistance": 4
44
116
  },
117
+ "renderChain": {
118
+ "tier": "high",
119
+ "stages": {
120
+ "includes": ["outline", "kuwahara", "watercolor"],
121
+ "order": ["outline", "kuwahara", "watercolor"]
122
+ },
123
+ "contributions": {
124
+ "graphOutputChanged": ["outline", "kuwahara", "watercolor"]
125
+ }
126
+ },
45
127
  "visibility": [
46
128
  {
47
129
  "allowTrivial": "The starter scene begins with the player visible and in frame; this held visibility row accompanies the look assertion.",
@@ -62,9 +144,31 @@
62
144
  "width": 1280,
63
145
  "height": 720,
64
146
  "minNonblankPixelRatio": 0.95,
65
- "minDarkPixelRatio": 0.2,
147
+ "minDarkPixelRatio": 0.04,
66
148
  "maxLuminance": 0.25
67
149
  }
150
+ },
151
+ {
152
+ "region": {
153
+ "x": 0,
154
+ "y": 0,
155
+ "width": 1280,
156
+ "height": 360,
157
+ "minNonblankPixelRatio": 0.95,
158
+ "minDarkPixelRatio": 0.08,
159
+ "maxLuminance": 0.25
160
+ }
161
+ },
162
+ {
163
+ "region": {
164
+ "x": 320,
165
+ "y": 180,
166
+ "width": 640,
167
+ "height": 420,
168
+ "minNonblankPixelRatio": 0.7,
169
+ "minDarkPixelRatio": 0.02,
170
+ "maxLuminance": 0.4
171
+ }
68
172
  }
69
173
  ]
70
174
  }
@@ -33,9 +33,10 @@
33
33
  "runtimeReady": true
34
34
  },
35
35
  "performance": {
36
- "maxDrawCalls": 160,
36
+ "maxDrawCalls": 330,
37
37
  "maxFrameMsP95": 33,
38
- "maxTriangles": 9800
38
+ "maxTriangles": 52000,
39
+ "minFps": 30
39
40
  },
40
41
  "resources": [
41
42
  {
@@ -36,10 +36,31 @@
36
36
  "noRuntimeDiagnostics": true,
37
37
  "runtimeReady": true
38
38
  },
39
+ "components": [
40
+ {
41
+ "allowTrivial": "GroundSnap settles the player before this movement observation; the finite near-zero clearance is the generated call-site proof.",
42
+ "component": "groundClearance",
43
+ "entity": "player",
44
+ "lte": 0.01
45
+ },
46
+ {
47
+ "allowTrivial": "The hero is authored at 1.22 m and normalised down to the template's 1.1 m convention, so the retained factor is below one; either side of one proves normaliseToMetres ran in the generated player.",
48
+ "component": "normaliseFactor",
49
+ "entity": "player",
50
+ "lte": 0.99
51
+ }
52
+ ],
39
53
  "movement": {
40
54
  "entity": "player",
41
55
  "minDistance": 0.5
42
56
  },
57
+ "visibility": [
58
+ {
59
+ "entity": "touch-controls",
60
+ "present": false,
61
+ "allowTrivial": "Desktop keyboard lanes intentionally omit touch controls while movement proves the scene is active."
62
+ }
63
+ ],
43
64
  "visual": [
44
65
  {
45
66
  "region": {
@@ -0,0 +1,42 @@
1
+ {
2
+ "name": "starter-touch-controls",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "movement-anchor",
12
+ "pointers": [{ "id": 7, "x": 0.18, "y": 0.75 }],
13
+ "holdTicks": 2,
14
+ "release": false
15
+ },
16
+ {
17
+ "kind": "input",
18
+ "label": "move-right",
19
+ "pointers": [{ "id": 7, "x": 0.38, "y": 0.75 }],
20
+ "holdTicks": 45,
21
+ "release": true
22
+ },
23
+ { "kind": "wait", "label": "settled", "waitTicks": 10, "release": true }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": {
27
+ "noConsoleErrors": true,
28
+ "noNetworkErrors": true,
29
+ "noRuntimeDiagnostics": true,
30
+ "runtimeReady": true
31
+ },
32
+ "movement": { "entity": "player", "minDistance": 0.1 },
33
+ "resources": [{ "id": "state", "path": "playerX", "changed": true }],
34
+ "visibility": [
35
+ {
36
+ "entity": "touch-controls",
37
+ "present": true,
38
+ "allowTrivial": "Touch-primary lanes keep the authored controls visible while state assertions prove they are live."
39
+ }
40
+ ]
41
+ }
42
+ }
@@ -0,0 +1,18 @@
1
+ import { GroundSnap, normaliseToMetres } from "@threenative/core";
2
+ import type { Mesh } from "three";
3
+
4
+ export interface IStarterConventions {
5
+ readonly applyGrounding: (surfaceY: number, dt: number) => void;
6
+ readonly groundSnap: GroundSnap;
7
+ readonly normaliseFactor: number;
8
+ }
9
+
10
+ export function preparePlayerConventions(model: Mesh): IStarterConventions {
11
+ const normaliseFactor = normaliseToMetres(model, { axis: "height", metres: 1.1 });
12
+ const groundSnap = new GroundSnap(model);
13
+ return {
14
+ applyGrounding: (surfaceY, dt) => groundSnap.apply(model, surfaceY, dt),
15
+ groundSnap,
16
+ normaliseFactor,
17
+ };
18
+ }
@@ -11,9 +11,11 @@ import type { GameState } from "../state.js";
11
11
  *
12
12
  * The island top sits below the ledge on purpose. A same-height landing has to be jumped
13
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.
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.
15
17
  */
16
- const ISLAND = { depth: 2.6, height: 0.4, top: -0.4, width: 3, x: 7.9, z: 0 } as const;
18
+ export const ISLAND = { depth: 2.6, height: 0.1, top: -0.4, width: 3, x: 7.9, z: 0 } as const;
17
19
  const POLE = { height: 2.4, radius: 0.05, x: 8.4, z: -0.5 } as const;
18
20
  const PENNANT_SCALE = 0.55;
19
21
 
@@ -22,6 +24,8 @@ export interface IGoalMaterials {
22
24
  readonly floor: Material;
23
25
  /** The pole. The accent role, and the only warm thing on the far side. */
24
26
  readonly goal: Material;
27
+ /** The sandbar's beach rim and the flank below it. */
28
+ readonly shore: Material;
25
29
  }
26
30
 
27
31
  export class Goal {
@@ -63,7 +67,18 @@ export class Goal {
63
67
  });
64
68
  this.pennant.name = "finish-flag-cloth";
65
69
  this.mesh = this.pennant;
66
- this.mesh.add(island, pole);
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);
67
82
  ctx.add(this.mesh);
68
83
 
69
84
  this.#body = new RigidBody3D({
@@ -1,7 +1,9 @@
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, Vector3 } 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>;
@@ -17,27 +19,38 @@ const COYOTE_TIME = 0.12;
17
19
  const JUMP_BUFFER = 0.14;
18
20
  const JUMP_SPEED = 5;
19
21
  const MOVE_SPEED = 2;
22
+ const PLAYER_FOOT_OFFSET = 0.51;
23
+ const VISUAL_ATTACHMENT_TOLERANCE = 0.1;
20
24
  const SPAWN = { x: -2, y: 0.5, z: 0 } as const;
21
25
 
22
26
  export class Player {
23
- readonly mesh: Mesh;
27
+ readonly mesh: Group;
28
+ readonly visual: Mesh;
24
29
  readonly body: CharacterBody3D;
25
30
  #coyoteTime = 0;
26
31
  #jumpBuffer = 0;
27
32
  #jumps = 0;
28
33
  #coyoteJumps = 0;
29
34
  #odometer = 0;
35
+ #supportSurfaceY = 0;
30
36
  #previousPosition = new Vector3();
37
+ #bodyWorldPosition = new Vector3();
38
+ #visualWorldPosition = new Vector3();
39
+ #visualBodyOffsetY: number | undefined;
31
40
  #hasPreviousPosition = false;
41
+ #conventions: IStarterConventions;
32
42
 
33
43
  constructor(
34
44
  ctx: GameCtx,
35
- material: Material,
45
+ materials: IHeroMaterials,
36
46
  spawn: { readonly x: number; readonly y: number; readonly z: number } = SPAWN,
37
47
  ) {
38
- 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);
39
52
  this.mesh.position.set(spawn.x, spawn.y, spawn.z);
40
- this.mesh.castShadow = true;
53
+ this.#conventions = preparePlayerConventions(this.visual);
41
54
  ctx.add(this.mesh);
42
55
  this.body = new CharacterBody3D({
43
56
  autostep: { maxHeight: 0.4, minWidth: 0.2 },
@@ -47,7 +60,12 @@ export class Player {
47
60
  });
48
61
  }
49
62
 
50
- 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 {
51
69
  if (this.#hasPreviousPosition) {
52
70
  this.#odometer += this.mesh.position.distanceTo(this.#previousPosition);
53
71
  }
@@ -55,7 +73,8 @@ export class Player {
55
73
  this.#coyoteTime = Math.max(0, this.#coyoteTime - dt);
56
74
  this.#jumpBuffer = Math.max(0, this.#jumpBuffer - dt);
57
75
  if (grounded) this.#coyoteTime = COYOTE_TIME;
58
- if (ctx.input.justPressed("jump")) this.#jumpBuffer = JUMP_BUFFER;
76
+ if (ctx.input.justPressed("jump") || touch?.jumpPressed === true)
77
+ this.#jumpBuffer = JUMP_BUFFER;
59
78
  if (this.#jumpBuffer > 0 && this.#coyoteTime > 0) {
60
79
  this.body.velocity.y = JUMP_SPEED;
61
80
  this.#jumpBuffer = 0;
@@ -64,12 +83,26 @@ export class Player {
64
83
  if (!grounded) this.#coyoteJumps += 1;
65
84
  }
66
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
+ }
67
91
  this.body.velocity.x = move.x * MOVE_SPEED;
68
92
  this.body.velocity.z = -move.y * MOVE_SPEED;
69
93
  this.#previousPosition.copy(this.mesh.position);
70
94
  this.body.moveAndSlide(dt);
71
95
  this.#hasPreviousPosition = true;
72
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();
73
106
  }
74
107
 
75
108
  respawn(): void {
@@ -82,16 +115,29 @@ export class Player {
82
115
  debug(): {
83
116
  coyoteJumps: number;
84
117
  grounded: boolean;
118
+ groundClearance: number | null;
119
+ groundCorrectionEnabled: boolean;
120
+ groundSurfaceY: number;
85
121
  jumps: number;
122
+ normaliseFactor: number;
86
123
  odometer: number;
87
124
  position: number[];
125
+ visualAttached: boolean;
126
+ visualAttachmentDrift: number;
88
127
  } {
128
+ const visualAttachmentDrift = this.#visualAttachmentDrift();
89
129
  return {
90
130
  coyoteJumps: this.#coyoteJumps,
91
131
  grounded: this.body.grounded,
132
+ groundClearance: this.#conventions.groundSnap.clearance,
133
+ groundCorrectionEnabled: this.#conventions.groundSnap.enabled,
134
+ groundSurfaceY: this.#supportSurfaceY,
92
135
  jumps: this.#jumps,
136
+ normaliseFactor: this.#conventions.normaliseFactor,
93
137
  odometer: this.#odometer,
94
138
  position: this.mesh.position.toArray(),
139
+ visualAttached: visualAttachmentDrift <= VISUAL_ATTACHMENT_TOLERANCE,
140
+ visualAttachmentDrift,
95
141
  };
96
142
  }
97
143
 
@@ -115,4 +161,21 @@ export class Player {
115
161
  this.body.dispose();
116
162
  this.mesh.removeFromParent();
117
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
+ }
118
181
  }