create-threenative 0.2.5 → 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 (631) hide show
  1. package/README.md +25 -3
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/build-profiles.md +126 -0
  4. package/agent-docs/references/capability-reference.md +1382 -65
  5. package/agent-docs/references/finding-assets.md +8 -1
  6. package/agent-docs/references/performance-basics.md +117 -0
  7. package/agent-docs/references/rigging-characters.md +51 -0
  8. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  9. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  10. package/agent-docs/references/visual-baseline.md +8 -4
  11. package/agent-docs/references/webview-ui.md +3 -2
  12. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  13. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  14. package/agent-files/.agents/skills/threenative-assets/SKILL.md +12 -4
  15. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  16. package/agent-files/.agents/skills/threenative-context/SKILL.md +9 -1
  17. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  19. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  20. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  21. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  22. package/agent-files/.claude/settings.json +38 -0
  23. package/agent-files/.codex/hooks.json +40 -0
  24. package/capabilities.json +1891 -101
  25. package/dist/index.d.ts +39 -1
  26. package/dist/index.js +480 -56
  27. package/dist/threenative.js +1247 -177
  28. package/package.json +6 -6
  29. package/template-assets/assets/mannequin-combat.glb +0 -0
  30. package/template-assets/assets/mannequin.glb +0 -0
  31. package/template-assets/assets/player-viewmodel.glb +0 -0
  32. package/template-assets/assets/sky.jpg +0 -0
  33. package/template-assets/clearwater/README.md +141 -0
  34. package/template-assets/clearwater/install.mjs +50 -0
  35. package/template-assets/clearwater/src/clearwater.ts +180 -0
  36. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  37. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  38. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  39. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  40. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  41. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  42. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  43. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  44. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  45. package/template-assets/patches/three@0.185.1.patch +2228 -105
  46. package/template-assets/worldEnvironment.ts +52 -1
  47. package/templates/action-rpg/AGENTS.md +43 -43
  48. package/templates/action-rpg/CLAUDE.md +43 -43
  49. package/templates/action-rpg/kit.json +1 -1
  50. package/templates/action-rpg/package.json +14 -8
  51. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  52. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  53. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  54. package/templates/action-rpg/src/conventions.ts +24 -18
  55. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  56. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  57. package/templates/action-rpg/src/entities/Player.ts +102 -32
  58. package/templates/action-rpg/src/game.ts +3 -3
  59. package/templates/action-rpg/src/render/camera.ts +18 -16
  60. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  61. package/templates/action-rpg/src/render/lighting.ts +45 -28
  62. package/templates/action-rpg/src/render/loading.ts +4 -4
  63. package/templates/action-rpg/src/render/materials.ts +191 -47
  64. package/templates/action-rpg/src/render/palette.ts +14 -13
  65. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  66. package/templates/action-rpg/src/render/props.ts +117 -0
  67. package/templates/action-rpg/src/render/quality.ts +40 -82
  68. package/templates/action-rpg/src/render/sky.ts +36 -13
  69. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  71. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  72. package/templates/action-rpg/src/style.css +9 -7
  73. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  74. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  75. package/templates/action-rpg/threenative.config.ts +14 -1
  76. package/templates/action-rpg/vite.config.ts +4 -1
  77. package/templates/minimal/AGENTS.md +12 -12
  78. package/templates/minimal/CLAUDE.md +12 -12
  79. package/templates/minimal/package.json +13 -7
  80. package/templates/minimal/playtests/play.playtest.json +6 -5
  81. package/templates/minimal/playtests/sky.playtest.json +27 -0
  82. package/templates/minimal/src/conventions.ts +6 -3
  83. package/templates/minimal/src/entities/Player.ts +73 -27
  84. package/templates/minimal/src/main.ts +2 -3
  85. package/templates/minimal/src/render/camera.ts +22 -4
  86. package/templates/minimal/src/render/lighting.ts +24 -48
  87. package/templates/minimal/src/render/materials.ts +158 -13
  88. package/templates/minimal/src/render/palette.ts +10 -7
  89. package/templates/minimal/src/render/postprocessing.ts +12 -25
  90. package/templates/minimal/src/render/quality.ts +35 -69
  91. package/templates/minimal/src/render/sky.ts +35 -54
  92. package/templates/minimal/src/render/touch-controls.ts +1 -1
  93. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  94. package/templates/minimal/src/scenes/Play.ts +121 -111
  95. package/templates/minimal/src/state.ts +0 -4
  96. package/templates/minimal/src/style.css +0 -10
  97. package/templates/minimal/threenative.config.ts +15 -1
  98. package/templates/minimal/vite.config.ts +4 -1
  99. package/templates/platformer/AGENTS.md +18 -56
  100. package/templates/platformer/CLAUDE.md +18 -56
  101. package/templates/platformer/kit.json +2 -2
  102. package/templates/platformer/package.json +14 -10
  103. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  104. package/templates/platformer/playtests/collect.playtest.json +8 -34
  105. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  106. package/templates/platformer/playtests/damage.playtest.json +40 -15
  107. package/templates/platformer/playtests/hud.playtest.json +34 -0
  108. package/templates/platformer/playtests/move.playtest.json +24 -0
  109. package/templates/platformer/playtests/performance.playtest.json +24 -7
  110. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  111. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  112. package/templates/platformer/playtests/survives.playtest.json +3 -19
  113. package/templates/platformer/playtests/world.playtest.json +26 -0
  114. package/templates/platformer/src/entities/Fox.ts +273 -0
  115. package/templates/platformer/src/entities/Pickup.ts +43 -60
  116. package/templates/platformer/src/entities/Walker.ts +88 -0
  117. package/templates/platformer/src/game.ts +11 -8
  118. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  119. package/templates/platformer/src/level/Stage.ts +469 -0
  120. package/templates/platformer/src/render/blocks.ts +94 -0
  121. package/templates/platformer/src/render/camera.ts +28 -3
  122. package/templates/platformer/src/render/fox.ts +196 -0
  123. package/templates/platformer/src/render/lighting.ts +42 -33
  124. package/templates/platformer/src/render/materials.ts +115 -5
  125. package/templates/platformer/src/render/palette.ts +68 -53
  126. package/templates/platformer/src/render/pickups.ts +142 -0
  127. package/templates/platformer/src/render/postprocessing.ts +12 -2
  128. package/templates/platformer/src/render/props.ts +147 -0
  129. package/templates/platformer/src/render/quality.ts +47 -99
  130. package/templates/platformer/src/render/scenery.ts +172 -0
  131. package/templates/platformer/src/render/sky.ts +120 -31
  132. package/templates/platformer/src/render/touch-controls.ts +5 -2
  133. package/templates/platformer/src/render/walkers.ts +96 -0
  134. package/templates/platformer/src/render/waterfall.ts +85 -0
  135. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  136. package/templates/platformer/src/scenes/Boot.ts +3 -4
  137. package/templates/platformer/src/scenes/Play.ts +362 -0
  138. package/templates/platformer/src/state.ts +16 -14
  139. package/templates/platformer/src/style.css +9 -8
  140. package/templates/platformer/src/ui/Hud.tsx +62 -29
  141. package/templates/platformer/src/ui/Menu.tsx +2 -2
  142. package/templates/platformer/threenative.config.ts +14 -1
  143. package/templates/platformer/vite.config.ts +4 -1
  144. package/templates/puzzle/AGENTS.md +21 -22
  145. package/templates/puzzle/CLAUDE.md +21 -22
  146. package/templates/puzzle/assets/native-proof.glb +0 -0
  147. package/templates/puzzle/assets/native-proof.png +0 -0
  148. package/templates/puzzle/kit.json +1 -1
  149. package/templates/puzzle/package.json +14 -8
  150. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  151. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  152. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  153. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  154. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  155. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  156. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  157. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  158. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  159. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  160. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  161. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  162. package/templates/puzzle/src/entities/Crate.ts +99 -42
  163. package/templates/puzzle/src/entities/Seal.ts +69 -0
  164. package/templates/puzzle/src/entities/Warden.ts +135 -0
  165. package/templates/puzzle/src/game.ts +15 -11
  166. package/templates/puzzle/src/render/camera.ts +66 -31
  167. package/templates/puzzle/src/render/crateShape.ts +70 -0
  168. package/templates/puzzle/src/render/lighting.ts +41 -41
  169. package/templates/puzzle/src/render/loading.ts +4 -4
  170. package/templates/puzzle/src/render/materials.ts +131 -27
  171. package/templates/puzzle/src/render/palette.ts +19 -29
  172. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  173. package/templates/puzzle/src/render/quality.ts +71 -80
  174. package/templates/puzzle/src/render/shapes.ts +109 -108
  175. package/templates/puzzle/src/render/sky.ts +18 -10
  176. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  177. package/templates/puzzle/src/render/vault.ts +315 -0
  178. package/templates/puzzle/src/render/warden.ts +46 -0
  179. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  180. package/templates/puzzle/src/scenes/Play.ts +793 -0
  181. package/templates/puzzle/src/state.ts +55 -24
  182. package/templates/puzzle/src/style.css +7 -8
  183. package/templates/puzzle/src/ui/App.tsx +2 -2
  184. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  185. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  186. package/templates/puzzle/threenative.config.ts +14 -1
  187. package/templates/puzzle/vite.config.ts +4 -1
  188. package/templates/racing/AGENTS.md +20 -21
  189. package/templates/racing/CLAUDE.md +20 -21
  190. package/templates/racing/package.json +14 -8
  191. package/templates/racing/playtests/boost.playtest.json +33 -12
  192. package/templates/racing/playtests/outcome.playtest.json +32 -50
  193. package/templates/racing/playtests/performance.playtest.json +2 -1
  194. package/templates/racing/playtests/ranking.playtest.json +5 -14
  195. package/templates/racing/playtests/rescue.playtest.json +2 -2
  196. package/templates/racing/playtests/reverse.playtest.json +30 -8
  197. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  198. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  199. package/templates/racing/src/entities/CarBody.ts +327 -0
  200. package/templates/racing/src/entities/LineDriver.ts +220 -0
  201. package/templates/racing/src/entities/RacingCar.ts +150 -89
  202. package/templates/racing/src/entities/Rival.ts +61 -24
  203. package/templates/racing/src/game.ts +5 -0
  204. package/templates/racing/src/render/camera.ts +49 -7
  205. package/templates/racing/src/render/lighting.ts +36 -37
  206. package/templates/racing/src/render/materials.ts +239 -19
  207. package/templates/racing/src/render/palette.ts +19 -21
  208. package/templates/racing/src/render/postprocessing.ts +12 -2
  209. package/templates/racing/src/render/quality.ts +43 -82
  210. package/templates/racing/src/render/shapes.ts +20 -6
  211. package/templates/racing/src/render/sky.ts +47 -39
  212. package/templates/racing/src/render/touch-controls.ts +1 -1
  213. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  214. package/templates/racing/src/scenes/Race.ts +107 -54
  215. package/templates/racing/src/state.ts +2 -0
  216. package/templates/racing/src/track/Checkline.ts +22 -7
  217. package/templates/racing/src/track/Lap.ts +64 -36
  218. package/templates/racing/src/track/Ranking.ts +20 -11
  219. package/templates/racing/src/track/Track.ts +809 -361
  220. package/templates/racing/src/track/TrackSector.ts +40 -11
  221. package/templates/racing/src/track/circuit.ts +477 -0
  222. package/templates/racing/src/track/rescue.ts +16 -4
  223. package/templates/racing/threenative.config.ts +14 -1
  224. package/templates/racing/vite.config.ts +4 -1
  225. package/templates/rts/AGENTS.md +96 -0
  226. package/templates/rts/CLAUDE.md +98 -0
  227. package/templates/rts/kit.json +7 -0
  228. package/templates/{defense → rts}/package.json +14 -8
  229. package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
  230. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  231. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  232. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  233. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  234. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  235. package/templates/rts/playtests/survives.playtest.json +58 -0
  236. package/templates/rts/public/favicon.svg +4 -0
  237. package/templates/rts/src/game.ts +64 -0
  238. package/templates/rts/src/orders.ts +22 -0
  239. package/templates/rts/src/render/army.ts +346 -0
  240. package/templates/rts/src/render/camera.ts +123 -0
  241. package/templates/rts/src/render/lighting.ts +61 -0
  242. package/templates/rts/src/render/loading.ts +33 -0
  243. package/templates/rts/src/render/materials.ts +152 -0
  244. package/templates/rts/src/render/models.ts +705 -0
  245. package/templates/rts/src/render/palette.ts +17 -0
  246. package/templates/rts/src/render/picking.ts +93 -0
  247. package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
  248. package/templates/rts/src/render/quality.ts +128 -0
  249. package/templates/rts/src/render/resources.ts +141 -0
  250. package/templates/rts/src/render/sky.ts +44 -0
  251. package/templates/rts/src/render/terrain.ts +116 -0
  252. package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
  253. package/templates/rts/src/scenes/Play.ts +650 -0
  254. package/templates/rts/src/sim/ai.ts +1140 -0
  255. package/templates/rts/src/sim/combat.ts +416 -0
  256. package/templates/rts/src/sim/construction.ts +374 -0
  257. package/templates/rts/src/sim/economy.ts +167 -0
  258. package/templates/rts/src/sim/game.ts +1082 -0
  259. package/templates/rts/src/sim/movement.ts +371 -0
  260. package/templates/rts/src/sim/nav.ts +276 -0
  261. package/templates/rts/src/sim/production.ts +180 -0
  262. package/templates/rts/src/sim/terrain.ts +170 -0
  263. package/templates/rts/src/sim/types.ts +647 -0
  264. package/templates/rts/src/sim/vision.ts +46 -0
  265. package/templates/rts/src/state.ts +100 -0
  266. package/templates/{defense → rts}/src/style.css +21 -8
  267. package/templates/rts/src/ui/App.tsx +21 -0
  268. package/templates/rts/src/ui/Commands.tsx +129 -0
  269. package/templates/rts/src/ui/GameUi.tsx +22 -0
  270. package/templates/rts/src/ui/Hud.tsx +165 -0
  271. package/templates/rts/src/ui/Minimap.tsx +84 -0
  272. package/templates/rts/tailwind.config.ts +2 -0
  273. package/templates/rts/threenative.config.ts +56 -0
  274. package/templates/rts/tsconfig.json +17 -0
  275. package/templates/{defense → rts}/vite.config.ts +4 -1
  276. package/templates/runner/AGENTS.md +8 -12
  277. package/templates/runner/CLAUDE.md +8 -12
  278. package/templates/runner/README.md +3 -3
  279. package/templates/runner/package.json +14 -8
  280. package/templates/runner/playtests/performance.playtest.json +2 -2
  281. package/templates/runner/src/conventions.ts +4 -3
  282. package/templates/runner/src/entities/Runner.ts +54 -7
  283. package/templates/runner/src/game.ts +2 -0
  284. package/templates/runner/src/render/camera.ts +4 -2
  285. package/templates/runner/src/render/dust.ts +5 -2
  286. package/templates/runner/src/render/lighting.ts +41 -45
  287. package/templates/runner/src/render/loading.ts +2 -2
  288. package/templates/runner/src/render/materials.ts +165 -25
  289. package/templates/runner/src/render/palette.ts +17 -28
  290. package/templates/runner/src/render/postprocessing.ts +12 -2
  291. package/templates/runner/src/render/quality.ts +42 -96
  292. package/templates/runner/src/render/shapes.ts +59 -37
  293. package/templates/runner/src/render/sky.ts +32 -41
  294. package/templates/runner/src/render/touch-controls.ts +1 -1
  295. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  296. package/templates/runner/src/scenes/Run.ts +26 -6
  297. package/templates/runner/src/track.ts +6 -1
  298. package/templates/runner/threenative.config.ts +14 -1
  299. package/templates/runner/vite.config.ts +4 -1
  300. package/templates/sailing/AGENTS.md +14 -14
  301. package/templates/sailing/CLAUDE.md +14 -14
  302. package/templates/sailing/assets/ship.glb +0 -0
  303. package/templates/sailing/package.json +14 -8
  304. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  305. package/templates/sailing/playtests/sails.playtest.json +33 -0
  306. package/templates/sailing/playtests/win.playtest.json +156 -8
  307. package/templates/sailing/src/conventions.ts +29 -2
  308. package/templates/sailing/src/entities/Ship.ts +381 -57
  309. package/templates/sailing/src/game.ts +14 -0
  310. package/templates/sailing/src/render/camera.ts +63 -9
  311. package/templates/sailing/src/render/lighting.ts +49 -27
  312. package/templates/sailing/src/render/materials.ts +50 -15
  313. package/templates/sailing/src/render/ocean.ts +647 -60
  314. package/templates/sailing/src/render/palette.ts +16 -12
  315. package/templates/sailing/src/render/postprocessing.ts +12 -2
  316. package/templates/sailing/src/render/props.ts +316 -442
  317. package/templates/sailing/src/render/quality.ts +14 -4
  318. package/templates/sailing/src/render/sky.ts +116 -23
  319. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  320. package/templates/sailing/src/scenes/Boot.ts +21 -0
  321. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  322. package/templates/sailing/src/state.ts +6 -0
  323. package/templates/sailing/src/ui/Hud.tsx +41 -9
  324. package/templates/sailing/threenative.config.ts +14 -1
  325. package/templates/sailing/vite.config.ts +4 -1
  326. package/templates/shooter/AGENTS.md +29 -44
  327. package/templates/shooter/CLAUDE.md +29 -44
  328. package/templates/shooter/index.html +1 -0
  329. package/templates/shooter/package.json +14 -8
  330. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  331. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  332. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  333. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  334. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  335. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  336. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  337. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  338. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  339. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  340. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  341. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  342. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  343. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  344. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  345. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  346. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  347. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  348. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  349. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  350. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  351. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  352. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  353. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  354. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  355. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  356. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  357. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  358. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  359. package/templates/shooter/playtests/performance.playtest.json +62 -26
  360. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  361. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  362. package/templates/shooter/playtests/survives.playtest.json +36 -30
  363. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  364. package/templates/shooter/src/entities/Breakables.ts +412 -0
  365. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  366. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  367. package/templates/shooter/src/entities/Rifle.ts +442 -0
  368. package/templates/shooter/src/entities/Target.ts +199 -83
  369. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  370. package/templates/shooter/src/game.ts +75 -41
  371. package/templates/shooter/src/main.ts +0 -1
  372. package/templates/shooter/src/postPhysics.ts +36 -0
  373. package/templates/shooter/src/render/camera.ts +78 -74
  374. package/templates/shooter/src/render/decals.ts +142 -82
  375. package/templates/shooter/src/render/facade.ts +1373 -0
  376. package/templates/shooter/src/render/gunfx.ts +704 -0
  377. package/templates/shooter/src/render/lighting.ts +52 -38
  378. package/templates/shooter/src/render/loading.ts +2 -2
  379. package/templates/shooter/src/render/materials.ts +100 -88
  380. package/templates/shooter/src/render/occlusion.ts +108 -0
  381. package/templates/shooter/src/render/palette.ts +10 -10
  382. package/templates/shooter/src/render/palm.ts +455 -0
  383. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  384. package/templates/shooter/src/render/postprocessing.ts +15 -3
  385. package/templates/shooter/src/render/quality.ts +40 -82
  386. package/templates/shooter/src/render/scale.ts +148 -15
  387. package/templates/shooter/src/render/shapes.ts +138 -613
  388. package/templates/shooter/src/render/sky.ts +35 -35
  389. package/templates/shooter/src/render/town-schematic.ts +120 -0
  390. package/templates/shooter/src/render/town.ts +986 -0
  391. package/templates/shooter/src/render/townMaterials.ts +160 -0
  392. package/templates/shooter/src/render/vehicles.ts +741 -0
  393. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  394. package/templates/shooter/src/scenes/Play.ts +727 -650
  395. package/templates/shooter/src/state.ts +26 -41
  396. package/templates/shooter/src/style.css +207 -11
  397. package/templates/shooter/src/surfaces.ts +131 -0
  398. package/templates/shooter/src/ui/App.tsx +9 -10
  399. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  400. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  401. package/templates/shooter/src/ui/Hud.tsx +428 -39
  402. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  403. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  404. package/templates/shooter/src/ui/main.tsx +2 -3
  405. package/templates/shooter/threenative.config.ts +14 -1
  406. package/templates/shooter/vite.config.ts +4 -1
  407. package/templates/starter/AGENTS.md +20 -20
  408. package/templates/starter/CLAUDE.md +20 -20
  409. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  410. package/templates/starter/package.json +15 -9
  411. package/templates/starter/playtests/play.playtest.json +2 -1
  412. package/templates/starter/playtests/{restart.playtest.json → production-readiness.playtest.json} +17 -12
  413. package/templates/starter/playtests/survives.playtest.json +1 -1
  414. package/templates/starter/src/conventions.ts +6 -3
  415. package/templates/starter/src/entities/Goal.ts +35 -42
  416. package/templates/starter/src/entities/Player.ts +99 -16
  417. package/templates/starter/src/render/arena.ts +131 -0
  418. package/templates/starter/src/render/lighting.ts +27 -44
  419. package/templates/starter/src/render/materials.ts +164 -35
  420. package/templates/starter/src/render/palette.ts +16 -16
  421. package/templates/starter/src/render/postprocessing.ts +6 -7
  422. package/templates/starter/src/render/quality.ts +43 -101
  423. package/templates/starter/src/render/shapes.ts +1 -1
  424. package/templates/starter/src/render/sky.ts +39 -45
  425. package/templates/starter/src/render/touch-controls.ts +3 -1
  426. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  427. package/templates/starter/src/scenes/Play.ts +82 -81
  428. package/templates/starter/src/ui/Hud.tsx +2 -2
  429. package/templates/starter/src/ui/Menu.tsx +5 -1
  430. package/templates/starter/threenative.config.ts +14 -1
  431. package/templates/starter/vite.config.ts +4 -1
  432. package/templates/tower-defense/.codex/config.toml +19 -0
  433. package/templates/tower-defense/.cursor/mcp.json +32 -0
  434. package/templates/tower-defense/.gemini/settings.json +32 -0
  435. package/templates/tower-defense/.mcp.json +32 -0
  436. package/templates/tower-defense/.vscode/mcp.json +36 -0
  437. package/templates/tower-defense/.zed/settings.json +36 -0
  438. package/templates/{defense → tower-defense}/AGENTS.md +16 -14
  439. package/templates/{defense → tower-defense}/CLAUDE.md +16 -14
  440. package/templates/tower-defense/README.md +16 -0
  441. package/templates/tower-defense/index.html +12 -0
  442. package/templates/tower-defense/kit.json +7 -0
  443. package/templates/tower-defense/opencode.json +41 -0
  444. package/templates/tower-defense/package.json +56 -0
  445. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  446. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  447. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  448. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  449. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  450. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  451. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  452. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  453. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  454. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  455. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  456. package/templates/tower-defense/src/balance.ts +187 -0
  457. package/templates/tower-defense/src/board/Board.ts +100 -0
  458. package/templates/tower-defense/src/board/Route.ts +84 -0
  459. package/templates/tower-defense/src/camera-rig.ts +62 -0
  460. package/templates/tower-defense/src/economy.ts +64 -0
  461. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  462. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  463. package/templates/tower-defense/src/game.ts +72 -0
  464. package/templates/tower-defense/src/intents.ts +21 -0
  465. package/templates/tower-defense/src/main.ts +15 -0
  466. package/templates/tower-defense/src/physics.ts +6 -0
  467. package/templates/tower-defense/src/render/camera.ts +38 -0
  468. package/templates/tower-defense/src/render/lighting.ts +42 -0
  469. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  470. package/templates/tower-defense/src/render/materials.ts +103 -0
  471. package/templates/tower-defense/src/render/palette.ts +58 -0
  472. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  473. package/templates/tower-defense/src/render/quality.ts +128 -0
  474. package/templates/tower-defense/src/render/shapes.ts +550 -0
  475. package/templates/tower-defense/src/render/sky.ts +27 -0
  476. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  477. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  478. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  479. package/templates/tower-defense/src/state.ts +88 -0
  480. package/templates/tower-defense/src/style.css +137 -0
  481. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  482. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  483. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  484. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  485. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  486. package/templates/tower-defense/src/ui/main.tsx +14 -0
  487. package/templates/tower-defense/src/waves.ts +90 -0
  488. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  489. package/templates/tower-defense/vite.config.ts +41 -0
  490. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  491. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  492. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -45
  493. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  494. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -57
  495. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -42
  496. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  497. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  498. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  499. package/agent-files/AGENT-ROLES.md +0 -26
  500. package/templates/action-rpg/src/render/shapes.ts +0 -269
  501. package/templates/action-rpg/src/render/types.ts +0 -3
  502. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  503. package/templates/defense/README.md +0 -10
  504. package/templates/defense/kit.json +0 -7
  505. package/templates/defense/playtests/leak.playtest.json +0 -23
  506. package/templates/defense/playtests/placement.playtest.json +0 -40
  507. package/templates/defense/playtests/scan.playtest.json +0 -20
  508. package/templates/defense/playtests/survive.playtest.json +0 -45
  509. package/templates/defense/playtests/survives.playtest.json +0 -36
  510. package/templates/defense/src/attackers/Attacker.ts +0 -120
  511. package/templates/defense/src/board/Route.ts +0 -94
  512. package/templates/defense/src/conventions.ts +0 -18
  513. package/templates/defense/src/economy.ts +0 -36
  514. package/templates/defense/src/entities/Player.ts +0 -52
  515. package/templates/defense/src/game.ts +0 -51
  516. package/templates/defense/src/physics.ts +0 -13
  517. package/templates/defense/src/placement/Buildable.ts +0 -49
  518. package/templates/defense/src/render/camera.ts +0 -16
  519. package/templates/defense/src/render/lighting.ts +0 -37
  520. package/templates/defense/src/render/materials.ts +0 -22
  521. package/templates/defense/src/render/palette.ts +0 -28
  522. package/templates/defense/src/render/quality.ts +0 -170
  523. package/templates/defense/src/render/shapes.ts +0 -246
  524. package/templates/defense/src/render/sky.ts +0 -45
  525. package/templates/defense/src/scenes/Boot.ts +0 -12
  526. package/templates/defense/src/scenes/Defense.ts +0 -231
  527. package/templates/defense/src/state.ts +0 -56
  528. package/templates/defense/src/towers/Tower.ts +0 -95
  529. package/templates/defense/src/towers/targeting.ts +0 -53
  530. package/templates/defense/src/ui/Hud.tsx +0 -62
  531. package/templates/defense/src/ui/Menu.tsx +0 -7
  532. package/templates/defense/src/waves.ts +0 -40
  533. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  534. package/templates/minimal/src/render/hud.ts +0 -69
  535. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  536. package/templates/platformer/playtests/chase.playtest.json +0 -21
  537. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  538. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  539. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  540. package/templates/platformer/playtests/physics.playtest.json +0 -14
  541. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  542. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  543. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  544. package/templates/platformer/src/conventions.ts +0 -18
  545. package/templates/platformer/src/entities/Character.ts +0 -286
  546. package/templates/platformer/src/entities/Chaser.ts +0 -118
  547. package/templates/platformer/src/entities/Patrol.ts +0 -93
  548. package/templates/platformer/src/level/Platform.ts +0 -46
  549. package/templates/platformer/src/render/rig.ts +0 -60
  550. package/templates/platformer/src/render/terrain.ts +0 -31
  551. package/templates/platformer/src/scenes/Level.ts +0 -241
  552. package/templates/puzzle/README.md +0 -43
  553. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  554. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  555. package/templates/puzzle/src/conventions.ts +0 -25
  556. package/templates/puzzle/src/entities/Ball.ts +0 -70
  557. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  558. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  559. package/templates/puzzle/src/physics.ts +0 -19
  560. package/templates/puzzle/src/room.ts +0 -83
  561. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  562. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  563. package/templates/shooter/playtests/combat.playtest.json +0 -48
  564. package/templates/shooter/playtests/fail.playtest.json +0 -31
  565. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  566. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  567. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  568. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  569. package/templates/shooter/src/combat/damage.ts +0 -40
  570. package/templates/shooter/src/conventions.ts +0 -51
  571. package/templates/shooter/src/entities/Pickup.ts +0 -70
  572. package/templates/shooter/src/entities/Player.ts +0 -310
  573. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  574. package/templates/shooter/src/playtest-events.ts +0 -15
  575. package/templates/shooter/src/render/touch-controls.ts +0 -305
  576. package/templates/shooter/src/render/types.ts +0 -3
  577. package/templates/shooter/src/render/ui.css +0 -330
  578. package/templates/shooter/src/render/ui.ts +0 -75
  579. package/templates/shooter/src/render/vfx.ts +0 -215
  580. package/templates/shooter/src/ui/Menu.tsx +0 -41
  581. package/templates/shooter/src/waves.ts +0 -50
  582. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  583. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  584. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  585. package/templates/starter/playtests/assets.playtest.json +0 -65
  586. package/templates/starter/playtests/buffer.playtest.json +0 -79
  587. package/templates/starter/playtests/cloth.playtest.json +0 -113
  588. package/templates/starter/playtests/coyote.playtest.json +0 -87
  589. package/templates/starter/playtests/gameover.playtest.json +0 -66
  590. package/templates/starter/playtests/goal.playtest.json +0 -67
  591. package/templates/starter/playtests/look.playtest.json +0 -175
  592. package/templates/starter/playtests/models-baseline.png +0 -0
  593. package/templates/starter/playtests/models.playtest.json +0 -74
  594. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  595. package/templates/starter/playtests/odometer.playtest.json +0 -54
  596. package/templates/starter/playtests/seed.playtest.json +0 -54
  597. package/templates/starter/playtests/textures-baseline.png +0 -0
  598. package/templates/starter/playtests/textures.playtest.json +0 -74
  599. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  600. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  601. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  602. package/templates/starter/src/render/coast.ts +0 -199
  603. package/templates/starter/src/render/hero.ts +0 -88
  604. package/templates/starter/src/render/implicitSurface.ts +0 -199
  605. package/templates/starter/src/render/kuwahara.ts +0 -174
  606. package/templates/starter/src/render/outline.ts +0 -141
  607. package/templates/starter/src/render/painterly.ts +0 -86
  608. package/templates/starter/src/render/rockRidge.ts +0 -198
  609. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  610. package/templates/starter/src/render/scenery.ts +0 -40
  611. package/templates/starter/src/render/textureLifetime.ts +0 -53
  612. package/templates/starter/src/render/water.ts +0 -38
  613. package/templates/starter/src/render/watercolor.ts +0 -85
  614. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  615. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  616. /package/templates/{defense → rts}/.codex/config.toml +0 -0
  617. /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
  618. /package/templates/{defense → rts}/.gemini/settings.json +0 -0
  619. /package/templates/{defense → rts}/.mcp.json +0 -0
  620. /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
  621. /package/templates/{defense → rts}/.zed/settings.json +0 -0
  622. /package/templates/{defense → rts}/index.html +0 -0
  623. /package/templates/{defense → rts}/opencode.json +0 -0
  624. /package/templates/{defense → rts}/src/main.ts +0 -0
  625. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  626. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  627. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  628. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  629. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  630. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  631. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
