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/dist/index.d.ts CHANGED
@@ -1,18 +1,20 @@
1
1
  #!/usr/bin/env node
2
- import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, ThreeNativeUiRenderer, IThreeNativeTexturesConfig } from '@threenative/core';
2
+ import { IThreeNativeIconVariants, ThreeNativeOrientation, IThreeNativeBootSplash, ThreeNativeUiRenderer, IThreeNativeAudioConfig, IThreeNativeConfig, IThreeNativeTexturesConfig } from '@threenative/core';
3
3
 
4
4
  interface IEngineFreshnessVitePlugin {
5
5
  readonly name: string;
6
- readonly apply: "serve";
7
6
  config(config: {
8
7
  readonly root?: string;
9
8
  }, env: {
10
9
  readonly command: string;
11
10
  }): {
12
- optimizeDeps: {
11
+ resolve: {
12
+ dedupe: string[];
13
+ };
14
+ optimizeDeps?: {
13
15
  force: boolean;
14
16
  };
15
- } | undefined;
17
+ };
16
18
  configureServer(server: {
17
19
  readonly config: {
18
20
  readonly root?: string;
@@ -48,6 +50,8 @@ interface IResolvedThreeNativeConfig {
48
50
  readonly title: string;
49
51
  readonly width: number;
50
52
  readonly height: number;
53
+ /** Start maximized on desktop; ignored when `display.fullscreen` is true. */
54
+ readonly maximized: boolean;
51
55
  readonly resizable: boolean;
52
56
  };
53
57
  readonly bootSplash?: IThreeNativeBootSplash;
@@ -56,15 +60,23 @@ interface IResolvedThreeNativeConfig {
56
60
  readonly preferWebGPU: boolean;
57
61
  readonly resolutionScale?: number | "auto";
58
62
  readonly antialias?: boolean;
63
+ readonly alphaAntialiasing?: boolean;
59
64
  readonly android?: {
60
65
  readonly resolutionScale?: number | "auto";
61
66
  readonly antialias?: boolean;
67
+ readonly alphaAntialiasing?: boolean;
62
68
  };
63
69
  };
64
70
  readonly ui: {
65
71
  readonly renderer: ThreeNativeUiRenderer;
66
72
  };
67
73
  readonly assets?: {
74
+ /** Audio conditioning options, or `"none"` to ship every clip exactly as committed. */
75
+ readonly audio?: "none" | IThreeNativeAudioConfig;
76
+ readonly budget?: NonNullable<IThreeNativeConfig["assets"]>["budget"];
77
+ readonly exclude?: readonly string[];
78
+ /** The bound on how many workers a bake may use; absent means the driver's default. */
79
+ readonly concurrency?: number;
68
80
  readonly models?: "none" | IThreeNativeModelsConfig;
69
81
  readonly output?: string;
70
82
  readonly source?: string;
@@ -170,6 +182,7 @@ declare const PACKAGE_SOURCE_FLAGS: {
170
182
  readonly "@threenative/playtest": "--playtest-package";
171
183
  readonly "@threenative/runtime-native": "--runtime-native-package";
172
184
  readonly "@threenative/ui": "--ui-package";
185
+ readonly "threenative-blender-mcp": "--blender-mcp-package";
173
186
  readonly "threenative-engine-mcp": "--engine-mcp-package";
174
187
  readonly "create-threenative": "--cli-package";
175
188
  };
@@ -196,11 +209,28 @@ interface IScaffoldResult {
196
209
  template: ScaffoldTemplate;
197
210
  }
198
211
  declare function templateRoot(): string;
199
- declare const FULL_LOADING_TEMPLATES: readonly ["action-rpg", "defense", "platformer", "racing", "sailing", "shooter", "starter"];
212
+ /**
213
+ * Every kit whose loading screen is stamped from the canonical source, read off disk rather than
214
+ * listed here. A kit added tomorrow is stamped the day it ships its appearance block, and one that
215
+ * drops the block leaves the list by deleting bytes rather than by editing this file.
216
+ */
217
+ declare function discoverStampedTemplates(root?: string): readonly ScaffoldTemplate[];
200
218
  /** The canonical generated loading implementation ships beside, rather than inside, a kit. */
201
219
  declare function canonicalLoadingPath(root?: string): string;
202
220
  /** Replaces only the declared per-kit appearance block and preserves the canonical implementation. */
203
221
  declare function stampLoadingSource(canonical: string, template: string): string;
222
+ /**
223
+ * Render sources every kit copies verbatim and no kit is expected to edit.
224
+ *
225
+ * `src/render/` is a floor the game rewrites, and almost all of it is a per-kit look. The
226
+ * render-chain plumbing is not: it is the same 600 lines in every kit, and keeping seven copies by
227
+ * hand let one fall a revision behind without anything failing. A file belongs here only when a
228
+ * kit editing it would be a mistake rather than a choice.
229
+ */
230
+ declare const SHARED_RENDER_SOURCES: readonly [string];
231
+ declare function canonicalRenderSourcePath(relativePath: string, root?: string): string;
232
+ /** Re-copies every shared render source into each kit that ships it. */
233
+ declare function restampSharedRenderCopies(root?: string): Promise<readonly string[]>;
204
234
  /** Re-stamps every tracked full kit from the canonical source, preserving each kit's appearance. */
205
235
  declare function restampTemplateLoadingCopies(root?: string): Promise<readonly string[]>;
206
236
  /** Reads every template directory on each call so a new kit is live without a TypeScript edit. */
@@ -213,6 +243,9 @@ declare function templateForGenre(genre: string, root?: string): ScaffoldTemplat
213
243
  declare function scaffoldCompletionMessage(manifests: readonly IKitManifest[], defaultTemplate?: string): string;
214
244
  declare function cliHelp(): string;
215
245
  declare function createProject(options: IScaffoldOptions, cwd?: string, root?: string): Promise<IScaffoldResult>;
246
+ /** The inverse of `scripts/workspace-packages.ts`'s `workspacePackageSourceFlag`; exported so
247
+ * the pair is gated rather than trusted. */
248
+ declare function packageNameFromFlag(flag: string): string | undefined;
216
249
  declare function parseArgs(argv: readonly string[]): IScaffoldOptions;
217
250
 
218
- export { FULL_LOADING_TEMPLATES, type IKitManifest, type IScaffoldOptions, type IScaffoldResult, type ScaffoldTemplate, canonicalLoadingPath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverTemplateNames, hashEngineDist, kitManifest, parseArgs, renderWebManifest, restampTemplateLoadingCopies, scaffoldCompletionMessage, stampLoadingSource, templateForGenre, templateRoot };
251
+ export { type IKitManifest, type IScaffoldOptions, type IScaffoldResult, SHARED_RENDER_SOURCES, type ScaffoldTemplate, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, stampLoadingSource, templateForGenre, templateRoot };
package/dist/index.js CHANGED
@@ -8,11 +8,12 @@ import { fileURLToPath, pathToFileURL } from 'url';
8
8
  import { LoadingManager, Box3, Vector3 } from 'three';
9
9
  import { createHash } from 'crypto';
10
10
  import { createRequire as createRequire$1 } from 'module';
11
- import { parsePng } from '@threenative/assets';
11
+ import { parsePng, parseAudioConfig } from '@threenative/assets';
12
12
 
13
13
  createRequire(import.meta.url);
14
14
  var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".glb", ".gltf"]);
15
- var CENTIMETRE_HEURISTIC_THRESHOLD = 10;
15
+ var METRE_UPPER_BOUND = 10;
16
+ var CENTIMETRE_LOWER_BOUND = 100;
16
17
  var RESOURCE_MIME_TYPES = {
17
18
  ".avif": "image/avif",
18
19
  ".gif": "image/gif",
@@ -205,11 +206,16 @@ function inspectScene(file, scene, animations, resourceCounts) {
205
206
  path: path5.resolve(file),
206
207
  textures: resourceCounts.textures ?? resources.textures,
207
208
  units: {
208
- label: largest !== void 0 && largest.value > CENTIMETRE_HEURISTIC_THRESHOLD ? "likely centimetres" : "likely metres",
209
+ label: unitsLabel(largest?.value ?? 0),
209
210
  longestAxis: largest?.value ?? 0
210
211
  }
211
212
  };
212
213
  }
214
+ function unitsLabel(longestAxis2) {
215
+ if (longestAxis2 <= METRE_UPPER_BOUND) return "likely metres";
216
+ if (longestAxis2 >= CENTIMETRE_LOWER_BOUND) return "likely centimetres";
217
+ return "ambiguous";
218
+ }
213
219
  function inspectionFailure(file, error) {
214
220
  const detail = error instanceof Error ? error.message : String(error);
215
221
  return new Error(`TN_ASSET_INSPECT_FAILED: ${file}: ${detail}`);
@@ -282,6 +288,109 @@ async function inspectCommand(argv, write = (text) => process.stdout.write(text)
282
288
  ` : formatAssetInspection(result));
283
289
  return result;
284
290
  }
291
+
292
+ // ../core/mcp/servers.mjs
293
+ var MCP_SERVERS = Object.freeze({
294
+ "threenative-assets": Object.freeze({
295
+ command: "node",
296
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/assets.mjs"]),
297
+ // Entries rather than an object literal: these are environment variable names, not identifiers,
298
+ // and written as property names they read as names the naming rule must judge.
299
+ env: Object.freeze(
300
+ Object.fromEntries([
301
+ ["ASSET_DOWNLOAD_DIR", "./public/assets"],
302
+ ["AUDIO_DOWNLOAD_DIR", "./public/audio"]
303
+ ])
304
+ )
305
+ }),
306
+ "threenative-sculpt": Object.freeze({
307
+ command: "node",
308
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/sculpt.mjs"])
309
+ }),
310
+ "threenative-engine": Object.freeze({
311
+ command: "node",
312
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/engine.mjs"])
313
+ }),
314
+ // Drives an installed Blender headlessly so a downloaded .fbx becomes a GLB. It ships no
315
+ // Blender and probes for one only when a tool is called, so a project that never converts a
316
+ // model pays nothing for having this server wired.
317
+ "threenative-blender": Object.freeze({
318
+ command: "node",
319
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/blender.mjs"])
320
+ })
321
+ });
322
+ var SERVER_FORMATS = Object.freeze({
323
+ // Claude Code (`.mcp.json`), Cursor and the Gemini CLI all read this one.
324
+ mcpServers: Object.freeze({
325
+ key: "mcpServers",
326
+ entry: (server) => ({
327
+ command: server.command,
328
+ args: [...server.args],
329
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
330
+ })
331
+ }),
332
+ // VS Code names the table `servers` and requires an explicit transport per server.
333
+ vscode: Object.freeze({
334
+ key: "servers",
335
+ entry: (server) => ({
336
+ type: "stdio",
337
+ command: server.command,
338
+ args: [...server.args],
339
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
340
+ })
341
+ }),
342
+ // opencode folds the command and its arguments into one array and spells the environment
343
+ // `environment`. A server it does not mark enabled is written down and never started.
344
+ opencode: Object.freeze({
345
+ key: "mcp",
346
+ entry: (server) => ({
347
+ type: "local",
348
+ command: [server.command, ...server.args],
349
+ enabled: true,
350
+ ...server.env === void 0 ? {} : { environment: { ...server.env } }
351
+ })
352
+ }),
353
+ // Zed calls them context servers and needs `source: "custom"` to accept a command of our own.
354
+ zed: Object.freeze({
355
+ key: "context_servers",
356
+ entry: (server) => ({
357
+ source: "custom",
358
+ command: server.command,
359
+ args: [...server.args],
360
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
361
+ })
362
+ })
363
+ });
364
+ Object.freeze(Object.keys(SERVER_FORMATS));
365
+ function codexServerBlock(name, server) {
366
+ const args = server.args.map((argument) => JSON.stringify(argument)).join(", ");
367
+ const lines = [
368
+ `[mcp_servers.${name}]`,
369
+ `command = ${JSON.stringify(server.command)}`,
370
+ `args = [${args}]`
371
+ ];
372
+ if (server.env !== void 0) {
373
+ lines.push("", `[mcp_servers.${name}.env]`);
374
+ for (const [key, value] of Object.entries(server.env)) {
375
+ lines.push(`${key} = ${JSON.stringify(value)}`);
376
+ }
377
+ }
378
+ return lines.join("\n");
379
+ }
380
+ Object.freeze(
381
+ Object.entries(MCP_SERVERS).map(
382
+ ([name, server]) => Object.freeze({ body: codexServerBlock(name, server), name })
383
+ )
384
+ );
385
+
386
+ // src/mcp-servers.ts
387
+ function serverEntryPath(server) {
388
+ const entry = server.args[0];
389
+ if (entry === void 0) {
390
+ throw new Error("TN_MCP_TABLE: an MCP server entry declares no shim to launch.");
391
+ }
392
+ return entry;
393
+ }
285
394
  var MARKER_RELATIVE = path5.join("node_modules", ".vite", "threenative-engine-build.json");
286
395
  function hashTree(hash, directory) {
287
396
  const entries = readdirSync(directory, { withFileTypes: true }).sort(
@@ -348,13 +457,14 @@ function createEngineFreshnessPlugin() {
348
457
  const rootOf = (config) => path5.resolve(config.root ?? process.cwd());
349
458
  return {
350
459
  name: "threenative-engine-freshness",
351
- apply: "serve",
352
- config(config) {
460
+ config(config, env) {
461
+ const resolve = { dedupe: ["three", "react", "react-dom"] };
462
+ if (env.command !== "serve") return { resolve };
353
463
  const root = rootOf(config);
354
464
  recordedHash = hashEngineDist(root);
355
465
  const marker = recordedHash === void 0 ? void 0 : readMarker(markerPath(root));
356
466
  if (recordedHash === void 0 || marker === void 0 || marker.hash === recordedHash) {
357
- return void 0;
467
+ return { resolve };
358
468
  }
359
469
  if (processIsAlive(marker.pid)) {
360
470
  const where = marker.port === void 0 ? `pid ${marker.pid}` : `pid ${marker.pid} on port ${marker.port}`;
@@ -363,7 +473,7 @@ function createEngineFreshnessPlugin() {
363
473
  `threenative: a dev server is still running at ${where}, serving engine build ${marker.hash.slice(0, 8)}; the installed build is ${recordedHash.slice(0, 8)}. Kill it before playing${how} \u2014 its tab renders yesterday's engine.`
364
474
  );
365
475
  }
366
- return { optimizeDeps: { force: true } };
476
+ return { resolve, optimizeDeps: { force: true } };
367
477
  },
368
478
  configureServer(server) {
369
479
  const root = rootOf(server.config);
@@ -912,11 +1022,17 @@ function validateDisplay(raw) {
912
1022
  }
913
1023
  function validateWindow(raw, appName) {
914
1024
  const window = assertRecord(raw, "window");
915
- assertKeys(window, "window", ["title", "width", "height", "resizable"]);
1025
+ assertKeys(window, "window", ["title", "width", "height", "maximized", "resizable"]);
916
1026
  return {
917
1027
  title: window.title === void 0 ? appName : nonEmptyString(window.title, "TN_CONFIG_WINDOW_TITLE_INVALID", "window.title"),
918
1028
  width: positiveInteger(window.width, 1280, "TN_CONFIG_WINDOW_WIDTH_INVALID", "window.width"),
919
1029
  height: positiveInteger(window.height, 720, "TN_CONFIG_WINDOW_HEIGHT_INVALID", "window.height"),
1030
+ maximized: booleanValue(
1031
+ window.maximized,
1032
+ false,
1033
+ "TN_CONFIG_WINDOW_MAXIMIZED_INVALID",
1034
+ "window.maximized"
1035
+ ),
920
1036
  resizable: booleanValue(
921
1037
  window.resizable,
922
1038
  true,
@@ -951,9 +1067,15 @@ function validateUi(raw) {
951
1067
  }
952
1068
  function validateRenderer(raw) {
953
1069
  const renderer = assertRecord(raw, "renderer");
954
- assertKeys(renderer, "renderer", ["preferWebGPU", "resolutionScale", "antialias", "android"]);
1070
+ assertKeys(renderer, "renderer", [
1071
+ "preferWebGPU",
1072
+ "resolutionScale",
1073
+ "antialias",
1074
+ "alphaAntialiasing",
1075
+ "android"
1076
+ ]);
955
1077
  const android = assertRecord(renderer.android, "renderer.android");
956
- assertKeys(android, "renderer.android", ["resolutionScale", "antialias"]);
1078
+ assertKeys(android, "renderer.android", ["resolutionScale", "antialias", "alphaAntialiasing"]);
957
1079
  const resolutionScale = renderer.resolutionScale;
958
1080
  const androidResolutionScale = android.resolutionScale;
959
1081
  for (const [name, value] of [
@@ -970,9 +1092,18 @@ function validateRenderer(raw) {
970
1092
  }
971
1093
  const antialias = booleanOrUndefined(renderer.antialias, "renderer.antialias");
972
1094
  const androidAntialias = booleanOrUndefined(android.antialias, "renderer.android.antialias");
1095
+ const alphaAntialiasing = booleanOrUndefined(
1096
+ renderer.alphaAntialiasing,
1097
+ "renderer.alphaAntialiasing"
1098
+ );
1099
+ const androidAlphaAntialiasing = booleanOrUndefined(
1100
+ android.alphaAntialiasing,
1101
+ "renderer.android.alphaAntialiasing"
1102
+ );
973
1103
  const androidOverrides = {
974
1104
  ...androidResolutionScale === void 0 ? {} : { resolutionScale: androidResolutionScale },
975
- ...androidAntialias === void 0 ? {} : { antialias: androidAntialias }
1105
+ ...androidAntialias === void 0 ? {} : { antialias: androidAntialias },
1106
+ ...androidAlphaAntialiasing === void 0 ? {} : { alphaAntialiasing: androidAlphaAntialiasing }
976
1107
  };
977
1108
  return {
978
1109
  preferWebGPU: booleanValue(
@@ -982,6 +1113,7 @@ function validateRenderer(raw) {
982
1113
  "renderer.preferWebGPU"
983
1114
  ),
984
1115
  ...antialias === void 0 ? {} : { antialias },
1116
+ ...alphaAntialiasing === void 0 ? {} : { alphaAntialiasing },
985
1117
  ...resolutionScale === void 0 ? {} : { resolutionScale },
986
1118
  ...Object.keys(androidOverrides).length === 0 ? {} : { android: androidOverrides }
987
1119
  };
@@ -1026,7 +1158,7 @@ function validateAssetTargets(raw) {
1026
1158
  }
1027
1159
  };
1028
1160
  }
1029
- var ASSET_TEXTURE_KEYS = ["overrides", "quality"];
1161
+ var ASSET_TEXTURE_KEYS = ["maxSize", "overrides", "quality"];
1030
1162
  var TEXTURE_OVERRIDE_KEYS = ["codec", "glob", "quality"];
1031
1163
  var TEXTURE_CODECS = ["etc1s", "none", "uastc"];
1032
1164
  function textureQuality(value, label) {
@@ -1035,6 +1167,15 @@ function textureQuality(value, label) {
1035
1167
  }
1036
1168
  return value;
1037
1169
  }
1170
+ function textureMaxSize(value) {
1171
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 4) {
1172
+ fail(
1173
+ "TN_CONFIG_ASSETS_INVALID",
1174
+ "assets.textures.maxSize must be a positive integer of at least 4."
1175
+ );
1176
+ }
1177
+ return value;
1178
+ }
1038
1179
  function validateTextureOverrides(raw) {
1039
1180
  if (!Array.isArray(raw)) {
1040
1181
  fail("TN_CONFIG_ASSETS_INVALID", "assets.textures.overrides must be an array.");
@@ -1075,6 +1216,7 @@ function validateTextures(raw) {
1075
1216
  const textures = assertRecord(raw, "assets.textures");
1076
1217
  assertKeys(textures, "assets.textures", ASSET_TEXTURE_KEYS);
1077
1218
  return {
1219
+ ...textures.maxSize === void 0 ? {} : { maxSize: textureMaxSize(textures.maxSize) },
1078
1220
  ...textures.quality === void 0 ? {} : { quality: textureQuality(textures.quality, "assets.textures.quality") },
1079
1221
  ...textures.overrides === void 0 ? {} : { overrides: validateTextureOverrides(textures.overrides) }
1080
1222
  };
@@ -1101,10 +1243,15 @@ function validateModels(raw) {
1101
1243
  "lightmap",
1102
1244
  "passes",
1103
1245
  "quantize",
1246
+ "sharedImages",
1104
1247
  "simplify",
1105
1248
  "textures",
1106
1249
  "virtual"
1107
1250
  ]);
1251
+ if (models.sharedImages !== void 0 && typeof models.sharedImages !== "boolean") {
1252
+ fail("TN_CONFIG_ASSETS_INVALID", "assets.models.sharedImages must be true or false.");
1253
+ }
1254
+ const sharedImages = models.sharedImages;
1108
1255
  let lightmap;
1109
1256
  if (models.lightmap !== void 0) {
1110
1257
  const rawLightmap = assertRecord(models.lightmap, "assets.models.lightmap");
@@ -1188,18 +1335,67 @@ function validateModels(raw) {
1188
1335
  ...lightmap === void 0 ? {} : { lightmap },
1189
1336
  ...passes === void 0 || Object.keys(passes).length === 0 ? {} : { passes },
1190
1337
  ...quantize === void 0 || Object.keys(quantize).length === 0 ? {} : { quantize },
1338
+ ...sharedImages === void 0 ? {} : { sharedImages },
1191
1339
  ...simplify === void 0 ? {} : { simplify },
1192
1340
  ...textures === void 0 ? {} : { textures },
1193
1341
  ...virtual === void 0 ? {} : { virtual }
1194
1342
  };
1195
1343
  }
1344
+ function validateBudget(raw) {
1345
+ const limit = (value) => value === "none" || typeof value === "number" && Number.isSafeInteger(value) && value > 0;
1346
+ if (limit(raw)) return raw;
1347
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw) || Object.entries(raw).some(
1348
+ ([key, value]) => !["uncooked", "total"].includes(key) || !limit(value)
1349
+ )) {
1350
+ fail(
1351
+ "TN_CONFIG_ASSETS_INVALID",
1352
+ 'assets.budget must contain positive integer byte limits or "none" for uncooked and total.'
1353
+ );
1354
+ }
1355
+ return raw;
1356
+ }
1357
+ function validateAudio(raw) {
1358
+ try {
1359
+ parseAudioConfig(raw);
1360
+ } catch (error) {
1361
+ fail("TN_CONFIG_ASSETS_INVALID", error instanceof Error ? error.message : String(error));
1362
+ }
1363
+ return raw;
1364
+ }
1196
1365
  function validateAssets(raw) {
1197
1366
  const assets = assertRecord(raw, "assets");
1198
- assertKeys(assets, "assets", ["models", "source", "output", "targets", "textures"]);
1367
+ assertKeys(assets, "assets", [
1368
+ "audio",
1369
+ "budget",
1370
+ "exclude",
1371
+ "concurrency",
1372
+ "models",
1373
+ "source",
1374
+ "output",
1375
+ "targets",
1376
+ "textures"
1377
+ ]);
1199
1378
  const targets = assets.targets === void 0 ? void 0 : validateAssetTargets(assets.targets);
1200
1379
  const models = assets.models === void 0 ? void 0 : validateModels(assets.models);
1201
1380
  const textures = assets.textures === void 0 ? void 0 : validateTextures(assets.textures);
1381
+ if (assets.exclude !== void 0 && (!Array.isArray(assets.exclude) || assets.exclude.some((glob) => typeof glob !== "string" || glob.trim() === ""))) {
1382
+ fail("TN_CONFIG_ASSETS_INVALID", "assets.exclude must be an array of non-empty glob strings.");
1383
+ }
1202
1384
  return {
1385
+ ...assets.audio === void 0 ? {} : { audio: validateAudio(assets.audio) },
1386
+ ...assets.exclude === void 0 ? {} : { exclude: assets.exclude },
1387
+ ...assets.budget === void 0 ? {} : { budget: validateBudget(assets.budget) },
1388
+ // The worker bound a bake may use. Validated here so a malformed value fails at config
1389
+ // load with the named code, and handed to the driver unchanged, which re-checks it —
1390
+ // the producer→consumer seam the config spec proves by running the pipeline.
1391
+ ...assets.concurrency === void 0 ? {} : {
1392
+ concurrency: positiveInteger(
1393
+ assets.concurrency,
1394
+ 1,
1395
+ "TN_CONFIG_ASSETS_INVALID",
1396
+ "assets.concurrency"
1397
+ )
1398
+ },
1203
1399
  ...assets.source === void 0 ? {} : { source: nonEmptyString(assets.source, "TN_CONFIG_ASSETS_INVALID", "assets.source") },
1204
1400
  ...assets.output === void 0 ? {} : { output: nonEmptyString(assets.output, "TN_CONFIG_ASSETS_INVALID", "assets.output") },
1205
1401
  ...targets === void 0 ? {} : { targets },
@@ -1382,9 +1578,15 @@ var PACKAGE_SOURCE_FLAGS = {
1382
1578
  "@threenative/playtest": "--playtest-package",
1383
1579
  "@threenative/runtime-native": "--runtime-native-package",
1384
1580
  "@threenative/ui": "--ui-package",
1581
+ "threenative-blender-mcp": "--blender-mcp-package",
1385
1582
  "threenative-engine-mcp": "--engine-mcp-package",
1386
1583
  "create-threenative": "--cli-package"
1387
1584
  };
1585
+ var UNSCOPED_PACKAGE_FLAG_ALIASES = {
1586
+ "blender-mcp": "threenative-blender-mcp",
1587
+ cli: "create-threenative",
1588
+ "engine-mcp": "threenative-engine-mcp"
1589
+ };
1388
1590
  var TEXT_FILE_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".html", ".json", ".md", ".svg", ".ts", ".tsx"]);
1389
1591
  var TEMPLATE_NAME = /^[a-z][a-z0-9-]*$/u;
1390
1592
  var SHARED_AGENT_MARKER_LINE = /^<!--\s*(?:shared:\s*[^>]+|\/shared)\s*-->\r?\n?/gmu;
@@ -1393,16 +1595,15 @@ function templateRoot() {
1393
1595
  return path5.resolve(path5.dirname(fileURLToPath(import.meta.url)), "../templates");
1394
1596
  }
1395
1597
  var LOADING_SOURCE_RELATIVE_PATH = path5.join("src", "render", "loading.ts");
1598
+ var LOADING_APPEARANCE_MARKER = "BEGIN THREENATIVE LOADING APPEARANCE";
1599
+ var TEMPLATE_ICON_NAME = "icon.png";
1396
1600
  var LOADING_APPEARANCE_BLOCK_PATTERN = /\/\* BEGIN THREENATIVE LOADING APPEARANCE \*\/[\s\S]*?\/\* END THREENATIVE LOADING APPEARANCE \*\//gu;
1397
- var FULL_LOADING_TEMPLATES = [
1398
- "action-rpg",
1399
- "defense",
1400
- "platformer",
1401
- "racing",
1402
- "sailing",
1403
- "shooter",
1404
- "starter"
1405
- ];
1601
+ function discoverStampedTemplates(root = templateRoot()) {
1602
+ return readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort((left, right) => left.localeCompare(right)).filter((template) => {
1603
+ const file = path5.join(root, template, LOADING_SOURCE_RELATIVE_PATH);
1604
+ return existsSync(file) && readFileSync(file, "utf8").includes(LOADING_APPEARANCE_MARKER);
1605
+ });
1606
+ }
1406
1607
  function canonicalLoadingPath(root = templateRoot()) {
1407
1608
  const local = path5.resolve(root, "..", "template-assets", "loading.ts");
1408
1609
  if (existsSync(local)) return local;
@@ -1422,10 +1623,30 @@ function stampLoadingSource(canonical, template) {
1422
1623
  const templateBlock = loadingAppearanceBlock(template, "template loading source");
1423
1624
  return canonical.replace(canonicalBlock, templateBlock);
1424
1625
  }
1626
+ var SHARED_RENDER_SOURCES = [path5.join("src", "render", "worldEnvironment.ts")];
1627
+ function canonicalRenderSourcePath(relativePath, root = templateRoot()) {
1628
+ const name = path5.basename(relativePath);
1629
+ const local = path5.resolve(root, "..", "template-assets", name);
1630
+ if (existsSync(local)) return local;
1631
+ return path5.resolve(templateRoot(), "..", "template-assets", name);
1632
+ }
1633
+ async function restampSharedRenderCopies(root = templateRoot()) {
1634
+ const stamped = [];
1635
+ for (const relativePath of SHARED_RENDER_SOURCES) {
1636
+ const canonical = await readFile(canonicalRenderSourcePath(relativePath, root), "utf8");
1637
+ for (const template of readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort((left, right) => left.localeCompare(right))) {
1638
+ const file = path5.join(root, template, relativePath);
1639
+ if (!existsSync(file)) continue;
1640
+ await writeFile(file, canonical);
1641
+ stamped.push(file);
1642
+ }
1643
+ }
1644
+ return stamped;
1645
+ }
1425
1646
  async function restampTemplateLoadingCopies(root = templateRoot()) {
1426
1647
  const canonical = await readFile(canonicalLoadingPath(root), "utf8");
1427
1648
  const stamped = [];
1428
- for (const template of FULL_LOADING_TEMPLATES) {
1649
+ for (const template of discoverStampedTemplates(root)) {
1429
1650
  const file = path5.join(root, template, LOADING_SOURCE_RELATIVE_PATH);
1430
1651
  const source = await readFile(file, "utf8");
1431
1652
  await writeFile(file, stampLoadingSource(canonical, source));
@@ -1444,6 +1665,21 @@ async function stampTemplateLoading(target, template, root) {
1444
1665
  stampLoadingSource(canonical, source)
1445
1666
  );
1446
1667
  }
1668
+ async function copyTemplateIcon(target, templateRootDirectory) {
1669
+ const source = path5.join(
1670
+ path5.dirname(templateRootDirectory),
1671
+ "template-assets",
1672
+ TEMPLATE_ICON_NAME
1673
+ );
1674
+ if (!existsSync(source)) {
1675
+ throw new Error(
1676
+ `TN_TEMPLATE_ICON_MISSING: '${source}' is not in the package; every generated project needs the native icon asset.`
1677
+ );
1678
+ }
1679
+ const destination = path5.join(target, "public", TEMPLATE_ICON_NAME);
1680
+ await mkdir(path5.dirname(destination), { recursive: true });
1681
+ await cp(source, destination, { errorOnExist: true, force: false });
1682
+ }
1447
1683
  function invalidManifest(file, reason) {
1448
1684
  throw new Error(`TN_KIT_MANIFEST_INVALID: ${file}: ${reason}`);
1449
1685
  }
@@ -1576,6 +1812,14 @@ async function renderTemplate(directory, replacements) {
1576
1812
  var REFERENCE_BUNDLE_DIRECTORY = "agent-docs";
1577
1813
  var REFERENCE_FILE_NAME = /^[a-z0-9][a-z0-9-]*\.md$/u;
1578
1814
  var AGENT_FILES_DIRECTORY = "agent-files";
1815
+ var AUTHORING_GITIGNORE_RULES = [
1816
+ "# ThreeNative local authoring state and dependency secrets",
1817
+ ".dream-loop/",
1818
+ "node_modules/",
1819
+ ".env",
1820
+ ".env.*",
1821
+ "!.env.example"
1822
+ ];
1579
1823
  var REFERENCE_TOKEN_PATTERN = /`agent-docs\/([a-z0-9][a-z0-9./-]*\.md)`|\[[^\]]*\]\(agent-docs\/([^)#]+\.md)\)/gu;
1580
1824
  async function copyReferenceBundle(target, templateRootDirectory, replacements) {
1581
1825
  const bundle = path5.join(
@@ -1608,8 +1852,29 @@ async function copyAgentFiles(target, templateRootDirectory) {
1608
1852
  }
1609
1853
  await cp(source, target, { recursive: true });
1610
1854
  }
1855
+ async function installAuthoringGitignore(target) {
1856
+ const file = path5.join(target, ".gitignore");
1857
+ const existing = existsSync(file) ? await readFile(file, "utf8") : "";
1858
+ const present = new Set(existing.split(/\r?\n/u));
1859
+ const missing = AUTHORING_GITIGNORE_RULES.filter((entry) => !present.has(entry));
1860
+ if (missing.length === 0) return;
1861
+ const prefix = existing.length === 0 || existing.endsWith("\n") ? existing : `${existing}
1862
+ `;
1863
+ await writeFile(
1864
+ file,
1865
+ `${prefix}${prefix.length > 0 && !prefix.endsWith("\n\n") ? "\n" : ""}${missing.join("\n")}
1866
+ `
1867
+ );
1868
+ }
1611
1869
  async function assertReferenceBundle(target) {
1612
- for (const file of ["AGENTS.md", "CLAUDE.md"]) {
1870
+ for (const file of [
1871
+ "AGENTS.md",
1872
+ "CLAUDE.md",
1873
+ ".agents/skills/threenative-visuals/SKILL.md",
1874
+ ".claude/skills/threenative-visuals/SKILL.md",
1875
+ ".agents/skills/threenative-assets/SKILL.md",
1876
+ ".claude/skills/threenative-assets/SKILL.md"
1877
+ ]) {
1613
1878
  const filePath = path5.join(target, file);
1614
1879
  if (existsSync(filePath)) await assertReferenceTargets(target, file, filePath);
1615
1880
  }
@@ -1688,11 +1953,9 @@ async function copyFrameworkPatches(target, templateRootDirectory) {
1688
1953
  await cp(source, destination);
1689
1954
  }
1690
1955
  var NODE_MODULES_PREFIX = "./node_modules/";
1691
- var REQUIRED_MCP_SERVERS = {
1692
- "threenative-assets": `${NODE_MODULES_PREFIX}@threenative/core/mcp/assets.mjs`,
1693
- "threenative-sculpt": `${NODE_MODULES_PREFIX}@threenative/core/mcp/sculpt.mjs`,
1694
- "threenative-engine": `${NODE_MODULES_PREFIX}@threenative/core/mcp/engine.mjs`
1695
- };
1956
+ var REQUIRED_MCP_SERVERS = Object.fromEntries(
1957
+ Object.entries(MCP_SERVERS).map(([name, server]) => [name, serverEntryPath(server)])
1958
+ );
1696
1959
  function mcpPackageName(entry) {
1697
1960
  const segments = entry.slice(NODE_MODULES_PREFIX.length).split("/");
1698
1961
  return entry.startsWith(`${NODE_MODULES_PREFIX}@`) ? segments.slice(0, 2).join("/") : segments[0] ?? "";
@@ -1777,9 +2040,11 @@ async function createProject(options, cwd = process.cwd(), root = templateRoot()
1777
2040
  await mkdir(target, { recursive: true });
1778
2041
  const source = path5.join(root, template);
1779
2042
  await cp(source, target, { recursive: true, errorOnExist: true });
2043
+ await copyTemplateIcon(target, root);
1780
2044
  if (existsSync(path5.join(target, "gitignore"))) {
1781
2045
  await rename(path5.join(target, "gitignore"), path5.join(target, ".gitignore"));
1782
2046
  }
2047
+ await installAuthoringGitignore(target);
1783
2048
  const projectName = packageName(target);
1784
2049
  const compactProjectId = projectName.toLowerCase().replace(/[^a-z0-9]+/gu, "") || "game";
1785
2050
  const projectId = /^[a-z]/u.test(compactProjectId) ? compactProjectId : `game${compactProjectId}`;
@@ -1812,8 +2077,8 @@ function packageNameFromFlag(flag) {
1812
2077
  return scopedSuffix.length === 0 ? void 0 : `@threenative/${scopedSuffix}`;
1813
2078
  }
1814
2079
  if (suffix === "runtime") return void 0;
1815
- if (suffix === "cli") return "create-threenative";
1816
- if (suffix === "engine-mcp") return "threenative-engine-mcp";
2080
+ const unscoped = UNSCOPED_PACKAGE_FLAG_ALIASES[suffix];
2081
+ if (unscoped !== void 0) return unscoped;
1817
2082
  return `@threenative/${suffix}`;
1818
2083
  }
1819
2084
  var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["--no-install", "--help", "-h"]);
@@ -1915,4 +2180,4 @@ if (entryPath !== void 0 && existsSync(entryPath) && realpathSync(path5.resolve(
1915
2180
  });
1916
2181
  }
1917
2182
 
1918
- export { FULL_LOADING_TEMPLATES, canonicalLoadingPath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverTemplateNames, hashEngineDist, kitManifest, parseArgs, renderWebManifest, restampTemplateLoadingCopies, scaffoldCompletionMessage, stampLoadingSource, templateForGenre, templateRoot };
2183
+ export { SHARED_RENDER_SOURCES, canonicalLoadingPath, canonicalRenderSourcePath, cliHelp, createEngineFreshnessPlugin, createProject, createWebBrandPlugin, discoverKitManifests, discoverStampedTemplates, discoverTemplateNames, hashEngineDist, kitManifest, packageNameFromFlag, parseArgs, renderWebManifest, restampSharedRenderCopies, restampTemplateLoadingCopies, scaffoldCompletionMessage, stampLoadingSource, templateForGenre, templateRoot };