create-threenative 0.2.3 → 0.2.5

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
package/package.json CHANGED
@@ -1,9 +1,32 @@
1
1
  {
2
2
  "name": "create-threenative",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "license": "MIT",
5
5
  "description": "Scaffold a readable ThreeNative game project.",
6
+ "keywords": [
7
+ "threenative",
8
+ "three",
9
+ "threejs",
10
+ "scaffold",
11
+ "create",
12
+ "starter",
13
+ "gamedev",
14
+ "template"
15
+ ],
16
+ "homepage": "https://github.com/ThreeNativeHQ/threenative#readme",
17
+ "bugs": {
18
+ "url": "https://github.com/ThreeNativeHQ/threenative/issues"
19
+ },
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/ThreeNativeHQ/threenative.git",
23
+ "directory": "packages/create-threenative"
24
+ },
6
25
  "type": "module",
26
+ "engines": {
27
+ "node": ">=20.19.0",
28
+ "pnpm": ">=10.0.0"
29
+ },
7
30
  "files": [
8
31
  "dist",
9
32
  "templates",
@@ -53,12 +76,14 @@
53
76
  "publint": "0.3.22",
54
77
  "tsup": "8.5.1",
55
78
  "typescript": "5.9.3",
56
- "@threenative/assets": "0.3.0",
57
- "@threenative/physics": "0.3.0",
58
- "@threenative/core": "0.3.0"
79
+ "vite": "8.2.0",
80
+ "@threenative/assets": "0.3.2",
81
+ "@threenative/core": "0.3.2",
82
+ "@threenative/physics": "0.3.2",
83
+ "threenative-blender-mcp": "0.1.2"
59
84
  },
60
85
  "peerDependencies": {
61
- "@threenative/assets": ">=0.3.0 <0.4.0"
86
+ "@threenative/assets": ">=0.3.2 <0.4.0"
62
87
  },
