create-threenative 0.2.6 → 0.2.7

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 (622) hide show
  1. package/README.md +2 -2
  2. package/agent-docs/references/build-profiles.md +126 -0
  3. package/agent-docs/references/capability-reference.md +431 -20
  4. package/agent-docs/references/performance-basics.md +8 -5
  5. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  6. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  7. package/agent-docs/references/visual-baseline.md +8 -4
  8. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +5 -5
  10. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/threenative-context/SKILL.md +1 -1
  12. package/agent-files/.agents/skills/threenative-performance/SKILL.md +3 -3
  13. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  14. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  15. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  16. package/capabilities.json +555 -21
  17. package/dist/index.d.ts +30 -1
  18. package/dist/index.js +294 -55
  19. package/dist/threenative.js +714 -154
  20. package/package.json +6 -6
  21. package/template-assets/assets/mannequin-combat.glb +0 -0
  22. package/template-assets/assets/mannequin.glb +0 -0
  23. package/template-assets/assets/player-viewmodel.glb +0 -0
  24. package/template-assets/assets/sky.jpg +0 -0
  25. package/template-assets/clearwater/README.md +141 -0
  26. package/template-assets/clearwater/install.mjs +50 -0
  27. package/template-assets/clearwater/src/clearwater.ts +180 -0
  28. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  29. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  30. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  31. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  32. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  33. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  34. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  35. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  36. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  37. package/template-assets/patches/three@0.185.1.patch +2101 -138
  38. package/template-assets/worldEnvironment.ts +52 -1
  39. package/templates/action-rpg/AGENTS.md +42 -42
  40. package/templates/action-rpg/CLAUDE.md +42 -42
  41. package/templates/action-rpg/kit.json +1 -1
  42. package/templates/action-rpg/package.json +13 -7
  43. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  44. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  45. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  46. package/templates/action-rpg/src/conventions.ts +24 -18
  47. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  48. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  49. package/templates/action-rpg/src/entities/Player.ts +102 -32
  50. package/templates/action-rpg/src/game.ts +3 -3
  51. package/templates/action-rpg/src/render/camera.ts +18 -16
  52. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  53. package/templates/action-rpg/src/render/lighting.ts +45 -28
  54. package/templates/action-rpg/src/render/loading.ts +4 -4
  55. package/templates/action-rpg/src/render/materials.ts +191 -47
  56. package/templates/action-rpg/src/render/palette.ts +14 -13
  57. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  58. package/templates/action-rpg/src/render/props.ts +117 -0
  59. package/templates/action-rpg/src/render/quality.ts +40 -82
  60. package/templates/action-rpg/src/render/sky.ts +36 -13
  61. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  62. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  63. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  64. package/templates/action-rpg/src/style.css +9 -7
  65. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  66. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  67. package/templates/action-rpg/threenative.config.ts +14 -1
  68. package/templates/action-rpg/vite.config.ts +4 -1
  69. package/templates/minimal/AGENTS.md +10 -10
  70. package/templates/minimal/CLAUDE.md +10 -10
  71. package/templates/minimal/package.json +12 -6
  72. package/templates/minimal/playtests/play.playtest.json +6 -5
  73. package/templates/minimal/playtests/sky.playtest.json +27 -0
  74. package/templates/minimal/src/conventions.ts +6 -3
  75. package/templates/minimal/src/entities/Player.ts +73 -27
  76. package/templates/minimal/src/main.ts +2 -3
  77. package/templates/minimal/src/render/camera.ts +22 -4
  78. package/templates/minimal/src/render/lighting.ts +24 -48
  79. package/templates/minimal/src/render/materials.ts +158 -13
  80. package/templates/minimal/src/render/palette.ts +10 -7
  81. package/templates/minimal/src/render/postprocessing.ts +12 -25
  82. package/templates/minimal/src/render/quality.ts +35 -69
  83. package/templates/minimal/src/render/sky.ts +35 -54
  84. package/templates/minimal/src/render/touch-controls.ts +1 -1
  85. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  86. package/templates/minimal/src/scenes/Play.ts +121 -111
  87. package/templates/minimal/src/state.ts +0 -4
  88. package/templates/minimal/src/style.css +0 -10
  89. package/templates/minimal/threenative.config.ts +14 -1
  90. package/templates/minimal/vite.config.ts +4 -1
  91. package/templates/platformer/AGENTS.md +18 -56
  92. package/templates/platformer/CLAUDE.md +18 -56
  93. package/templates/platformer/kit.json +2 -2
  94. package/templates/platformer/package.json +13 -9
  95. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  96. package/templates/platformer/playtests/collect.playtest.json +8 -34
  97. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  98. package/templates/platformer/playtests/damage.playtest.json +40 -15
  99. package/templates/platformer/playtests/hud.playtest.json +34 -0
  100. package/templates/platformer/playtests/move.playtest.json +24 -0
  101. package/templates/platformer/playtests/performance.playtest.json +24 -7
  102. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  103. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  104. package/templates/platformer/playtests/survives.playtest.json +3 -19
  105. package/templates/platformer/playtests/world.playtest.json +26 -0
  106. package/templates/platformer/src/entities/Fox.ts +273 -0
  107. package/templates/platformer/src/entities/Pickup.ts +43 -60
  108. package/templates/platformer/src/entities/Walker.ts +88 -0
  109. package/templates/platformer/src/game.ts +11 -8
  110. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  111. package/templates/platformer/src/level/Stage.ts +469 -0
  112. package/templates/platformer/src/render/blocks.ts +94 -0
  113. package/templates/platformer/src/render/camera.ts +28 -3
  114. package/templates/platformer/src/render/fox.ts +196 -0
  115. package/templates/platformer/src/render/lighting.ts +42 -33
  116. package/templates/platformer/src/render/materials.ts +115 -5
  117. package/templates/platformer/src/render/palette.ts +68 -53
  118. package/templates/platformer/src/render/pickups.ts +142 -0
  119. package/templates/platformer/src/render/postprocessing.ts +12 -2
  120. package/templates/platformer/src/render/props.ts +147 -0
  121. package/templates/platformer/src/render/quality.ts +47 -99
  122. package/templates/platformer/src/render/scenery.ts +172 -0
  123. package/templates/platformer/src/render/sky.ts +120 -31
  124. package/templates/platformer/src/render/touch-controls.ts +5 -2
  125. package/templates/platformer/src/render/walkers.ts +96 -0
  126. package/templates/platformer/src/render/waterfall.ts +85 -0
  127. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  128. package/templates/platformer/src/scenes/Boot.ts +3 -4
  129. package/templates/platformer/src/scenes/Play.ts +362 -0
  130. package/templates/platformer/src/state.ts +16 -14
  131. package/templates/platformer/src/style.css +9 -8
  132. package/templates/platformer/src/ui/Hud.tsx +62 -29
  133. package/templates/platformer/src/ui/Menu.tsx +2 -2
  134. package/templates/platformer/threenative.config.ts +14 -1
  135. package/templates/platformer/vite.config.ts +4 -1
  136. package/templates/puzzle/AGENTS.md +19 -20
  137. package/templates/puzzle/CLAUDE.md +19 -20
  138. package/templates/puzzle/assets/native-proof.glb +0 -0
  139. package/templates/puzzle/assets/native-proof.png +0 -0
  140. package/templates/puzzle/kit.json +1 -1
  141. package/templates/puzzle/package.json +13 -7
  142. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  143. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  144. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  145. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  146. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  147. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  148. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  149. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  150. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  151. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  152. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  153. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  154. package/templates/puzzle/src/entities/Crate.ts +99 -42
  155. package/templates/puzzle/src/entities/Seal.ts +69 -0
  156. package/templates/puzzle/src/entities/Warden.ts +135 -0
  157. package/templates/puzzle/src/game.ts +15 -11
  158. package/templates/puzzle/src/render/camera.ts +66 -31
  159. package/templates/puzzle/src/render/crateShape.ts +70 -0
  160. package/templates/puzzle/src/render/lighting.ts +41 -41
  161. package/templates/puzzle/src/render/loading.ts +4 -4
  162. package/templates/puzzle/src/render/materials.ts +131 -27
  163. package/templates/puzzle/src/render/palette.ts +19 -29
  164. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  165. package/templates/puzzle/src/render/quality.ts +71 -80
  166. package/templates/puzzle/src/render/shapes.ts +109 -108
  167. package/templates/puzzle/src/render/sky.ts +18 -10
  168. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  169. package/templates/puzzle/src/render/vault.ts +315 -0
  170. package/templates/puzzle/src/render/warden.ts +46 -0
  171. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  172. package/templates/puzzle/src/scenes/Play.ts +793 -0
  173. package/templates/puzzle/src/state.ts +55 -24
  174. package/templates/puzzle/src/style.css +7 -8
  175. package/templates/puzzle/src/ui/App.tsx +2 -2
  176. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  177. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  178. package/templates/puzzle/threenative.config.ts +14 -1
  179. package/templates/puzzle/vite.config.ts +4 -1
  180. package/templates/racing/AGENTS.md +19 -20
  181. package/templates/racing/CLAUDE.md +19 -20
  182. package/templates/racing/package.json +13 -7
  183. package/templates/racing/playtests/boost.playtest.json +33 -12
  184. package/templates/racing/playtests/outcome.playtest.json +32 -50
  185. package/templates/racing/playtests/performance.playtest.json +2 -1
  186. package/templates/racing/playtests/ranking.playtest.json +5 -14
  187. package/templates/racing/playtests/rescue.playtest.json +2 -2
  188. package/templates/racing/playtests/reverse.playtest.json +30 -8
  189. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  190. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  191. package/templates/racing/src/entities/CarBody.ts +327 -0
  192. package/templates/racing/src/entities/LineDriver.ts +220 -0
  193. package/templates/racing/src/entities/RacingCar.ts +150 -89
  194. package/templates/racing/src/entities/Rival.ts +61 -24
  195. package/templates/racing/src/game.ts +5 -0
  196. package/templates/racing/src/render/camera.ts +49 -7
  197. package/templates/racing/src/render/lighting.ts +36 -37
  198. package/templates/racing/src/render/materials.ts +239 -19
  199. package/templates/racing/src/render/palette.ts +19 -21
  200. package/templates/racing/src/render/postprocessing.ts +12 -2
  201. package/templates/racing/src/render/quality.ts +43 -82
  202. package/templates/racing/src/render/shapes.ts +20 -6
  203. package/templates/racing/src/render/sky.ts +47 -39
  204. package/templates/racing/src/render/touch-controls.ts +1 -1
  205. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  206. package/templates/racing/src/scenes/Race.ts +107 -54
  207. package/templates/racing/src/state.ts +2 -0
  208. package/templates/racing/src/track/Checkline.ts +22 -7
  209. package/templates/racing/src/track/Lap.ts +64 -36
  210. package/templates/racing/src/track/Ranking.ts +20 -11
  211. package/templates/racing/src/track/Track.ts +809 -361
  212. package/templates/racing/src/track/TrackSector.ts +40 -11
  213. package/templates/racing/src/track/circuit.ts +477 -0
  214. package/templates/racing/src/track/rescue.ts +16 -4
  215. package/templates/racing/threenative.config.ts +14 -1
  216. package/templates/racing/vite.config.ts +4 -1
  217. package/templates/rts/AGENTS.md +96 -0
  218. package/templates/rts/CLAUDE.md +98 -0
  219. package/templates/rts/kit.json +7 -0
  220. package/templates/{defense → rts}/package.json +13 -7
  221. package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
  222. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  223. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  224. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  225. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  226. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  227. package/templates/rts/playtests/survives.playtest.json +58 -0
  228. package/templates/rts/public/favicon.svg +4 -0
  229. package/templates/rts/src/game.ts +64 -0
  230. package/templates/rts/src/orders.ts +22 -0
  231. package/templates/rts/src/render/army.ts +346 -0
  232. package/templates/rts/src/render/camera.ts +123 -0
  233. package/templates/rts/src/render/lighting.ts +61 -0
  234. package/templates/rts/src/render/loading.ts +33 -0
  235. package/templates/rts/src/render/materials.ts +152 -0
  236. package/templates/rts/src/render/models.ts +705 -0
  237. package/templates/rts/src/render/palette.ts +17 -0
  238. package/templates/rts/src/render/picking.ts +93 -0
  239. package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
  240. package/templates/rts/src/render/quality.ts +128 -0
  241. package/templates/rts/src/render/resources.ts +141 -0
  242. package/templates/rts/src/render/sky.ts +44 -0
  243. package/templates/rts/src/render/terrain.ts +116 -0
  244. package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
  245. package/templates/rts/src/scenes/Play.ts +650 -0
  246. package/templates/rts/src/sim/ai.ts +1140 -0
  247. package/templates/rts/src/sim/combat.ts +416 -0
  248. package/templates/rts/src/sim/construction.ts +374 -0
  249. package/templates/rts/src/sim/economy.ts +167 -0
  250. package/templates/rts/src/sim/game.ts +1082 -0
  251. package/templates/rts/src/sim/movement.ts +371 -0
  252. package/templates/rts/src/sim/nav.ts +276 -0
  253. package/templates/rts/src/sim/production.ts +180 -0
  254. package/templates/rts/src/sim/terrain.ts +170 -0
  255. package/templates/rts/src/sim/types.ts +647 -0
  256. package/templates/rts/src/sim/vision.ts +46 -0
  257. package/templates/rts/src/state.ts +100 -0
  258. package/templates/{defense → rts}/src/style.css +21 -8
  259. package/templates/rts/src/ui/App.tsx +21 -0
  260. package/templates/rts/src/ui/Commands.tsx +129 -0
  261. package/templates/rts/src/ui/GameUi.tsx +22 -0
  262. package/templates/rts/src/ui/Hud.tsx +165 -0
  263. package/templates/rts/src/ui/Minimap.tsx +84 -0
  264. package/templates/rts/tailwind.config.ts +2 -0
  265. package/templates/rts/threenative.config.ts +56 -0
  266. package/templates/rts/tsconfig.json +17 -0
  267. package/templates/{defense → rts}/vite.config.ts +4 -1
  268. package/templates/runner/AGENTS.md +6 -10
  269. package/templates/runner/CLAUDE.md +6 -10
  270. package/templates/runner/README.md +3 -3
  271. package/templates/runner/package.json +13 -7
  272. package/templates/runner/playtests/performance.playtest.json +2 -2
  273. package/templates/runner/src/conventions.ts +4 -3
  274. package/templates/runner/src/entities/Runner.ts +54 -7
  275. package/templates/runner/src/game.ts +2 -0
  276. package/templates/runner/src/render/camera.ts +4 -2
  277. package/templates/runner/src/render/dust.ts +5 -2
  278. package/templates/runner/src/render/lighting.ts +41 -45
  279. package/templates/runner/src/render/loading.ts +2 -2
  280. package/templates/runner/src/render/materials.ts +165 -25
  281. package/templates/runner/src/render/palette.ts +17 -28
  282. package/templates/runner/src/render/postprocessing.ts +12 -2
  283. package/templates/runner/src/render/quality.ts +42 -96
  284. package/templates/runner/src/render/shapes.ts +59 -37
  285. package/templates/runner/src/render/sky.ts +32 -41
  286. package/templates/runner/src/render/touch-controls.ts +1 -1
  287. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  288. package/templates/runner/src/scenes/Run.ts +26 -6
  289. package/templates/runner/src/track.ts +6 -1
  290. package/templates/runner/threenative.config.ts +14 -1
  291. package/templates/runner/vite.config.ts +4 -1
  292. package/templates/sailing/AGENTS.md +12 -12
  293. package/templates/sailing/CLAUDE.md +12 -12
  294. package/templates/sailing/assets/ship.glb +0 -0
  295. package/templates/sailing/package.json +13 -7
  296. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  297. package/templates/sailing/playtests/sails.playtest.json +33 -0
  298. package/templates/sailing/playtests/win.playtest.json +156 -8
  299. package/templates/sailing/src/conventions.ts +29 -2
  300. package/templates/sailing/src/entities/Ship.ts +381 -57
  301. package/templates/sailing/src/game.ts +14 -0
  302. package/templates/sailing/src/render/camera.ts +63 -9
  303. package/templates/sailing/src/render/lighting.ts +49 -27
  304. package/templates/sailing/src/render/materials.ts +50 -15
  305. package/templates/sailing/src/render/ocean.ts +647 -60
  306. package/templates/sailing/src/render/palette.ts +16 -12
  307. package/templates/sailing/src/render/postprocessing.ts +12 -2
  308. package/templates/sailing/src/render/props.ts +316 -442
  309. package/templates/sailing/src/render/quality.ts +14 -4
  310. package/templates/sailing/src/render/sky.ts +116 -23
  311. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  312. package/templates/sailing/src/scenes/Boot.ts +21 -0
  313. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  314. package/templates/sailing/src/state.ts +6 -0
  315. package/templates/sailing/src/ui/Hud.tsx +41 -9
  316. package/templates/sailing/threenative.config.ts +14 -1
  317. package/templates/sailing/vite.config.ts +4 -1
  318. package/templates/shooter/AGENTS.md +27 -42
  319. package/templates/shooter/CLAUDE.md +27 -42
  320. package/templates/shooter/index.html +1 -0
  321. package/templates/shooter/package.json +13 -7
  322. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  323. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  324. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  325. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  326. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  327. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  328. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  329. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  330. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  331. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  332. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  333. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  334. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  335. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  336. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  337. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  338. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  339. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  340. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  341. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  342. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  343. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  344. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  345. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  346. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  347. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  348. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  349. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  350. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  351. package/templates/shooter/playtests/performance.playtest.json +62 -26
  352. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  353. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  354. package/templates/shooter/playtests/survives.playtest.json +36 -30
  355. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  356. package/templates/shooter/src/entities/Breakables.ts +412 -0
  357. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  358. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  359. package/templates/shooter/src/entities/Rifle.ts +442 -0
  360. package/templates/shooter/src/entities/Target.ts +199 -83
  361. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  362. package/templates/shooter/src/game.ts +75 -41
  363. package/templates/shooter/src/main.ts +0 -1
  364. package/templates/shooter/src/postPhysics.ts +36 -0
  365. package/templates/shooter/src/render/camera.ts +78 -74
  366. package/templates/shooter/src/render/decals.ts +142 -82
  367. package/templates/shooter/src/render/facade.ts +1373 -0
  368. package/templates/shooter/src/render/gunfx.ts +704 -0
  369. package/templates/shooter/src/render/lighting.ts +52 -38
  370. package/templates/shooter/src/render/loading.ts +2 -2
  371. package/templates/shooter/src/render/materials.ts +100 -88
  372. package/templates/shooter/src/render/occlusion.ts +108 -0
  373. package/templates/shooter/src/render/palette.ts +10 -10
  374. package/templates/shooter/src/render/palm.ts +455 -0
  375. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  376. package/templates/shooter/src/render/postprocessing.ts +15 -3
  377. package/templates/shooter/src/render/quality.ts +40 -82
  378. package/templates/shooter/src/render/scale.ts +148 -15
  379. package/templates/shooter/src/render/shapes.ts +138 -613
  380. package/templates/shooter/src/render/sky.ts +35 -35
  381. package/templates/shooter/src/render/town-schematic.ts +120 -0
  382. package/templates/shooter/src/render/town.ts +986 -0
  383. package/templates/shooter/src/render/townMaterials.ts +160 -0
  384. package/templates/shooter/src/render/vehicles.ts +741 -0
  385. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  386. package/templates/shooter/src/scenes/Play.ts +727 -650
  387. package/templates/shooter/src/state.ts +26 -41
  388. package/templates/shooter/src/style.css +207 -11
  389. package/templates/shooter/src/surfaces.ts +131 -0
  390. package/templates/shooter/src/ui/App.tsx +9 -10
  391. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  392. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  393. package/templates/shooter/src/ui/Hud.tsx +428 -39
  394. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  395. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  396. package/templates/shooter/src/ui/main.tsx +2 -3
  397. package/templates/shooter/threenative.config.ts +14 -1
  398. package/templates/shooter/vite.config.ts +4 -1
  399. package/templates/starter/AGENTS.md +17 -17
  400. package/templates/starter/CLAUDE.md +17 -17
  401. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  402. package/templates/starter/package.json +13 -7
  403. package/templates/starter/playtests/play.playtest.json +2 -1
  404. package/templates/starter/playtests/survives.playtest.json +1 -1
  405. package/templates/starter/src/conventions.ts +6 -3
  406. package/templates/starter/src/entities/Goal.ts +35 -42
  407. package/templates/starter/src/entities/Player.ts +99 -16
  408. package/templates/starter/src/render/arena.ts +131 -0
  409. package/templates/starter/src/render/lighting.ts +27 -44
  410. package/templates/starter/src/render/materials.ts +164 -35
  411. package/templates/starter/src/render/palette.ts +16 -16
  412. package/templates/starter/src/render/postprocessing.ts +6 -7
  413. package/templates/starter/src/render/quality.ts +43 -101
  414. package/templates/starter/src/render/shapes.ts +1 -1
  415. package/templates/starter/src/render/sky.ts +39 -45
  416. package/templates/starter/src/render/touch-controls.ts +3 -1
  417. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  418. package/templates/starter/src/scenes/Play.ts +82 -81
  419. package/templates/starter/threenative.config.ts +14 -1
  420. package/templates/starter/vite.config.ts +4 -1
  421. package/templates/tower-defense/.codex/config.toml +19 -0
  422. package/templates/tower-defense/.cursor/mcp.json +32 -0
  423. package/templates/tower-defense/.gemini/settings.json +32 -0
  424. package/templates/tower-defense/.mcp.json +32 -0
  425. package/templates/tower-defense/.vscode/mcp.json +36 -0
  426. package/templates/tower-defense/.zed/settings.json +36 -0
  427. package/templates/{defense → tower-defense}/AGENTS.md +14 -12
  428. package/templates/{defense → tower-defense}/CLAUDE.md +14 -12
  429. package/templates/tower-defense/README.md +16 -0
  430. package/templates/tower-defense/index.html +12 -0
  431. package/templates/tower-defense/kit.json +7 -0
  432. package/templates/tower-defense/opencode.json +41 -0
  433. package/templates/tower-defense/package.json +56 -0
  434. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  435. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  436. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  437. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  438. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  439. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  440. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  441. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  442. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  443. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  444. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  445. package/templates/tower-defense/src/balance.ts +187 -0
  446. package/templates/tower-defense/src/board/Board.ts +100 -0
  447. package/templates/tower-defense/src/board/Route.ts +84 -0
  448. package/templates/tower-defense/src/camera-rig.ts +62 -0
  449. package/templates/tower-defense/src/economy.ts +64 -0
  450. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  451. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  452. package/templates/tower-defense/src/game.ts +72 -0
  453. package/templates/tower-defense/src/intents.ts +21 -0
  454. package/templates/tower-defense/src/main.ts +15 -0
  455. package/templates/tower-defense/src/physics.ts +6 -0
  456. package/templates/tower-defense/src/render/camera.ts +38 -0
  457. package/templates/tower-defense/src/render/lighting.ts +42 -0
  458. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  459. package/templates/tower-defense/src/render/materials.ts +103 -0
  460. package/templates/tower-defense/src/render/palette.ts +58 -0
  461. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  462. package/templates/tower-defense/src/render/quality.ts +128 -0
  463. package/templates/tower-defense/src/render/shapes.ts +550 -0
  464. package/templates/tower-defense/src/render/sky.ts +27 -0
  465. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  466. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  467. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  468. package/templates/tower-defense/src/state.ts +88 -0
  469. package/templates/tower-defense/src/style.css +137 -0
  470. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  471. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  472. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  473. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  474. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  475. package/templates/tower-defense/src/ui/main.tsx +14 -0
  476. package/templates/tower-defense/src/waves.ts +90 -0
  477. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  478. package/templates/tower-defense/vite.config.ts +41 -0
  479. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  480. package/agent-files/.claude/skills/ponytail/SKILL.md +0 -68
  481. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  482. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -53
  483. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  484. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -65
  485. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -58
  486. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  487. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  488. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  489. package/agent-files/AGENT-ROLES.md +0 -26
  490. package/templates/action-rpg/src/render/shapes.ts +0 -269
  491. package/templates/action-rpg/src/render/types.ts +0 -3
  492. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  493. package/templates/defense/README.md +0 -10
  494. package/templates/defense/kit.json +0 -7
  495. package/templates/defense/playtests/leak.playtest.json +0 -23
  496. package/templates/defense/playtests/placement.playtest.json +0 -40
  497. package/templates/defense/playtests/scan.playtest.json +0 -20
  498. package/templates/defense/playtests/survive.playtest.json +0 -45
  499. package/templates/defense/playtests/survives.playtest.json +0 -36
  500. package/templates/defense/src/attackers/Attacker.ts +0 -120
  501. package/templates/defense/src/board/Route.ts +0 -94
  502. package/templates/defense/src/conventions.ts +0 -18
  503. package/templates/defense/src/economy.ts +0 -36
  504. package/templates/defense/src/entities/Player.ts +0 -52
  505. package/templates/defense/src/game.ts +0 -51
  506. package/templates/defense/src/physics.ts +0 -13
  507. package/templates/defense/src/placement/Buildable.ts +0 -49
  508. package/templates/defense/src/render/camera.ts +0 -16
  509. package/templates/defense/src/render/lighting.ts +0 -37
  510. package/templates/defense/src/render/materials.ts +0 -22
  511. package/templates/defense/src/render/palette.ts +0 -28
  512. package/templates/defense/src/render/quality.ts +0 -170
  513. package/templates/defense/src/render/shapes.ts +0 -246
  514. package/templates/defense/src/render/sky.ts +0 -45
  515. package/templates/defense/src/scenes/Boot.ts +0 -12
  516. package/templates/defense/src/scenes/Defense.ts +0 -231
  517. package/templates/defense/src/state.ts +0 -56
  518. package/templates/defense/src/towers/Tower.ts +0 -95
  519. package/templates/defense/src/towers/targeting.ts +0 -53
  520. package/templates/defense/src/ui/Hud.tsx +0 -62
  521. package/templates/defense/src/ui/Menu.tsx +0 -7
  522. package/templates/defense/src/waves.ts +0 -40
  523. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  524. package/templates/minimal/src/render/hud.ts +0 -69
  525. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  526. package/templates/platformer/playtests/chase.playtest.json +0 -21
  527. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  528. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  529. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  530. package/templates/platformer/playtests/physics.playtest.json +0 -14
  531. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  532. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  533. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  534. package/templates/platformer/src/conventions.ts +0 -18
  535. package/templates/platformer/src/entities/Character.ts +0 -286
  536. package/templates/platformer/src/entities/Chaser.ts +0 -118
  537. package/templates/platformer/src/entities/Patrol.ts +0 -93
  538. package/templates/platformer/src/level/Platform.ts +0 -46
  539. package/templates/platformer/src/render/rig.ts +0 -60
  540. package/templates/platformer/src/render/terrain.ts +0 -31
  541. package/templates/platformer/src/scenes/Level.ts +0 -241
  542. package/templates/puzzle/README.md +0 -43
  543. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  544. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  545. package/templates/puzzle/src/conventions.ts +0 -25
  546. package/templates/puzzle/src/entities/Ball.ts +0 -70
  547. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  548. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  549. package/templates/puzzle/src/physics.ts +0 -19
  550. package/templates/puzzle/src/room.ts +0 -83
  551. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  552. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  553. package/templates/shooter/playtests/combat.playtest.json +0 -48
  554. package/templates/shooter/playtests/fail.playtest.json +0 -31
  555. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  556. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  557. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  558. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  559. package/templates/shooter/src/combat/damage.ts +0 -40
  560. package/templates/shooter/src/conventions.ts +0 -51
  561. package/templates/shooter/src/entities/Pickup.ts +0 -70
  562. package/templates/shooter/src/entities/Player.ts +0 -310
  563. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  564. package/templates/shooter/src/playtest-events.ts +0 -15
  565. package/templates/shooter/src/render/touch-controls.ts +0 -305
  566. package/templates/shooter/src/render/types.ts +0 -3
  567. package/templates/shooter/src/render/ui.css +0 -330
  568. package/templates/shooter/src/render/ui.ts +0 -75
  569. package/templates/shooter/src/render/vfx.ts +0 -215
  570. package/templates/shooter/src/ui/Menu.tsx +0 -41
  571. package/templates/shooter/src/waves.ts +0 -50
  572. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  573. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  574. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  575. package/templates/starter/playtests/assets.playtest.json +0 -65
  576. package/templates/starter/playtests/buffer.playtest.json +0 -79
  577. package/templates/starter/playtests/cloth.playtest.json +0 -113
  578. package/templates/starter/playtests/coyote.playtest.json +0 -87
  579. package/templates/starter/playtests/gameover.playtest.json +0 -66
  580. package/templates/starter/playtests/goal.playtest.json +0 -67
  581. package/templates/starter/playtests/look.playtest.json +0 -175
  582. package/templates/starter/playtests/models-baseline.png +0 -0
  583. package/templates/starter/playtests/models.playtest.json +0 -74
  584. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  585. package/templates/starter/playtests/odometer.playtest.json +0 -54
  586. package/templates/starter/playtests/restart.playtest.json +0 -91
  587. package/templates/starter/playtests/seed.playtest.json +0 -54
  588. package/templates/starter/playtests/textures-baseline.png +0 -0
  589. package/templates/starter/playtests/textures.playtest.json +0 -74
  590. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  591. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  592. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  593. package/templates/starter/src/render/coast.ts +0 -199
  594. package/templates/starter/src/render/hero.ts +0 -88
  595. package/templates/starter/src/render/implicitSurface.ts +0 -199
  596. package/templates/starter/src/render/kuwahara.ts +0 -174
  597. package/templates/starter/src/render/outline.ts +0 -141
  598. package/templates/starter/src/render/painterly.ts +0 -86
  599. package/templates/starter/src/render/rockRidge.ts +0 -198
  600. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  601. package/templates/starter/src/render/scenery.ts +0 -40
  602. package/templates/starter/src/render/textureLifetime.ts +0 -53
  603. package/templates/starter/src/render/water.ts +0 -38
  604. package/templates/starter/src/render/watercolor.ts +0 -85
  605. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  606. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  607. /package/templates/{defense → rts}/.codex/config.toml +0 -0
  608. /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
  609. /package/templates/{defense → rts}/.gemini/settings.json +0 -0
  610. /package/templates/{defense → rts}/.mcp.json +0 -0
  611. /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
  612. /package/templates/{defense → rts}/.zed/settings.json +0 -0
  613. /package/templates/{defense → rts}/index.html +0 -0
  614. /package/templates/{defense → rts}/opencode.json +0 -0
  615. /package/templates/{defense → rts}/src/main.ts +0 -0
  616. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  617. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  618. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  619. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  620. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  621. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  622. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
