create-threenative 0.2.15 → 0.2.18

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 (488) hide show
  1. package/agent-docs/kit-mcp.md +10 -0
  2. package/agent-docs/kit-router.md +14 -0
  3. package/agent-docs/kit-stuck.md +7 -0
  4. package/agent-docs/references/assertion-reference.md +54 -110
  5. package/agent-docs/references/capability-reference.md +1740 -254
  6. package/agent-docs/references/conventions.md +299 -0
  7. package/agent-docs/references/kit-action-rpg.md +40 -0
  8. package/agent-docs/references/kit-adventure.md +40 -0
  9. package/agent-docs/references/kit-collectathon.md +38 -0
  10. package/agent-docs/references/kit-kart.md +31 -0
  11. package/agent-docs/references/kit-minimal.md +29 -0
  12. package/agent-docs/references/kit-platformer.md +34 -0
  13. package/agent-docs/references/kit-puzzle.md +22 -0
  14. package/agent-docs/references/kit-racing.md +26 -0
  15. package/agent-docs/references/kit-rain.md +31 -0
  16. package/agent-docs/references/kit-rts.md +34 -0
  17. package/agent-docs/references/kit-runner.md +32 -0
  18. package/agent-docs/references/kit-sailing.md +41 -0
  19. package/agent-docs/references/kit-shooter.md +33 -0
  20. package/agent-docs/references/kit-snow.md +33 -0
  21. package/agent-docs/references/kit-starter.md +55 -0
  22. package/agent-docs/references/kit-tower-defense.md +27 -0
  23. package/agent-docs/references/performance-basics.md +8 -4
  24. package/agent-docs/references/terrain-authoring.md +2 -1
  25. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  26. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  27. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +84 -59
  28. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  29. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  30. package/agent-files/.claude/settings.json +25 -0
  31. package/agent-files/.codex/hooks.json +18 -1
  32. package/dist/index.d.ts +97 -6
  33. package/dist/index.js +899 -271
  34. package/dist/terrain-kit.d.ts +7 -0
  35. package/dist/terrain-kit.js +82 -0
  36. package/dist/threenative.js +114 -16
  37. package/dist/web-engine-ccd-ik-solver.js +127 -0
  38. package/dist/web-engine-gltf-loader.js +71 -20
  39. package/dist/web-engine-post-effects.js +39 -14
  40. package/dist/web-engine-runtime.js +10011 -4101
  41. package/package.json +15 -9
  42. package/template-assets/clearwater/README.md +1 -1
  43. package/template-assets/patches/manifest.json +18 -0
  44. package/template-assets/patches/three@0.187.0.patch +2004 -407
  45. package/template-assets/terrain/alpine/assets.json +12 -0
  46. package/template-assets/terrain/alpine/bake.mjs +6 -0
  47. package/template-assets/terrain/alpine/credits.json +164 -0
  48. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  49. package/template-assets/terrain/alpine/recipe.json +119 -0
  50. package/template-assets/terrain/alpine/surface.json +53 -0
  51. package/template-assets/terrain/coastal/assets.json +11 -0
  52. package/template-assets/terrain/coastal/bake.mjs +6 -0
  53. package/template-assets/terrain/coastal/credits.json +117 -0
  54. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  55. package/template-assets/terrain/coastal/recipe.json +113 -0
  56. package/template-assets/terrain/coastal/surface.json +41 -0
  57. package/template-assets/terrain/desert/assets.json +12 -0
  58. package/template-assets/terrain/desert/bake.mjs +6 -0
  59. package/template-assets/terrain/desert/credits.json +164 -0
  60. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  61. package/template-assets/terrain/desert/recipe.json +108 -0
  62. package/template-assets/terrain/desert/surface.json +54 -0
  63. package/template-assets/terrain/forest/assets.json +65 -0
  64. package/template-assets/terrain/forest/bake.mjs +8 -0
  65. package/template-assets/terrain/forest/credits.json +225 -0
  66. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  67. package/template-assets/terrain/forest/recipe.json +350 -0
  68. package/template-assets/terrain/forest/surface.json +79 -0
  69. package/template-assets/terrain/tundra/assets.json +12 -0
  70. package/template-assets/terrain/tundra/bake.mjs +6 -0
  71. package/template-assets/terrain/tundra/credits.json +164 -0
  72. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  73. package/template-assets/terrain/tundra/recipe.json +277 -0
  74. package/template-assets/terrain/tundra/surface.json +54 -0
  75. package/templates/action-rpg/AGENTS.md +103 -84
  76. package/templates/action-rpg/CLAUDE.md +103 -84
  77. package/templates/action-rpg/kit.json +1 -0
  78. package/templates/action-rpg/package.json +7 -7
  79. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  80. package/templates/action-rpg/src/game.ts +2 -1
  81. package/templates/action-rpg/src/render/atmosphere.ts +11 -16
  82. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  83. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  84. package/templates/action-rpg/src/render/clouds.ts +13 -0
  85. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  86. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  87. package/templates/action-rpg/src/render/quality.ts +10 -33
  88. package/templates/action-rpg/src/scenes/Play.ts +30 -1
  89. package/templates/action-rpg/src/style.css +4 -0
  90. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  91. package/templates/action-rpg/threenative.config.ts +0 -3
  92. package/templates/action-rpg/vite.config.ts +2 -0
  93. package/templates/adventure/AGENTS.md +92 -44
  94. package/templates/adventure/CLAUDE.md +92 -44
  95. package/templates/adventure/kit.json +5 -1
  96. package/templates/adventure/package.json +7 -7
  97. package/templates/adventure/src/game.ts +1 -1
  98. package/templates/adventure/src/style.css +4 -0
  99. package/templates/adventure/tsconfig.json +1 -1
  100. package/templates/adventure/vite.config.ts +2 -0
  101. package/templates/collectathon/AGENTS.md +93 -42
  102. package/templates/collectathon/CLAUDE.md +93 -42
  103. package/templates/collectathon/package.json +7 -7
  104. package/templates/collectathon/src/game.ts +1 -1
  105. package/templates/collectathon/src/level/Course.ts +55 -9
  106. package/templates/collectathon/src/level/terrain.ts +27 -6
  107. package/templates/collectathon/src/main.ts +1 -0
  108. package/templates/collectathon/src/render/foliage.ts +359 -98
  109. package/templates/collectathon/src/render/sky.ts +76 -12
  110. package/templates/collectathon/src/render/water.ts +32 -10
  111. package/templates/collectathon/src/scenes/Play.ts +18 -5
  112. package/templates/collectathon/src/style.css +4 -0
  113. package/templates/collectathon/tsconfig.json +1 -1
  114. package/templates/collectathon/vite.config.ts +2 -0
  115. package/templates/kart/AGENTS.md +87 -42
  116. package/templates/kart/CLAUDE.md +87 -42
  117. package/templates/kart/package.json +6 -6
  118. package/templates/kart/src/game.ts +1 -1
  119. package/templates/kart/src/main.ts +1 -0
  120. package/templates/kart/src/style.css +4 -0
  121. package/templates/kart/tsconfig.json +1 -1
  122. package/templates/kart/vite.config.ts +2 -0
  123. package/templates/minimal/AGENTS.md +105 -84
  124. package/templates/minimal/CLAUDE.md +105 -84
  125. package/templates/minimal/package.json +6 -6
  126. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  127. package/templates/minimal/src/game.ts +1 -1
  128. package/templates/minimal/src/render/atmosphere.ts +11 -16
  129. package/templates/minimal/src/render/backlightControls.ts +10 -0
  130. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  131. package/templates/minimal/src/render/camera.ts +13 -2
  132. package/templates/minimal/src/render/clouds.ts +13 -0
  133. package/templates/minimal/src/render/gpuSky.ts +4 -7
  134. package/templates/minimal/src/render/lighting.ts +4 -2
  135. package/templates/minimal/src/render/materialLighting.ts +5 -5
  136. package/templates/minimal/src/render/materials.ts +10 -0
  137. package/templates/minimal/src/render/quality.ts +7 -32
  138. package/templates/minimal/src/scenes/Play.ts +4 -1
  139. package/templates/minimal/vite.config.ts +7 -1
  140. package/templates/platformer/AGENTS.md +95 -46
  141. package/templates/platformer/CLAUDE.md +95 -46
  142. package/templates/platformer/index.html +1 -1
  143. package/templates/platformer/main.html +12 -0
  144. package/templates/platformer/package.json +7 -7
  145. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  146. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  147. package/templates/platformer/src/entities/Fox.ts +21 -6
  148. package/templates/platformer/src/game.ts +1 -1
  149. package/templates/platformer/src/main.ts +1 -0
  150. package/templates/platformer/src/render/backlightControls.ts +10 -0
  151. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  152. package/templates/platformer/src/render/materialLighting.ts +5 -5
  153. package/templates/platformer/src/render/quality.ts +7 -32
  154. package/templates/platformer/src/scenes/Play.ts +2 -1
  155. package/templates/platformer/src/style.css +4 -0
  156. package/templates/platformer/src/worker-page.ts +29 -0
  157. package/templates/platformer/src/worker.ts +5 -0
  158. package/templates/platformer/tsconfig.json +1 -1
  159. package/templates/platformer/vite.config.ts +4 -0
  160. package/templates/puzzle/AGENTS.md +97 -80
  161. package/templates/puzzle/CLAUDE.md +97 -80
  162. package/templates/puzzle/package.json +7 -7
  163. package/templates/puzzle/src/game.ts +1 -1
  164. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  165. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  166. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  167. package/templates/puzzle/src/render/quality.ts +7 -32
  168. package/templates/puzzle/src/scenes/Play.ts +1 -1
  169. package/templates/puzzle/src/style.css +4 -0
  170. package/templates/puzzle/tsconfig.json +1 -1
  171. package/templates/puzzle/vite.config.ts +2 -0
  172. package/templates/racing/AGENTS.md +100 -82
  173. package/templates/racing/CLAUDE.md +100 -82
  174. package/templates/racing/package.json +7 -7
  175. package/templates/racing/src/game.ts +1 -1
  176. package/templates/racing/src/render/atmosphere.ts +11 -16
  177. package/templates/racing/src/render/backlightControls.ts +10 -0
  178. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  179. package/templates/racing/src/render/clouds.ts +13 -0
  180. package/templates/racing/src/render/gpuSky.ts +4 -7
  181. package/templates/racing/src/render/materialLighting.ts +5 -5
  182. package/templates/racing/src/render/quality.ts +7 -32
  183. package/templates/racing/src/scenes/Race.ts +4 -1
  184. package/templates/racing/src/style.css +4 -0
  185. package/templates/racing/tsconfig.json +1 -1
  186. package/templates/racing/vite.config.ts +2 -0
  187. package/templates/rain/AGENTS.md +96 -84
  188. package/templates/rain/CLAUDE.md +96 -84
  189. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  190. package/templates/rain/package.json +6 -6
  191. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  192. package/templates/rain/src/game.ts +1 -1
  193. package/templates/rain/src/scenes/Boot.ts +1 -0
  194. package/templates/rain/src/state.ts +7 -0
  195. package/templates/rain/src/ui/GameUi.tsx +7 -1
  196. package/templates/rain/vite.config.ts +6 -0
  197. package/templates/rts/AGENTS.md +100 -85
  198. package/templates/rts/CLAUDE.md +100 -85
  199. package/templates/rts/package.json +6 -6
  200. package/templates/rts/src/game.ts +1 -1
  201. package/templates/rts/src/render/backlightControls.ts +10 -0
  202. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  203. package/templates/rts/src/render/materialLighting.ts +5 -5
  204. package/templates/rts/src/render/quality.ts +7 -31
  205. package/templates/rts/src/scenes/Play.ts +1 -1
  206. package/templates/rts/src/style.css +4 -0
  207. package/templates/rts/vite.config.ts +2 -0
  208. package/templates/runner/AGENTS.md +97 -80
  209. package/templates/runner/CLAUDE.md +97 -80
  210. package/templates/runner/package.json +7 -7
  211. package/templates/runner/playtests/performance.playtest.json +1 -1
  212. package/templates/runner/src/game.ts +1 -1
  213. package/templates/runner/src/render/atmosphere.ts +11 -16
  214. package/templates/runner/src/render/backlightControls.ts +10 -0
  215. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  216. package/templates/runner/src/render/clouds.ts +13 -0
  217. package/templates/runner/src/render/gpuSky.ts +4 -7
  218. package/templates/runner/src/render/lighting.ts +53 -11
  219. package/templates/runner/src/render/materialLighting.ts +5 -5
  220. package/templates/runner/src/render/quality.ts +7 -32
  221. package/templates/runner/src/scenes/Run.ts +8 -4
  222. package/templates/runner/src/style.css +4 -0
  223. package/templates/runner/threenative.config.ts +0 -3
  224. package/templates/runner/tsconfig.json +1 -1
  225. package/templates/runner/vite.config.ts +2 -0
  226. package/templates/sailing/AGENTS.md +96 -79
  227. package/templates/sailing/CLAUDE.md +96 -79
  228. package/templates/sailing/package.json +7 -7
  229. package/templates/sailing/playtests/sails.playtest.json +1 -0
  230. package/templates/sailing/src/game.ts +1 -1
  231. package/templates/sailing/src/render/backlightControls.ts +10 -0
  232. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  233. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  234. package/templates/sailing/src/render/materialLighting.ts +5 -5
  235. package/templates/sailing/src/render/quality.ts +7 -32
  236. package/templates/sailing/src/render/sky.ts +4 -0
  237. package/templates/sailing/src/style.css +5 -0
  238. package/templates/sailing/threenative.config.ts +0 -3
  239. package/templates/sailing/vite.config.ts +6 -0
  240. package/templates/shooter/AGENTS.md +97 -68
  241. package/templates/shooter/CLAUDE.md +97 -68
  242. package/templates/shooter/package.json +7 -7
  243. package/templates/shooter/src/game.ts +3 -2
  244. package/templates/shooter/src/render/atmosphere.ts +11 -16
  245. package/templates/shooter/src/render/backlightControls.ts +10 -0
  246. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  247. package/templates/shooter/src/render/clouds.ts +13 -0
  248. package/templates/shooter/src/render/gpuSky.ts +4 -7
  249. package/templates/shooter/src/render/materialLighting.ts +5 -5
  250. package/templates/shooter/src/render/quality.ts +10 -33
  251. package/templates/shooter/src/scenes/Play.ts +4 -1
  252. package/templates/shooter/src/style.css +4 -0
  253. package/templates/shooter/vite.config.ts +2 -0
  254. package/templates/snow/AGENTS.md +95 -76
  255. package/templates/snow/CLAUDE.md +95 -76
  256. package/templates/snow/package.json +7 -7
  257. package/templates/snow/src/game.ts +1 -1
  258. package/templates/snow/src/render/backlightControls.ts +10 -0
  259. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  260. package/templates/snow/src/render/materialLighting.ts +5 -5
  261. package/templates/snow/src/render/quality.ts +7 -32
  262. package/templates/snow/src/style.css +5 -0
  263. package/templates/snow/threenative.config.ts +0 -3
  264. package/templates/snow/vite.config.ts +6 -0
  265. package/templates/starter/AGENTS.md +109 -88
  266. package/templates/starter/CLAUDE.md +109 -88
  267. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  268. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  269. package/templates/starter/package.json +7 -7
  270. package/templates/starter/src/entities/Crate.ts +5 -2
  271. package/templates/starter/src/entities/Player.ts +10 -22
  272. package/templates/starter/src/game.ts +4 -3
  273. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  274. package/templates/starter/src/render/atmosphere.ts +11 -16
  275. package/templates/starter/src/render/backlightControls.ts +10 -0
  276. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  277. package/templates/starter/src/render/clouds.ts +13 -0
  278. package/templates/starter/src/render/contactShadow.ts +1 -1
  279. package/templates/starter/src/render/gpuSky.ts +4 -7
  280. package/templates/starter/src/render/lighting.ts +54 -4
  281. package/templates/starter/src/render/materialLighting.ts +5 -5
  282. package/templates/starter/src/render/postprocessing.ts +11 -10
  283. package/templates/starter/src/render/quality.ts +14 -1
  284. package/templates/starter/src/render/temporalAA.ts +8 -7
  285. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  286. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  287. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  288. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  289. package/templates/starter/src/render/temporalMoire.ts +190 -0
  290. package/templates/starter/src/render/temporalResolve.ts +75 -16
  291. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  292. package/templates/starter/src/scenes/Play.ts +53 -32
  293. package/templates/starter/src/state.ts +2 -0
  294. package/templates/starter/src/style.css +4 -0
  295. package/templates/starter/src/ui/Menu.tsx +5 -1
  296. package/templates/starter/vite.config.ts +2 -0
  297. package/templates/tower-defense/AGENTS.md +97 -81
  298. package/templates/tower-defense/CLAUDE.md +97 -81
  299. package/templates/tower-defense/package.json +7 -7
  300. package/templates/tower-defense/src/game.ts +1 -1
  301. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  302. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  303. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  304. package/templates/tower-defense/src/render/quality.ts +7 -32
  305. package/templates/tower-defense/src/scenes/Battle.ts +1 -1
  306. package/templates/tower-defense/src/style.css +4 -0
  307. package/templates/tower-defense/tsconfig.json +1 -1
  308. package/templates/tower-defense/vite.config.ts +2 -0
  309. package/capabilities.json +0 -9197
  310. package/templates/AGENTS.md +0 -21
  311. package/templates/CLAUDE.md +0 -23
  312. package/templates/action-rpg/.codex/config.toml +0 -23
  313. package/templates/action-rpg/.cursor/mcp.json +0 -38
  314. package/templates/action-rpg/.gemini/settings.json +0 -38
  315. package/templates/action-rpg/.mcp.json +0 -38
  316. package/templates/action-rpg/.vscode/mcp.json +0 -43
  317. package/templates/action-rpg/.zed/settings.json +0 -43
  318. package/templates/action-rpg/opencode.json +0 -49
  319. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  320. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  321. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  322. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  323. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  324. package/templates/adventure/.codex/config.toml +0 -23
  325. package/templates/adventure/.cursor/mcp.json +0 -38
  326. package/templates/adventure/.gemini/settings.json +0 -38
  327. package/templates/adventure/.mcp.json +0 -38
  328. package/templates/adventure/.vscode/mcp.json +0 -43
  329. package/templates/adventure/.zed/settings.json +0 -43
  330. package/templates/adventure/opencode.json +0 -49
  331. package/templates/collectathon/.codex/config.toml +0 -23
  332. package/templates/collectathon/.cursor/mcp.json +0 -38
  333. package/templates/collectathon/.gemini/settings.json +0 -38
  334. package/templates/collectathon/.mcp.json +0 -38
  335. package/templates/collectathon/.vscode/mcp.json +0 -43
  336. package/templates/collectathon/.zed/settings.json +0 -43
  337. package/templates/collectathon/opencode.json +0 -49
  338. package/templates/kart/.codex/config.toml +0 -23
  339. package/templates/kart/.cursor/mcp.json +0 -38
  340. package/templates/kart/.gemini/settings.json +0 -38
  341. package/templates/kart/.mcp.json +0 -38
  342. package/templates/kart/.vscode/mcp.json +0 -43
  343. package/templates/kart/.zed/settings.json +0 -43
  344. package/templates/kart/opencode.json +0 -49
  345. package/templates/minimal/.codex/config.toml +0 -23
  346. package/templates/minimal/.cursor/mcp.json +0 -38
  347. package/templates/minimal/.gemini/settings.json +0 -38
  348. package/templates/minimal/.mcp.json +0 -38
  349. package/templates/minimal/.vscode/mcp.json +0 -43
  350. package/templates/minimal/.zed/settings.json +0 -43
  351. package/templates/minimal/opencode.json +0 -49
  352. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  353. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  354. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  355. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  356. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  357. package/templates/platformer/.codex/config.toml +0 -23
  358. package/templates/platformer/.cursor/mcp.json +0 -38
  359. package/templates/platformer/.gemini/settings.json +0 -38
  360. package/templates/platformer/.mcp.json +0 -38
  361. package/templates/platformer/.vscode/mcp.json +0 -43
  362. package/templates/platformer/.zed/settings.json +0 -43
  363. package/templates/platformer/opencode.json +0 -49
  364. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  365. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  366. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  367. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  368. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  369. package/templates/puzzle/.codex/config.toml +0 -23
  370. package/templates/puzzle/.cursor/mcp.json +0 -38
  371. package/templates/puzzle/.gemini/settings.json +0 -38
  372. package/templates/puzzle/.mcp.json +0 -38
  373. package/templates/puzzle/.vscode/mcp.json +0 -43
  374. package/templates/puzzle/.zed/settings.json +0 -43
  375. package/templates/puzzle/opencode.json +0 -49
  376. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  377. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  378. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  379. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  380. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  381. package/templates/racing/.codex/config.toml +0 -23
  382. package/templates/racing/.cursor/mcp.json +0 -38
  383. package/templates/racing/.gemini/settings.json +0 -38
  384. package/templates/racing/.mcp.json +0 -38
  385. package/templates/racing/.vscode/mcp.json +0 -43
  386. package/templates/racing/.zed/settings.json +0 -43
  387. package/templates/racing/opencode.json +0 -49
  388. package/templates/racing/src/render/environmentContribution.ts +0 -188
  389. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  390. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  391. package/templates/racing/src/render/environmentSampling.ts +0 -193
  392. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  393. package/templates/rain/.codex/config.toml +0 -23
  394. package/templates/rain/.cursor/mcp.json +0 -38
  395. package/templates/rain/.gemini/settings.json +0 -38
  396. package/templates/rain/.mcp.json +0 -38
  397. package/templates/rain/.vscode/mcp.json +0 -43
  398. package/templates/rain/.zed/settings.json +0 -43
  399. package/templates/rain/opencode.json +0 -49
  400. package/templates/rts/.codex/config.toml +0 -23
  401. package/templates/rts/.cursor/mcp.json +0 -38
  402. package/templates/rts/.gemini/settings.json +0 -38
  403. package/templates/rts/.mcp.json +0 -38
  404. package/templates/rts/.vscode/mcp.json +0 -43
  405. package/templates/rts/.zed/settings.json +0 -43
  406. package/templates/rts/opencode.json +0 -49
  407. package/templates/rts/src/render/environmentContribution.ts +0 -188
  408. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  409. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  410. package/templates/rts/src/render/environmentSampling.ts +0 -193
  411. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  412. package/templates/runner/.codex/config.toml +0 -23
  413. package/templates/runner/.cursor/mcp.json +0 -38
  414. package/templates/runner/.gemini/settings.json +0 -38
  415. package/templates/runner/.mcp.json +0 -38
  416. package/templates/runner/.vscode/mcp.json +0 -43
  417. package/templates/runner/.zed/settings.json +0 -43
  418. package/templates/runner/README.md +0 -43
  419. package/templates/runner/opencode.json +0 -49
  420. package/templates/runner/src/render/environmentContribution.ts +0 -188
  421. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  422. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  423. package/templates/runner/src/render/environmentSampling.ts +0 -193
  424. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  425. package/templates/sailing/.codex/config.toml +0 -23
  426. package/templates/sailing/.cursor/mcp.json +0 -38
  427. package/templates/sailing/.gemini/settings.json +0 -38
  428. package/templates/sailing/.mcp.json +0 -38
  429. package/templates/sailing/.vscode/mcp.json +0 -43
  430. package/templates/sailing/.zed/settings.json +0 -43
  431. package/templates/sailing/README.md +0 -28
  432. package/templates/sailing/opencode.json +0 -49
  433. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  434. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  435. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  436. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  437. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  438. package/templates/shooter/.codex/config.toml +0 -23
  439. package/templates/shooter/.cursor/mcp.json +0 -38
  440. package/templates/shooter/.gemini/settings.json +0 -38
  441. package/templates/shooter/.mcp.json +0 -38
  442. package/templates/shooter/.vscode/mcp.json +0 -43
  443. package/templates/shooter/.zed/settings.json +0 -43
  444. package/templates/shooter/opencode.json +0 -49
  445. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  446. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  447. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  448. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  449. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  450. package/templates/snow/.codex/config.toml +0 -23
  451. package/templates/snow/.cursor/mcp.json +0 -38
  452. package/templates/snow/.gemini/settings.json +0 -38
  453. package/templates/snow/.mcp.json +0 -38
  454. package/templates/snow/.vscode/mcp.json +0 -43
  455. package/templates/snow/.zed/settings.json +0 -43
  456. package/templates/snow/README.md +0 -26
  457. package/templates/snow/opencode.json +0 -49
  458. package/templates/snow/src/render/environmentContribution.ts +0 -188
  459. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  460. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  461. package/templates/snow/src/render/environmentSampling.ts +0 -193
  462. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  463. package/templates/starter/.codex/config.toml +0 -23
  464. package/templates/starter/.cursor/mcp.json +0 -38
  465. package/templates/starter/.gemini/settings.json +0 -38
  466. package/templates/starter/.mcp.json +0 -38
  467. package/templates/starter/.vscode/mcp.json +0 -43
  468. package/templates/starter/.zed/settings.json +0 -43
  469. package/templates/starter/opencode.json +0 -49
  470. package/templates/starter/src/render/environmentContribution.ts +0 -188
  471. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  472. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  473. package/templates/starter/src/render/environmentSampling.ts +0 -193
  474. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  475. package/templates/starter/src/render/rendererGate.ts +0 -36
  476. package/templates/tower-defense/.codex/config.toml +0 -23
  477. package/templates/tower-defense/.cursor/mcp.json +0 -38
  478. package/templates/tower-defense/.gemini/settings.json +0 -38
  479. package/templates/tower-defense/.mcp.json +0 -38
  480. package/templates/tower-defense/.vscode/mcp.json +0 -43
  481. package/templates/tower-defense/.zed/settings.json +0 -43
  482. package/templates/tower-defense/README.md +0 -16
  483. package/templates/tower-defense/opencode.json +0 -49
  484. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  485. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  486. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  487. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  488. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -1,97 +1,118 @@