63
88
  "scripts": {
64
89
  "build": "tsup --config tsup.config.ts && publint",
@@ -36,7 +36,11 @@ interface ILoadingHost {
36
36
  };
37
37
  readonly renderer: { compileAsync(scene: Scene, camera: Camera): Promise<void> };
38
38
  readonly scene: Scene;
39
- readonly startup: { readonly progress: number; whenReady(): Promise<void> };
39
+ readonly startup: {
40
+ readonly progress: number;
41
+ readonly warmup?: { readonly status: "complete" | "incomplete" | "unavailable" };
42
+ whenReady(): Promise<void>;
43
+ };
40
44
  readonly viewport?: {
41
45
  readonly safeArea: { height: number; width: number; x: number; y: number };
42
46
  };
@@ -231,7 +235,13 @@ export function createLoadingScreen(host: ILoadingHost): ILoadingController {
231
235
  };
232
236
 
233
237
  const updateProgress = (value: number): void => {
234
- progress = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
238
+ const bounded = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
239
+ // A missing or incomplete backend observation cannot prove that all first-use work is done.
240
+ // Keep the bar visibly indeterminate until readiness removes the cover; never turn unknown
241
+ // coverage into a false 100% claim.
242
+ const observationUnknown =
243
+ host.startup.warmup !== undefined && host.startup.warmup.status !== "complete";
244
+ progress = observationUnknown ? Math.min(0.9, bounded) : bounded;
235
245
  setFillUv(fill.geometry, progress, fillBaseU);
236
246
  status?.update(progress);
237
247
  layout();
@@ -1,5 +1,5 @@
1
1
  diff --git a/build/three.cjs b/build/three.cjs
2
- index 8939a67d..b0f91724 100644
2
+ index 8939a67dd76325ccd25ee8806fc4d22b1caea88a..b0f917241f1f2cd25baa21dec20edda32176ef6a 100644
3
3
  --- a/build/three.cjs
4
4
  +++ b/build/three.cjs
5
5
  @@ -26116,6 +26116,8 @@ function copyArrayContents( src, target ) {
@@ -12,7 +12,7 @@ index 8939a67d..b0f91724 100644
12
12
  * Constructs a new batched mesh.
13
13
  *
14
14
  diff --git a/build/three.core.js b/build/three.core.js
15
- index 0bb9262c..868a634b 100644
15
+ index 0bb9262cd029f411933d077fd44197a51ec5e8e9..868a634b4294be5f32664912a50813d55d6dd6e7 100644
16
16
  --- a/build/three.core.js
17
17
  +++ b/build/three.core.js
18
18
  @@ -26136,6 +26136,8 @@ function copyArrayContents( src, target ) {
@@ -25,7 +25,7 @@ index 0bb9262c..868a634b 100644
25
25
  * Constructs a new batched mesh.
26
26
  *
27
27
  diff --git a/build/three.webgpu.js b/build/three.webgpu.js
28
- index 2e490796..325b497a 100644
28
+ index 2e490796d4d4aa9479b04a5c46ddbf31cc05b1a1..d05599255744ccfca19dbfd0433da612583ce6ea 100644
29
29
  --- a/build/three.webgpu.js
30
30
  +++ b/build/three.webgpu.js
31
31
  @@ -18500,7 +18500,8 @@ const instance = /*@__PURE__*/ Fn( ( [ matrices, colors = null ], builder ) => {
@@ -86,7 +86,56 @@ index 2e490796..325b497a 100644
86
86
 
87
87
  }
88
88
 
89
- @@ -39725,7 +39742,8 @@ class VelocityNode extends TempNode {
89
+ @@ -29911,6 +29928,18 @@ class RenderObject {
90
+ */
91
+ this._sourceMaterial = renderer._currentSourceMaterial;
92
+
93
+ + /**
94
+ + * The version of `_sourceMaterial` this render object was last validated against.
95
+ + *
96
+ + * An override material is shared by every object in the pass and is used as a per-object
97
+ + * scratchpad, so its own `version` moves for reasons that have nothing to do with this
98
+ + * render object. The source material's version is the signal that does.
99
+ + *
100
+ + * @type {number}
101
+ + * @default 0
102
+ + */
103
+ + this.sourceVersion = ( this._sourceMaterial === null || this._sourceMaterial === undefined ) ? 0 : this._sourceMaterial.version;
104
+ +
105
+ /**
106
+ * An event listener which is defined by `RenderObjects`. It performs
107
+ * clean up tasks when `dispose()` on this render object.
108
+ @@ -30707,9 +30736,18 @@ class RenderObjects {
109
+
110
+ }
111
+
112
+ - if ( renderObject.version !== material.version || renderObject.needsUpdate ) {
113
+ + // When the renderer is drawing through an override material, that material is shared by
114
+ + // the whole pass and mutated per object, so its `version` alone answers the wrong
115
+ + // question. The source material this object actually carries answers the right one.
116
+ +
117
+ + const sourceMaterial = this.renderer._currentSourceMaterial;
118
+ + const sourceTracked = sourceMaterial !== null && sourceMaterial !== undefined;
119
+ + const sourceReplaced = sourceTracked && renderObject._sourceMaterial !== sourceMaterial;
120
+ + const sourceChanged = sourceTracked && ( sourceReplaced || renderObject.sourceVersion !== sourceMaterial.version );
121
+
122
+ - if ( renderObject.initialCacheKey !== renderObject.getCacheKey() ) {
123
+ + if ( renderObject.version !== material.version || sourceChanged || renderObject.needsUpdate ) {
124
+ +
125
+ + if ( sourceReplaced || renderObject.initialCacheKey !== renderObject.getCacheKey() ) {
126
+
127
+ renderObject.dispose();
128
+
129
+ @@ -30719,6 +30757,8 @@ class RenderObjects {
130
+
131
+ renderObject.version = material.version;
132
+
133
+ + if ( sourceTracked ) renderObject.sourceVersion = sourceMaterial.version;
134
+ +
135
+ }
136
+
137
+ }
138
+ @@ -39725,7 +39765,8 @@ class VelocityNode extends TempNode {
90
139
 
91
140
  const previousModelMatrix = getPreviousMatrix( object );
92
141
 
@@ -96,7 +145,7 @@ index 2e490796..325b497a 100644
96
145
 
97
146
  //
98
147
 
99
- @@ -53841,7 +53859,7 @@ class NodeBuilder {
148
+ @@ -53841,7 +53882,7 @@ class NodeBuilder {
100
149
 
101
150
  const mrt = this.renderer.getMRT();
102
151
 
@@ -105,7 +154,58 @@ index 2e490796..325b497a 100644
105
154
 
106
155
  }
107
156
 
108
- @@ -83814,6 +83832,14 @@ class WebGPUBackend extends Backend {
157
+ @@ -62731,6 +62772,7 @@ class Renderer {
158
+ let materialDisplacementMap;
159
+ let materialDisplacementScale;
160
+ let materialDisplacementBias;
161
+ + let materialAlphaTest;
162
+
163
+ const previousSourceMaterial = this._currentSourceMaterial;
164
+
165
+ @@ -62756,6 +62798,7 @@ class Renderer {
166
+ materialDisplacementMap = overrideMaterial.displacementMap;
167
+ materialDisplacementScale = overrideMaterial.displacementScale;
168
+ materialDisplacementBias = overrideMaterial.displacementBias;
169
+ + materialAlphaTest = overrideMaterial.alphaTest;
170
+
171
+ if ( material.positionNode && material.positionNode.isNode ) {
172
+
173
+ @@ -62763,7 +62806,15 @@ class Renderer {
174
+
175
+ }
176
+
177
+ - overrideMaterial.alphaTest = material.alphaTest;
178
+ + // `Material.alphaTest`'s setter bumps `version` whenever alpha-test-ness flips, and this
179
+ + // override material is shared by every caster in the pass. A scene that mixes alpha-tested
180
+ + // casters with opaque ones therefore moves that shared version several times per frame,
181
+ + // and every OTHER render object drawn with it then fails the version gate in
182
+ + // `RenderObjects.get` and recomputes a full material cache key that always matches.
183
+ + // Writing the backing field leaves the `alphaTest` getter — and so the cache key — still
184
+ + // reporting this caster's value, while each render object tracks the staleness signal
185
+ + // that belongs to it: its own source material's version.
186
+ + overrideMaterial._alphaTest = material.alphaTest;
187
+ overrideMaterial.alphaMap = material.alphaMap;
188
+ overrideMaterial.displacementMap = material.displacementMap;
189
+ overrideMaterial.displacementScale = material.displacementScale;
190
+ @@ -62825,6 +62876,7 @@ class Renderer {
191
+ scene.overrideMaterial.displacementMap = materialDisplacementMap;
192
+ scene.overrideMaterial.displacementScale = materialDisplacementScale;
193
+ scene.overrideMaterial.displacementBias = materialDisplacementBias;
194
+ + scene.overrideMaterial._alphaTest = materialAlphaTest;
195
+
196
+ }
197
+
198
+ @@ -79586,7 +79638,8 @@ class WGSLNodeBuilder extends NodeBuilder {
199
+
200
+ uniformGPU = buffer;
201
+
202
+ - uniformNode.name = name ? name : 'NodeBuffer_' + uniformNode.id;
203
+ + // The base builder supplies a unique name within this program. A process-wide
204
+ + // allocation id changes otherwise identical shader source for every buffer.
205
+
206
+ } else {
207
+
208
+ @@ -83814,6 +83867,14 @@ class WebGPUBackend extends Backend {
109
209
  */
110
210
  this.compatibilityMode = null;
111
211
 
@@ -120,7 +220,7 @@ index 2e490796..325b497a 100644
120
220
  /**
121
221
  * A reference to the device.
122
222
  *
123
- @@ -83926,7 +83952,9 @@ class WebGPUBackend extends Backend {
223
+ @@ -83926,7 +83987,9 @@ class WebGPUBackend extends Backend {
124
224
  xrCompatible: renderer.xr.enabled
125
225
  };
126
226
 
@@ -132,7 +232,7 @@ index 2e490796..325b497a 100644
132
232
  if ( adapter === null ) {
133
233
 
134
234
  diff --git a/src/nodes/accessors/Batch.js b/src/nodes/accessors/Batch.js
135
- index ab62e98d..2cf4bb60 100644
235
+ index ab62e98dadab2539d7e1d663fd42267bbc8ebcaa..2cf4bb6039853d5c922e89041419250b243694ef 100644
136
236
  --- a/src/nodes/accessors/Batch.js
137
237
  +++ b/src/nodes/accessors/Batch.js
138
238
  @@ -1,6 +1,6 @@
@@ -178,7 +278,7 @@ index ab62e98d..2cf4bb60 100644
178
278
  -
179
279
  -
180
280
  diff --git a/src/nodes/accessors/Instance.js b/src/nodes/accessors/Instance.js
181
- index b89834b9..c7b7bdd7 100644
281
+ index b89834b9166c75fd946ade24db265bf8c367d244..c7b7bdd7a31d852a581d4bc75a1e1afc1d214e5e 100644
182
282
  --- a/src/nodes/accessors/Instance.js
183
283
  +++ b/src/nodes/accessors/Instance.js
184
284
  @@ -220,7 +220,8 @@ export const instance = /*@__PURE__*/ Fn( ( [ matrices, colors = null ], builder
@@ -192,7 +292,7 @@ index b89834b9..c7b7bdd7 100644
192
292
  } );
193
293
 
194
294
  diff --git a/src/nodes/accessors/Skinning.js b/src/nodes/accessors/Skinning.js
195
- index 2356aed8..aaeea633 100644
295
+ index 2356aed8656dceb1ea74b73ea2e739371a960484..aaeea633a8ece291be5faf868e312867ddad01b6 100644
196
296
  --- a/src/nodes/accessors/Skinning.js
197
297
  +++ b/src/nodes/accessors/Skinning.js
198
298
  @@ -149,7 +149,8 @@ export const skinning = /*@__PURE__*/ Fn( ( [ skinnedMesh ], builder ) => {
@@ -216,7 +316,7 @@ index 2356aed8..aaeea633 100644
216
316
  }
217
317
 
218
318
  diff --git a/src/nodes/accessors/VelocityNode.js b/src/nodes/accessors/VelocityNode.js
219
- index 373548b0..c48002ab 100644
319
+ index 373548b0b587e7da3ef0993bfe316af420e7f66c..c48002abbce20ee8b29908cf314d7b03afe0db03 100644
220
320
  --- a/src/nodes/accessors/VelocityNode.js
221
321
  +++ b/src/nodes/accessors/VelocityNode.js
222
322
  @@ -106,7 +106,8 @@ class VelocityNode extends TempNode {
@@ -230,7 +330,7 @@ index 373548b0..c48002ab 100644
230
330
  //
231
331
 
232
332
  diff --git a/src/nodes/core/NodeBuilder.js b/src/nodes/core/NodeBuilder.js
233
- index be00b81e..1990da8f 100644
333
+ index be00b81ef36e1af83b0066603e616f8f1f81a115..1990da8fe8f1f29a7b53030756dfd966d8de3cb6 100644
234
334
  --- a/src/nodes/core/NodeBuilder.js
235
335
  +++ b/src/nodes/core/NodeBuilder.js
236
336
  @@ -3450,7 +3450,7 @@ class NodeBuilder {
@@ -243,7 +343,7 @@ index be00b81e..1990da8f 100644
243
343
  }
244
344
 
245
345
  diff --git a/src/objects/BatchedMesh.js b/src/objects/BatchedMesh.js
246
- index 2ef7cb25..35cc0ffe 100644
346
+ index 2ef7cb257438826059eb2408b3756c4891f06a10..35cc0ffe83a69ea9fa5fca6dec2d820ca193f88d 100644
247
347
  --- a/src/objects/BatchedMesh.js
248
348
  +++ b/src/objects/BatchedMesh.js
249
349
  @@ -181,6 +181,8 @@ function copyArrayContents( src, target ) {
@@ -255,8 +355,129 @@ index 2ef7cb25..35cc0ffe 100644
255
355
  /**
256
356
  * Constructs a new batched mesh.
257
357
  *
358
+ diff --git a/src/renderers/common/Bindings.js b/src/renderers/common/Bindings.js
359
+ index 5f3d213a016b37db3b2e5d022da3dd0234d86f6d..7a9a168f29773f37ef9a51ef9f07ade9f3ea95ef 100644
360
+ --- a/src/renderers/common/Bindings.js
361
+ +++ b/src/renderers/common/Bindings.js
362
+ @@ -206,10 +206,14 @@ class Bindings extends DataMap {
363
+
364
+ } else if ( binding.isSampledTexture ) {
365
+
366
+ + // Async node compilation can yield while a viewport node changes targets.
367
+ + // Refresh its reference before creating the first GPU binding, not after.
368
+ + binding.update();
369
+ this.textures.updateTexture( binding.texture );
370
+
371
+ } else if ( binding.isSampler ) {
372
+
373
+ + binding.update();
374
+ this.textures.updateSampler( binding );
375
+
376
+ } else if ( binding.isStorageBuffer ) {
377
+ diff --git a/src/renderers/common/RenderObject.js b/src/renderers/common/RenderObject.js
378
+ index c900fa4c9654f8cf3512e96de52a2c1c83e189a6..d0a87eabffc8f667ebe9b2f0eccda0ddf3309652 100644
379
+ --- a/src/renderers/common/RenderObject.js
380
+ +++ b/src/renderers/common/RenderObject.js
381
+ @@ -299,6 +299,18 @@ class RenderObject {
382
+ */
383
+ this._sourceMaterial = renderer._currentSourceMaterial;
384
+
385
+ + /**
386
+ + * The version of `_sourceMaterial` this render object was last validated against.
387
+ + *
388
+ + * An override material is shared by every object in the pass and is used as a per-object
389
+ + * scratchpad, so its own `version` moves for reasons that have nothing to do with this
390
+ + * render object. The source material's version is the signal that does.
391
+ + *
392
+ + * @type {number}
393
+ + * @default 0
394
+ + */
395
+ + this.sourceVersion = ( this._sourceMaterial === null || this._sourceMaterial === undefined ) ? 0 : this._sourceMaterial.version;
396
+ +
397
+ /**
398
+ * An event listener which is defined by `RenderObjects`. It performs
399
+ * clean up tasks when `dispose()` on this render object.
400
+ diff --git a/src/renderers/common/RenderObjects.js b/src/renderers/common/RenderObjects.js
401
+ index 676cc2bd4169427ed420f2467b1e6684bd2aeebc..0fa661db793548254a15ff43f39207abcc43ef49 100644
402
+ --- a/src/renderers/common/RenderObjects.js
403
+ +++ b/src/renderers/common/RenderObjects.js
404
+ @@ -124,9 +124,18 @@ class RenderObjects {
405
+
406
+ }
407
+
408
+ - if ( renderObject.version !== material.version || renderObject.needsUpdate ) {
409
+ + // When the renderer is drawing through an override material, that material is shared by
410
+ + // the whole pass and mutated per object, so its `version` alone answers the wrong
411
+ + // question. The source material this object actually carries answers the right one.
412
+
413
+ - if ( renderObject.initialCacheKey !== renderObject.getCacheKey() ) {
414
+ + const sourceMaterial = this.renderer._currentSourceMaterial;
415
+ + const sourceTracked = sourceMaterial !== null && sourceMaterial !== undefined;
416
+ + const sourceReplaced = sourceTracked && renderObject._sourceMaterial !== sourceMaterial;
417
+ + const sourceChanged = sourceTracked && ( sourceReplaced || renderObject.sourceVersion !== sourceMaterial.version );
418
+ +
419
+ + if ( renderObject.version !== material.version || sourceChanged || renderObject.needsUpdate ) {
420
+ +
421
+ + if ( sourceReplaced || renderObject.initialCacheKey !== renderObject.getCacheKey() ) {
422
+
423
+ renderObject.dispose();
424
+
425
+ @@ -136,6 +145,8 @@ class RenderObjects {
426
+
427
+ renderObject.version = material.version;
428
+
429
+ + if ( sourceTracked ) renderObject.sourceVersion = sourceMaterial.version;
430
+ +
431
+ }
432
+
433
+ }
434
+ diff --git a/src/renderers/common/Renderer.js b/src/renderers/common/Renderer.js
435
+ index 8dfc2ae055ad7b9d4c00e91f7d52a39e747caebe..e9d27b3ddad3b1f080a717d1f6683b60afd2b259 100644
436
+ --- a/src/renderers/common/Renderer.js
437
+ +++ b/src/renderers/common/Renderer.js
438
+ @@ -3550,6 +3550,7 @@ class Renderer {
439
+ let materialDisplacementMap;
440
+ let materialDisplacementScale;
441
+ let materialDisplacementBias;
442
+ + let materialAlphaTest;
443
+
444
+ const previousSourceMaterial = this._currentSourceMaterial;
445
+
446
+ @@ -3575,6 +3576,7 @@ class Renderer {
447
+ materialDisplacementMap = overrideMaterial.displacementMap;
448
+ materialDisplacementScale = overrideMaterial.displacementScale;
449
+ materialDisplacementBias = overrideMaterial.displacementBias;
450
+ + materialAlphaTest = overrideMaterial.alphaTest;
451
+
452
+ if ( material.positionNode && material.positionNode.isNode ) {
453
+
454
+ @@ -3582,7 +3584,15 @@ class Renderer {
455
+
456
+ }
457
+
458
+ - overrideMaterial.alphaTest = material.alphaTest;
459
+ + // `Material.alphaTest`'s setter bumps `version` whenever alpha-test-ness flips, and this
460
+ + // override material is shared by every caster in the pass. A scene that mixes alpha-tested
461
+ + // casters with opaque ones therefore moves that shared version several times per frame,
462
+ + // and every OTHER render object drawn with it then fails the version gate in
463
+ + // `RenderObjects.get` and recomputes a full material cache key that always matches.
464
+ + // Writing the backing field leaves the `alphaTest` getter — and so the cache key — still
465
+ + // reporting this caster's value, while each render object tracks the staleness signal
466
+ + // that belongs to it: its own source material's version.
467
+ + overrideMaterial._alphaTest = material.alphaTest;
468
+ overrideMaterial.alphaMap = material.alphaMap;
469
+ overrideMaterial.displacementMap = material.displacementMap;
470
+ overrideMaterial.displacementScale = material.displacementScale;
471
+ @@ -3644,6 +3654,7 @@ class Renderer {
472
+ scene.overrideMaterial.displacementMap = materialDisplacementMap;
473
+ scene.overrideMaterial.displacementScale = materialDisplacementScale;
474
+ scene.overrideMaterial.displacementBias = materialDisplacementBias;
475
+ + scene.overrideMaterial._alphaTest = materialAlphaTest;
476
+
477
+ }
478
+
258
479
  diff --git a/src/renderers/webgpu/WebGPUBackend.js b/src/renderers/webgpu/WebGPUBackend.js
259
- index 06e20369..37b5e0be 100644
480
+ index 06e203693ed9b168a2bddf773cd8ce8dc23196e4..37b5e0be09967e8acbd38e570b71eb201fc9bad7 100644
260
481
  --- a/src/renderers/webgpu/WebGPUBackend.js
261
482
  +++ b/src/renderers/webgpu/WebGPUBackend.js
262
483
  @@ -102,6 +102,14 @@ class WebGPUBackend extends Backend {
@@ -285,3 +506,17 @@ index 06e20369..37b5e0be 100644
285
506
 
286
507
  if ( adapter === null ) {
287
508
 
509
+ diff --git a/src/renderers/webgpu/nodes/WGSLNodeBuilder.js b/src/renderers/webgpu/nodes/WGSLNodeBuilder.js
510
+ index be07536301cd47ef2544e4a54f6abe17407f52af..6144b98ddeb5d53c5cf280bb51401385a4427547 100644
511
+ --- a/src/renderers/webgpu/nodes/WGSLNodeBuilder.js
512
+ +++ b/src/renderers/webgpu/nodes/WGSLNodeBuilder.js
513
+ @@ -1323,7 +1323,8 @@ class WGSLNodeBuilder extends NodeBuilder {
514
+
515
+ uniformGPU = buffer;
516
+
517
+ - uniformNode.name = name ? name : 'NodeBuffer_' + uniformNode.id;
518
+ + // The base builder supplies a unique name within this program. A process-wide
519
+ + // allocation id changes otherwise identical shader source for every buffer.
520
+
521
+ } else {
522
+