package/README.md CHANGED
@@ -6,7 +6,7 @@ Scaffold a ThreeNative game:
6
6
  pnpm create threenative my-game
7
7
  ```
8
8
 
9
- The default template is `starter`. Choose `minimal`, `platformer`, `action-rpg`, `defense`,
9
+ The default template is `starter`. Choose `minimal`, `platformer`, `action-rpg`, `tower-defense`,
10
10
  `racing`, `sailing`, or `shooter` for a different starting point:
11
11
 
12
12
  ```sh
@@ -14,7 +14,7 @@ pnpm create threenative my-game --template minimal
14
14
  pnpm create threenative my-game --template starter
15
15
  pnpm create threenative my-game --template platformer
16
16
  pnpm create threenative my-game --template action-rpg
17
- pnpm create threenative my-game --template defense
17
+ pnpm create threenative my-game --template tower-defense
18
18
  pnpm create threenative my-game --template racing
19
19
  pnpm create threenative my-game --template sailing
20
20
  pnpm create threenative my-game --template shooter
@@ -0,0 +1,126 @@
1
+ # Cook profiles — one asset tree, a different representation per artifact
2
+
3
+ Companion to the commented `buildProfiles` example in this project's `threenative.config.ts`. A
4
+ profile is **not** a second asset pipeline: it is one compiler, run with different
5
+ resource-processing options, so the phone build can ship smaller bytes out of the same sources you
6
+ already committed. With no `buildProfiles` block every build behaves exactly as it always has —
7
+ this is opt-in and the ordinary `assets` block still means what it means.
8
+
9
+ ```ts
10
+ buildProfiles: {
11
+ defaults: { android: "compact" }, // a target's default profile
12
+ profiles: {
13
+ compact: {
14
+ assets: { textures: { maxSize: 1024 }, models: { textures: { maxSize: 1024 } } },
15
+ artifactBudget: { packagedAssetBytes: { limit: 18_000_000, severity: "error" } },
16
+ performanceBudget: { maxDrawCalls: 300, maxFrameMsP95: 22 },
17
+ },
18
+ },
19
+ },
20
+ ```
21
+
22
+ ## Which profile a build cooks
23
+
24
+ 1. `threenative build --target android --profile compact` — **the flag wins.**
25
+ 2. `buildProfiles.defaults.android` — the target's own default.
26
+ 3. Neither — the `assets` block is used exactly as declared.
27
+
28
+ Every build that selects a profile announces it before it cooks, so a log never leaves you guessing
29
+ which representation produced the bytes:
30
+
31
+ ```
32
+ threenative build: profile compact (flag) for web
33
+ threenative build: profile compact (default) for android
34
+ ```
35
+
36
+ An unknown name fails the build by name (`TN_CONFIG_PROFILE_UNKNOWN`, listing the profiles this
37
+ project declares) **before any asset is encoded**, rather than shipping the wrong representation.
38
+ Every declared profile is validated, not only the selected one, so a broken budget cannot lie in
39
+ wait for the day someone names that profile.
40
+
41
+ ## What an overlay may change
42
+
43
+ `profiles.<name>.assets` may change `audio`, `budget`, `lod`, `models`, `targets` and `textures`
44
+ — the *processing* options. It may **not** restate `source`, `output` or `exclude`: the directory
45
+ tree being compiled, where it is written, and what is left out are one answer for the whole
46
+ project, because two profiles disagreeing about the source tree is a build that cooks half a game.
47
+ Those keys are refused.
48
+
49
+ The cap is `maxSize` on the longest edge, preserving aspect and 4x4 alignment, and never
50
+ upscaling — a 512² source under `maxSize: 1024` ships byte-identical. `assets.models.textures.maxSize`
51
+ caps the images carried *inside* a `.glb`, and the two caps key apart: capping one never renames or
52
+ re-encodes the other.
53
+
54
+ **A cap and a `codec: "none"` override cannot both be true**, and the build says so
55
+ (`TN_CONFIG_PROFILE_CONFLICT`): that override returns the authored bytes before resizing, so the
56
+ cap would silently do nothing. Drop the override or take the cap out of the profile.
57
+
58
+ ## Native is decoder-free, and the cap still holds
59
+
60
+ Android and iOS ship no WASM, so no KTX2 transcoder and no Meshopt/Draco decoder exists in the
61
+ bundle — a phone cannot decode them, so the cook never produces them. A cap on such a target is
62
+ applied by **resizing the image during the compile** and shipping a PNG, not by writing a KTX2
63
+ nobody could read. The dimension you asked for is the dimension the file decodes to, alpha kept, and
64
+ the source on disk is never modified. Meshopt output is omitted for the same reason.
65
+
66
+ That is also why `assets.budget`'s `uncooked` ceiling is exempt on a mobile target without
67
+ decoders: those bytes are deliberately left raw, not accidentally uncooked. Read the two numbers
68
+ separately — see `agent-docs/mobile-memory-budget.md` for what a decoded image actually costs a
69
+ phone.
70
+
71
+ ## Byte budgets, and what the two numbers are
72
+
73
+ `artifactBudget` is a ceiling on **what the build produced**, measured on the staged artifact
74
+ before it is published:
75
+
76
+ - `artifactBytes` — the produced artifact: a file, or the recursive sum of a directory, `.app`
77
+ bundle or outDir. It is everything the player downloads or installs, code included.
78
+ - `packagedAssetBytes` — the sum of the **asset files that survived the packaging selector**: the
79
+ manifest-declared closure that was actually staged. This is the number to write when the question
80
+ is "did the cook do its job".
81
+
82
+ Each is `{ limit, severity }`. `"error"` refuses the build and leaves the previous artifact exactly
83
+ where it was — the new one is published only when every gate has passed; `"warn"` prints and
84
+ publishes. Neither is a judgement about the look: a profile can ship a smaller image, and what that
85
+ image looks like is still yours.
86
+
87
+ ## Frame budgets are not measured by the build
88
+
89
+ `performanceBudget` takes the harness's own `assert.performance` fields — `minFps`, `maxFrameMsP95`,
90
+ `maxDrawCalls`, `maxTriangles`, `maxPassDrawCalls`, `maxPassTriangles`, `maxPhaseMsP95` (phases
91
+ `hostGap`, `update`, `render`, `overlay`, `residual`; passes `main`, `shadow`, `reflection`,
92
+ `nested`). The build cannot measure any of it — those numbers only exist once a runtime drew frames
93
+ — so a performance budget never refuses a build and never passes one. It is published into the
94
+ build report and enforced by the next run.
95
+
96
+ ## `--build-report` carries the budget with the bytes
97
+
98
+ Every build publishes `<artifact>.build-report.json` **atomically beside the artifact it wrote**:
99
+ `schemaVersion`, `target`, `profile`, the artifact's `sha256`, the manifest's `sha256`, the two
100
+ measured byte counts, and the `performanceBudget` (or `null`). A report that exists is a build that
101
+ finished.
102
+
103
+ ```sh
104
+ npx threenative-playtest playtests/survives.playtest.json --url http://127.0.0.1:5173 \
105
+ --build-report dist.build-report.json --artifact dist --browser-recipe webgpu
106
+ ```
107
+
108
+ The runner re-hashes the artifact under test and refuses the run when it is not the one the report
109
+ describes (`TN_PLAYTEST_BUILD_REPORT_STALE`, naming both digests) — a budget measured on other bytes
110
+ bounds nothing. It also refuses a report for a different target, a malformed report, and a budget
111
+ the target cannot observe. Otherwise the budget merges **per key** into the scenario's
112
+ `assert.performance`, and the scenario's own value wins where it declares one. `--artifact` is
113
+ required on browser and Android because nothing else says which build the run exercises; `--target
114
+ desktop` and `--target ios` already name it.
115
+
116
+ ## Appearance is still yours
117
+
118
+ A profile changes representation, not look: which bytes reach the disk, and the ceilings that hold
119
+ the build to them. Materials, shaders, lighting, tone mapping, post and framing are your
120
+ `src/render/` code and stay there — the same `1024²` texture under a different sampler, a different
121
+ mip bias and a different exposure is three different looks from one profile. If a profile makes the
122
+ game look wrong, fix the appearance in your own source; do not reach for a byte ceiling to hide it.
123
+
124
+ To see what a cook actually chose, read the manifest's `via` for the assets your scenario loads, or
125
+ `ctx.assets.resolved` in the running game, which reports each logical path's URL and the `via` that
126
+ resolved it (`manifest` or the no-manifest `source` fallback).