1
1
  <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
2
 
3
- # AGENTS.md — __PROJECT_NAME__ starter
4
- Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
5
- ## Ownership
6
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
7
- `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as Unreal's default sky and a rigged figure: `src/render/sky.ts` draws an atmosphere sky with clouds (`atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) that is the background, the environment light and the height-fog colour, `lighting.ts` adds the one sun at `SUN_DIRECTION`, tinted by the air it crosses, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Move `SUN_DIRECTION` and the sky, sun colour and fog follow; `SKY_OPTIONS` in `sky.ts` takes `sky: "photo"` (the `assets/sky.jpg` photograph, Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce); swap the rig and edit `CLIPS`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `src/render/sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
8
-
9
- ## Start every change
10
- 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
11
- 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints,
12
- direct the user to review it, and wait for explicit approval plus an instruction to implement it.
13
- 3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
14
- use returned subpaths and `attachToBone` rather than rebuilding installed systems.
15
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` enables continuous collision by default; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
16
- ## When the framework blocks you, write plain Three.js
3
+ <!-- shared: kit-identity -->
4
+ # AGENTS.md — __PROJECT_NAME__ (Starter, the starter template)
5
+
6
+ A polished default project with a React HUD, physics, and a ready-to-edit scene. Routing words: starter. `CLAUDE.md` is a copy of this file.
7
+ <!-- /shared -->
8
+
9
+ <!-- shared: kit-router -->
10
+ ## Authoring flow
11
+
12
+ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
13
+
14
+ 1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
15
+ 2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
+ 4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
18
+ 5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
19
+ 6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
20
+ 7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
21
+ 8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
22
+
23
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
24
+ <!-- /shared -->
25
+
26
+ <!-- shared: kit-mcp -->
27
+ ## MCP servers
17
28
 