@@ -6,9 +6,16 @@ asset tools when the asset is conventional; build anything specific to this game
6
6
 
7
7
  Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
8
8
  your host lists its tools alongside your own. Your host reads that file from the directory it was
9
- launched in: start the session in this project, not in a parent of it. It advertises 40; these 8
9
+ launched in: start the session in this project, not in a parent of it. It advertises 44; these 8
10
10
  are the loop you will use for nearly everything:
11
11
 
12
+ For a humanoid that needs a skeleton or more motion, use the complete
13
+ [`rigging-characters.md`](rigging-characters.md) recipe. Inspect with `asset_inspect_rig`,
14
+ preserve or fit a rig with `asset_auto_rig`, select and bake donor clips with
15
+ `asset_retarget_animations`, and confirm the result with `asset_preview_animation` on a nonblank
16
+ contact sheet. AETHER / 02 is the pinned sample; its 18-bone rig has no fingers or toes, and the
17
+ tools report those absent roles instead of inventing them.
18
+
12
19
  For a bespoke animated creature, use the complete [`creating-creatures.md`](creating-creatures.md)
13
20
  recipe. It keeps the editable spec and claims under `.threenative/creatures/`, compiles the GLB
14
21
  into the configured `assets/` source, and requires independent preview review before game
@@ -0,0 +1,117 @@
1
+ # Performance basics — what the engine already does, and what you choose
2
+
3
+ Every frame this framework runs the same measured loop. Some performance work is done for you;
4
+ the rest is a content choice only the game can make. This page is the short list of both, so you
5
+ reach for the right abstraction before you profile anything.
6
+
7
+ ## The split
8
+
9
+ - **The engine decides what it can measure where it is used**: world-transform preparation, scene
10
+ batching and projection, per-pass culling, resolution, load scheduling, asset cooking, first-use
11
+ warmup, and the frame meter. Do not hand-roll these — a hand-rolled version usually costs you the
12
+ engine's version.
13
+ - **You decide what cannot be read from the code**: how much detail is on screen, how many objects,
14
+ what never moves, how far shadows reach, how many particles. Those are content decisions, and the
15
+ frame meter reports what they cost.
16
+
17
+ If you can measure the value where it is used, let the engine decide; a constant you are told to
18
+ revisit later is the engine's job, not yours.
19
+
20
+ ## Automatic — leave it alone
21
+
22
+ - **Scene batching and projection.** The engine merges equal geometry and material into fewer draws
23
+ and projects the authored scene automatically. A per-mesh `onBeforeRender` / `onAfterRender` hook
24
+ that packs buffers or mutates geometry makes the whole scene decline projection. Put once-per-draw
25
+ work in `ctx.beforeRender(fn)` instead: it runs after the frame's last fixed update and before
26
+ projection packs, on the batched and unbatched paths alike.
27
+ - **Transform preparation.** Exactly one world-matrix preparation runs per actual world draw. Never
28
+ call `updateMatrixWorld(true)` yourself, and do not set `scene.matrixWorldAutoUpdate = false`
29
+ unless you then update the scene yourself. Marking a measured-static subtree
30
+ `matrixWorldAutoUpdate = false` is allowed and the engine will skip it, but its parents must stay
31
+ still. For one node that never moves, `node.updateMatrix(); node.matrixAutoUpdate = false` is the
32
+ cheaper pair: it skips the per-object compose and leaves the walk intact.
33
+ - **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
34
+ and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
35
+ batch bounds that span the map.
36
+ - **The projected-size cut is yours to tune**, not the engine's: `renderer.minimumProjectedPixels`
37
+ (default `0.5`; a shipped title raised it to `2`) drops what the render camera cannot resolve
38
+ before it is submitted. Raise it before you write LOD machinery, and read `TN_PROJECTION` to see
39
+ how many objects it actually drops. Shadow casters are never dropped on the main view alone, so a
40
+ scene of small casters stays expensive — `castShadow = false` on props the cut would otherwise
41
+ drop is the game's call.
42
+ - **Resolution.** `render.resolutionScale: "auto"` holds GPU headroom and never lowers resolution
43
+ on a CPU overrun; `TN_FRAME_BUDGET` reports the scale actually used. A number is the named pin
44
+ override.
45
+ - **Quality.** Each template ships `src/render/quality.ts` (three tiers, platform default,
46
+ `TN_QUALITY_TIER`) and `adaptiveQuality.ts` (measured frame windows). Use the tiers; do not invent
47
+ a fourth switch.
48
+ - **Loading.** `loadAll(items, load)` loads with bounded concurrency and returns results in the
49
+ input's order. `addInSlices(objects, add)` attaches hundreds of objects across frames. A pool that
50
+ pushes results lands a different asset every load.
51
+ - **Assets.** The build cooks textures to KTX2/Basis, deduplicates model images and reports bytes;
52
+ `assets.budget` fails the build over a ceiling. Do not ship unpacked 4K textures and plan to
53
+ optimize later.
54
+ - **First use.** `warmUpScene(scene, camera)` compiles what a scene needs in slices, presenting a
55
+ frame between each. Warm up the real scene before interactive play; do not pre-touch every
56
+ possible variant.
57
+
58
+ ## Where the frame actually goes, in that order
59
+
60
+ Ask these three questions before you profile anything, because they decide who owns the fix:
61
+
62
+ 1. **Is the GPU busy?** `TN_FRAME_BUDGET` carries `gpuMs`. A frame with a 16 ms `render` phase and a
63
+ 2 ms GPU is not a rendering problem — the GPU is idle and waiting for JavaScript.
64
+ `gpuMs` is sampled one frame in eight (`renderer.gpuTimestampFrameInterval`, default `8`): reading
65
+ every pass of every frame cost native Midway 161 ms/s of main-thread JavaScript.
66
+ 2. **How many objects does the scene walk?** `TN_PROJECTION` reports `considered`, `culled`,
67
+ `exemptShadowCasters` and `exemptFrustumCulled` for the frame. Three.js visits every object once
68
+ per pass (main, each shadow, each reflection) and that visit is roughly 2 µs each on a desktop
69
+ core: 1,600 objects is ~3.5 ms of a 16 ms render before a single draw is issued. This is the
70
+ number to move, and the only lever is fewer objects.
71
+ 3. **Is it the engine's own work?** It usually is not: measured on a 1,561-mesh game, the engine's
72
+ whole share — camera cull, frame-op recorder, frame meter — was under 1.5 ms of a 20 ms frame,
73
+ with the rest being three.js's walk over the game's scene plus the game's own `update`.
74
+
75
+ A GPU that is idle with a slow `render` phase is an object-count problem, not a graphics problem.
76
+
77
+ ## Reach for these before you write your own
78
+
79
+ | You have | Use | What it gives you |
80
+ | --- | --- | --- |
81
+ | Many copies of one shape | `InstancedBatch` | One draw, no per-copy mesh |
82
+ | Many *different* shapes that never move relative to each other — a ship, a rig, a building, the static parts of an imported model | `mergeParts` | One mesh per material, so the walk visits one object instead of dozens; pass `preserve: ["uv", "normal"]` when the pieces carry authored normals or texture UVs |
83
+ | One over-detailed body seen at many distances | `ClusteredBatch` / `ClusteredMesh` | Each copy submits the detail its distance earns |
84
+ | A particle surface | `GPUParticles3D` | Pooled dispatch, game-owned appearance |
85
+ | Bullet streaks | `TracerPool3D` | Pooled travelling meshes |
86
+ | A sprite that faces the camera | `Billboard3D` | No hand-written per-frame orientation |
87
+ | One directional shadow over an open world | `VirtualShadowNode` | Camera-centred, texel-snapped clip levels; `trackCaster` for movers |
88
+ | Distance detail swaps | three's `LOD` | Standard, and the engine can still batch it |
89
+ | Raycasts over a large static scene | `GPUSceneBVH` / `ScenePicker` | Built once, queried many times |
90
+
91
+ ## The shortcuts that cost a frame
92
+
93
+ - One mesh per bullet or particle. Pool them (`TracerPool3D`, `GPUParticles3D`) or instance them.
94
+ - A fresh `Vector3`, array or object per entity inside `update`. Hoist it out of the loop and reuse
95
+ it; allocation shows up as GC in the trace, not in the average.
96
+ - A per-mesh render hook that packs buffers. That is `ctx.beforeRender` once per draw.
97
+ - Many shadow-casting lights, or one 4K shadow map for a whole valley. One directional light plus
98
+ `VirtualShadowNode`.
99
+ - The same large equirect on `scene.background` and `scene.environment`. The environment light is
100
+ charged again and moves in power-of-two steps — see `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`.
101
+ - A unique material or texture per copy. Share materials and images; the batcher merges equal
102
+ material and geometry.
103
+
104
+ ## Measure, then change one thing
105
+
106
+ `TN_FRAME_BUDGET` reports `fps`, `gpuMs` and the five phases (`update`, `render`, `overlay`,
107
+ `residual`, `hostGap`) plus per-pass draws and triangles; `TN_PROJECTION` reports the object census
108
+ (`considered`, `culled`, `exemptShadowCasters`) and the cut's threshold; `TN_RENDER_PROJECTION`
109
+ reports whether the scene batched and, when it did not, the reason. Launching with `DEV_MODE=true`
110
+ turns on the engine's dev surfaces (backtick opens the object and geometry inspector) and puts the
111
+ scene-shape verdict in a corner chip, so the engine's own finding is on screen while you play instead
112
+ of after you grep. It draws the verdict alone: the loop's rAF rate is throttled under a compositor or
113
+ a virtual display, so a frame rate read off that chip — or off a screenshot — is a number that lies
114
+ exactly when someone is measuring. `npx @threenative/playtest perf` turns a log into a windowed
115
+ report. When the percentile is
116
+ bad but the cause is not obvious, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md` names the function before you
117
+ change a line.
@@ -0,0 +1,51 @@
1
+ # Rigging characters — the full MCP tool loop
2
+
3
+ Companion to the humanoid paragraph in `finding-assets.md`. Reach for these tools when a game
4
+ needs a rigged character or extra motion on an existing one. The model choice, clip selection,
5
+ material changes and intentional motion adjustments stay authored game data; the tools only
6
+ produce the GLB.
7
+
8
+ AETHER / 02 is the pinned default sample: an 18-bone humanoid with 11 clips, five materials, both
9
+ UV sets, tangents and two material extensions. `SkeletalMesh3D` loads it and its `hand.R` is the
10
+ weapon attachment bone. It is CC0, and was built from a 14-unit source robot, so its source size
11
+ is preserved unless a game explicitly authors a `SkeletalMesh3D.size` override.
12
+
13
+ ## 1. Inspect before deciding
14
+
15
+ `asset_inspect_rig` takes a local GLB path, or `{ "sourceId": "aether-02" }` to acquire the pinned
16
+ sample into the development cache, plus optional local UAL ZIP/GLB libraries. It reports meshes,
17
+ joints, suggested bone-role mappings with ambiguity, attribute and extension support, measured
18
+ bounds, clips, and the actual attachment candidates. It never downloads the animation libraries;
19
+ supply local archives or select release donors by clip id.
20
+
21
+ ## 2. Preserve or fit a rig
22
+
23
+ `asset_auto_rig` preserves an existing valid rig by default. For an unrigged upright biped it fits
24
+ an 18-joint skeleton from measured geometry, then binds smooth (up to four normalized influences)
25
+ or rigid (one bone per connected mechanical region) weights and publishes the skinned GLB under the
26
+ project root. When the anatomy is ambiguous — arms joined to the torso, legs not separated — it
27
+ returns a correction request with the measured landmarks instead of a bad rig; pass corrected
28
+ `overrides` and call it again. Replacing a real rig requires `replaceRig: true`.
29
+
30
+ ## 3. Select and retarget motion
31
+
32
+ `asset_retarget_animations` fetches only the donor clips you select from the pinned release and
33
+ bakes them onto the target: `{ "id": "ual1/Walk_Loop", "variant": "in_place" }`. In-place is the
34
+ normal game-controlled locomotion output; root motion explicitly uses the matching `root_motion`
35
+ variant. New clips keep their namespace (`ual1/Walk_Loop`) so an existing `Walk` is never
36
+ overwritten. Existing target clips survive unless you pass `keepExistingClips: false` for a
37
+ game-minimal export. Target materials, UVs, tangents and extensions are preserved.
38
+
39
+ ## 4. Confirm with a contact sheet
40
+
41
+ `asset_preview_animation` renders a prepared GLB from two to six angles with an optional clip time
42
+ or an explicit bone pose, and publishes a nonblank contact sheet under the project root. A missing
43
+ rendering backend returns an explicit `unavailable` result; a blank frame fails. Inspect the sheet
44
+ before delivery — a valid animation container alone is not approval.
45
+
46
+ ## 5. Cook and play
47
+
48
+ Load the prepared GLB the ordinary way and play clips with `SkeletalMesh3D` and its update loop.
49
+ Attach a game-authored weapon with `attachToBone(character.root, "hand.R", weapon)`. Credit the
50
+ source and keep its license notice with the asset; the donor libraries are CC0, and the pinned
51
+ clips are fetched once into the development cache on first use, then reused offline.
@@ -12,7 +12,7 @@ Companion to the short `Building what you cannot download` section in this proje
12
12
  - **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
13
13
  landmark, scenery composition, or environment set piece whose silhouette must match. Use
14
14
  the sculpt tools to turn that reference into editable `src/render/` source.
15
- - **Bespoke, without a reference image** — read `agent-docs/dream-loop.md` and acquire one from
15
+ - **Bespoke, without a reference image** — read `node_modules/create-threenative/agent-docs/references/dream-loop.md` and acquire one from
16
16
  the user or an explicitly selected host/provider tool. Do not invent a reference: comparison
17
17
  without evidence is unguided iteration.
18
18
 
@@ -90,7 +90,7 @@ suppressed either way — acknowledging the trap does not give the display a vsy
90
90
 
91
91
  The same command also refuses when WebGPU came from SwiftShader, Chromium's CPU rasteriser
92
92
  (`TN_TRACE_SOFTWARE_ADAPTER`): a trace of software rendering names software rendering's functions.
93
- `agent-docs/capture-the-frame.md` covers that adapter trap in full.
93
+ `node_modules/create-threenative/agent-docs/references/capture-the-frame.md` covers that adapter trap in full.
94
94
 
95
95
  ## After the trace
96
96
 
@@ -20,10 +20,14 @@ Three.js source in this project, yours to rewrite or delete.
20
20
  - `postprocessing.ts` — the editable presets and `setupPost` delegation.
21
21
  - `worldEnvironment.ts` — the editable Godot-named render chain: tone mapping/exposure and
22
22
  optional TSL stages, with `createRenderChain` reporting applied or refused stages.
23
- - `scenery.ts` — `createScenery`, the collider-free half of the world: columns under ledges,
24
- spires in the middle distance, an unlit ridge on the horizon. **Keep something in all three
25
- bands.** A lit floor alone in black reads as a test fixture no matter how good the floor
26
- is, and it is the single cheapest thing to fix in a first screenshot.
23
+ - `materials.ts` — `floorMaterial`, `structureMaterial` and `propMaterial`, over a `DataTexture`
24
+ metre grid and a grain normal map. **Two greys and one saturated colour is the whole rule:**
25
+ light grid where the player walks, dark grid on sides and structure, and a single saturated
26
+ hue reserved for what they can touch. A lit floor alone in black reads as a test fixture no
27
+ matter how good the floor is, and the darkest band is the cheapest thing to fix in a first
28
+ screenshot.
29
+ - `arena.ts` — the ground, the walls and one platform builder. **Keep something in all three
30
+ depth bands:** the ground the player stands on, the dark mass behind it, and the sky above.
27
31
 
28
32
  ## Traps
29
33
 
@@ -10,10 +10,11 @@ ships, and never the game itself. The scene stays in the native runtime; only th
10
10
  | web | the page itself, beside `GameCanvas` | shipped |
11
11
  | Android | a transparent `WebView` over the SDL surface | shipped, proven on a Pixel 8 |
12
12
  | desktop (Linux) | a transparent WebKitGTK window over the game window | shipped |
13
- | desktop (Windows, macOS) | — | no host yet; use `ui: { renderer: "native" }` |
13
+ | desktop (Windows) | a transparent WebView2 surface over the game | implemented; final distribution verification is platform-specific |
14
+ | desktop (macOS) | a transparent `WKWebView` over the game | implemented; final distribution verification is platform-specific |
14
15
  | iOS | a transparent `WKWebView` over the Metal layer | written, **unproven on hardware** |
15
16
 
16
- Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
17
+ `ui.renderer` defaults to `"web"`. Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
17
18
  and no extra process, and draws `View`/`Text` quads inside the rendered frame instead.
18
19
 
19
20
  ## Two things cross the boundary, and nothing else
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: file-engine-bug
3
- description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session. Use when doctor and a minimal repro separate an engine bug from a game or machine problem, and you have pasted output proving it.
3
+ description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session, and move a game-side patch for it upstream. Use when doctor and a minimal repro separate an engine bug from a game or machine problem, when you have pasted output proving it, or when a patch in patches/ fixes one.
4
4
  ---
5
5
 
6
6
  # Filing an engine bug
@@ -20,7 +20,18 @@ fix that lives in this game's source, and not a machine problem doctor names.
20
20
  Implement the workaround first and continue the game (`AGENTS.md`: never stall on a framework
21
21
  bug). Filing does not wait for the workaround to be clean.
22
22
 
23
- ## 2. Search before filing
23
+ ## 2. A patch is temporary — ship the fix through one PR
24
+
25
+ A fix inside `@threenative/*` may **start** as a game-side patch
26
+ (`patches/@threenative+<package>@<version>.patch`, wired through pnpm `patchedDependencies`, every
27
+ hunk commented with the game it came from) so you can iterate and measure it against the game. The
28
+ patch is temporary: **once the fixes are settled** — measured, reviewed, regression checks green —
29
+ move them into the engine **through one pull request** on the ThreeNative repository, batching every
30
+ settled hunk with the checks that prove it rather than opening one PR per fix. Delete the game
31
+ patch when a release carrying the merged fixes is pinned. A mechanism that stays in a game patch is
32
+ a bug in the process: the next game hits the same wall.
33
+
34
+ ## 3. Search before filing
24
35
 
25
36
  ```sh
26
37
  gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or three keywords>"
@@ -29,7 +40,7 @@ gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or th
29
40
  An open issue already covering it: add your repro and output as a comment
30
41
  (`gh issue comment <number> --body-file <file>`) instead of a new report.
31
42
 
32
- ## 3. File it
43
+ ## 4. File it
33
44
 
34
45
  Write the body to a file first; quoting goes through `--body-file`, never inline:
35
46
 
@@ -49,7 +60,7 @@ The body carries, in this order:
49
60
  from the project's `package.json`.
50
61
  - **Workaround** — what the game shipped with to keep moving.
51
62
 
52
- ## 4. When not to file
63
+ ## 5. When not to file
53
64
 
54
65
  - `gh auth status` fails or `gh` is missing: do not authenticate for the user and do not stall —
55
66
  hand them the drafted title and body file and name the one command that files it.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: ponytail
3
+ description: >
4
+ Force the laziest solution that actually works: smallest, shortest, most minimal.
5
+ Use on any coding task in this game — writing, adding, refactoring, fixing,
6
+ reviewing, or picking a dependency — and whenever a request smells over-built
7
+ ("simplest", "minimal", "yagni", "do less", "shortest path", "too much code",
8
+ "bloat", "boilerplate"). Adds YAGNI and reuse to the engine's capability-first
9
+ rule: never hand-write what an installed @threenative system already does.
10
+ Source: github.com/DietrichGebert/ponytail (MIT). Do NOT use for non-coding
11
+ requests (general knowledge, prose, translation, summaries, recipes).
12
+ argument-hint: "[off]"
13
+ license: MIT
14
+ ---
15
+
16
+ # Ponytail — lazy senior dev
17
+
18
+ You are a lazy senior developer. Lazy means efficient, not careless. The best code
19
+ is the code never written. Active every response; this project's hook re-injects the
20
+ ruleset every session and prompt, and `PONYTAIL=off` or "stop ponytail" turns it off.
21
+
22
+ ## The ladder
23
+
24
+ Stop at the first rung that holds. The ladder runs *after* you understand the
25
+ problem, not instead of it: read the code the change touches and trace the real
26
+ flow end to end, then climb. Two rungs work → take the higher one and move on.
27
+
28
+ 1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
29
+ 2. **Already installed in the engine?** Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect hits with `engine_capability_detail`, and reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; never skip it because the task looks small, and never jump to hand-written code while it is unsearched.
30
+ 3. **Already in this game?** Reuse a helper, type, or pattern that already lives in `src/`. Re-implementing what sits a few files over is the most common slop.
31
+ 4. **Stdlib or engine convention does it?** `loadAll`, `addInSlices`, `GroundSnap`, an input vector, a physics query — reach for those before writing your own loop.
32
+ 5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
33
+ 6. **Can it be one line?** One line.
34
+ 7. **Only then:** the minimum code that works, in this game's `src/`.
35
+
36
+ ## Rules
37
+
38
+ - No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
39
+ - No boilerplate, no scaffolding "for later"; later can scaffold for itself. Deletion over addition. Boring over clever.
40
+ - Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place is a second bug.
41
+ - Complex request? Ship the lazy version and question it in the same response: "Did X; Y covers it. Need full X? Say so." Never stall on a question you can default.
42
+ - Two same-size options? Take the one correct on edge cases — lazy means less code, not the flimsier algorithm.
43
+ - Bug fix = root cause, not symptom: grep every caller of the function you touch and fix the shared one. One guard where all callers route through is smaller than a guard per caller, and patching only the path the ticket names leaves a sibling caller broken.
44
+ - Mark a deliberate corner cut with a `ponytail:` comment naming the ceiling and the upgrade path.
45
+
46
+ ## Output
47
+
48
+ Code first. Then at most three short lines: what was skipped, when to add it.
49
+ Pattern: `[code] → skipped: [X], add when [Y].` No essays, no feature tours, no
50
+ design notes. Explanation the user explicitly asked for (a plan, a report, per-phase
51
+ notes) is not debt — give it in full.
52
+
53
+ ## When NOT to be lazy
54
+
55
+ Never simplify away: understanding the problem (a small diff you do not understand is
56
+ just laziness dressed up as efficiency), input validation at trust boundaries, error
57
+ handling that prevents data loss, security, accessibility, anything explicitly
58
+ requested, and the calibration real hardware needs. Lazy code without its check is
59
+ unfinished: non-trivial logic leaves ONE runnable check behind — the smallest thing
60
+ that fails if the logic breaks. In this game the proof is a playtest scenario, never a
61
+ new test framework; trivial one-liners need no test.
62
+
63
+ ## Boundaries
64
+
65
+ Ponytail governs what you build, not how you talk. "stop ponytail" / "normal mode" /
66
+ `PONYTAIL=off`: revert. Level persists until changed or session end.
67
+
68
+ The shortest path to done is the right path.
@@ -26,20 +26,28 @@ If FabCLI needs a session, proactively run `fabcli auth login`. Use Claude brows
26
26
  `chrome:control-chrome`, to complete the login with the user's active browser session, then retry
27
27
  the MCP call. Never read, copy, print, or persist browser cookies or tokens. The MCP checks
28
28
  entitlement and accepts only Fab Standard or CC-BY; it never claims or buys. Full arguments:
29
- `agent-docs/finding-assets.md`.
29
+ `node_modules/create-threenative/agent-docs/references/finding-assets.md`.
30
30
 
31
- For a bespoke animated creature, follow `agent-docs/creating-creatures.md`. Call the five
31
+ For a bespoke animated creature, follow `node_modules/create-threenative/agent-docs/references/creating-creatures.md`. Call the five
32
32
  `creature_*` tools through the project asset server, keep the editable spec and claims in
33
33
  `.threenative/creatures/`, compile into the configured `assets/` source, and get independent
34
34
  visual review before delivery. `creature_status` distinguishes compile-only availability from
35
35
  optional preview/check dependencies; an unavailable renderer is not approval.
36
36
 
37
+ For a humanoid that needs a skeleton or more motion, follow `node_modules/create-threenative/agent-docs/references/rigging-characters.md`.
38
+ Inspect first with `asset_inspect_rig` (a local GLB or the pinned `aether-02` sample), auto-rig an
39
+ unrigged biped with `asset_auto_rig` (or pass explicit landmarks when it returns a correction
40
+ request), select donors with `asset_retarget_animations` (in-place by default; `root_motion` only
41
+ from the matching `_RM` donor), and confirm the result with `asset_preview_animation` on a
42
+ nonblank contact sheet before cooking. The 18-bone AETHER sample has no fingers or toes; the
43
+ tools report those absent roles instead of inventing them.
44
+
37
45
  Choose the sculpt branch before coding: conventional → asset tools; trivial → portable geometry;
38
46
  bespoke with a reference → `sculpt_plan`, `sculpt_spec_gate` until every region passes, one
39
47
  factory per pass in `src/render/`, then `sculpt_compare` and `sculpt_pass_gate` against a real
40
- capture; bespoke without a reference → read `agent-docs/dream-loop.md` and acquire a
48
+ capture; bespoke without a reference → read `node_modules/create-threenative/agent-docs/references/dream-loop.md` and acquire a
41
49
  user-supplied or explicitly authorized target before sculpting. Use `node scripts/reference.mjs`
42
50
  only when the user selected its provider/model; never invent a reference or hide a missing key.
43
51
  `sculpt_grimoire` supplies techniques. `threenative-sculpt-mcp` guides source and never launches
44
52
  a browser. A missing/blank capture fails; credit the reference before the turn ends. See
45
- `agent-docs/sculpt-from-a-reference.md`.
53
+ `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`.
@@ -21,7 +21,7 @@ movement, navigation, attachment, particle, terrain, or measurement system.
21
21
 
22
22
  The manifest is the complete public surface; grep misses subpath exports such as
23
23
  `@threenative/physics/navigation`. If MCP is unavailable after `npx threenative doctor`, use
24
- `agent-docs/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
24
+ `node_modules/create-threenative/agent-docs/references/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
25
25
  Returned constraints are binding: import navigation from its returned subpath, use `attachToBone`
26
26
  for held weapons (add a portable `Bone` named `RightHand` when needed), and never invent platform
27
27
  support. One game rewrote 446 installed lines and ran at 9 FPS; discovery prevents that.
@@ -6,7 +6,7 @@ description: Use the portable ThreeNative ctx lifecycle, scheduling, randomness,
6
6
  # ThreeNative context surface
7
7
 
8
8
  These are properties on `ctx`, never imports; use them before writing equivalent game plumbing.
9
- The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
9
+ The recipes are in `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md` and imports still require
10
10
  `engine_search_capabilities`.
11
11
 
12
12
  | Use | Instead of | Contract |
@@ -14,6 +14,7 @@ The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
14
14
  | `ctx.goto("<scene-name>")` | hand reset | async scene rebuild |
15
15
  | `ctx.tween(...)` | `Math.sin`/`lerp` accumulator | timed interpolation with optional `ease` |
16
16
  | `ctx.after(...)` / `ctx.every(...)` | timer branches in `update` | disposable schedules |
17
+ | `ctx.beforeRender(fn)` | per-frame packing in `update` or an object `onBeforeRender` hook | one dispatch per actual world draw, after the last fixed step and before the projection; cleared like `ctx.afterPhysics` |
17
18
  | `ctx.random.range(-1, 1)` | `Math.random()` | reproducible when `seed` is configured |
18
19
  | `ctx.pointer.on(...)` / `ctx.pointer.drag(...)` | hover/press/drag bookkeeping | web/native pointer-id stream |
19
20
  | `ctx.raycast()` / `ctx.raycastAll()` | `new Raycaster()` | backend-neutral intersections |
@@ -29,6 +30,13 @@ restart, `game.goto("<scene-name>")` from React resets declared initial state fi
29
30
  uses `ctx.state.set({ /* copy this game's initial-state shape */ })` before the goto. `ctx.random` is
30
31
  deterministic only when `defineGame({ seed })` is configured.
31
32
 
33
+ `ctx.beforeRender(fn)` runs once per actual world draw, after the frame's last fixed update and
34
+ before the projection reconciles, so `fn` reads the frame's final state; a held, loader-only frame
35
+ draws no world and dispatches nothing. It is cleared on scene change and stop, like
36
+ `ctx.afterPhysics`. Reach for it when the draw itself consumes per-frame CPU work — packing an
37
+ instanced batch, rebuilding a buffer — instead of an object `onBeforeRender` hook, which makes the
38
+ render projection decline the whole frame.
39
+
32
40
  `pnpm budgets` rejects superseded raw constructs such as `new Audio(`, `Math.random(`,
33
41
  `new Raycaster(`, `.visible = false`, and `new Box3().setFromObject(`; use the named capability or
34
42
  annotate a genuinely necessary line with a non-empty `// engine-override: reason`.
@@ -5,14 +5,28 @@ description: Measure ThreeNative frame budgets and report platform evidence with
5
5
 
6
6
  # ThreeNative performance evidence
7
7
 
8
- Refill scratch and pool objects. Static GLBs may use `assets.models.lightmap:{atlasSize,padding}`;
9
- load through `ctx.assets.model()`, remove it to roll back, and never claim Android/iOS from a
10
- web/desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`, and
11
- `residual`; `defineGame({ frameBudget: false })` silences output, never measurement.
8
+ Pool objects; load static GLBs through `ctx.assets.model()`; never claim Android/iOS from a
9
+ desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
10
+ `residual` and per-pass draws and triangles. `defineGame({ frameBudget: false })` silences
11
+ output, never measurement.
12
12
 
13
- Unexecuted platforms stay unverified; never invent numbers. Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. The bounded proof shape is
14
- `{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12}}}` and its
15
- fields are defined in `agent-docs/assertion-reference.md#performance`.
13
+ ## When the scene is the problem
14
+
15
+ `TN_SCENE_WARNING` fires when the GPU used under a third of a frame whose render phase overran
16
+ the display period: move draws and objects, not settings. `npx threenative doctor` and
17
+ `DEV_MODE=true` repeat it; `TN_FRAME_SPANS=1` splits that phase.
18
+ The largest static win is free — three skips per-object binding updates when nothing changed, so
19
+ not writing a transform saved 7.35 ms on 1,561 objects where `markStatic(root)` saved 0.009 ms.
20
+
21
+ ## Use the shipped defaults
22
+
23
+ The engine prepares transforms, batches, culls, scales resolution and cooks assets;
24
+ read `node_modules/create-threenative/agent-docs/references/performance-basics.md` before hand-rolling any.
25
+ Unexecuted platforms stay unverified; never invent numbers.
26
+ Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Bounded proof:
27
+ `{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`,
28
+ defined in `node_modules/create-threenative/agent-docs/references/assertion-reference.md#performance`; pass bounds fail closed without a
29
+ per-pass split.
16
30
 
17
31
  |Tier|Measure|Floor|Target|
18
32
  |---|---|---:|---:|
@@ -37,6 +51,8 @@ fields are defined in `agent-docs/assertion-reference.md#performance`.
37
51
  |4|Thermal-status|≤2|≤1|
38
52
  |4|Whole-device-current|—|report;not-gated|
39
53
 
40
- On Android, budget roughly a 500 MiB driver floor before your own textures; a dual-use
41
- equirectangular environment adds about 48 MiB. Fix it with `agent-docs/mobile-memory-budget.md`,
42
- which carries the measurement conditions behind both numbers.
54
+ Android: budget a ~500 MiB driver floor before textures; a dual-use equirectangular
55
+ environment adds ~48 MiB: `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`.
56
+
57
+ Name the hot function: `--cpu-prof <file>` (native, or a browser/desktop playtest) writes a
58
+ DevTools `.cpuprofile`.
@@ -40,5 +40,5 @@ Playtests fail closed: a missing entity, absent observation, or empty assertion
40
40
  `allowTrivial` waiver needs a 20-character reason; `true` alone is invalid, and all-waived
41
41
  triviality fails `TN_PLAYTEST_SCENARIO_ASSERTS_NOTHING`. Use `holdTicks`/`waitTicks` for fixed-step
42
42
  time (`holdFrames`/`waitFrames` are compatibility aliases); `warmupFrames` means RAF warmup.
43
- Read `agent-docs/assertion-reference.md` for assertion fields and `agent-docs/debug-surface.md`
43
+ Read `node_modules/create-threenative/agent-docs/references/assertion-reference.md` for assertion fields and `node_modules/create-threenative/agent-docs/references/debug-surface.md`
44
44
  for bridge globals. The JSON-safe bridge resource is `state`; `GameState` is a deprecated alias.
@@ -17,4 +17,4 @@ intents; `src/game.ts` decides their meaning. `useUiState<GameState>()` is undef
17
17
  snapshot, and `useUiIntent()` sends commands. Mark every touch target `data-tn-interactive`; the
18
18
  host routes marked pointer-down events to UI and unmarked touches to the game. Share state and
19
19
  components, but keep appearance in `src/ui/`. The full state, hit-region, and renderer contract is
20
- `agent-docs/webview-ui.md`.
20
+ `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
@@ -17,10 +17,10 @@ Use browser automation on the user's real Chrome when available; otherwise run
17
17
  status. A black headless capture is a capture failure until proven otherwise.
18
18
 
19
19
  For reference matching, solve lighting first: search `engine_search_capabilities` before adding
20
- effects, read `TN_RENDER_CHAIN`, and use `agent-docs/visual-baseline.md` and
21
- `agent-docs/capture-the-frame.md` for the per-file baseline and capture recipe.
20
+ effects, read `TN_RENDER_CHAIN`, and use `node_modules/create-threenative/agent-docs/references/visual-baseline.md` and
21
+ `node_modules/create-threenative/agent-docs/references/capture-the-frame.md` for the per-file baseline and capture recipe.
22
22
 
23
- For a supplied or explicitly generated target, read `agent-docs/dream-loop.md`. It is the shared
23
+ For a supplied or explicitly generated target, read `node_modules/create-threenative/agent-docs/references/dream-loop.md`. It is the shared
24
24
  workflow for locking the target, preserving its hash, obtaining a fresh gameplay capture, and
25
25
  asking the read-only verifier for an independent `PASS`, `REQUEST_CHANGES`, or `NOT_OBSERVED`.
26
26
  Run `node scripts/visual-loop.mjs --record <run>/run.json` before and after each round; read its
@@ -38,4 +38,4 @@ visible while tuning bounds, density, and `bakeBudgetMs`.
38
38
  never hand-author a device constant. A `(0, 1]` value pins it; invalid values fail at config load.
39
39
  Both modes report `TN_FRAME_BUDGET.surface` (`resolutionScale`, `scaleSource`, sample count, and
40
40
  buffer size), and `display: config.display` must reach `defineGame`. See the pixel-budget details
41
- in `agent-docs/visual-baseline.md` and the engine's measurement skill.
41
+ in `node_modules/create-threenative/agent-docs/references/visual-baseline.md` and the engine's measurement skill.
@@ -0,0 +1,51 @@
1
+ #!/usr/bin/env node
2
+ // Project-scoped ponytail activation. Runs only where this file is installed: the engine repo
3
+ // and every project `create-threenative` generates. It injects the same ruleset on session,
4
+ // prompt and subagent start so the AGENTS.md rule cannot drift out of the model's context.
5
+ //
6
+ // It is deliberately small: no mode file, no statusline, no state written outside the project.
7
+ // `PONYTAIL=off` (or removing this hook) turns it off.
8
+
9
+ if (process.env.PONYTAIL === "off") process.exit(0);
10
+
11
+ const RULESET = [
12
+ "PONYTAIL MODE ACTIVE — laziest solution that actually works.",
13
+ "",
14
+ "Before writing code, stop at the first rung that holds (read the code the change touches first):",
15
+ "1. Does this need to exist? No -> skip it (YAGNI).",
16
+ "2. Already installed in the engine? Search `engine_search_capabilities` and inspect with `engine_capability_detail` — reuse the returned system. This rung IS the critical capability gate; a shipped node, convention, helper or subpath is the answer, never hand-write what it already does.",
17
+ "3. Already in this game? Reuse what is in `src/`.",
18
+ "4. Stdlib or engine convention (loadAll, addInSlices, GroundSnap, an input vector, a physics query)? Use it.",
19
+ "5. Already-installed dependency? Use it; add none for a few lines.",
20
+ "6. One line? One line.",
21
+ "7. Only then: the minimum code that works.",
22
+ "",
23
+ "No unrequested abstractions, no boilerplate, no scaffolding for later; deletion over addition; fewest files; shortest diff once you understand the problem. Bug fix = grep every caller and fix the shared function once. Code first, then at most three short lines (`[code] -> skipped: [X], add when [Y].`).",
24
+ "Never simplify away: understanding the problem, trust-boundary validation, error handling that prevents data loss, security, accessibility, anything explicitly requested, hardware calibration. Non-trivial logic leaves ONE runnable check behind — here that is a playtest scenario.",
25
+ 'Off: "stop ponytail" / `PONYTAIL=off`. Full rules: `.claude/skills/ponytail/SKILL.md` or `.agents/skills/ponytail/SKILL.md`.',
26
+ ].join("\n");
27
+
28
+ let stdin = "";
29
+ process.stdin.setEncoding("utf8");
30
+ process.stdin.on("data", (chunk) => {
31
+ stdin += chunk;
32
+ });
33
+ process.stdin.on("end", emit);
34
+ process.stdin.on("error", () => process.exit(0));
35
+ // Never hang a session, and never fail one: an unreadable skill or closed stdin exits quietly.
36
+ setTimeout(() => process.exit(0), 3000).unref();
37
+
38
+ function emit() {
39
+ let event = "SessionStart";
40
+ try {
41
+ event = JSON.parse(stdin || "{}").hook_event_name || event;
42
+ } catch {
43
+ // Malformed stdin still gets the ruleset; the event name only shapes the envelope.
44
+ }
45
+ process.stdout.write(
46
+ JSON.stringify({
47
+ hookSpecificOutput: { hookEventName: event, additionalContext: RULESET },
48
+ }),
49
+ );
50
+ process.exit(0);
51
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
9
+ "timeout": 5,
10
+ "statusMessage": "Loading ponytail..."
11
+ }
12
+ ]
13
+ }
14
+ ],
15
+ "UserPromptSubmit": [
16
+ {
17
+ "hooks": [
18
+ {
19
+ "type": "command",
20
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
21
+ "timeout": 5
22
+ }
23
+ ]
24
+ }
25
+ ],
26
+ "SubagentStart": [
27
+ {
28
+ "hooks": [
29
+ {
30
+ "type": "command",
31
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
32
+ "timeout": 5
33
+ }
34
+ ]
35
+ }
36
+ ]
37
+ }
38
+ }