create-threenative 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -3,11 +3,13 @@ import { playtest } from "@threenative/core/playtest";
3
3
  import type { IPhysicsContext } from "@threenative/physics";
4
4
  import { rapier } from "@threenative/physics";
5
5
  import config from "../threenative.config.js";
6
+ import { observeQualityWindow } from "./render/postprocessing.js";
6
7
  import { Play } from "./scenes/Play.js";
7
8
  import type { GameState } from "./state.js";
8
9
 
9
10
  // game.state is the single store: the fixed-step loop writes it, and React/playtests read it.
10
11
  const game = defineGame<GameState, IPhysicsContext>({
12
+ frameBudget: { onWindow: (window) => observeQualityWindow(window) },
11
13
  input: {
12
14
  // The four directions of `input.vector("move")`. Declared rather than inherited from the
13
15
  // default binding, so the axis every scene reads is visible where the game is defined.
@@ -0,0 +1,195 @@
1
+ import { type QualityTier, resolveQualityTier } from "./quality.js";
2
+
3
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
4
+
5
+ /** Structural subset of the engine's completed frame window; rendering source stays portable. */
6
+ export interface IQualityWindow {
7
+ readonly window: number;
8
+ readonly frames: number;
9
+ readonly fps: number;
10
+ readonly presented: { readonly p95: number };
11
+ readonly frame: { readonly p95: number };
12
+ readonly gpuMs?: number;
13
+ readonly gpuAgeFrames?: number;
14
+ readonly surface?: { readonly compiling?: boolean };
15
+ }
16
+
17
+ export interface IQualityDecision {
18
+ readonly tier: QualityTier;
19
+ readonly source: "auto" | "pinned";
20
+ readonly changed: boolean;
21
+ readonly meter: "gpu" | "presented";
22
+ readonly fallback?: "gpu-unavailable" | "gpu-invalid" | "gpu-age-unavailable" | "gpu-stale";
23
+ readonly reason: string;
24
+ readonly budgetMs: number;
25
+ readonly overloadBudgetMs: number;
26
+ readonly gpuMs?: number;
27
+ readonly cpuMs?: number;
28
+ readonly costMs?: number;
29
+ }
30
+
31
+ export interface IAdaptiveQualityOptions {
32
+ readonly targetFps?: number;
33
+ readonly overloadedWindows?: number;
34
+ readonly healthyWindows?: number;
35
+ readonly headroom?: number;
36
+ readonly presentationTolerance?: number;
37
+ readonly cooldownMs?: number;
38
+ readonly startupWindows?: number;
39
+ readonly minFrames?: number;
40
+ readonly maxGpuAgeFrames?: number;
41
+ readonly now?: () => number;
42
+ /** The scene passes its actual loading state; elapsed time cannot establish readiness. */
43
+ readonly ready?: () => boolean;
44
+ }
45
+
46
+ /** The game owns this policy. Platform selects the first look; measured load selects later ones. */
47
+ export function createAdaptiveQuality(
48
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
49
+ options: IAdaptiveQualityOptions = {},
50
+ ) {
51
+ const policy = {
52
+ targetFps: 60,
53
+ overloadedWindows: 2,
54
+ healthyWindows: 5,
55
+ headroom: 0.2,
56
+ presentationTolerance: 0.05,
57
+ cooldownMs: 5000,
58
+ startupWindows: 1,
59
+ minFrames: 30,
60
+ maxGpuAgeFrames: 4,
61
+ ...options,
62
+ };
63
+ for (const key of ["targetFps", "overloadedWindows", "healthyWindows", "minFrames"] as const) {
64
+ if (!Number.isFinite(policy[key]) || policy[key] <= 0)
65
+ throw new Error(`quality ${key} must be positive.`);
66
+ }
67
+ for (const key of ["cooldownMs", "startupWindows", "maxGpuAgeFrames"] as const) {
68
+ if (!Number.isFinite(policy[key]) || policy[key] < 0)
69
+ throw new Error(`quality ${key} must be non-negative.`);
70
+ }
71
+ for (const key of [
72
+ "overloadedWindows",
73
+ "healthyWindows",
74
+ "startupWindows",
75
+ "minFrames",
76
+ "maxGpuAgeFrames",
77
+ ] as const) {
78
+ if (!Number.isInteger(policy[key])) throw new Error(`quality ${key} must be an integer.`);
79
+ }
80
+ if (!Number.isFinite(policy.headroom) || policy.headroom <= 0 || policy.headroom >= 1)
81
+ throw new Error("quality headroom must be between zero and one.");
82
+ if (
83
+ !Number.isFinite(policy.presentationTolerance) ||
84
+ policy.presentationTolerance < 0 ||
85
+ policy.presentationTolerance >= 1
86
+ )
87
+ throw new Error("quality presentationTolerance must be between zero and one.");
88
+ const now = options.now ?? (() => performance.now());
89
+ const ready = options.ready ?? (() => true);
90
+ let tier = resolveQualityTier(request);
91
+ const pinned = request.tier !== undefined;
92
+ const budgetMs = 1000 / policy.targetFps;
93
+ let startup = policy.startupWindows;
94
+ let lastWindow = 0;
95
+ let lastChange = Number.NEGATIVE_INFINITY;
96
+ let overloaded = 0;
97
+ let healthy = 0;
98
+ const finite = (value: number | undefined): value is number =>
99
+ value !== undefined && Number.isFinite(value);
100
+ return {
101
+ get tier() {
102
+ return tier;
103
+ },
104
+ pinned,
105
+ observe(window: IQualityWindow): IQualityDecision {
106
+ const gpu = window.gpuMs;
107
+ const age = window.gpuAgeFrames;
108
+ const fallback: IQualityDecision["fallback"] =
109
+ gpu === undefined
110
+ ? "gpu-unavailable"
111
+ : !Number.isFinite(gpu) || gpu <= 0
112
+ ? "gpu-invalid"
113
+ : age === undefined || !Number.isInteger(age) || age < 0
114
+ ? "gpu-age-unavailable"
115
+ : age > policy.maxGpuAgeFrames
116
+ ? "gpu-stale"
117
+ : undefined;
118
+ const costMs = fallback === undefined ? (gpu as number) : window.presented.p95;
119
+ // Presented intervals include vsync jitter, so fallback overload gets a small tolerance.
120
+ const overloadBudgetMs =
121
+ fallback === undefined ? budgetMs : budgetMs * (1 + policy.presentationTolerance);
122
+ const reportFields: Pick<IQualityDecision, "fallback" | "gpuMs" | "cpuMs" | "costMs"> = {
123
+ ...(fallback === undefined ? {} : { fallback }),
124
+ ...(finite(gpu) ? { gpuMs: gpu } : {}),
125
+ ...(finite(window.frame.p95) ? { cpuMs: window.frame.p95 } : {}),
126
+ ...(finite(costMs) ? { costMs } : {}),
127
+ };
128
+ const report = (reason: string, changed = false): IQualityDecision => ({
129
+ tier,
130
+ source: pinned ? "pinned" : "auto",
131
+ changed,
132
+ reason,
133
+ budgetMs,
134
+ overloadBudgetMs,
135
+ meter: fallback === undefined ? "gpu" : "presented",
136
+ ...reportFields,
137
+ });
138
+ let skip: string | undefined;
139
+ if (
140
+ !Number.isInteger(window.window) ||
141
+ window.window <= lastWindow ||
142
+ !Number.isInteger(window.frames) ||
143
+ window.frames < policy.minFrames ||
144
+ !Number.isFinite(window.fps) ||
145
+ window.fps <= 0 ||
146
+ !Number.isFinite(costMs) ||
147
+ costMs <= 0
148
+ )
149
+ skip = "invalid";
150
+ if (Number.isInteger(window.window) && window.window > lastWindow) lastWindow = window.window;
151
+ if (!ready()) {
152
+ startup = policy.startupWindows;
153
+ skip = "startup";
154
+ } else if (window.surface?.compiling) skip = "compiling";
155
+ else if (skip === undefined && startup > 0) {
156
+ startup -= 1;
157
+ skip = "startup";
158
+ }
159
+ if (skip !== undefined) {
160
+ overloaded = 0;
161
+ healthy = 0;
162
+ return report(skip);
163
+ }
164
+ if (pinned) return report("pinned");
165
+ overloaded = costMs > overloadBudgetMs ? overloaded + 1 : 0;
166
+ healthy = costMs <= budgetMs * (1 - policy.headroom) ? healthy + 1 : 0;
167
+ const direction =
168
+ overloaded >= policy.overloadedWindows ? -1 : healthy >= policy.healthyWindows ? 1 : 0;
169
+ if (direction === 0) return report("steady");
170
+ const next = QUALITY_TIERS[QUALITY_TIERS.indexOf(tier) + direction];
171
+ if (next === undefined) return report(direction < 0 ? "at-floor" : "at-ceiling");
172
+ const time = now();
173
+ if (!Number.isFinite(time)) throw new Error("quality clock must return finite milliseconds.");
174
+ if (time - lastChange < policy.cooldownMs) {
175
+ overloaded = 0;
176
+ healthy = 0;
177
+ return report("cooldown");
178
+ }
179
+ tier = next;
180
+ lastChange = time;
181
+ overloaded = 0;
182
+ healthy = 0;
183
+ return report(direction < 0 ? "overloaded" : "headroom", true);
184
+ },
185
+ };
186
+ }
187
+
188
+ export function formatQualityAdaptation(decision: IQualityDecision): string {
189
+ return (
190
+ `TN_QUALITY_TIER ${decision.tier} source=${decision.source} meter=${decision.meter}` +
191
+ ` reason=${decision.reason} fallback=${decision.fallback ?? "none"}` +
192
+ ` budgetMs=${decision.budgetMs} overloadBudgetMs=${decision.overloadBudgetMs}` +
193
+ ` costMs=${decision.costMs ?? "unavailable"}`
194
+ );
195
+ }
@@ -45,7 +45,7 @@ export function createSpringArm(
45
45
  // Lead the route rather than centring the character. The level runs left to right, so
46
46
  // aiming ahead of the player puts the gap and the flag in frame from the first tick
47
47
  // instead of leaving half the picture empty behind them.
48
- const lookAhead = options.lookAhead ?? new Vec3(2.1, 0.9, -0.4);
48
+ const lookAhead = options.lookAhead ?? new Vec3(1.8, 0.35, -1.15);
49
49
  const damping = options.damping ?? 0.18;
50
50
  const startingDistance = offset.length();
51
51
  const offsetDirection =
@@ -0,0 +1,199 @@
1
+ // Generated for you: ordinary Three.js, with every coastal shape and colour game-owned.
2
+ // This file composes the starter's scene; it does not add physics or choose a framework look.
3
+ import {
4
+ ConeGeometry,
5
+ CylinderGeometry,
6
+ DodecahedronGeometry,
7
+ Group,
8
+ type Material,
9
+ Mesh,
10
+ PlaneGeometry,
11
+ SphereGeometry,
12
+ TorusGeometry,
13
+ } from "three";
14
+ import { block } from "./shapes.js";
15
+ import { type IWaveDisplacementSource, createWaterMaterial } from "./water.js";
16
+
17
+ export interface ICoastalMaterials {
18
+ readonly flower: Material;
19
+ readonly grass: Material;
20
+ readonly grassDark: Material;
21
+ readonly rock: Material;
22
+ readonly sand: Material;
23
+ readonly shoreline: Material;
24
+ }
25
+ const TUFTS = [
26
+ [-4.25, -1.28, 0.85],
27
+ [-3.65, 1.32, 0.72],
28
+ [-2.5, -1.42, 0.66],
29
+ [-1.05, 1.38, 0.76],
30
+ [0.75, -1.4, 0.74],
31
+ [1.9, 1.35, 0.82],
32
+ [3.15, -1.3, 0.68],
33
+ [4.12, 1.18, 0.78],
34
+ ] as const;
35
+ const REEDS = [-4.45, -0.3, 3.95] as const;
36
+
37
+ /** Builds the little island, its water, and the repeated vegetation around the play route. */
38
+ export function createCoastalScene(
39
+ materials: ICoastalMaterials,
40
+ waves: IWaveDisplacementSource,
41
+ random: () => number,
42
+ ): Group {
43
+ const coast = new Group();
44
+ coast.name = "coastal-diorama";
45
+
46
+ const water = new Mesh(new PlaneGeometry(72, 72, 64, 64), createWaterMaterial(waves));
47
+ water.geometry.rotateX(-Math.PI / 2);
48
+ water.name = "stylized-water";
49
+ // The wave crest reaches above the base plane; leave clearance below the lower goal
50
+ // sandbar so the animated surface never clips through its top.
51
+ water.position.set(0, -0.78, -18);
52
+ water.frustumCulled = false;
53
+ water.receiveShadow = true;
54
+ coast.add(water);
55
+
56
+ const beach = new Mesh(new CylinderGeometry(1, 1, 0.18, 32), materials.sand);
57
+ beach.name = "island-beach";
58
+ beach.position.y = -0.06;
59
+ beach.scale.set(5.25, 1, 2.15);
60
+ beach.receiveShadow = true;
61
+ coast.add(beach);
62
+
63
+ const grass = new Mesh(new CylinderGeometry(1, 1, 0.09, 32), materials.grass);
64
+ grass.name = "island-grass";
65
+ grass.position.y = 0.02;
66
+ grass.scale.set(4.82, 1, 1.72);
67
+ grass.receiveShadow = true;
68
+ coast.add(grass);
69
+
70
+ const shoreRing = new Mesh(new TorusGeometry(1, 0.055, 5, 32), materials.shoreline);
71
+ shoreRing.name = "island-shoreline";
72
+ shoreRing.position.y = 0.025;
73
+ shoreRing.scale.set(5.12, 1, 2.02);
74
+ shoreRing.receiveShadow = true;
75
+ coast.add(shoreRing);
76
+
77
+ const path = block(4.8, 0.035, 0.5, materials.sand, {
78
+ castShadow: false,
79
+ radius: 0.12,
80
+ });
81
+ path.name = "island-footpath";
82
+ path.position.set(0.1, 0.065, 0);
83
+ coast.add(path);
84
+
85
+ const bladeGeometry = new ConeGeometry(0.075, 0.58, 5);
86
+ for (const [x, z, scale] of TUFTS) addTuft(coast, bladeGeometry, materials, x, z, scale, random);
87
+
88
+ const reedGeometry = new ConeGeometry(0.06, 0.82, 5);
89
+ for (const x of REEDS) addReeds(coast, reedGeometry, materials, x, random);
90
+
91
+ const rockGeometry = new DodecahedronGeometry(1, 0);
92
+ for (const [x, z, scale] of [
93
+ [-4.45, 0.65, 0.42],
94
+ [-3.95, -0.52, 0.3],
95
+ [4.42, -0.62, 0.4],
96
+ [4.05, 0.72, 0.28],
97
+ ] as const) {
98
+ const rock = new Mesh(rockGeometry, materials.rock);
99
+ rock.position.set(x, 0.12, z);
100
+ rock.scale.set(scale * 1.35, scale, scale * 0.9);
101
+ rock.rotation.set(random() * 0.3, random() * Math.PI, random() * 0.2);
102
+ rock.castShadow = true;
103
+ rock.receiveShadow = true;
104
+ coast.add(rock);
105
+ }
106
+
107
+ for (const [x, z] of [
108
+ [-2.95, 1.05],
109
+ [2.55, -1.03],
110
+ [3.45, 0.92],
111
+ ] as const)
112
+ addFlower(coast, materials, x, z);
113
+
114
+ addDistantIslands(coast, materials.rock);
115
+ return coast;
116
+ }
117
+
118
+ function addTuft(
119
+ parent: Group,
120
+ geometry: ConeGeometry,
121
+ materials: ICoastalMaterials,
122
+ x: number,
123
+ z: number,
124
+ scale: number,
125
+ random: () => number,
126
+ ): void {
127
+ const tuft = new Group();
128
+ tuft.position.set(x, 0.09, z);
129
+ const lean = (random() - 0.5) * 0.28;
130
+ for (const [offset, material] of [
131
+ [-0.09, materials.grassDark],
132
+ [0, materials.grass],
133
+ [0.09, materials.grassDark],
134
+ ] as const) {
135
+ const blade = new Mesh(geometry, material);
136
+ blade.position.x = offset;
137
+ blade.rotation.z = lean + offset;
138
+ blade.rotation.y = random() * Math.PI;
139
+ blade.scale.setScalar(scale * (0.9 + random() * 0.18));
140
+ blade.castShadow = true;
141
+ tuft.add(blade);
142
+ }
143
+ parent.add(tuft);
144
+ }
145
+
146
+ function addReeds(
147
+ parent: Group,
148
+ geometry: ConeGeometry,
149
+ materials: ICoastalMaterials,
150
+ x: number,
151
+ random: () => number,
152
+ ): void {
153
+ const reeds = new Group();
154
+ reeds.position.set(x, 0.1, -1.5);
155
+ for (let index = 0; index < 3; index += 1) {
156
+ const reed = new Mesh(geometry, materials.grassDark);
157
+ reed.position.set((index - 1) * 0.1, index * 0.03, (random() - 0.5) * 0.14);
158
+ reed.rotation.z = (random() - 0.5) * 0.32;
159
+ reed.rotation.y = random() * Math.PI;
160
+ reed.scale.setScalar(0.72 + random() * 0.2);
161
+ reed.castShadow = true;
162
+ reeds.add(reed);
163
+ }
164
+ parent.add(reeds);
165
+ }
166
+
167
+ function addFlower(parent: Group, materials: ICoastalMaterials, x: number, z: number): void {
168
+ const flower = new Group();
169
+ flower.position.set(x, 0.1, z);
170
+ const stem = new Mesh(new CylinderGeometry(0.018, 0.028, 0.34, 6), materials.grassDark);
171
+ stem.position.y = 0.17;
172
+ const head = new Mesh(new SphereGeometry(0.095, 8, 6), materials.flower);
173
+ head.position.y = 0.37;
174
+ stem.castShadow = true;
175
+ head.castShadow = true;
176
+ flower.add(stem, head);
177
+ parent.add(flower);
178
+ }
179
+
180
+ function addDistantIslands(parent: Group, material: Material): void {
181
+ const horizon = new Group();
182
+ horizon.name = "distant-islands";
183
+ const geometry = new DodecahedronGeometry(1, 1);
184
+ for (const [x, z, scale] of [
185
+ [-10, -13, 2.1],
186
+ [-3.7, -16, 1.4],
187
+ [5.5, -14, 1.8],
188
+ [12, -19, 2.7],
189
+ ] as const) {
190
+ const island = new Mesh(geometry, material);
191
+ island.position.set(x, -0.25, z);
192
+ island.scale.set(scale * 1.45, scale * 0.62, scale);
193
+ island.rotation.y = x * 0.13;
194
+ island.castShadow = false;
195
+ island.receiveShadow = false;
196
+ horizon.add(island);
197
+ }
198
+ parent.add(horizon);
199
+ }
@@ -0,0 +1,88 @@
1
+ // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
+ // ThreeNative does not read this file.
3
+ //
4
+ // The player character, built from the rounded primitives in `shapes.ts`. It lives in its own
5
+ // file because it is the one object here with a design rather than a shape: fifteen placed boxes
6
+ // in three materials, merged down per material so the whole character costs three draw calls.
7
+ import { type BufferGeometry, type Material, Mesh } from "three";
8
+ import { roundedBox } from "./shapes.js";
9
+
10
+ export interface IHeroMaterials {
11
+ readonly accent: Material;
12
+ readonly body: Material;
13
+ readonly dark: Material;
14
+ }
15
+
16
+ export type HeroPartMerger = (
17
+ parts: Iterable<Mesh>,
18
+ options: { readonly label: string },
19
+ ) => BufferGeometry;
20
+
21
+ /**
22
+ * The player character.
23
+ *
24
+ * A `roundedBox(0.6, 1, 0.6)` in one cream colour is what stood here, and it is the first thing a
25
+ * new project shows anyone: a featureless pill. The hero is the one object in a starter scene that
26
+ * has to look deliberate, because everything else — the ledge, the crate, the flag — is obviously
27
+ * scaffolding and reads fine as scaffolding.
28
+ *
29
+ * Authored **centred on y = 0** so `normaliseToMetres(model, { axis: "height", metres: 1.1 })`
30
+ * scales it without moving the feet off the collision capsule.
31
+ *
32
+ * The returned value is a `Mesh`, not a `Group`, because `Player.visual` is one and both
33
+ * `GroundSnap` and `preparePlayerConventions` are written against it. Children hang off it.
34
+ */
35
+ export function hero(materials: IHeroMaterials, mergeParts: HeroPartMerger): Mesh {
36
+ const parts = new Map<Material, Mesh[]>();
37
+ const add = (mesh: Mesh): Mesh => {
38
+ const bucket = parts.get(mesh.material as Material);
39
+ if (bucket === undefined) parts.set(mesh.material as Material, [mesh]);
40
+ else bucket.push(mesh);
41
+ return mesh;
42
+ };
43
+
44
+ const torso = add(new Mesh(roundedBox(0.44, 0.42, 0.32, 0.13, 2), materials.body));
45
+ torso.position.y = 0.06;
46
+ const head = add(new Mesh(roundedBox(0.36, 0.32, 0.32, 0.13, 2), materials.body));
47
+ head.position.y = 0.42;
48
+ const visor = add(new Mesh(roundedBox(0.28, 0.1, 0.06, 0.03, 1), materials.dark));
49
+ visor.position.set(0, 0.37, -0.16);
50
+ const brim = add(new Mesh(roundedBox(0.46, 0.05, 0.42, 0.02, 1), materials.accent));
51
+ brim.position.y = 0.52;
52
+ const crown = add(new Mesh(roundedBox(0.3, 0.16, 0.28, 0.08, 2), materials.accent));
53
+ crown.position.y = 0.6;
54
+ const scarf = add(new Mesh(roundedBox(0.42, 0.1, 0.34, 0.05, 1), materials.accent));
55
+ scarf.position.y = 0.19;
56
+ const tail = add(new Mesh(roundedBox(0.12, 0.26, 0.08, 0.04, 1), materials.accent));
57
+ tail.position.set(0.02, 0.06, 0.19);
58
+ tail.rotation.x = 0.5;
59
+ const pack = add(new Mesh(roundedBox(0.28, 0.28, 0.16, 0.07, 2), materials.dark));
60
+ pack.position.set(0, 0.06, 0.2);
61
+
62
+ for (const side of [-1, 1]) {
63
+ const arm = add(new Mesh(roundedBox(0.12, 0.3, 0.14, 0.055, 1), materials.body));
64
+ arm.position.set(side * 0.28, 0.02, 0);
65
+ arm.rotation.z = side * -0.16;
66
+ const hand = add(new Mesh(roundedBox(0.12, 0.11, 0.13, 0.05, 1), materials.dark));
67
+ hand.position.set(side * 0.31, -0.15, 0);
68
+ const leg = add(new Mesh(roundedBox(0.15, 0.3, 0.16, 0.06, 1), materials.dark));
69
+ leg.position.set(side * 0.12, -0.36, 0);
70
+ const boot = add(new Mesh(roundedBox(0.17, 0.1, 0.22, 0.045, 1), materials.accent));
71
+ boot.position.set(side * 0.12, -0.51, -0.02);
72
+ }
73
+
74
+ // Merged down to one mesh per material: fifteen little boxes is fifteen draw calls for one
75
+ // character, and with the shadow pass that is thirty. The three materials stay separate, so the
76
+ // hat, the pack and the body are still repainted from `materials.ts` alone.
77
+ const meshes: Mesh[] = [];
78
+ for (const [material, group] of parts) {
79
+ const merged = new Mesh(mergeParts(group, { label: "hero" }), material);
80
+ merged.castShadow = true;
81
+ merged.receiveShadow = true;
82
+ meshes.push(merged);
83
+ }
84
+ const root = meshes[0];
85
+ if (root === undefined) throw new Error("The hero produced no geometry.");
86
+ for (const extra of meshes.slice(1)) root.add(extra);
87
+ return root;
88
+ }