18
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
19
- piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
20
- bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
21
- (API, expectation, result, replacement); never stall the game.
22
- ## Workflow skills
29
+ `.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
23
30
 
24
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
25
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
26
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
27
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
28
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
29
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
30
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
31
- - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
32
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
31
+ - `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
32
+ - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
+ - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
+ - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
+ - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
+ <!-- /shared -->
33
38
 
34
- ## Commands and map
39
+ ## This kit
40
+
41
+ <!-- shared: kit-files -->
42
+ Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`, `worker-page.ts`, `worker.ts`.
43
+ 4 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
44
+ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
45
+ Kit notes: `node_modules/create-threenative/agent-docs/references/kit-starter.md`.
46
+ <!-- /shared -->
47
+
48
+ `Play`: a grid test arena (`src/render/arena.ts`) with a pickup, crate, jump gap and spawn; `platform()` builds both course ends.
49
+ React mounts from `src/main.ts`; `src/game.ts` is portable. This repository owns gameplay and every visible choice in `src/render/`.
50
+
51
+ <!-- shared: kit-commands -->
52
+ ## Commands
35
53
 
36
54
  ```sh
37
- pnpm dev
38
- pnpm studio
39
- pnpm build
40
- pnpm build --target desktop
41
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
42
- node tools/look.mjs
55
+ pnpm dev # play in the browser
56
+ pnpm test # typecheck, lint, format, then every playtest
57
+ pnpm build --target desktop # also: web, android, ios
58
+ pnpm studio # open the game in Studio
59
+ pnpm test:native # native proof
60
+ npx threenative doctor # build, import, device or blank-frame failure
61
+ npx threenative doctor --fix # refresh agent files
43
62
  ```
63
+ <!-- /shared -->
64
+
65
+ <!-- shared: kit-conventions -->
66
+ ## Conventions
67
+
68
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
69
+
70
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
71
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
72
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
73
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
74
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
75
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
76
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
77
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
78
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
79
+ - **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
80
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
81
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
82
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
83
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
84
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
85
+ - **Feet on the floor** `#ground-snap`: `GroundSnap`. Override: `enabled: false`.
86
+ - **One metre is one metre** `#scale`: `normaliseToMetres`. Override: per-call options.
87
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
88
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
89
+ - **Rough diffuse** `#rough-diffuse`: on. Override: `material.roughDiffuse = false`.
90
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
91
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
92
+ - **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
93
+ - **Shadows** `#shadows`: soft by source radius. Override: `penumbraScale`; `VirtualShadowNode` options. Marker: `TN_SHADOW_TIER`.
94
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
95
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
96
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
97
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
98
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
99
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
100
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
101
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
102
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
103
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
104
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
105
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
106
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
107
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
108
+ <!-- /shared -->
109
+
110
+ <!-- shared: kit-stuck -->
111
+ ## When the framework blocks you, write plain Three.js
112
+
113
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
114
+
115
+ ## Stuck
44
116
 
