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
@@ -5,10 +5,10 @@ import { randomUUID, createHash } from 'crypto';
5
5
  import { readFile, readdir, stat, mkdir, writeFile, rm, rename, access, unlink } from 'fs/promises';
6
6
  import { createRequire as createRequire$1 } from 'module';
7
7
  import path2 from 'path';
8
- import { compileAssets, parsePng } from '@threenative/assets';
8
+ import { compileAssets, parsePng, parseAudioConfig } from '@threenative/assets';
9
9
  import { pathToFileURL, fileURLToPath } from 'url';
10
10
  import { existsSync, realpathSync, readFileSync, statSync, openSync, readSync, closeSync, accessSync, constants } from 'fs';
11
- import { homedir } from 'os';
11
+ import { platform, homedir } from 'os';
12
12
 
13
13
  createRequire(import.meta.url);
14
14
  var ORIENTATIONS = ["landscape", "portrait", "sensor"];
@@ -526,11 +526,17 @@ function validateDisplay(raw) {
526
526
  }
527
527
  function validateWindow(raw, appName) {
528
528
  const window = assertRecord(raw, "window");
529
- assertKeys(window, "window", ["title", "width", "height", "resizable"]);
529
+ assertKeys(window, "window", ["title", "width", "height", "maximized", "resizable"]);
530
530
  return {
531
531
  title: window.title === void 0 ? appName : nonEmptyString(window.title, "TN_CONFIG_WINDOW_TITLE_INVALID", "window.title"),
532
532
  width: positiveInteger(window.width, 1280, "TN_CONFIG_WINDOW_WIDTH_INVALID", "window.width"),
533
533
  height: positiveInteger(window.height, 720, "TN_CONFIG_WINDOW_HEIGHT_INVALID", "window.height"),
534
+ maximized: booleanValue(
535
+ window.maximized,
536
+ false,
537
+ "TN_CONFIG_WINDOW_MAXIMIZED_INVALID",
538
+ "window.maximized"
539
+ ),
534
540
  resizable: booleanValue(
535
541
  window.resizable,
536
542
  true,
@@ -565,9 +571,15 @@ function validateUi(raw) {
565
571
  }
566
572
  function validateRenderer(raw) {
567
573
  const renderer = assertRecord(raw, "renderer");
568
- assertKeys(renderer, "renderer", ["preferWebGPU", "resolutionScale", "antialias", "android"]);
574
+ assertKeys(renderer, "renderer", [
575
+ "preferWebGPU",
576
+ "resolutionScale",
577
+ "antialias",
578
+ "alphaAntialiasing",
579
+ "android"
580
+ ]);
569
581
  const android = assertRecord(renderer.android, "renderer.android");
570
- assertKeys(android, "renderer.android", ["resolutionScale", "antialias"]);
582
+ assertKeys(android, "renderer.android", ["resolutionScale", "antialias", "alphaAntialiasing"]);
571
583
  const resolutionScale = renderer.resolutionScale;
572
584
  const androidResolutionScale = android.resolutionScale;
573
585
  for (const [name, value] of [
@@ -584,9 +596,18 @@ function validateRenderer(raw) {
584
596
  }
585
597
  const antialias = booleanOrUndefined(renderer.antialias, "renderer.antialias");
586
598
  const androidAntialias = booleanOrUndefined(android.antialias, "renderer.android.antialias");
599
+ const alphaAntialiasing = booleanOrUndefined(
600
+ renderer.alphaAntialiasing,
601
+ "renderer.alphaAntialiasing"
602
+ );
603
+ const androidAlphaAntialiasing = booleanOrUndefined(
604
+ android.alphaAntialiasing,
605
+ "renderer.android.alphaAntialiasing"
606
+ );
587
607
  const androidOverrides = {
588
608
  ...androidResolutionScale === void 0 ? {} : { resolutionScale: androidResolutionScale },
589
- ...androidAntialias === void 0 ? {} : { antialias: androidAntialias }
609
+ ...androidAntialias === void 0 ? {} : { antialias: androidAntialias },
610
+ ...androidAlphaAntialiasing === void 0 ? {} : { alphaAntialiasing: androidAlphaAntialiasing }
590
611
  };
591
612
  return {
592
613
  preferWebGPU: booleanValue(
@@ -596,6 +617,7 @@ function validateRenderer(raw) {
596
617
  "renderer.preferWebGPU"
597
618
  ),
598
619
  ...antialias === void 0 ? {} : { antialias },
620
+ ...alphaAntialiasing === void 0 ? {} : { alphaAntialiasing },
599
621
  ...resolutionScale === void 0 ? {} : { resolutionScale },
600
622
  ...Object.keys(androidOverrides).length === 0 ? {} : { android: androidOverrides }
601
623
  };
@@ -640,7 +662,7 @@ function validateAssetTargets(raw) {
640
662
  }
641
663
  };
642
664
  }
643
- var ASSET_TEXTURE_KEYS = ["overrides", "quality"];
665
+ var ASSET_TEXTURE_KEYS = ["maxSize", "overrides", "quality"];
644
666
  var TEXTURE_OVERRIDE_KEYS = ["codec", "glob", "quality"];
645
667
  var TEXTURE_CODECS = ["etc1s", "none", "uastc"];
646
668
  function textureQuality(value, label) {
@@ -649,6 +671,15 @@ function textureQuality(value, label) {
649
671
  }
650
672
  return value;
651
673
  }
674
+ function textureMaxSize(value) {
675
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 4) {
676
+ fail(
677
+ "TN_CONFIG_ASSETS_INVALID",
678
+ "assets.textures.maxSize must be a positive integer of at least 4."
679
+ );
680
+ }
681
+ return value;
682
+ }
652
683
  function validateTextureOverrides(raw) {
653
684
  if (!Array.isArray(raw)) {
654
685
  fail("TN_CONFIG_ASSETS_INVALID", "assets.textures.overrides must be an array.");
@@ -689,6 +720,7 @@ function validateTextures(raw) {
689
720
  const textures = assertRecord(raw, "assets.textures");
690
721
  assertKeys(textures, "assets.textures", ASSET_TEXTURE_KEYS);
691
722
  return {
723
+ ...textures.maxSize === void 0 ? {} : { maxSize: textureMaxSize(textures.maxSize) },
692
724
  ...textures.quality === void 0 ? {} : { quality: textureQuality(textures.quality, "assets.textures.quality") },
693
725
  ...textures.overrides === void 0 ? {} : { overrides: validateTextureOverrides(textures.overrides) }
694
726
  };
@@ -715,10 +747,15 @@ function validateModels(raw) {
715
747
  "lightmap",
716
748
  "passes",
717
749
  "quantize",
750
+ "sharedImages",
718
751
  "simplify",
719
752
  "textures",
720
753
  "virtual"
721
754
  ]);
755
+ if (models.sharedImages !== void 0 && typeof models.sharedImages !== "boolean") {
756
+ fail("TN_CONFIG_ASSETS_INVALID", "assets.models.sharedImages must be true or false.");
757
+ }
758
+ const sharedImages = models.sharedImages;
722
759
  let lightmap;
723
760
  if (models.lightmap !== void 0) {
724
761
  const rawLightmap = assertRecord(models.lightmap, "assets.models.lightmap");
@@ -802,18 +839,67 @@ function validateModels(raw) {
802
839
  ...lightmap === void 0 ? {} : { lightmap },
803
840
  ...passes === void 0 || Object.keys(passes).length === 0 ? {} : { passes },
804
841
  ...quantize === void 0 || Object.keys(quantize).length === 0 ? {} : { quantize },
842
+ ...sharedImages === void 0 ? {} : { sharedImages },
805
843
  ...simplify === void 0 ? {} : { simplify },
806
844
  ...textures === void 0 ? {} : { textures },
807
845
  ...virtual === void 0 ? {} : { virtual }
808
846
  };
809
847
  }
848
+ function validateBudget(raw) {
849
+ const limit = (value) => value === "none" || typeof value === "number" && Number.isSafeInteger(value) && value > 0;
850
+ if (limit(raw)) return raw;
851
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw) || Object.entries(raw).some(
852
+ ([key, value]) => !["uncooked", "total"].includes(key) || !limit(value)
853
+ )) {
854
+ fail(
855
+ "TN_CONFIG_ASSETS_INVALID",
856
+ 'assets.budget must contain positive integer byte limits or "none" for uncooked and total.'
857
+ );
858
+ }
859
+ return raw;
860
+ }
861
+ function validateAudio(raw) {
862
+ try {
863
+ parseAudioConfig(raw);
864
+ } catch (error) {
865
+ fail("TN_CONFIG_ASSETS_INVALID", error instanceof Error ? error.message : String(error));
866
+ }
867
+ return raw;
868
+ }
810
869
  function validateAssets(raw) {
811
870
  const assets = assertRecord(raw, "assets");
812
- assertKeys(assets, "assets", ["models", "source", "output", "targets", "textures"]);
871
+ assertKeys(assets, "assets", [
872
+ "audio",
873
+ "budget",
874
+ "exclude",
875
+ "concurrency",
876
+ "models",
877
+ "source",
878
+ "output",
879
+ "targets",
880
+ "textures"
881
+ ]);
813
882
  const targets = assets.targets === void 0 ? void 0 : validateAssetTargets(assets.targets);
814
883
  const models = assets.models === void 0 ? void 0 : validateModels(assets.models);
815
884
  const textures = assets.textures === void 0 ? void 0 : validateTextures(assets.textures);
885
+ if (assets.exclude !== void 0 && (!Array.isArray(assets.exclude) || assets.exclude.some((glob) => typeof glob !== "string" || glob.trim() === ""))) {
886
+ fail("TN_CONFIG_ASSETS_INVALID", "assets.exclude must be an array of non-empty glob strings.");
887
+ }
816
888
  return {
889
+ ...assets.audio === void 0 ? {} : { audio: validateAudio(assets.audio) },
890
+ ...assets.exclude === void 0 ? {} : { exclude: assets.exclude },
891
+ ...assets.budget === void 0 ? {} : { budget: validateBudget(assets.budget) },
892
+ // The worker bound a bake may use. Validated here so a malformed value fails at config
893
+ // load with the named code, and handed to the driver unchanged, which re-checks it —
894
+ // the producer→consumer seam the config spec proves by running the pipeline.
895
+ ...assets.concurrency === void 0 ? {} : {
896
+ concurrency: positiveInteger(
897
+ assets.concurrency,
898
+ 1,
899
+ "TN_CONFIG_ASSETS_INVALID",
900
+ "assets.concurrency"
901
+ )
902
+ },
817
903
  ...assets.source === void 0 ? {} : { source: nonEmptyString(assets.source, "TN_CONFIG_ASSETS_INVALID", "assets.source") },
818
904
  ...assets.output === void 0 ? {} : { output: nonEmptyString(assets.output, "TN_CONFIG_ASSETS_INVALID", "assets.output") },
819
905
  ...targets === void 0 ? {} : { targets },
@@ -945,10 +1031,10 @@ async function assertNativeBundleCompatible(bundle, target) {
945
1031
  `TN_NATIVE_WASM_ON_MOBILE: ${target} bundle contains ${wasm.map(([label]) => label).join(", ")}. Move web-only WASM imports out of src/game.ts or provide a threenative-native conditional backend; mobile navigation is owned by PRD-052.`
946
1032
  );
947
1033
  }
948
- function assertNativeUiRendererCompatible(target, renderer, platform = process.platform) {
1034
+ function assertNativeUiRendererCompatible(target, renderer, platform2 = process.platform) {
949
1035
  if (renderer === "native" || target === "android" || target === "ios") return;
950
- if (target === "desktop" && platform === "linux") return;
951
- const platformName = platform === "darwin" ? "macOS" : platform === "win32" ? "Windows" : platform;
1036
+ if (target === "desktop" && platform2 === "linux") return;
1037
+ const platformName = platform2 === "darwin" ? "macOS" : platform2 === "win32" ? "Windows" : platform2;
952
1038
  throw new Error(
953
1039
  `TN_UI_RENDERER_UNSUPPORTED: ui.renderer is "web", but ${target} has no WebView host on ${platformName}. Set ui.renderer to "native" for ${target}.`
954
1040
  );
@@ -991,7 +1077,7 @@ async function assertNativeAssetsCompatible(cwd, target, config) {
991
1077
  const ktx2 = rows.filter(([, entry]) => typeof entry.output === "string" && /\.ktx2$/iu.test(entry.output)).map(([logical]) => logical);
992
1078
  if (ktx2.length > 0) {
993
1079
  throw new Error(
994
- `TN_NATIVE_KTX2_UNSUPPORTED: ${target} cannot ship compiled KTX2 textures (${namedAssets(ktx2)}). The mobile native runtime has no WebAssembly and therefore no Basis transcoder, so nothing in the bundle can decode them. Set assets.textures to "none" so native builds ship the source textures, or keep the compressed textures on the web target.`
1080
+ `TN_NATIVE_KTX2_UNSUPPORTED: ${target} cannot ship compiled KTX2 textures (${namedAssets(ktx2)}). The mobile native runtime has no WebAssembly and therefore no Basis transcoder, so nothing in the bundle can decode them. Replace or transcode the authored KTX2 source for mobile, or exclude it from mobile builds; keep compressed textures on the web target.`
995
1081
  );
996
1082
  }
997
1083
  const compressedModels = rows.filter(
@@ -1001,7 +1087,7 @@ async function assertNativeAssetsCompatible(cwd, target, config) {
1001
1087
  ).map(([logical]) => logical);
1002
1088
  if (compressedModels.length > 0) {
1003
1089
  throw new Error(
1004
- `TN_NATIVE_MESH_COMPRESSION_UNSUPPORTED: ${target} cannot ship compressed model geometry (${namedAssets(compressedModels)}). The mobile native runtime has no WebAssembly and therefore no Meshopt or Draco decoder. Set assets.models to "none" so native builds ship uncompressed geometry, or keep the compressed models on the web target.`
1090
+ `TN_NATIVE_MESH_COMPRESSION_UNSUPPORTED: ${target} cannot ship compressed model geometry (${namedAssets(compressedModels)}). The mobile native runtime has no WebAssembly and therefore no Meshopt or Draco decoder. Native compilation keeps shared images and decoder-free model rewrites while omitting Meshopt output; rebuild the native target, or keep compressed models on the web target.`
1005
1091
  );
1006
1092
  }
1007
1093
  }
@@ -1067,6 +1153,14 @@ function uiBuildDriver(cwd, page, output) {
1067
1153
  // weapon among them. Nothing in `src/ui/` reads those files; it reaches the game through
1068
1154
  // published state and intents.
1069
1155
  " publicDir: false,",
1156
+ // One React, one ReactDOM, whatever the import graph looks like. The UI entry resolves its
1157
+ // peers beside the game while a linked package — `@threenative/ui`, or anything else pnpm
1158
+ // symlinks in — resolves the same bare specifiers beside itself, so a hook-owning package
1159
+ // installed outside the project brings a second physical copy into the bundle. React's
1160
+ // dispatcher lives in module state, so the copy the entry did not mount reads null and the
1161
+ // first `useState` on the phone throws `Cannot read properties of null`. `mergeConfig`
1162
+ // concatenates arrays, so a project that deduped its own packages keeps every one of them.
1163
+ ' resolve: { dedupe: ["react", "react-dom"] },',
1070
1164
  " build: {",
1071
1165
  ` outDir: ${literal(output)},`,
1072
1166
  " emptyOutDir: true,",
@@ -1079,7 +1173,7 @@ function uiBuildDriver(cwd, page, output) {
1079
1173
  }
1080
1174
  async function buildWeb(cwd, viteArgs = []) {
1081
1175
  const config = await loadConfig(cwd);
1082
- await compileAssets({ config: config.assets, cwd });
1176
+ await compileAssets({ config: config.assets, cwd, platform: "web" });
1083
1177
  await run(executable(cwd, "vite"), ["build", ...viteArgs], cwd);
1084
1178
  }
1085
1179
  async function nativeEntry(cwd, config) {
@@ -1162,17 +1256,10 @@ async function bundleNative(cwd, runtimeRoot, entry, target) {
1162
1256
  );
1163
1257
  return output;
1164
1258
  }
1165
- function installedRuntime(runtimeRoot) {
1166
- if (process.env.THREENATIVE_RUNTIME_BINARY)
1167
- return path2.resolve(process.env.THREENATIVE_RUNTIME_BINARY);
1168
- const key = `${process.platform}-${process.arch}`;
1169
- const filename = process.platform === "win32" ? "threenative-runtime.exe" : "threenative-runtime";
1170
- return path2.join(runtimeRoot, "prebuilt", key, filename);
1171
- }
1172
- async function buildNative(target, cwd) {
1259
+ async function buildNative(target, cwd, allowSourceBuild = false) {
1173
1260
  const config = await loadConfig(cwd);
1174
1261
  assertNativeUiRendererCompatible(target, config.ui.renderer);
1175
- await compileAssets({ config: config.assets, cwd });
1262
+ await compileAssets({ config: config.assets, cwd, platform: target });
1176
1263
  await assertNativeAssetsCompatible(cwd, target, config);
1177
1264
  const entry = await nativeEntry(cwd, config);
1178
1265
  const orientation = config.display.orientation;
@@ -1210,6 +1297,7 @@ async function buildNative(target, cwd) {
1210
1297
  process.execPath,
1211
1298
  [
1212
1299
  path2.join(runtimeRoot, "scripts", "package-android.mjs"),
1300
+ ...allowSourceBuild ? ["--allow-source-build"] : [],
1213
1301
  "--bundle",
1214
1302
  bundle,
1215
1303
  "--assets",
@@ -1238,8 +1326,7 @@ async function buildNative(target, cwd) {
1238
1326
  ...ui === void 0 ? [] : ["--ui", ui],
1239
1327
  "--config",
1240
1328
  configPath,
1241
- "--runtime",
1242
- installedRuntime(runtimeRoot),
1329
+ ...process.env.THREENATIVE_RUNTIME_BINARY ? ["--runtime", path2.resolve(process.env.THREENATIVE_RUNTIME_BINARY)] : [],
1243
1330
  "--output",
1244
1331
  output
1245
1332
  ],
@@ -1247,6 +1334,9 @@ async function buildNative(target, cwd) {
1247
1334
  );
1248
1335
  }
1249
1336
  async function build(options) {
1337
+ if (options.allowSourceBuild && options.target !== "android") {
1338
+ throw new Error("--allow-source-build is supported only for --target android.");
1339
+ }
1250
1340
  const cwd = path2.resolve(options.cwd ?? process.cwd());
1251
1341
  if (options.target === "web") await buildWeb(cwd, options.viteArgs);
1252
1342
  else {
@@ -1255,7 +1345,7 @@ async function build(options) {
1255
1345
  `${options.target} build does not accept ${options.viteArgs?.join(" ")}. iOS output is simulator-only; device signing remains OPEN.`
1256
1346
  );
1257
1347
  }
1258
- await buildNative(options.target, cwd);
1348
+ await buildNative(options.target, cwd, options.allowSourceBuild === true);
1259
1349
  }
1260
1350
  }
1261
1351
  function buildHelp() {
@@ -1264,6 +1354,7 @@ function buildHelp() {
1264
1354
  "",
1265
1355
  "Options:",
1266
1356
  " --target <target> Choose web, desktop, android, or ios (default: web).",
1357
+ " --allow-source-build Explicitly allow Android maintainer source compilation.",
1267
1358
  " --help Show this help."
1268
1359
  ].join("\n")}
1269
1360
  `;
@@ -1277,13 +1368,23 @@ function parseBuildArgs(argv) {
1277
1368
  if (!TARGETS.includes(value)) {
1278
1369
  throw new Error(`Unknown build target '${value ?? ""}'. Choose ${TARGETS.join(", ")}.`);
1279
1370
  }
1371
+ const allowSourceBuild = argv.includes("--allow-source-build");
1372
+ if (allowSourceBuild && value !== "android") {
1373
+ throw new Error("--allow-source-build is supported only for --target android.");
1374
+ }
1280
1375
  const consumed = /* @__PURE__ */ new Set([0]);
1376
+ if (allowSourceBuild) {
1377
+ for (let index = 1; index < argv.length; index += 1) {
1378
+ if (argv[index] === "--allow-source-build") consumed.add(index);
1379
+ }
1380
+ }
1281
1381
  if (targetIndex !== -1) {
1282
1382
  consumed.add(targetIndex);
1283
1383
  consumed.add(targetIndex + 1);
1284
1384
  }
1285
1385
  return {
1286
1386
  target: value,
1387
+ ...allowSourceBuild ? { allowSourceBuild: true } : {},
1287
1388
  viteArgs: argv.filter((_, index) => !consumed.has(index))
1288
1389
  };
1289
1390
  }
@@ -1294,36 +1395,373 @@ var commandSummaries = {
1294
1395
  build: "Build web or native output.",
1295
1396
  doctor: "Check this project and report what would break a build."
1296
1397
  };
1398
+ var BLENDER_VERSION_FLOOR = Object.freeze({ major: 4, minor: 2 });
1399
+ var BLENDER_INSTALL_GUIDANCE = Object.freeze({
1400
+ linux: "sudo snap install blender --classic (or your distribution's package, or https://www.blender.org/download/)",
1401
+ macos: "brew install --cask blender (or https://www.blender.org/download/)",
1402
+ windows: "winget install --id BlenderFoundation.Blender (or https://www.blender.org/download/)"
1403
+ });
1404
+ function floorString() {
1405
+ return `${BLENDER_VERSION_FLOOR.major}.${BLENDER_VERSION_FLOOR.minor}`;
1406
+ }
1407
+ function installCommandFor(platformName = platform()) {
1408
+ if (platformName === "darwin") return BLENDER_INSTALL_GUIDANCE.macos;
1409
+ if (platformName === "win32") return BLENDER_INSTALL_GUIDANCE.windows;
1410
+ return BLENDER_INSTALL_GUIDANCE.linux;
1411
+ }
1412
+ function executableFile(candidate) {
1413
+ try {
1414
+ if (!existsSync(candidate) || !statSync(candidate).isFile()) return false;
1415
+ accessSync(candidate, constants.X_OK);
1416
+ return true;
1417
+ } catch {
1418
+ return false;
1419
+ }
1420
+ }
1421
+ function binaryNames(platformName) {
1422
+ return platformName === "win32" ? ["blender.exe", "blender.com"] : ["blender"];
1423
+ }
1424
+ function pathCandidates(environment, platformName) {
1425
+ const raw = environment.PATH ?? environment.Path ?? "";
1426
+ if (raw.trim().length === 0) return [];
1427
+ return raw.split(path2.delimiter).filter((directory) => directory.trim().length > 0).flatMap((directory) => binaryNames(platformName).map((name) => path2.join(directory, name)));
1428
+ }
1429
+ function conventionalCandidates(platformName, home) {
1430
+ if (platformName === "darwin") {
1431
+ return [
1432
+ "/Applications/Blender.app/Contents/MacOS/Blender",
1433
+ path2.join(home, "Applications/Blender.app/Contents/MacOS/Blender")
1434
+ ];
1435
+ }
1436
+ if (platformName === "win32") {
1437
+ const roots = [
1438
+ process.env.ProgramFiles ?? "C:\\Program Files",
1439
+ process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)"
1440
+ ];
1441
+ return roots.flatMap(
1442
+ (root) => ["5.2", "5.1", "5.0", "4.5", "4.2"].map(
1443
+ (release) => path2.join(root, "Blender Foundation", `Blender ${release}`, "blender.exe")
1444
+ )
1445
+ );
1446
+ }
1447
+ return [
1448
+ "/usr/bin/blender",
1449
+ "/usr/local/bin/blender",
1450
+ "/snap/bin/blender",
1451
+ "/var/lib/flatpak/exports/bin/org.blender.Blender",
1452
+ path2.join(home, ".local/bin/blender")
1453
+ ];
1454
+ }
1455
+ function parseBlenderVersion(output) {
1456
+ const match = /^Blender\s+(\d+\.\d+(?:\.\d+)?)/mu.exec(output);
1457
+ return match?.[1];
1458
+ }
1459
+ function compareToFloor(version) {
1460
+ const [major = 0, minor = 0] = version.split(".").map((part) => Number.parseInt(part, 10));
1461
+ if (Number.isNaN(major) || Number.isNaN(minor)) return false;
1462
+ if (major !== BLENDER_VERSION_FLOOR.major) return major > BLENDER_VERSION_FLOOR.major;
1463
+ return minor >= BLENDER_VERSION_FLOOR.minor;
1464
+ }
1465
+ var probeBlenderVersion = (binary) => {
1466
+ try {
1467
+ const output = execFileSync(binary, ["--version"], {
1468
+ encoding: "utf8",
1469
+ stdio: ["ignore", "pipe", "pipe"],
1470
+ timeout: 3e4
1471
+ });
1472
+ return parseBlenderVersion(output);
1473
+ } catch {
1474
+ return void 0;
1475
+ }
1476
+ };
1477
+ function resolveBlender(environment = process.env, options = {}) {
1478
+ const platformName = options.platform ?? platform();
1479
+ const home = options.home ?? environment.HOME ?? environment.USERPROFILE ?? homedir();
1480
+ const probeVersion = options.probeVersion ?? probeBlenderVersion;
1481
+ const minimumVersion = floorString();
1482
+ const install = BLENDER_INSTALL_GUIDANCE;
1483
+ const override = environment.THREENATIVE_BLENDER_PATH;
1484
+ if (override !== void 0 && override.trim().length > 0) {
1485
+ const candidate = path2.resolve(override.trim());
1486
+ if (!executableFile(candidate)) {
1487
+ return {
1488
+ available: false,
1489
+ cause: "blender-unreadable",
1490
+ detail: `THREENATIVE_BLENDER_PATH points at '${candidate}', which is not an executable file.`,
1491
+ install,
1492
+ minimumVersion,
1493
+ path: candidate
1494
+ };
1495
+ }
1496
+ return classify(candidate, probeVersion, minimumVersion, install);
1497
+ }
1498
+ const candidates = [
1499
+ ...pathCandidates(environment, platformName),
1500
+ ...conventionalCandidates(platformName, home)
1501
+ ];
1502
+ for (const candidate of candidates) {
1503
+ if (!executableFile(candidate)) continue;
1504
+ const classified = classify(candidate, probeVersion, minimumVersion, install);
1505
+ if (classified.cause !== "blender-unreadable") return classified;
1506
+ }
1507
+ return {
1508
+ available: false,
1509
+ cause: "blender-missing",
1510
+ detail: `No Blender ${minimumVersion} or newer was found. Set THREENATIVE_BLENDER_PATH, or install it: ${installCommandFor(platformName)}`,
1511
+ install,
1512
+ minimumVersion
1513
+ };
1514
+ }
1515
+ function classify(binary, probeVersion, minimumVersion, install) {
1516
+ const version = probeVersion(binary);
1517
+ if (version === void 0) {
1518
+ return {
1519
+ available: false,
1520
+ cause: "blender-unreadable",
1521
+ detail: `'${binary}' did not report a Blender version.`,
1522
+ install,
1523
+ minimumVersion,
1524
+ path: binary
1525
+ };
1526
+ }
1527
+ if (!compareToFloor(version)) {
1528
+ return {
1529
+ available: false,
1530
+ cause: "blender-too-old",
1531
+ detail: `Blender ${version} at '${binary}' is older than the supported floor ${minimumVersion}.`,
1532
+ install,
1533
+ minimumVersion,
1534
+ path: binary,
1535
+ version
1536
+ };
1537
+ }
1538
+ return {
1539
+ available: true,
1540
+ detail: `Blender ${version} at '${binary}'.`,
1541
+ install,
1542
+ minimumVersion,
1543
+ path: binary,
1544
+ version
1545
+ };
1546
+ }
1547
+
1548
+ // ../core/mcp/servers.mjs
1549
+ var MCP_SERVERS = Object.freeze({
1550
+ "threenative-assets": Object.freeze({
1551
+ command: "node",
1552
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/assets.mjs"]),
1553
+ // Entries rather than an object literal: these are environment variable names, not identifiers,
1554
+ // and written as property names they read as names the naming rule must judge.
1555
+ env: Object.freeze(
1556
+ Object.fromEntries([
1557
+ ["ASSET_DOWNLOAD_DIR", "./public/assets"],
1558
+ ["AUDIO_DOWNLOAD_DIR", "./public/audio"]
1559
+ ])
1560
+ )
1561
+ }),
1562
+ "threenative-sculpt": Object.freeze({
1563
+ command: "node",
1564
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/sculpt.mjs"])
1565
+ }),
1566
+ "threenative-engine": Object.freeze({
1567
+ command: "node",
1568
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/engine.mjs"])
1569
+ }),
1570
+ // Drives an installed Blender headlessly so a downloaded .fbx becomes a GLB. It ships no
1571
+ // Blender and probes for one only when a tool is called, so a project that never converts a
1572
+ // model pays nothing for having this server wired.
1573
+ "threenative-blender": Object.freeze({
1574
+ command: "node",
1575
+ args: Object.freeze(["./node_modules/@threenative/core/mcp/blender.mjs"])
1576
+ })
1577
+ });
1578
+ var MCP_PACKAGES = Object.freeze({
1579
+ assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.8.0" }),
1580
+ sculpt: Object.freeze({ name: "threenative-sculpt-mcp", version: "0.1.1" }),
1581
+ engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.2" }),
1582
+ blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.2" })
1583
+ });
1584
+ var SERVER_FORMATS = Object.freeze({
1585
+ // Claude Code (`.mcp.json`), Cursor and the Gemini CLI all read this one.
1586
+ mcpServers: Object.freeze({
1587
+ key: "mcpServers",
1588
+ entry: (server) => ({
1589
+ command: server.command,
1590
+ args: [...server.args],
1591
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
1592
+ })
1593
+ }),
1594
+ // VS Code names the table `servers` and requires an explicit transport per server.
1595
+ vscode: Object.freeze({
1596
+ key: "servers",
1597
+ entry: (server) => ({
1598
+ type: "stdio",
1599
+ command: server.command,
1600
+ args: [...server.args],
1601
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
1602
+ })
1603
+ }),
1604
+ // opencode folds the command and its arguments into one array and spells the environment
1605
+ // `environment`. A server it does not mark enabled is written down and never started.
1606
+ opencode: Object.freeze({
1607
+ key: "mcp",
1608
+ entry: (server) => ({
1609
+ type: "local",
1610
+ command: [server.command, ...server.args],
1611
+ enabled: true,
1612
+ ...server.env === void 0 ? {} : { environment: { ...server.env } }
1613
+ })
1614
+ }),
1615
+ // Zed calls them context servers and needs `source: "custom"` to accept a command of our own.
1616
+ zed: Object.freeze({
1617
+ key: "context_servers",
1618
+ entry: (server) => ({
1619
+ source: "custom",
1620
+ command: server.command,
1621
+ args: [...server.args],
1622
+ ...server.env === void 0 ? {} : { env: { ...server.env } }
1623
+ })
1624
+ })
1625
+ });
1626
+ Object.freeze(Object.keys(SERVER_FORMATS));
1627
+ function codexServerBlock(name, server) {
1628
+ const args = server.args.map((argument) => JSON.stringify(argument)).join(", ");
1629
+ const lines = [
1630
+ `[mcp_servers.${name}]`,
1631
+ `command = ${JSON.stringify(server.command)}`,
1632
+ `args = [${args}]`
1633
+ ];
1634
+ if (server.env !== void 0) {
1635
+ lines.push("", `[mcp_servers.${name}.env]`);
1636
+ for (const [key, value] of Object.entries(server.env)) {
1637
+ lines.push(`${key} = ${JSON.stringify(value)}`);
1638
+ }
1639
+ }
1640
+ return lines.join("\n");
1641
+ }
1642
+ Object.freeze(
1643
+ Object.entries(MCP_SERVERS).map(
1644
+ ([name, server]) => Object.freeze({ body: codexServerBlock(name, server), name })
1645
+ )
1646
+ );
1647
+
1648
+ // ../core/mcp/install.mjs
1649
+ var MCP_HOSTS = Object.freeze([
1650
+ Object.freeze({
1651
+ id: "claude-code",
1652
+ label: "Claude Code",
1653
+ file: ".mcp.json",
1654
+ format: "mcpServers"
1655
+ }),
1656
+ Object.freeze({ id: "codex", label: "Codex", file: ".codex/config.toml", format: "codex" }),
1657
+ Object.freeze({ id: "cursor", label: "Cursor", file: ".cursor/mcp.json", format: "mcpServers" }),
1658
+ Object.freeze({ id: "vscode", label: "VS Code", file: ".vscode/mcp.json", format: "vscode" }),
1659
+ Object.freeze({
1660
+ id: "gemini-cli",
1661
+ label: "Gemini CLI",
1662
+ file: ".gemini/settings.json",
1663
+ format: "mcpServers"
1664
+ }),
1665
+ Object.freeze({
1666
+ id: "opencode",
1667
+ label: "opencode",
1668
+ file: "opencode.json",
1669
+ format: "opencode",
1670
+ // Written only when this installer creates the file, so a second install still reports
1671
+ // "unchanged" rather than rewriting a config the user has since edited.
1672
+ seed: Object.freeze({ $schema: "https://opencode.ai/config.json" })
1673
+ }),
1674
+ Object.freeze({ id: "zed", label: "Zed", file: ".zed/settings.json", format: "zed" })
1675
+ ]);
1676
+
1677
+ // src/mcp-servers.ts
1678
+ function serverEntryPath(server) {
1679
+ const entry = server.args[0];
1680
+ if (entry === void 0) {
1681
+ throw new Error("TN_MCP_TABLE: an MCP server entry declares no shim to launch.");
1682
+ }
1683
+ return entry;
1684
+ }
1685
+ function serverPackageKey(server) {
1686
+ const entry = serverEntryPath(server);
1687
+ const file = entry.slice(entry.lastIndexOf("/") + 1);
1688
+ return file.endsWith(".mjs") ? file.slice(0, -".mjs".length) : file;
1689
+ }
1690
+
1691
+ // src/doctor.ts
1692
+ var ANDROID_RELEASE_SIGNING_ENV = [
1693
+ "ORG_GRADLE_PROJECT_threenativeKeystore",
1694
+ "ORG_GRADLE_PROJECT_threenativeKeystoreAlias",
1695
+ "ORG_GRADLE_PROJECT_threenativeKeystorePassword",
1696
+ "ORG_GRADLE_PROJECT_threenativeKeyPassword"
1697
+ ];
1297
1698
  var DEFAULT_NATIVE_ENTRY = "src/game.ts";
1298
1699
  var RUNTIME_PACKAGE = "@threenative/runtime-native";
1299
1700
  var PLAYTEST_BINARY = "threenative-playtest";
1300
1701
  var ANDROID_JDK_MAJOR = 17;
1301
1702
  var ANDROID_COMPILE_SDK = 35;
1302
- var MCP_SERVER_SPECS = [
1303
- {
1304
- configName: "threenative-assets",
1305
- expectedArgs: "./node_modules/@threenative/core/mcp/assets.mjs",
1306
- packageName: "threenative-asset-mcp",
1307
- // Kept equal to what `@threenative/core` actually installs — its package.json dependency and
1308
- // `mcp/servers.mjs` both say 0.6.0, and doctor.spec asserts all three agree. A doctor that
1309
- // reports a version the install does not use tells a game author their MCP surface is
1310
- // something it is not.
1311
- version: "0.6.0"
1312
- },
1313
- {
1314
- configName: "threenative-sculpt",
1315
- expectedArgs: "./node_modules/@threenative/core/mcp/sculpt.mjs",
1316
- packageName: "threenative-sculpt-mcp",
1317
- version: "0.1.1"
1318
- },
1319
- {
1320
- configName: "threenative-engine",
1321
- expectedArgs: "./node_modules/@threenative/core/mcp/engine.mjs",
1322
- packageName: "@threenative/core",
1323
- version: "0.3.0"
1703
+ var CORE_PACKAGE_NAME = "@threenative/core";
1704
+ var CORE_PACKAGE_VERSION = "0.3.2";
1705
+ var CORE_RESOLVED_SERVERS = /* @__PURE__ */ new Set([
1706
+ "threenative-engine",
1707
+ "threenative-blender"
1708
+ ]);
1709
+ var MCP_SERVER_SPECS = Object.entries(MCP_SERVERS).map(
1710
+ ([configName, server]) => {
1711
+ const resolvesToCore = CORE_RESOLVED_SERVERS.has(configName);
1712
+ const key = serverPackageKey(server);
1713
+ const declared = MCP_PACKAGES[key];
1714
+ if (!resolvesToCore && declared === void 0) {
1715
+ throw new Error(
1716
+ `TN_DOCTOR_MCP_TABLE: MCP server '${configName}' launches '${key}.mjs', which MCP_PACKAGES does not declare.`
1717
+ );
1718
+ }
1719
+ return {
1720
+ configName,
1721
+ expectedArgs: serverEntryPath(server),
1722
+ packageName: resolvesToCore ? CORE_PACKAGE_NAME : declared.name,
1723
+ version: resolvesToCore ? CORE_PACKAGE_VERSION : declared.version
1724
+ };
1324
1725
  }
1325
- ];
1726
+ );
1326
1727
  var ASSET_DOWNLOAD_DIRECTORIES = ["public/assets", "public/audio"];
1728
+ var BLENDER_SOURCE_SUFFIXES = [".fbx", ".blend", ".obj", ".dae"];
1729
+ var BLENDER_PACKAGE = (() => {
1730
+ const declared = MCP_PACKAGES.blender;
1731
+ if (declared === void 0) {
1732
+ throw new Error("TN_DOCTOR_MCP_TABLE: MCP_PACKAGES declares no 'blender' package.");
1733
+ }
1734
+ return declared;
1735
+ })();
1736
+ var BLENDER_SERVER = (() => {
1737
+ const entry = Object.entries(MCP_SERVERS).find(
1738
+ ([, server]) => serverPackageKey(server) === "blender"
1739
+ );
1740
+ if (entry === void 0) {
1741
+ throw new Error("TN_DOCTOR_MCP_TABLE: no configured MCP server launches blender.mjs.");
1742
+ }
1743
+ return entry[0];
1744
+ })();
1745
+ var MCP_HOST_TABLE = MCP_HOSTS;
1746
+ var MANUAL_GLOBAL_MCP_HOSTS = Object.freeze([
1747
+ "Windsurf",
1748
+ "Cline",
1749
+ "Amp",
1750
+ "the JetBrains assistants"
1751
+ ]);
1752
+ for (const host of MCP_HOSTS) {
1753
+ const claimed = MANUAL_GLOBAL_MCP_HOSTS.find(
1754
+ (name) => host.label.toLowerCase() === name.toLowerCase()
1755
+ );
1756
+ if (claimed !== void 0) {
1757
+ throw new Error(
1758
+ `TN_DOCTOR_MCP_TABLE: '${claimed}' is wired project-scoped now, so doctor must stop calling it machine-wide only.`
1759
+ );
1760
+ }
1761
+ }
1762
+ var SHAPE_VERIFIABLE_HOSTS = MCP_HOSTS.filter(
1763
+ ({ format }) => format === "mcpServers"
1764
+ );
1327
1765
  function detectX11Compositor(environment = process.env) {
1328
1766
  if (environment.DISPLAY === void 0) return void 0;
1329
1767
  try {
@@ -1457,29 +1895,41 @@ function mcpServerMatches(spec, value) {
1457
1895
  const env = record(server.env);
1458
1896
  return env?.ASSET_DOWNLOAD_DIR === "./public/assets" && env.AUDIO_DOWNLOAD_DIR === "./public/audio";
1459
1897
  }
1460
- function mcpConfig(snapshot) {
1461
- if (!snapshot.files.has(".mcp.json")) return { kind: "missing" };
1462
- const source = snapshot.readText(".mcp.json");
1463
- if (source === void 0) return { detail: ".mcp.json could not be read", kind: "malformed" };
1898
+ function readServerTable(snapshot, host) {
1899
+ const source = snapshot.readText(host.file);
1900
+ if (source === void 0) return { detail: `${host.file} could not be read` };
1464
1901
  let parsed;
1465
1902
  try {
1466
1903
  parsed = JSON.parse(source);
1467
1904
  } catch (error) {
1468
1905
  return {
1469
- detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
1470
- kind: "malformed"
1906
+ detail: `${host.file} is invalid JSON: ${error instanceof Error ? error.message : String(error)}`
1471
1907
  };
1472
1908
  }
1473
- const root = record(parsed);
1474
- const servers = record(root?.mcpServers);
1475
- return servers === void 0 ? { detail: "missing an object-valued mcpServers property", kind: "malformed" } : { kind: "ready", servers };
1909
+ const servers = record(record(parsed)?.mcpServers);
1910
+ return servers === void 0 ? { detail: `${host.file} is missing an object-valued mcpServers property` } : { servers };
1476
1911
  }
1477
- function mcpServerCheck(snapshot, spec, value) {
1912
+ function mcpConfig(snapshot) {
1913
+ const present = SHAPE_VERIFIABLE_HOSTS.filter(({ file }) => snapshot.files.has(file));
1914
+ if (present.length === 0) return { kind: "missing" };
1915
+ const malformed = [];
1916
+ const parsed = [];
1917
+ for (const host of present) {
1918
+ const result = readServerTable(snapshot, host);
1919
+ if ("servers" in result) parsed.push({ host, servers: result.servers });
1920
+ else malformed.push(result.detail);
1921
+ }
1922
+ if (parsed.length === 0) return { detail: malformed.join("; "), kind: "malformed" };
1923
+ const wired = ({ servers }) => MCP_SERVER_SPECS.filter(({ configName }) => servers[configName] !== void 0).length;
1924
+ const best = parsed.reduce((left, right) => wired(right) > wired(left) ? right : left);
1925
+ return { host: best.host, kind: "ready", servers: best.servers };
1926
+ }
1927
+ function mcpServerCheck(snapshot, spec, value, file) {
1478
1928
  const name = `capability search: ${spec.packageName}`;
1479
1929
  if (value === void 0) {
1480
1930
  return {
1481
- detail: `${spec.configName} is missing from .mcp.json; expected ${spec.packageName}@${spec.version}`,
1482
- fix: "Restore the server entry from the generated .mcp.json.",
1931
+ detail: `${spec.configName} is missing from ${file}; expected ${spec.packageName}@${spec.version}`,
1932
+ fix: `Restore the server entry in ${file}, which @threenative/core generates.`,
1483
1933
  name,
1484
1934
  status: "fail"
1485
1935
  };
@@ -1487,7 +1937,7 @@ function mcpServerCheck(snapshot, spec, value) {
1487
1937
  if (!mcpServerMatches(spec, value)) {
1488
1938
  return {
1489
1939
  detail: `${spec.configName} is hand-edited or malformed; expected ${JSON.stringify(expectedMcpServer(spec))}`,
1490
- fix: "Restore the generated .mcp.json entry so the ThreeNative shim and asset directories remain wired.",
1940
+ fix: `Restore the generated ${file} entry so the ThreeNative shim and asset directories remain wired.`,
1491
1941
  name,
1492
1942
  status: "fail"
1493
1943
  };
@@ -1530,7 +1980,7 @@ function mcpServerCheck(snapshot, spec, value) {
1530
1980
  }
1531
1981
  if (installedVersion !== spec.version) {
1532
1982
  return {
1533
- detail: `${spec.configName} resolves ${spec.packageName}@${installedVersion}; the .mcp.json fallback is ${spec.packageName}@${spec.version}`,
1983
+ detail: `${spec.configName} resolves ${spec.packageName}@${installedVersion}; the ${file} fallback is ${spec.packageName}@${spec.version}`,
1534
1984
  fix: `Install ${spec.packageName}@${spec.version} so the capability contract is version-matched.`,
1535
1985
  name,
1536
1986
  status: "warn"
@@ -1549,7 +1999,7 @@ function probeMcpServer(projectRoot, spec) {
1549
1999
  method: "initialize",
1550
2000
  params: {
1551
2001
  capabilities: {},
1552
- clientInfo: { name: "threenative-doctor", version: "0.3.0" },
2002
+ clientInfo: { name: "threenative-doctor", version: "0.3.2" },
1553
2003
  protocolVersion: "2025-06-18"
1554
2004
  }
1555
2005
  });
@@ -1598,12 +2048,17 @@ ${list}
1598
2048
  }
1599
2049
  return { detail: `transport initialized and advertised ${tools.length} tool(s)`, status: "ok" };
1600
2050
  }
1601
- function mcpSummary(serverChecks) {
2051
+ function mcpSummary(serverChecks, host) {
1602
2052
  const failed = serverChecks.filter(({ status: status2 }) => status2 === "fail").length;
1603
2053
  const warned = serverChecks.filter(({ status: status2 }) => status2 === "warn").length;
1604
2054
  const status = failed > 0 ? "fail" : warned > 0 ? "warn" : "ok";
1605
2055
  return {
1606
- detail: status === "ok" ? "all three configured MCP servers resolve" : `${serverChecks.length - failed - warned} server(s) resolve; ${warned} reachable by npx only; ${failed} malformed or missing`,
2056
+ // Transport, and only transport. A server that starts is a server that answers `tools/list`;
2057
+ // whether the application one of its tools drives is installed is a separate fact, reported by
2058
+ // `model conversion`. The old wording — "all three configured MCP servers resolve" — claimed a
2059
+ // complete authoring toolchain, and had also been wrong about the count since the fourth
2060
+ // server landed.
2061
+ detail: status === "ok" ? `all ${serverChecks.length} servers in ${host.file} resolve; transport only, external applications are reported separately` : `${serverChecks.length - failed - warned} of ${serverChecks.length} server(s) in ${host.file} resolve; ${warned} reachable by npx only; ${failed} malformed or missing; transport only, external applications are reported separately`,
1607
2062
  fix: status === "ok" ? void 0 : "Inspect the per-server capability search checks below.",
1608
2063
  name: "capability search",
1609
2064
  status
@@ -1611,30 +2066,35 @@ function mcpSummary(serverChecks) {
1611
2066
  }
1612
2067
  function capabilitySearchChecks(snapshot) {
1613
2068
  const config = mcpConfig(snapshot);
1614
- if (config.kind === "missing") {
1615
- return [
1616
- {
1617
- detail: "no .mcp.json, so an agent here cannot search engine capabilities and will hand-write what exists",
1618
- fix: "Restore the .mcp.json a scaffolded project ships, which wires the ThreeNative MCP servers.",
1619
- name: "capability search",
1620
- status: "fail"
1621
- }
1622
- ];
1623
- }
1624
- if (config.kind === "malformed") {
2069
+ const verifiable = SHAPE_VERIFIABLE_HOSTS.map(({ file }) => file).join(", ");
2070
+ if (config.kind === "missing" || config.kind === "malformed") {
2071
+ const elsewhere = MCP_HOST_TABLE.filter((host) => hostWiring(snapshot, host) === "wired").map(
2072
+ ({ label }) => label
2073
+ );
2074
+ const cause = config.kind === "missing" ? `no server table this check can validate (${verifiable})` : `no readable server table: ${config.detail}`;
2075
+ if (elsewhere.length > 0) {
2076
+ return [
2077
+ {
2078
+ detail: `${cause}; ${elsewhere.join(", ")} carry the servers in a format only 'editor activation' reads`,
2079
+ fix: `Reinstall @threenative/core if you also want ${verifiable} wired; an agent in ${elsewhere[0]} already has capability search.`,
2080
+ name: "capability search",
2081
+ status: "warn"
2082
+ }
2083
+ ];
2084
+ }
1625
2085
  return [
1626
2086
  {
1627
- detail: `.mcp.json is malformed: ${config.detail}`,
1628
- fix: "Restore a valid generated .mcp.json, preserving any unrelated servers.",
2087
+ detail: config.kind === "missing" ? `no ${verifiable}, so an agent here cannot search engine capabilities and will hand-write what exists` : cause,
2088
+ fix: config.kind === "missing" ? "Restore the .mcp.json a scaffolded project ships, which wires the ThreeNative MCP servers." : "Restore a valid generated config, preserving any unrelated servers.",
1629
2089
  name: "capability search",
1630
2090
  status: "fail"
1631
2091
  }
1632
2092
  ];
1633
2093
  }
1634
2094
  const serverChecks = MCP_SERVER_SPECS.map(
1635
- (spec) => mcpServerCheck(snapshot, spec, config.servers[spec.configName])
2095
+ (spec) => mcpServerCheck(snapshot, spec, config.servers[spec.configName], config.host.file)
1636
2096
  );
1637
- return [mcpSummary(serverChecks), ...serverChecks];
2097
+ return [mcpSummary(serverChecks, config.host), ...serverChecks];
1638
2098
  }
1639
2099
  function readJsonSync(file) {
1640
2100
  try {
@@ -1725,26 +2185,35 @@ function assetPipelineCheck(snapshot) {
1725
2185
  status
1726
2186
  };
1727
2187
  }
1728
- function androidToolchainStatus(probe) {
2188
+ function androidToolchainFacts(probe) {
1729
2189
  const details = [];
2190
+ const blockers = [];
1730
2191
  let status = probe.status ?? "ok";
1731
2192
  if (probe.jdkVersion === void 0 || probe.jdkMajor === void 0) {
1732
- details.push(`JDK not found; Android builds require JDK ${ANDROID_JDK_MAJOR}`);
2193
+ const blocker = `JDK not found; Android builds require JDK ${ANDROID_JDK_MAJOR}`;
2194
+ details.push(blocker);
2195
+ blockers.push(blocker);
1733
2196
  status = "warn";
1734
2197
  } else if (probe.jdkMajor !== ANDROID_JDK_MAJOR) {
1735
- details.push(
1736
- `JDK ${probe.jdkVersion} found; Android builds support JDK ${ANDROID_JDK_MAJOR} only`
1737
- );
2198
+ const blocker = `JDK ${probe.jdkVersion} found; Android builds support JDK ${ANDROID_JDK_MAJOR} only`;
2199
+ details.push(blocker);
2200
+ blockers.push(blocker);
1738
2201
  status = "warn";
1739
2202
  } else {
1740
2203
  details.push(`JDK ${probe.jdkVersion} found (supported JDK ${ANDROID_JDK_MAJOR})`);
1741
2204
  }
1742
2205
  if (probe.sdkVersion === void 0) {
1743
- details.push(`Android SDK platform android-${ANDROID_COMPILE_SDK} not found`);
2206
+ const blocker = `Android SDK platform android-${ANDROID_COMPILE_SDK} not found`;
2207
+ details.push(blocker);
2208
+ blockers.push(blocker);
1744
2209
  status = "warn";
1745
2210
  } else {
1746
2211
  details.push(`Android SDK platform android-${ANDROID_COMPILE_SDK} ${probe.sdkVersion} found`);
1747
2212
  }
2213
+ return { blockers, details, status };
2214
+ }
2215
+ function androidToolchainStatus(probe) {
2216
+ const { details, status } = androidToolchainFacts(probe);
1748
2217
  return {
1749
2218
  detail: details.join("; "),
1750
2219
  fix: status === "ok" ? void 0 : `Install Android SDK platform android-${ANDROID_COMPILE_SDK} and JDK ${ANDROID_JDK_MAJOR}, or set ANDROID_HOME or ANDROID_SDK_ROOT and JAVA_HOME (or put JDK ${ANDROID_JDK_MAJOR} on PATH).`,
@@ -1774,18 +2243,22 @@ function playtestFailureDetail(error) {
1774
2243
  const output = [childOutput(fields?.stderr), childOutput(fields?.stdout)].filter((value) => value !== void 0).join("\n");
1775
2244
  return output.length > 0 ? output : error instanceof Error ? error.message : String(error);
1776
2245
  }
1777
- function playtestInvocation(runner) {
2246
+ function playtestInvocation(runner, capturePath) {
1778
2247
  if (process.platform !== "win32" || !/\.cmd$/iu.test(runner)) {
1779
- return { args: ["doctor", "--text"], command: runner };
2248
+ return {
2249
+ args: ["doctor", "--text", ...capturePath === void 0 ? [] : ["--capture", capturePath]],
2250
+ command: runner
2251
+ };
1780
2252
  }
1781
2253
  const command = process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe";
2254
+ const capture = capturePath === void 0 ? "" : ` --capture "${capturePath.replaceAll('"', '\\"')}"`;
1782
2255
  return {
1783
- args: ["/d", "/s", "/c", `"${runner}" doctor --text`],
2256
+ args: ["/d", "/s", "/c", `"${runner}" doctor --text${capture}`],
1784
2257
  command
1785
2258
  };
1786
2259
  }
1787
- function executePlaytestDoctor(runner, projectRoot) {
1788
- const invocation = playtestInvocation(runner);
2260
+ function executePlaytestDoctor(runner, projectRoot, capturePath) {
2261
+ const invocation = playtestInvocation(runner, capturePath);
1789
2262
  return execFileSync(invocation.command, invocation.args, {
1790
2263
  cwd: projectRoot,
1791
2264
  encoding: "utf8",
@@ -1793,11 +2266,11 @@ function executePlaytestDoctor(runner, projectRoot) {
1793
2266
  timeout: 3e4
1794
2267
  });
1795
2268
  }
1796
- function playtestCheck(snapshot) {
2269
+ function playtestCheck(snapshot, capturePath) {
1797
2270
  const runner = playtestRunner(snapshot);
1798
2271
  if (runner === void 0) return missingPlaytestCheck(snapshot);
1799
2272
  try {
1800
- const output = snapshot.runPlaytestDoctor?.() ?? executePlaytestDoctor(runner, snapshot.projectRoot);
2273
+ const output = snapshot.runPlaytestDoctor?.(capturePath) ?? executePlaytestDoctor(runner, snapshot.projectRoot, capturePath);
1801
2274
  const detail = output.trim();
1802
2275
  return {
1803
2276
  detail: detail.length === 0 ? "threenative-playtest doctor completed" : `threenative-playtest doctor completed:
@@ -2168,10 +2641,87 @@ function iosTargetCheck(snapshot) {
2168
2641
  status: iosHost ? "fail" : "warn"
2169
2642
  };
2170
2643
  }
2171
- function targetChecks(snapshot, nativeRuntime) {
2644
+ function requestedBuildBlockers(snapshot, request, nativeRuntime) {
2645
+ const blockers = [];
2646
+ if (request.target === "web") {
2647
+ if (!snapshot.files.has("src/main.ts")) blockers.push("src/main.ts is missing");
2648
+ return blockers;
2649
+ }
2650
+ if (nativeRuntime.status !== "ok")
2651
+ blockers.push(nativeRuntime.detail.replace(/^(?:unavailable|unknown) — /u, ""));
2652
+ const nativeEntry2 = nativeEntryCheck(snapshot);
2653
+ if (nativeEntry2.status === "fail") blockers.push(nativeEntry2.detail);
2654
+ if (request.target === "desktop") {
2655
+ const overlay = snapshot.desktopOverlay;
2656
+ if (overlay?.status === "fail") blockers.push(overlay.detail);
2657
+ return blockers;
2658
+ }
2659
+ if (request.target === "ios") {
2660
+ if (process.platform !== "darwin" || process.arch !== "arm64")
2661
+ blockers.push(
2662
+ `iOS packaging requires darwin-arm64; this host is ${process.platform}-${process.arch}`
2663
+ );
2664
+ else if (!runtimeFileAvailable(snapshot, "scripts/package-ios.mjs"))
2665
+ blockers.push(`${RUNTIME_PACKAGE} has no iOS packager`);
2666
+ return blockers;
2667
+ }
2668
+ if (!runtimeFileAvailable(snapshot, "scripts/package-android.mjs"))
2669
+ blockers.push(`${RUNTIME_PACKAGE} has no Android packager`);
2670
+ const androidToolchain = snapshot.androidToolchain ?? (snapshot.projectRoot === void 0 ? void 0 : probeAndroidToolchain());
2671
+ if (androidToolchain === void 0) blockers.push("the Android toolchain was not probed");
2672
+ else blockers.push(...androidToolchainFacts(androidToolchain).blockers);
2673
+ if (request.mode === "release") {
2674
+ const environment = snapshot.environment ?? {};
2675
+ const missing = ANDROID_RELEASE_SIGNING_ENV.filter(
2676
+ (name) => (environment[name] ?? "").trim().length === 0
2677
+ );
2678
+ if (missing.length > 0)
2679
+ blockers.push(`release signing inputs are not set: ${missing.join(", ")}`);
2680
+ }
2681
+ return blockers;
2682
+ }
2683
+ function requestedBuildCheck(snapshot, request, nativeRuntime) {
2684
+ const { target } = request;
2685
+ if (target === void 0) return void 0;
2686
+ const scope = `${target}${request.mode === void 0 ? "" : ` ${request.mode}`}`;
2687
+ const blockers = requestedBuildBlockers(snapshot, { ...request, target }, nativeRuntime);
2688
+ if (blockers.length === 0)
2689
+ return { detail: `buildable \u2014 ${scope}`, name: "requested build", status: "ok" };
2690
+ return {
2691
+ detail: `not buildable \u2014 ${scope}: ${blockers.join("; ")}`,
2692
+ fix: target === "android" ? `Install JDK ${ANDROID_JDK_MAJOR} and Android SDK platform android-${ANDROID_COMPILE_SDK}, reinstall ${RUNTIME_PACKAGE} so its prebuilt downloads${request.mode === "release" ? `, and export ${ANDROID_RELEASE_SIGNING_ENV.join(", ")} from the game's build environment` : ""}.` : `Resolve the cause above, then run 'threenative doctor --target ${target}' again.`,
2693
+ name: "requested build",
2694
+ status: "fail"
2695
+ };
2696
+ }
2697
+ var TARGET_PREREQUISITE_OWNERS = Object.freeze(
2698
+ {
2699
+ "desktop overlay": Object.freeze(["desktop"]),
2700
+ // Its own words are "so a native build has nothing to start"; a web build starts src/main.ts.
2701
+ "native entry": Object.freeze(["android", "desktop", "ios"]),
2702
+ "native runtime": Object.freeze(["android", "desktop", "ios"])
2703
+ }
2704
+ );
2705
+ function unrequestedTarget(check) {
2706
+ return check.status === "fail" ? { ...check, status: "warn" } : check;
2707
+ }
2708
+ function requestedTarget(check, requestedBuild) {
2709
+ if (requestedBuild?.status !== "fail") return check;
2710
+ const probed = /^available(?: — (?<facts>.+)| \((?<key>[^)]+)\))$/su.exec(check.detail)?.groups;
2711
+ const facts = probed?.facts ?? probed?.key;
2712
+ if (facts === void 0) return check;
2713
+ const blockers = /^not buildable — [^:]*: (?<why>.+)$/su.exec(requestedBuild.detail)?.groups?.why ?? requestedBuild.detail;
2714
+ return {
2715
+ ...check,
2716
+ detail: `not buildable \u2014 ${blockers}; probed: ${facts}`,
2717
+ fix: requestedBuild.fix ?? check.fix,
2718
+ status: "fail"
2719
+ };
2720
+ }
2721
+ function targetChecks(snapshot, nativeRuntime, request, requestedBuild) {
2172
2722
  const webAvailable = snapshot.files.has("src/main.ts");
2173
2723
  const desktopDetail = nativeRuntime.status === "ok" ? nativeRuntime.detail : `unavailable \u2014 ${nativeRuntime.detail.replace(/^(?:unavailable|unknown) — /u, "")}`;
2174
- return [
2724
+ const checks = [
2175
2725
  webAvailable ? { detail: "available \u2014 src/main.ts", name: "target web", status: "ok" } : {
2176
2726
  detail: "unavailable \u2014 src/main.ts is missing",
2177
2727
  name: "target web",
@@ -2185,6 +2735,10 @@ function targetChecks(snapshot, nativeRuntime) {
2185
2735
  androidTargetCheck(snapshot),
2186
2736
  iosTargetCheck(snapshot)
2187
2737
  ];
2738
+ if (request.target === void 0) return checks;
2739
+ return checks.map(
2740
+ (check) => check.name === `target ${request.target}` ? requestedTarget(check, requestedBuild) : unrequestedTarget(check)
2741
+ );
2188
2742
  }
2189
2743
  function desktopOverlayCheck(probe) {
2190
2744
  return {
@@ -2194,7 +2748,103 @@ function desktopOverlayCheck(probe) {
2194
2748
  status: probe.status
2195
2749
  };
2196
2750
  }
2197
- function diagnoseProject(snapshot) {
2751
+ var ASSET_MANIFEST = "public/assets.manifest.json";
2752
+ function hostWiring(snapshot, host) {
2753
+ if (!snapshot.files.has(host.file)) return "absent";
2754
+ const source = snapshot.readText(host.file);
2755
+ if (source === void 0) return "unreadable";
2756
+ if (host.file.endsWith(".json")) {
2757
+ try {
2758
+ const parsed = JSON.parse(source);
2759
+ if (record(parsed) === void 0) return "unreadable";
2760
+ } catch {
2761
+ return "unreadable";
2762
+ }
2763
+ }
2764
+ const missing = MCP_SERVER_SPECS.filter(({ configName }) => !source.includes(configName));
2765
+ return missing.length === 0 ? "wired" : "incomplete";
2766
+ }
2767
+ function editorActivationCheck(snapshot) {
2768
+ const wirings = MCP_HOST_TABLE.map((host) => ({ host, wiring: hostWiring(snapshot, host) }));
2769
+ const broken = wirings.filter(({ wiring }) => wiring === "incomplete" || wiring === "unreadable");
2770
+ const wired = wirings.filter(({ wiring }) => wiring === "wired");
2771
+ const manual = `${MANUAL_GLOBAL_MCP_HOSTS.join(", ")} read a machine-wide config only and are wired by hand`;
2772
+ const named = broken.map(
2773
+ ({ host, wiring }) => `${host.file} is ${wiring === "unreadable" ? "unreadable" : "missing ThreeNative servers"}`
2774
+ ).join("; ");
2775
+ if (wired.length === 0) {
2776
+ return {
2777
+ detail: `no project-scoped host config carries the ThreeNative servers (looked for ${MCP_HOST_TABLE.map(({ file }) => file).join(", ")})${named === "" ? "" : `; ${named}`}. ${manual}`,
2778
+ fix: "Reinstall @threenative/core in this project; its postinstall writes every project-scoped host config.",
2779
+ name: "editor activation",
2780
+ status: "fail"
2781
+ };
2782
+ }
2783
+ if (broken.length > 0) {
2784
+ return {
2785
+ // The file is the user's: doctor names it and never rewrites it.
2786
+ detail: `${named} \u2014 ${wired.length} of ${MCP_HOST_TABLE.length} host configs are complete. ${manual}`,
2787
+ fix: "Reinstall @threenative/core to rewrite the host configs it owns, or restore the listed file by hand; doctor never edits it.",
2788
+ name: "editor activation",
2789
+ status: "warn"
2790
+ };
2791
+ }
2792
+ return {
2793
+ detail: `${wired.length} of ${MCP_HOST_TABLE.length} host configs carry the servers (${wired.map(({ host }) => host.label).join(
2794
+ ", "
2795
+ )}); one is enough for the host you work in. Whether an editor loaded it is not observable from here. ${manual}`,
2796
+ name: "editor activation",
2797
+ status: "ok"
2798
+ };
2799
+ }
2800
+ function conversionsExecuted(snapshot) {
2801
+ const source = snapshot.readText(ASSET_MANIFEST);
2802
+ if (source === void 0) return void 0;
2803
+ let parsed;
2804
+ try {
2805
+ parsed = JSON.parse(source);
2806
+ } catch {
2807
+ return void 0;
2808
+ }
2809
+ const entries = record(parsed)?.entries;
2810
+ if (!Array.isArray(entries)) return void 0;
2811
+ return entries.filter((entry) => typeof record(entry)?.importedFrom === "string").length;
2812
+ }
2813
+ function modelConversionCheck(snapshot) {
2814
+ const probe = snapshot.blender;
2815
+ if (probe === void 0) return void 0;
2816
+ const name = "model conversion";
2817
+ const sources = [...snapshot.files].filter(
2818
+ (file) => BLENDER_SOURCE_SUFFIXES.some((suffix) => file.toLowerCase().endsWith(suffix))
2819
+ );
2820
+ const executed = conversionsExecuted(snapshot);
2821
+ const ran = executed === void 0 ? "no bake manifest here, so no conversion is proven" : executed === 0 ? "the bake manifest records no converted model" : `the bake manifest records ${executed} converted model(s)`;
2822
+ const transport = snapshot.mcpServerHealth?.get(BLENDER_SERVER);
2823
+ if (transport?.status === "fail") {
2824
+ return {
2825
+ detail: `${BLENDER_SERVER} is configured, but ${transport.detail}; no conversion tool is reachable \u2014 ${ran}`,
2826
+ fix: `Reinstall @threenative/core and ${BLENDER_PACKAGE.name}, then rerun doctor.`,
2827
+ name,
2828
+ status: "fail"
2829
+ };
2830
+ }
2831
+ const reachable = transport === void 0 ? `${BLENDER_SERVER} was not probed` : `${BLENDER_SERVER} transport is up`;
2832
+ if (!probe.available) {
2833
+ const carried = sources.length === 0 ? "no .fbx, .blend, .obj or .dae in this project, so nothing needs it yet" : `${sources.length} source(s) in this project need it: ${sources.slice(0, 3).join(", ")}`;
2834
+ return {
2835
+ detail: `${reachable}, but conversion is unavailable: ${probe.detail} \u2014 ${carried}; ${ran}`,
2836
+ fix: `Install Blender when you want to convert those formats: ${probe.installCommand}`,
2837
+ name,
2838
+ status: "warn"
2839
+ };
2840
+ }
2841
+ return {
2842
+ detail: `${reachable} and Blender ${probe.version ?? "(version unreported)"} converts .fbx, .blend, .obj and .dae on this machine; ${ran}`,
2843
+ name,
2844
+ status: "ok"
2845
+ };
2846
+ }
2847
+ function diagnoseProject(snapshot, options = {}) {
2198
2848
  if (record(snapshot.packageJson) === void 0) {
2199
2849
  return {
2200
2850
  checks: [
@@ -2209,9 +2859,11 @@ function diagnoseProject(snapshot) {
2209
2859
  };
2210
2860
  }
2211
2861
  const hasPlaytests = [...snapshot.files].some((file) => file.endsWith(".playtest.json"));
2862
+ const blender = modelConversionCheck(snapshot);
2212
2863
  const nativeRuntime = nativeRuntimeCheck(snapshot);
2213
2864
  const apkSize = apkSizeCheck(snapshot);
2214
- const playtest = playtestCheck(snapshot);
2865
+ const playtest = playtestCheck(snapshot, options.capturePath);
2866
+ const requestedBuild = requestedBuildCheck(snapshot, options, nativeRuntime);
2215
2867
  const checks = [
2216
2868
  { detail: "readable", name: "package.json", status: "ok" },
2217
2869
  ...dependencyChecks(snapshot),
@@ -2220,7 +2872,8 @@ function diagnoseProject(snapshot) {
2220
2872
  assetPipelineCheck(snapshot),
2221
2873
  ...apkSize === void 0 ? [] : [apkSize],
2222
2874
  ...!usesDesktopOverlay(snapshot.config) || snapshot.desktopOverlay === void 0 ? [] : [desktopOverlayCheck(snapshot.desktopOverlay)],
2223
- ...targetChecks(snapshot, nativeRuntime),
2875
+ ...targetChecks(snapshot, nativeRuntime, options, requestedBuild),
2876
+ ...requestedBuild === void 0 ? [] : [requestedBuild],
2224
2877
  snapshot.files.has("src/main.ts") ? { detail: "src/main.ts is the web entry", name: "web entry", status: "ok" } : {
2225
2878
  detail: "no src/main.ts, so 'threenative build' has no web entry to bundle",
2226
2879
  fix: "Add src/main.ts, which mounts the game and any browser-only UI.",
@@ -2234,9 +2887,15 @@ function diagnoseProject(snapshot) {
2234
2887
  name: "playtests",
2235
2888
  status: "warn"
2236
2889
  },
2237
- ...capabilitySearchChecks(snapshot)
2890
+ ...capabilitySearchChecks(snapshot),
2891
+ editorActivationCheck(snapshot),
2892
+ ...blender === void 0 ? [] : [blender]
2238
2893
  ];
2239
- return { checks, pass: checks.every(({ status }) => status !== "fail") };
2894
+ const scoped = options.target === void 0 ? checks : checks.map((check) => {
2895
+ const owners = TARGET_PREREQUISITE_OWNERS[check.name];
2896
+ return owners === void 0 || owners.includes(options.target) ? check : unrequestedTarget(check);
2897
+ });
2898
+ return { checks: scoped, pass: scoped.every(({ status }) => status !== "fail") };
2240
2899
  }
2241
2900
  async function collectFiles(root, relative = "", depth = 0) {
2242
2901
  if (depth > 3) return [];
@@ -2294,7 +2953,7 @@ async function readProject(root) {
2294
2953
  const runtimeManifestUrl = runtimeRoot === void 0 || runtimeVersion === void 0 ? void 0 : await runtimeReleaseManifestUrl(runtimeRoot, runtimeVersion);
2295
2954
  const playtestRunnerPath = resolveBinaryFrom(projectRoot, PLAYTEST_BINARY);
2296
2955
  const mcpServerHealth = /* @__PURE__ */ new Map();
2297
- if (files.has(".mcp.json")) {
2956
+ if (SHAPE_VERIFIABLE_HOSTS.some(({ file }) => files.has(file))) {
2298
2957
  for (const spec of MCP_SERVER_SPECS) {
2299
2958
  if (existsSync(path2.resolve(projectRoot, spec.expectedArgs))) {
2300
2959
  mcpServerHealth.set(spec.configName, probeMcpServer(projectRoot, spec));
@@ -2317,10 +2976,20 @@ async function readProject(root) {
2317
2976
  }
2318
2977
  },
2319
2978
  androidToolchain: probeAndroidToolchain(),
2979
+ blender: (() => {
2980
+ const status = resolveBlender();
2981
+ return {
2982
+ available: status.available,
2983
+ detail: status.detail,
2984
+ installCommand: installCommandFor(),
2985
+ ...status.version === void 0 ? {} : { version: status.version }
2986
+ };
2987
+ })(),
2320
2988
  ...usesDesktopOverlay(config) ? { desktopOverlay: probeDesktopOverlay() } : {},
2989
+ environment: process.env,
2321
2990
  ...playtestRunnerPath === void 0 ? {} : {
2322
2991
  playtestRunnerPath,
2323
- runPlaytestDoctor: () => executePlaytestDoctor(playtestRunnerPath, projectRoot)
2992
+ runPlaytestDoctor: (capturePath) => executePlaytestDoctor(playtestRunnerPath, projectRoot, capturePath)
2324
2993
  },
2325
2994
  ...runtimeRoot === void 0 ? {} : {
2326
2995
  readRuntimeText: (relative) => {
@@ -2372,18 +3041,30 @@ function formatDoctorReport(report) {
2372
3041
  }
2373
3042
 
2374
3043
  // src/threenative.ts
3044
+ var DOCTOR_TARGETS = ["web", "desktop", "android", "ios"];
3045
+ var DOCTOR_MODES = ["debug", "release"];
2375
3046
  function cliHelp(command) {
2376
3047
  if (command === "build") return buildHelp();
2377
3048
  if (command === "doctor") {
2378
3049
  return `${[
2379
- "Usage: threenative doctor [--text]",
3050
+ "Usage: threenative doctor [--target web|desktop|android|ios] [--mode debug|release]",
3051
+ " [--text] [--capture <path>]",
2380
3052
  "",
2381
3053
  "Checks this project against what the build and the native host assume about it:",
2382
3054
  "installed and version-matched @threenative packages, a portable entry that",
2383
3055
  "default-exports a game, a web entry, a scenario that can prove it, and the",
2384
3056
  "capability search an authoring agent needs.",
2385
3057
  "",
3058
+ "--target names the build you are about to run, so a prerequisite that build needs",
3059
+ " fails the report instead of describing the target as available with a warning.",
3060
+ " Targets you did not ask for stay in the report but no longer decide the exit code.",
3061
+ "--mode debug|release scopes it further; release additionally requires the game's own",
3062
+ " Android signing inputs. Requires --target.",
3063
+ " Release packaging itself is not implemented yet: 'threenative build' has no --mode, and",
3064
+ " the Android packager still assembles debug. --mode release predicts what that build will",
3065
+ " need once PRD-212 ships it, so a green report here is a forecast, not a release.",
2386
3066
  "Prints JSON by default; --text prints the same report for a person.",
3067
+ "--capture forwards a browser census JSON or native TN_PIPELINE_EVENT log to the playtest doctor.",
2387
3068
  "Exits 0 when nothing failed, 1 when a check failed."
2388
3069
  ].join("\n")}
2389
3070
  `;
@@ -2407,7 +3088,43 @@ function helpFor(argv) {
2407
3088
  ${cliHelp()}`);
2408
3089
  }
2409
3090
  async function runDoctorCommand(argv, cwd = process.cwd()) {
2410
- const report = diagnoseProject(await readProject(cwd));
3091
+ let capturePath;
3092
+ let mode;
3093
+ let target;
3094
+ const valueFor = (flag, value) => {
3095
+ if (value === void 0 || value.startsWith("--"))
3096
+ throw new Error(`doctor: '${flag}' requires a value.`);
3097
+ return value;
3098
+ };
3099
+ for (let index = 0; index < argv.length; index += 1) {
3100
+ const flag = argv[index];
3101
+ if (flag === "--text") continue;
3102
+ if (flag === "--capture") {
3103
+ capturePath = valueFor(flag, argv[index + 1]);
3104
+ index += 1;
3105
+ continue;
3106
+ }
3107
+ if (flag === "--target") {
3108
+ const value = valueFor(flag, argv[index + 1]);
3109
+ if (!DOCTOR_TARGETS.includes(value))
3110
+ throw new Error(`doctor: '--target' must be one of ${DOCTOR_TARGETS.join(", ")}.`);
3111
+ target = value;
3112
+ index += 1;
3113
+ continue;
3114
+ }
3115
+ if (flag === "--mode") {
3116
+ const value = valueFor(flag, argv[index + 1]);
3117
+ if (!DOCTOR_MODES.includes(value))
3118
+ throw new Error(`doctor: '--mode' must be one of ${DOCTOR_MODES.join(", ")}.`);
3119
+ mode = value;
3120
+ index += 1;
3121
+ continue;
3122
+ }
3123
+ throw new Error(`doctor: unknown option '${String(flag)}'.`);
3124
+ }
3125
+ if (mode !== void 0 && target === void 0)
3126
+ throw new Error("doctor: '--mode' requires '--target'.");
3127
+ const report = diagnoseProject(await readProject(cwd), { capturePath, mode, target });
2411
3128
  process.stdout.write(
2412
3129
  argv.includes("--text") ? formatDoctorReport(report) : `${JSON.stringify(report, null, 2)}
2413
3130
  `