45
- The game boots straight into `Play`: a test arena holding a pickup, a crate, a gap you must jump and
46
- a flag, which together produce `won` or `lost`; `R` and the React restart intent rebuild from
47
- `initialState`. Keep the packaged `assets/native-proof.glb` load and its console marker for the
48
- desktop asset gate. `Play.ts` owns gameplay, `src/render/` owns the look, `src/ui/Hud.tsx`/`Menu.tsx`
49
- own UI, and `state.ts` publishes JSON-safe values. Keep `playtests/survives.playtest.json` as smoke
50
- proof and update outcome tests. `index.html` runs `game.ts` in a web worker
51
- (`src/worker.ts`, page side `src/worker-page.ts`), so a busy page cannot stall its frames; `main.html` is the named override that runs it on the page thread.
52
-
53
- On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src/render/touch-controls.ts` adds a left movement stick and right jump button; the scene passes its input to `Player`, with keyboard mapping as the desktop fallback.
54
- ## Portable authoring contracts
55
-
56
- Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
57
-
58
- Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
59
- Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale. `ctx.beforeRender(fn)` registers scene work that runs once per actual world draw, after the frame's last fixed update and before the projection packs, so `fn` reads the frame's final state; a held loader frame draws no world and dispatches nothing, and the registration clears on scene change and stop like `ctx.afterPhysics`. Automatic drawing resolution (`render.resolutionScale: "auto"` on `defineGame`) reads fresh GPU cost before presentation timing, so a host delay alone does not spend pixels while GPU headroom is observed and sustained headroom restores resolution; missing or stale GPU timing probes one rung and refunds it unless fewer pixels earn a better frame rate, oscillation holds are temporary, a numeric `resolutionScale` is the named pin override, and `TN_FRAME_BUDGET` reports the actual scale, its source, the GPU time as a mean/p50/p95/max series over resolved frames (`gpu`, with `gpuStale` counting frames that had no fresh reading and `gpu` absent rather than zero when there were none), and the draw calls and triangles each render pass submitted (main, shadow, reflection) under either policy. The engine's scene-render projection — an internal mirror that collapses repeated draws — is on by default; `render.projection: false` is the named opt-out and builds no mirror, so a game that measured it as a loss pays nothing to decline it, reported as `TN_RENDER_PROJECTION` reasonCode `disabled`. When the mirror draws props whose materials differ only in base colour, it proves a **bounded slice** of those materials each frame (`render.projection.materialChecks: "spread"`, the default) instead of all of them, so a base-colour edit still lands the same frame while any other material edit — a new roughness, map or define — leaves the batch and is drawn exactly up to `materialCheckStaleFrames` frames later, which `TN_RENDER_PROJECTION` reports. Name `"everyFrame"` to pay for every material every frame instead. A water surface's mirrored pass redraws every frame by default; `reflection.refreshInterval: N` redraws it every Nth presented frame and samples the previous reflection target in between, which halves the pass's cost at the price of up to `N - 1` frames of lag while the camera moves.
60
- React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`, and style `[data-tn-native-select]` / `[data-tn-native-select-option]` if the game has a `<select>`: on desktop the UI is drawn into the game's own frame with no view for a native popup to open into, so the engine renders the list in the page and the project gives it a look, the same division as `[data-threenative-debug-overlay]`. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
61
- `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then
62
- `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch.
63
- `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded
64
- randomness is deterministic only when `defineGame({ seed })` is configured.
65
-
66
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each
67
- rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names
68
- tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which
69
- therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
70
-
71
- `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate.
72
-
73
- ## The arena is a test arena, and its look is a grid
74
- `src/render/arena.ts` owns the ground, the four walls, one pillar, and `platform()`, the single builder both ends of the course are cut from. A platform is a light metre-grid plate over a dark-grid body down to the ground: two meshes, so the player collides with exactly the triangles they can see, and the sides read as structure while the walking surface reads as floor. The ground has no collider — that is the pit under the gap, and why falling costs a life instead of landing on scenery. Move a platform and move its support surface in `Play.ts` and `Goal.ts` with it, or grounding will answer for a surface that is no longer there.
75
- The sun's shadow camera covers the diagonal of `ARENA` down to `GROUND_Y`; changing those dimensions updates coverage automatically.
76
- `materials.ts` is the whole look: two greys and one saturated colour. Light grid where the player walks, dark grid on sides and structure, and the single `accent` hue reserved for the crate, the pickup and the flagpole — what you can touch. `worldGridUVs` makes one grid tile one metre on every face of every prop, so call it after a geometry is placed and before it is given to a mesh.
77
- ## Quality and proof
78
-
79
- WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` selects the boot tier (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`; `unknown` falls back to `isMobile()`), and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
80
- `setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit. A bounded participating medium is generated source you own: `src/render/volumetricFog.ts` and its three companions build depth-correct mist, and `STARTER_MIST` there owns this game's density, colour, bounds and its single `enabled` flag — off costs no target and no pixel. `Play` passes it the live `ctx.renderer.kind`, so the WebGL fallback allocates nothing, and it owns `scene.fog` while it lives, so aerial perspective and god rays must stay off: they render the same air. `setupPost`'s `fog` factory rebuilds it whenever the tier replaces the chain. It is lit by `ambient` until you pass `points` (unshadowed, finite-range `PointLight`s) or a `sun` whose shadow map already exists — nothing wires one for you.
81
- The shipped chain comes from `qualityPreset(tier)` and `WorldEnvironment` in `@threenative/core`. Keep this game's sky, materials, grade and effect overrides in `src/render/`; `TN_RENDER_CHAIN` reports every applied or refused stage. The neutral grade and optional film grain remain game-owned in `grade.ts` and `public/grade.cube`. Every override has a name on the same quality preset, and a missing stage observation is a failure.
82
- `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
83
-
84
- `src/render/temporalAA.ts` is an experimental, opt-in TRAANode provider for scene input reconstruction. Shipped quality tiers use the engine's built-in `traa` stage instead, and `debug().temporal` reports whichever one runs. Supply colour/depth/velocity from the same scene pass through a `traa` RenderChain stage, reset history on camera cuts, and dispose with the stage. The optional exact scene-pass argument enables a bounded raw4 current-footprint candidate for supported reduced rasters; it owns four-sample beauty and matching visibility replays and restores ordinary pass policy on unsupported inputs. Opaque RGB remains a pixel-frequency approximation; alpha-tested visibility uses sample interpolation. The ordinary path uses scene-pass MSAA disabled. `temporalResolve.ts` retains optional linear/Catmull–Rom and ordinary-blend comparisons, both depth-history vetoes, and mandatory RGB clipping. Original quality/recovery, GPU cost, automatic scaling and native gates remain unqualified.
85
- ## One shadow for a big outdoor level
86
- When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. Movers sort themselves: a caster whose matrix changes draws through a per-level mover map and returns to the cached levels after `staticAfterFrames` quiet frames, each change redrawing only its own region. `trackCaster(object)` pins a mover for good, `pinStatic(object)` opts an object out; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
87
- ## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
88
-
89
- The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
90
- For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
91
- ## Optional multiplayer transport
92
- For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
93
-
94
- High-tier desktop browser WebGPU adds game-owned grazing backlight (`lighting.ts`: `rimGain: 0`) and measured-dark directional fill (`fillGain: 0` or black `fillColor`). `materialLighting.ts` preserves borrowed material maps and restores originals on lower quality/exit; mobile, software, WebGL and native retain originals. `TN_ENVIRONMENT_CONTRIBUTION` reports even with overrides zero; `environmentSampling.ts` estimates actual IBL once during load; unavailable/stale samples stay unknown and disable analytic fill. Native material terms remain unqualified.
95
- `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds. One fog owner at a time: an enabled `STARTER_MIST` clears both `scene.fog` and `scene.fogNode`.
96
-
97
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`; this kit uses them. Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset. The render log reports the override.
117
+ `npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
118
+ <!-- /shared -->
@@ -30,67 +30,67 @@
30
30
  "perAdapter": {
31
31
  "integrated": {
32
32
  "contributions": {
33
- "graphOutputChanged": ["ambientOcclusion", "traa", "bloom", "vignette"]
33
+ "graphOutputChanged": ["ambientOcclusion", "ssr", "bloom", "vignette", "antialias"]
34
34
  },
35
35
  "stages": {
36
- "includes": ["ambientOcclusion", "traa", "bloom", "vignette"],
37
- "excludes": ["motionBlur", "grade", "grain"],
38
- "order": ["ambientOcclusion", "traa", "bloom", "vignette"]
36
+ "excludes": ["ssgi", "traa", "motionBlur", "grade", "grain"],
37
+ "includes": ["ambientOcclusion", "ssr", "bloom", "vignette", "antialias"],
38
+ "order": ["ambientOcclusion", "ssr", "bloom", "vignette", "antialias"]
39
39
  },
40
40
  "tier": "medium"
41
41
  },
42
42
  "mobile-high": {
43
43
  "contributions": {
44
- "graphOutputChanged": ["ambientOcclusion", "traa", "bloom", "vignette"]
44
+ "graphOutputChanged": ["ambientOcclusion", "ssr", "bloom", "vignette", "antialias"]
45
45
  },
46
46
  "stages": {
47
- "includes": ["ambientOcclusion", "traa", "bloom", "vignette"],
48
- "excludes": ["motionBlur", "grade", "grain"],
49
- "order": ["ambientOcclusion", "traa", "bloom", "vignette"]
47
+ "excludes": ["ssgi", "traa", "motionBlur", "grade", "grain"],
48
+ "includes": ["ambientOcclusion", "ssr", "bloom", "vignette", "antialias"],
49
+ "order": ["ambientOcclusion", "ssr", "bloom", "vignette", "antialias"]
50
50
  },
51
51
  "tier": "medium"
52
52
  },
53
53
  "mobile-low": {
54
54
  "contributions": {
55
- "graphOutputChanged": ["bloom", "vignette", "antialias"]
55
+ "graphOutputChanged": ["ssr", "bloom", "vignette", "antialias"]
56
56
  },
57
57
  "stages": {
58
- "includes": ["bloom", "vignette", "antialias"],
59
- "excludes": ["ambientOcclusion", "motionBlur", "grade", "grain"],
60
- "order": ["bloom", "vignette", "antialias"]
58
+ "excludes": ["ambientOcclusion", "ssgi", "traa", "motionBlur", "grade", "grain"],
59
+ "includes": ["ssr", "bloom", "vignette", "antialias"],
60
+ "order": ["ssr", "bloom", "vignette", "antialias"]
61
61
  },
62
62
  "tier": "low"
63
63
  },
64
64
  "mobile-mid": {
65
65
  "contributions": {
66
- "graphOutputChanged": ["bloom", "vignette", "antialias"]
66
+ "graphOutputChanged": ["ssr", "bloom", "vignette", "antialias"]
67
67
  },
68
68
  "stages": {
69
- "includes": ["bloom", "vignette", "antialias"],
70
- "excludes": ["ambientOcclusion", "motionBlur", "grade", "grain"],
71
- "order": ["bloom", "vignette", "antialias"]
69
+ "excludes": ["ambientOcclusion", "ssgi", "traa", "motionBlur", "grade", "grain"],
70
+ "includes": ["ssr", "bloom", "vignette", "antialias"],
71
+ "order": ["ssr", "bloom", "vignette", "antialias"]
72
72
  },
73
73
  "tier": "low"
74
74
  },
75
75
  "software": {
76
76
  "contributions": {
77
- "graphOutputChanged": ["bloom", "vignette", "antialias"]
77
+ "graphOutputChanged": ["ssr", "bloom", "vignette", "antialias"]
78
78
  },
79
79
  "stages": {
80
- "includes": ["bloom", "vignette", "antialias"],
81
- "excludes": ["ambientOcclusion", "motionBlur", "grade", "grain"],
82
- "order": ["bloom", "vignette", "antialias"]
80
+ "excludes": ["ambientOcclusion", "ssgi", "traa", "motionBlur", "grade", "grain"],
81
+ "includes": ["ssr", "bloom", "vignette", "antialias"],
82
+ "order": ["ssr", "bloom", "vignette", "antialias"]
83
83
  },
84
84
  "tier": "low"
85
85
  }
86
86
  },
87
87
  "stages": {
88
- "includes": ["ambientOcclusion", "traa", "motionBlur", "bloom", "vignette"],
89
- "excludes": ["grade", "grain"],
90
- "order": ["ambientOcclusion", "traa", "motionBlur", "bloom", "vignette"]
88
+ "excludes": ["traa", "motionBlur", "grade", "grain"],
89
+ "includes": ["ambientOcclusion", "ssgi", "ssr", "bloom", "vignette", "antialias"],
90
+ "order": ["ambientOcclusion", "ssgi", "ssr", "bloom", "vignette", "antialias"]
91
91
  },
92
92
  "contributions": {
93
- "graphOutputChanged": ["ambientOcclusion", "traa", "motionBlur", "bloom", "vignette"]
93
+ "graphOutputChanged": ["ambientOcclusion", "ssgi", "ssr", "bloom", "vignette", "antialias"]
94
94
  }
95
95
  },
96
96
  "resources": [
@@ -38,18 +38,18 @@
38
38
  "components": [
39
39
  {
40
40
  "entity": "smooth-motion",
41
- "component": "samples",
41
+ "component": "tickSamples",
42
42
  "gte": 21
43
43
  },
44
44
  {
45
45
  "entity": "smooth-motion",
46
- "component": "playerCv",
46
+ "component": "tickPlayerCv",
47
47
  "gte": 0,
48
48
  "lte": 0.1
49
49
  },
50
50
  {
51
51
  "entity": "smooth-motion",
52
- "component": "cameraCv",
52
+ "component": "tickCameraCv",
53
53
  "gte": 0,
54
54
  "lte": 0.1
55
55
  }
@@ -20,9 +20,9 @@
20
20
  "format:check": "biome format src"
21
21
  },
22
22
  "dependencies": {
23
- "@threenative/core": "0.3.11",
24
- "@threenative/physics": "0.3.11",
25
- "@threenative/ui": "0.3.11",
23
+ "@threenative/core": "0.3.13",
24
+ "@threenative/physics": "0.3.13",
25
+ "@threenative/ui": "0.3.13",
26
26
  "react": "19.2.0",
27
27
  "react-dom": "19.2.0",
28
28
  "react-reconciler": "0.33.0",
@@ -30,13 +30,13 @@
30
30
  },
31
31
  "devDependencies": {
32
32
  "@tailwindcss/vite": "4.3.3",
33
- "@threenative/assets": "0.3.12",
34
- "@threenative/playtest": "0.3.11",
33
+ "@threenative/assets": "0.3.14",
34
+ "@threenative/playtest": "0.3.13",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
37
  "@types/three": "0.187.0",
38
38
  "@vitejs/plugin-react": "6.0.5",
39
- "create-threenative": "0.2.15",
39
+ "create-threenative": "0.2.18",
40
40
  "esbuild": "0.27.0",
41
41
  "playwright": "1.62.1",
42
42
  "tailwindcss": "4.3.3",
@@ -47,7 +47,7 @@
47
47
  "eslint": "10.13.0"
48
48
  },
49
49
  "optionalDependencies": {
50
- "@threenative/runtime-native": "0.3.11"
50
+ "@threenative/runtime-native": "0.3.13"
51
51
  },
52
52
  "overrides": {
53
53
  "sharp": ">=0.35.4",
@@ -16,6 +16,9 @@ export class Crate {
16
16
  y: number,
17
17
  z: number,
18
18
  material: Material,
19
+ // On a tier with a sun shadow sharp enough to ground it, the blob is a second, blurred shadow
20
+ // beside the sun's; Play.ts draws it only on `low`, which has no ambient occlusion pass.
21
+ contactShadow: () => boolean = () => true,
19
22
  ) {
20
23
  this.mesh = new Mesh(roundedBox(1, 1, 1), material);
21
24
  this.mesh.position.set(x, y, z);
@@ -31,8 +34,8 @@ export class Crate {
31
34
  from.set(x, y, z);
32
35
  to.set(x, y - 6, z);
33
36
  const gap = ctx.physics.directSpaceState.intersectRay({ from, to })?.distance;
34
- this.#shadow.object.visible = gap !== undefined;
35
- if (gap === undefined) return;
37
+ this.#shadow.object.visible = gap !== undefined && contactShadow();
38
+ if (!this.#shadow.object.visible || gap === undefined) return;
36
39
  this.#shadow.object.position.set(x, y - gap + 0.03, z);
37
40
  this.#shadow.fade(Math.max(0, 1 - (gap - 0.5) / 1.5));
38
41
  });
@@ -1,14 +1,6 @@
1
1
  import { BlendSpace1D, type ICtx, SkeletalMesh3D } from "@threenative/core";
2
2
  import { CharacterBody3D, CollisionShape3D, type IPhysicsContext } from "@threenative/physics";
3
- import {
4
- type AnimationClip,
5
- Group,
6
- MathUtils,
7
- type Mesh,
8
- type Object3D,
9
- Quaternion,
10
- Vector3,
11
- } from "three";
3
+ import { type AnimationClip, Group, type Mesh, type Object3D, Quaternion, Vector3 } from "three";
12
4
  import { type IStarterConventions, preparePlayerConventions } from "../conventions.js";
13
5
  import type { ITouchInput } from "../render/touch-controls.js";
14
6
  import type { GameState } from "../state.js";
@@ -64,6 +56,7 @@ export class Player {
64
56
  #landing = 0;
65
57
  #wasGrounded = true;
66
58
  #supportSurfaceY = 0;
59
+ #heading = new Quaternion();
67
60
  #previousPosition = new Vector3();
68
61
  #bodyWorldPosition = new Vector3();
69
62
  #visualWorldPosition = new Vector3();
@@ -114,12 +107,7 @@ export class Player {
114
107
  });
115
108
  }
116
109
 
117
- update(
118
- ctx: GameCtx,
119
- dt: number,
120
- supportSurfaceY?: (position: Pick<Vector3, "x" | "y" | "z">) => number | undefined,
121
- touch?: ITouchInput,
122
- ): void {
110
+ update(ctx: GameCtx, dt: number, touch?: ITouchInput): void {
123
111
  if (this.#hasPreviousPosition) {
124
112
  this.#odometer += this.mesh.position.distanceTo(this.#previousPosition);
125
113
  // The solver applies moveAndSlide after update; measure its last completed step.
@@ -163,11 +151,8 @@ export class Player {
163
151
  this.body.moveAndSlide(dt);
164
152
  this.#hasPreviousPosition = true;
165
153
  if (this.body.grounded) this.#coyoteTime = COYOTE_TIME;
166
- const supportingSurfaceY = supportSurfaceY?.(this.mesh.position);
167
- const canCorrectGrounding =
168
- this.body.grounded && this.body.velocity.y <= 0 && supportingSurfaceY !== undefined;
169
- // The resolver identifies the supporting collider; derive the contact plane from the
170
- // grounded character so a changed platform height never pulls the visual from its body.
154
+ const canCorrectGrounding = this.body.grounded && this.body.velocity.y <= 0;
155
+ // Derive the contact plane from the grounded body, including terrain outside the arena.
171
156
  if (canCorrectGrounding) this.#supportSurfaceY = this.mesh.position.y - PLAYER_FOOT_OFFSET;
172
157
  this.#conventions.groundSnap.enabled = canCorrectGrounding;
173
158
  this.#conventions.applyGrounding(this.#supportSurfaceY, dt);
@@ -190,6 +175,7 @@ export class Player {
190
175
  facingAxis: "+x" | "-x" | "+z" | "-z";
191
176
  gait: "idle" | "walk" | "run" | "air";
192
177
  grounded: boolean;
178
+ facingZ: number;
193
179
  groundClearance: number | null;
194
180
  groundCorrectionEnabled: boolean;
195
181
  groundSurfaceY: number;
@@ -226,6 +212,7 @@ export class Player {
226
212
  ? "run"
227
213
  : "walk",
228
214
  grounded: this.body.grounded,
215
+ facingZ: this.character.root.getWorldDirection(new Vector3()).z,
229
216
  groundClearance: this.#conventions.groundSnap.clearance,
230
217
  groundCorrectionEnabled: this.#conventions.groundSnap.enabled,
231
218
  groundSurfaceY: this.#supportSurfaceY,
@@ -266,8 +253,9 @@ export class Player {
266
253
  const figure = this.character.root;
267
254
  if (Math.hypot(inputX, inputZ) > 0.05) {
268
255
  const heading = Math.atan2(inputX, inputZ);
269
- const turn = MathUtils.euclideanModulo(heading - figure.rotation.y + Math.PI, Math.PI * 2);
270
- figure.rotation.y += (turn - Math.PI) * Math.min(1, dt * 12);
256
+ // Matrix decomposition can represent a half-turn with x/z Euler rotations.
257
+ this.#heading.setFromAxisAngle(this.mesh.up, heading);
258
+ figure.quaternion.slerp(this.#heading, Math.min(1, dt * 12));
271
259
  }
272
260
  const grounded = this.body.grounded;
273
261
  this.#landing -= dt;
@@ -19,17 +19,18 @@ const game = defineGame<GameState, IPhysicsContext>({
19
19
  right: ["ArrowRight", "KeyD"],
20
20
  up: ["ArrowUp", "KeyW"],
21
21
  },
22
- run: { keys: ["ShiftLeft", "ShiftRight"] },
22
+ // Pad buttons use the W3C standard numbers: 0 is ✕ on a DualShock, 7 is R2, 9 is OPTIONS.
23
+ run: { buttons: [7], keys: ["ShiftLeft", "ShiftRight"] },
23
24
  jump: { buttons: [0], keys: ["Space"] },
24
25
  flagGust: { keys: ["KeyG"] },
25
- restart: { keys: ["KeyR"] },
26
+ restart: { buttons: [9], keys: ["KeyR"] },
26
27
  // Wheel, pinch and the right stick share one portable camera intent. Negative DOM deltaY
27
28
  // (toward-user) is positive scroll intent on browser and native; the scene owns the framing.
28
29
  zoom: { gamepadAxes: [3], pinch: true, scroll: true },
29
30
  },
30
31
  plugins: [rapier(), replay(), playtest()],
31
32
  display: config.display,
32
- render: config.renderer,
33
+ renderer: config.renderer,
33
34
  scenes: { play: Play },
34
35
  seed: 90210,
35
36
  start: "play",
@@ -66,6 +66,11 @@ export function createAdaptiveQuality(
66
66
  let lastChange = Number.NEGATIVE_INFINITY;
67
67
  let overloaded = 0;
68
68
  let healthy = 0;
69
+ // What a raise that failed cost, as a ratio of the cost before it, by the tier it fell back to. A raise from that
70
+ // tier waits until the predicted cost fits: retrying on headroom alone switched medium's shadows on and off every
71
+ // few seconds where low fits only without them (PRD-871).
72
+ const raiseCost = new Map<QualityTier, number>();
73
+ let raisedFrom: { tier: QualityTier; costMs: number } | undefined;
69
74
  const finite = (value: number | undefined): value is number =>
70
75
  value !== undefined && Number.isFinite(value);
71
76
  return {
@@ -156,6 +161,15 @@ export function createAdaptiveQuality(
156
161
  if (direction === 0) return report("steady");
157
162
  const next = QUALITY_TIERS[QUALITY_TIERS.indexOf(tier) + direction];
158
163
  if (next === undefined) return report(direction < 0 ? "at-floor" : "at-ceiling");
164
+ const ratio = raiseCost.get(tier);
165
+ if (
166
+ direction > 0 &&
167
+ ratio !== undefined &&
168
+ costMs * ratio > budgetMs * (1 - policy.headroom)
169
+ ) {
170
+ healthy = 0;
171
+ return report("predicted");
172
+ }
159
173
  const time = now();
160
174
  if (!Number.isFinite(time)) throw new Error("quality clock must return finite milliseconds.");
161
175
  if (time - lastChange < policy.cooldownMs) {
@@ -163,6 +177,9 @@ export function createAdaptiveQuality(
163
177
  healthy = 0;
164
178
  return report("cooldown");
165
179
  }
180
+ if (direction < 0 && raisedFrom?.tier === next)
181
+ raiseCost.set(next, costMs / raisedFrom.costMs);
182
+ raisedFrom = direction > 0 ? { tier, costMs } : undefined;
166
183
  tier = next;
167
184
  lastChange = time;
168
185
  overloaded = 0;