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
@@ -10,15 +10,15 @@
10
10
  "build:desktop": "threenative build --target desktop",
11
11
  "build:android": "threenative build --target android",
12
12
  "build:ios": "threenative build --target ios",
13
- "test:native": "pnpm build:desktop && threenative-playtest --scenario native-playtests/survives.playtest.json --target desktop --executable dist-native/__PROJECT_NAME__",
13
+ "test:native": "pnpm build:desktop && threenative-playtest --scenario native-playtests/survives.playtest.json --scenario native-playtests/float.playtest.json --target desktop --executable dist-native/__PROJECT_NAME__",
14
14
  "pretest": "playwright install chromium",
15
15
  "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
16
16
  "typecheck": "tsc --noEmit -p tsconfig.json"
17
17
  },
18
18
  "dependencies": {
19
- "@threenative/core": "0.3.0",
20
- "@threenative/physics": "0.3.0",
21
- "@threenative/ui": "0.3.0",
19
+ "@threenative/core": "0.3.2",
20
+ "@threenative/physics": "0.3.2",
21
+ "@threenative/ui": "0.3.2",
22
22
  "react": "19.2.0",
23
23
  "react-dom": "19.2.0",
24
24
  "react-reconciler": "0.33.0",
@@ -26,13 +26,13 @@
26
26
  },
27
27
  "devDependencies": {
28
28
  "@tailwindcss/vite": "4.3.3",
29
- "@threenative/assets": "0.3.0",
30
- "@threenative/playtest": "0.3.0",
29
+ "@threenative/assets": "0.3.2",
30
+ "@threenative/playtest": "0.3.2",
31
31
  "@types/react": "19.2.0",
32
32
  "@types/react-dom": "19.2.0",
33
33
  "@types/three": "0.185.3",
34
34
  "@vitejs/plugin-react": "6.0.5",
35
- "create-threenative": "0.2.3",
35
+ "create-threenative": "0.2.5",
36
36
  "esbuild": "0.27.0",
37
37
  "playwright": "1.62.1",
38
38
  "tailwindcss": "4.3.3",
@@ -41,7 +41,7 @@
41
41
  "@gltf-transform/cli": "4.4.2"
42
42
  },
43
43
  "optionalDependencies": {
44
- "@threenative/runtime-native": "0.3.0"
44
+ "@threenative/runtime-native": "0.3.2"
45
45
  },
46
46
  "pnpm": {
47
47
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -0,0 +1,75 @@
1
+ {
2
+ "name": "sailing-hull-floats-after-the-run-ends",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
9
+ "warmupFrames": 2900,
10
+ "subject": "player",
11
+ "steps": [
12
+ {
13
+ "kind": "wait",
14
+ "label": "settle-after-the-run-ends",
15
+ "waitTicks": 90,
16
+ "release": true
17
+ },
18
+ {
19
+ "kind": "wait",
20
+ "label": "swell-after-the-run-ends",
21
+ "waitTicks": 240,
22
+ "release": true
23
+ }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": {
27
+ "noConsoleErrors": true,
28
+ "runtimeReady": true
29
+ },
30
+ "resources": [
31
+ {
32
+ "id": "state",
33
+ "path": "status",
34
+ "equals": "lost",
35
+ "throughoutSteps": true,
36
+ "allowTrivial": "Held on purpose, and the reason this scenario exists. The wind runs out at 45 s with no input, so the long warmup ends the run before the baseline is taken: the harness reports this row as already satisfied, which is the proof that every sample below is observed after gameplay stopped. A run that were still sailing here would be measuring the case playtests/float.playtest.json already covers."
37
+ },
38
+ {
39
+ "id": "state",
40
+ "path": "wind",
41
+ "lte": 0,
42
+ "throughoutSteps": true,
43
+ "allowTrivial": "The other half of the same precondition: the wind is spent before the first observation and cannot come back, so no step below can re-enter the sailing branch and quietly restore the updates this scenario is checking for."
44
+ }
45
+ ],
46
+ "components": [
47
+ {
48
+ "entity": "player",
49
+ "component": "seaHeight",
50
+ "changed": true,
51
+ "allowTrivial": "The finding. The ship samples the swell only when its visual update runs; while that update lived inside gameplay it stopped the moment the run ended, and this height froze at whatever wave the boat died on. Every sample here is post-terminal, so a seaHeight that no longer moves is the freeze itself rather than a still ocean."
52
+ },
53
+ {
54
+ "entity": "player",
55
+ "component": "oceanSteps",
56
+ "gte": 200,
57
+ "changed": true,
58
+ "allowTrivial": "The sea must still be simulating after the run is over. Without this row a frozen hull on a frozen ocean would satisfy floatGap, and the scenario would report green on a still photograph."
59
+ },
60
+ {
61
+ "entity": "player",
62
+ "component": "floatGap",
63
+ "gte": -0.08,
64
+ "lte": 0.08,
65
+ "allowTrivial": "The drawn hull's design waterline still sits on the sea after the run is over; a finished game that leaves the boat hanging off its own surface is the visible half of the same defect."
66
+ },
67
+ {
68
+ "entity": "player",
69
+ "component": "readbackStaleFrames",
70
+ "gte": 0,
71
+ "allowTrivial": "A negative age means the GPU height copy never landed, so nothing downstream of it can be trusted."
72
+ }
73
+ ]
74
+ }
75
+ }
@@ -0,0 +1,59 @@
1
+ {
2
+ "name": "sailing-hull-floats",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
9
+ "warmupFrames": 40,
10
+ "subject": "player",
11
+ "steps": [
12
+ {
13
+ "kind": "wait",
14
+ "label": "settle",
15
+ "waitTicks": 90,
16
+ "release": true
17
+ },
18
+ {
19
+ "kind": "wait",
20
+ "label": "swell",
21
+ "waitTicks": 240,
22
+ "release": true
23
+ }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": {
27
+ "noConsoleErrors": true,
28
+ "runtimeReady": true
29
+ },
30
+ "components": [
31
+ {
32
+ "entity": "player",
33
+ "component": "oceanSteps",
34
+ "gte": 200,
35
+ "changed": true,
36
+ "allowTrivial": "The ocean's compute passes must actually dispatch: a SpectralOcean whose process() never runs holds whatever the warmup left in its cascade buffers, and the water is then a still photograph that every other assertion here passes on."
37
+ },
38
+ {
39
+ "entity": "player",
40
+ "component": "seaHeight",
41
+ "changed": true,
42
+ "allowTrivial": "The sea under the hull must move: a spectral ocean whose compute passes never dispatch reads back the same height every frame, and every other assertion here still passes on a frozen sheet of water."
43
+ },
44
+ {
45
+ "entity": "player",
46
+ "component": "floatGap",
47
+ "gte": -0.08,
48
+ "lte": 0.08,
49
+ "allowTrivial": "The drawn hull's design waterline sits on the sea surface; a hull riding above its own water is the failure this row exists to catch."
50
+ },
51
+ {
52
+ "entity": "player",
53
+ "component": "readbackStaleFrames",
54
+ "gte": 0,
55
+ "allowTrivial": "A negative age means the GPU height copy never landed, so nothing downstream of it can be trusted."
56
+ }
57
+ ]
58
+ }
59
+ }
@@ -1,21 +1,36 @@
1
1
  {
2
2
  "acceptanceId": "prd-236-performance-sailing",
3
- "artifacts": { "screenshots": "after" },
3
+ "artifacts": {
4
+ "screenshots": "after"
5
+ },
4
6
  "assert": {
5
7
  "performance": {
6
- "maxDrawCalls": 120,
8
+ "maxDrawCalls": 140,
7
9
  "maxFrameMsP95": 33,
8
- "maxTriangles": 90000
10
+ "maxTriangles": 138000,
11
+ "minFps": 30
9
12
  }
10
13
  },
11
14
  "name": "production-performance",
12
15
  "schemaVersion": 1,
13
16
  "steps": [
14
- { "kind": "input", "press": "ArrowUp", "holdTicks": 60, "release": true },
15
- { "kind": "wait", "waitTicks": 600, "release": true }
17
+ {
18
+ "kind": "input",
19
+ "press": "ArrowUp",
20
+ "holdTicks": 60,
21
+ "release": true
22
+ },
23
+ {
24
+ "kind": "wait",
25
+ "waitTicks": 600,
26
+ "release": true
27
+ }
16
28
  ],
17
29
  "subject": "player",
18
30
  "target": "web",
19
- "viewport": { "height": 1080, "width": 1920 },
31
+ "viewport": {
32
+ "height": 1080,
33
+ "width": 1920
34
+ },
20
35
  "warmupFrames": 60
21
36
  }
@@ -22,6 +22,14 @@
22
22
  "noRuntimeDiagnostics": true,
23
23
  "runtimeReady": true
24
24
  },
25
+ "components": [
26
+ {
27
+ "allowTrivial": "The ship has an authored non-unit size; this retained factor proves normaliseToMetres ran in the generated vessel.",
28
+ "component": "normaliseFactor",
29
+ "entity": "player",
30
+ "lte": 0.99
31
+ }
32
+ ],
25
33
  "movement": { "entity": "player", "minDistance": 0.5 },
26
34
  "visual": [
27
35
  {
@@ -0,0 +1,48 @@
1
+ {
2
+ "name": "sailing-touch-controls",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "movement-anchor",
12
+ "pointers": [{ "id": 7, "x": 0.18, "y": 0.75 }],
13
+ "holdTicks": 2,
14
+ "release": false
15
+ },
16
+ {
17
+ "kind": "input",
18
+ "label": "sail-forward",
19
+ "pointers": [{ "id": 7, "x": 0.18, "y": 0.55 }],
20
+ "holdTicks": 90,
21
+ "release": true
22
+ },
23
+ { "kind": "wait", "label": "settled", "waitTicks": 10, "release": true }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": {
27
+ "noConsoleErrors": true,
28
+ "noNetworkErrors": true,
29
+ "noRuntimeDiagnostics": true,
30
+ "runtimeReady": true
31
+ },
32
+ "movement": { "entity": "player", "minDistance": 0.1 },
33
+ "resources": [
34
+ {
35
+ "id": "state",
36
+ "path": "shipZ",
37
+ "changed": true
38
+ }
39
+ ],
40
+ "visibility": [
41
+ {
42
+ "entity": "touch-controls",
43
+ "present": true,
44
+ "allowTrivial": "Touch-primary lanes keep the authored sailing control visible while movement state proves it is live."
45
+ }
46
+ ]
47
+ }
48
+ }
@@ -0,0 +1,8 @@
1
+ import { normaliseToMetres } from "@threenative/core";
2
+ import type { Group } from "three";
3
+
4
+ export function prepareShipConventions(model: Group): number {
5
+ // 4.6 m stem to transom. At 2.5 the caravel came out smaller than the course buoys beside it,
6
+ // which reads as a toy rather than a passage-making vessel.
7
+ return normaliseToMetres(model, { axis: "longest", metres: 4.6 });
8
+ }
@@ -1,32 +1,81 @@
1
1
  import type { ICtx } from "@threenative/core";
2
- import type { WaveField } from "@threenative/core";
2
+ import type { SpectralOcean } from "@threenative/core";
3
3
  import {
4
4
  Buoyancy3D,
5
5
  CollisionShape3D,
6
6
  type IPhysicsContext,
7
7
  RigidBody3D,
8
8
  } from "@threenative/physics";
9
- import { Group } from "three";
9
+ import { Group, MathUtils } from "three";
10
+ import { prepareShipConventions } from "../conventions.js";
10
11
  import { createMaterials } from "../render/materials.js";
11
12
  import { createShipModel } from "../render/props.js";
13
+ import type { ITouchInput } from "../render/touch-controls.js";
12
14
  import type { GameState } from "../state.js";
13
15
 
14
16
  type GameCtx = ICtx<GameState, IPhysicsContext>;
15
17
 
18
+ /**
19
+ * `SpectralOcean` as the water surface `Buoyancy3D` measures against.
20
+ *
21
+ * The two contracts differ by exactly this adapter: buoyancy asks for a height at a point and a
22
+ * time, and the ocean answers with a height and the age in frames of the GPU copy it came from.
23
+ * Before the first readback lands there is no answer at all, and mean sea level is the right one
24
+ * to give — `Buoyancy3D` rejects a non-finite height by name, so returning nothing is not an
25
+ * option and returning `NaN` would take the whole scene down on frame one.
26
+ */
27
+ function oceanSurface(ocean: SpectralOcean): { sample(x: number, z: number): { height: number } } {
28
+ return {
29
+ sample: (x, z) => ({ height: ocean.sampleHeight(x, z)?.height ?? 0 }),
30
+ };
31
+ }
32
+
16
33
  const MAX_SPEED = 3.8;
17
34
  const STEERING_SPEED = 2.5;
35
+ /** The hull's draught at the template's 4.6 m convention, in world metres. */
36
+ const DESIGN_DRAUGHT = 0.62;
18
37
 
19
38
  export class Ship {
39
+ /** The physics body's transform. Heave comes from here; attitude does not. */
20
40
  readonly mesh = new Group();
41
+ /** What the player sees: the body's position, with an attitude taken from the swell. */
42
+ readonly visual = new Group();
21
43
  readonly body: RigidBody3D;
22
44
  readonly buoyancy: Buoyancy3D;
23
45
  #capsized = false;
46
+ #normaliseFactor: number;
47
+ #heading = 0;
48
+ #elapsed = 0;
49
+ #immersion = 0.5;
50
+ #seaHeight = 0;
51
+ #staleFrames = -1;
52
+ readonly #ocean: SpectralOcean;
24
53
 
25
- constructor(ctx: GameCtx, field: WaveField) {
54
+ constructor(ctx: GameCtx, ocean: SpectralOcean) {
55
+ this.#ocean = ocean;
26
56
  this.mesh.position.set(0, 0.24, 7);
57
+ this.visual.position.set(0, 0.24, 7);
27
58
  this.mesh.castShadow = true;
28
- this.mesh.add(createShipModel(createMaterials()));
59
+ const model = createShipModel(createMaterials());
60
+ this.#normaliseFactor = prepareShipConventions(model);
61
+ // The hull hangs off `visual`, not off the physics body.
62
+ //
63
+ // `Buoyancy3D` applies its displaced-volume force at each hull point, so a point that is
64
+ // deeper than its neighbour torques the body — which is right. What no game can reach is the
65
+ // other half of that: Rapier's angular damping is not on `IRigidBody3DOptions`, and the drag
66
+ // term inside `Buoyancy3D` is computed from the body's *linear* velocity, so it is identical
67
+ // at every point and damps no rotation at all. The torque therefore accumulates with nothing
68
+ // opposing it, and within a few seconds of spawning the ship is tumbling. It always was: the
69
+ // template's own first frame showed the old model lying on its side, and that read as "the
70
+ // boat is a plank" rather than as a boat rolled ninety degrees.
71
+ //
72
+ // So the body keeps the heave — that is what buoyancy is for and it is worth having — and the
73
+ // attitude is read off the swell instead: three height samples around the hull give the pitch
74
+ // and the roll, so the ship pitches into the face of a wave and rolls with the beam of it,
75
+ // which is both stable and closer to what a boat does than a free-spinning rigid body ever was.
76
+ this.visual.add(model);
29
77
  ctx.add(this.mesh);
78
+ ctx.add(this.visual);
30
79
 
31
80
  this.body = new RigidBody3D({
32
81
  collisionLayer: 1,
@@ -40,21 +89,32 @@ export class Ship {
40
89
  body: this.body,
41
90
  density: 1_000,
42
91
  drag: 12,
43
- field,
92
+ field: oceanSurface(ocean),
44
93
  gravity: 9.81,
94
+ // All four points sit **below** the body's centre, at the hull's bottom corners. Two of them
95
+ // used to sit at +0.32 — above it — which puts buoyancy over the centre of mass at the stern
96
+ // and gives the ship a standing moment it can only resolve by rolling onto its side. It did:
97
+ // the template's own first frame showed the hull lying flat on the water with the sail
98
+ // floating beside it, and that was read as "the boat is a plank" rather than as a capsize.
45
99
  hullPoints: [
46
- { position: [-0.45, -0.32, -0.75], volume: 0.275 },
47
- { position: [0.45, -0.32, -0.75], volume: 0.275 },
48
- { position: [-0.45, 0.32, 0.75], volume: 0.275 },
49
- { position: [0.45, 0.32, 0.75], volume: 0.275 },
100
+ { position: [-0.45, -0.3, -0.75], volume: 0.275 },
101
+ { position: [0.45, -0.3, -0.75], volume: 0.275 },
102
+ { position: [-0.45, -0.3, 0.75], volume: 0.275 },
103
+ { position: [0.45, -0.3, 0.75], volume: 0.275 },
50
104
  ],
51
105
  pointSpacing: 0.64,
52
106
  volume: 1.1,
53
107
  });
54
108
  }
55
109
 
56
- update(ctx: GameCtx, deltaTime: number, wind: number): void {
110
+ update(ctx: GameCtx, deltaTime: number, wind: number, touch?: ITouchInput): void {
111
+ this.#elapsed += deltaTime;
57
112
  const move = ctx.input.vector("move");
113
+ if (touch !== undefined) {
114
+ move.x += touch.move.x;
115
+ move.y += touch.move.y;
116
+ move.clampLength(0, 1);
117
+ }
58
118
  const speed = MAX_SPEED * Math.max(0, Math.min(1, wind));
59
119
  const targetX = move.x * STEERING_SPEED * Math.max(0.4, wind);
60
120
  const targetZ = -move.y * speed;
@@ -65,26 +125,102 @@ export class Ship {
65
125
  y: velocity.y,
66
126
  z: velocity.z + (targetZ - velocity.z) * blend,
67
127
  };
68
- this.mesh.rotation.y += move.x * deltaTime * 0.35;
128
+ this.#heading += move.x * deltaTime * 0.35;
129
+ }
130
+
131
+ /**
132
+ * Read the swell under the ship and set the visual's attitude from it.
133
+ *
134
+ * Two samples a boat-length apart give the pitch, two across the beam give the roll. Both are
135
+ * eased rather than snapped, so the ship lags the water the way a hull with mass does.
136
+ *
137
+ * This is drawing, not gameplay, so the scene calls it every frame rather than from `update`.
138
+ * While it lived inside `update` it stopped the moment the run ended — the ocean went on moving
139
+ * under a hull that had frozen mid-wave, and the boat read as welded to a sheet of water that
140
+ * was still visibly rolling past it. Winning the course was the most likely way to see it.
141
+ */
142
+ updateVisual(deltaTime: number): void {
143
+ if (this.#capsized) return;
144
+ const { x, z } = this.mesh.position;
145
+ // `SpectralOcean` has no closed form, so its CPU height is a throttled copy of what the GPU
146
+ // produced and can be `undefined` until the first readback lands. Falling back to the mean
147
+ // sea level for those frames is the whole handling this needs — a boat sitting flat at y = 0
148
+ // for the first fraction of a second is invisible, and throwing is not.
149
+ const heightAt = (sampleX: number, sampleZ: number): number =>
150
+ this.#ocean.sampleHeight(sampleX, sampleZ)?.height ?? 0;
151
+ // Sampled across the hull's real length and beam, not a token metre. The height copy is a
152
+ // bilinear read of a grid about three metres across, so two probes closer together than that
153
+ // largely describe the same cell and the ship barely responds to the swell it is in.
154
+ const aheadHeight = heightAt(x, z - 1.7);
155
+ const asternHeight = heightAt(x, z + 1.7);
156
+ const portHeight = heightAt(x - 0.95, z);
157
+ const starboardHeight = heightAt(x + 0.95, z);
158
+ const hereHeight = heightAt(x, z);
159
+ const probe = this.#ocean.sampleHeight(x, z);
160
+ this.#seaHeight = hereHeight;
161
+ this.#staleFrames = probe === undefined ? -1 : probe.staleFrames;
162
+ // The ship's bow is at **-Z**, so a positive `rotation.x` lifts it — which means the pitch is
163
+ // driven by how much higher the water *ahead* is, not the water astern. Written the other way
164
+ // round the bow rose over troughs and drove into the face of every wave, and the ship
165
+ // photographed as though it were going under bow-first.
166
+ //
167
+ // Clamped, because the height field is a copy of a GPU buffer read on a grid coarser than the
168
+ // hull: two probes can disagree by more than the sea actually does, and without a limit one
169
+ // bad pair throws the ship onto its beam ends for a frame.
170
+ const pitch = MathUtils.clamp(Math.atan2(aheadHeight - asternHeight, 3.4), -0.3, 0.3);
171
+ // How deep the bow is in the water it is meeting. This is the number the HUD's waterline
172
+ // shows: `Buoyancy3D.submergedFraction` measures its hull points through the body's own
173
+ // quaternion, and with the body free to tumble that reading swings between 0 and 1 with
174
+ // nothing to do with what the player can see.
175
+ this.#immersion = Math.min(
176
+ 1,
177
+ Math.max(0, 0.5 + (aheadHeight - this.visual.position.y) / DESIGN_DRAUGHT),
178
+ );
179
+ const roll = MathUtils.clamp(Math.atan2(starboardHeight - portHeight, 1.9), -0.26, 0.26);
180
+ const blend = Math.min(1, Math.max(0, deltaTime) * 3.2);
181
+ this.visual.position.x = this.mesh.position.x;
182
+ this.visual.position.z = this.mesh.position.z;
183
+ // The design waterline sits on the sampled water. The copy can be many frames old while the
184
+ // GPU FFT is busy, so easing this axis would invent a second lag and let the hull drift beyond
185
+ // its own sampled surface between readbacks. Copying the body's y instead put the hull wherever
186
+ // the buoyancy solver happened to have pushed it that frame — which, with no angular damping
187
+ // to settle it, was rarely the same place twice and often most of a hull below the surface.
188
+ this.visual.position.y = hereHeight;
189
+ this.visual.rotation.y = this.#heading;
190
+ this.visual.rotation.x += (pitch - this.visual.rotation.x) * blend;
191
+ this.visual.rotation.z += (roll - this.visual.rotation.z) * blend;
69
192
  }
70
193
 
71
194
  capsize(): void {
72
195
  if (this.#capsized) return;
73
196
  this.#capsized = true;
74
- const model = this.mesh.children[0];
75
- if (model !== undefined) model.rotation.z = Math.PI / 2;
197
+ this.visual.rotation.z = Math.PI / 2;
76
198
  }
77
199
 
78
200
  get capsized(): boolean {
79
201
  return this.#capsized;
80
202
  }
81
203
 
204
+ /** Fraction of the hull the sea is over, from the swell the ship is actually sitting in. */
205
+ get immersion(): number {
206
+ return this.#capsized ? 1 : this.#immersion;
207
+ }
208
+
82
209
  debug(): Record<string, unknown> {
83
210
  const velocity = this.body.linearVelocity;
84
211
  return {
85
212
  capsized: this.#capsized,
86
213
  linearVelocity: [velocity.x, velocity.y, velocity.z],
214
+ normaliseFactor: this.#normaliseFactor,
87
215
  position: this.mesh.position.toArray(),
216
+ immersion: this.#immersion,
217
+ // The three numbers a scenario needs to prove the ship is *floating* rather than merely
218
+ // existing: the sea under it, how far the drawn hull sits off that surface, and whether the
219
+ // height copy is arriving at all. A screenshot cannot tell a still ocean from a moving one.
220
+ seaHeight: this.#seaHeight,
221
+ floatGap: this.visual.position.y - this.#seaHeight,
222
+ readbackStaleFrames: this.#staleFrames,
223
+ oceanSteps: this.#ocean.steps,
88
224
  submergedFraction: this.buoyancy.submergedFraction,
89
225
  };
90
226
  }
@@ -92,5 +228,6 @@ export class Ship {
92
228
  dispose(): void {
93
229
  this.body.dispose();
94
230
  this.mesh.removeFromParent();
231
+ this.visual.removeFromParent();
95
232
  }
96
233
  }
@@ -2,20 +2,27 @@
2
2
  import type { PerspectiveCamera } from "three";
3
3
 
4
4
  export function setupCamera(camera: PerspectiveCamera): void {
5
- camera.fov = 48;
5
+ camera.fov = 52;
6
6
  camera.near = 0.1;
7
- camera.far = 120;
8
- camera.position.set(8, 7, 11);
9
- camera.lookAt(0, 0, 0);
7
+ camera.far = 420;
8
+ camera.position.set(5.2, 2.6, 6.4);
9
+ camera.lookAt(0, 0.6, -2);
10
10
  camera.updateProjectionMatrix();
11
11
  }
12
12
 
13
+ /**
14
+ * Follow from off the starboard quarter, near the water.
15
+ *
16
+ * Held at eight up and six across the ship was a speck in the middle of an empty sea and the rig —
17
+ * the thing that makes it a ship — was too small to read at all. Low and close puts the sails
18
+ * against the sky, which is the shot this game is about.
19
+ */
13
20
  export function followShip(
14
21
  camera: PerspectiveCamera,
15
22
  target: { x: number; y: number; z: number },
16
23
  ): void {
17
- camera.position.x = target.x + 8;
18
- camera.position.y = target.y + 6;
19
- camera.position.z = target.z + 10;
20
- camera.lookAt(target.x, target.y, target.z - 2);
24
+ camera.position.x = target.x + 5.2;
25
+ camera.position.y = target.y + 2.6;
26
+ camera.position.z = target.z + 6.4;
27
+ camera.lookAt(target.x, target.y + 0.9, target.z - 2.4);
21
28
  }
@@ -13,10 +13,15 @@ type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
13
13
  export function setupLighting(scene: Scene, renderer: ShadowRenderer): DirectionalLight {
14
14
  renderer.shadowMap.enabled = true;
15
15
  renderer.shadowMap.type = PCFSoftShadowMap;
16
- scene.add(new HemisphereLight(palette.skyHigh, palette.shadow, 1.8));
16
+ // The ground term is a muted sea blue, not the trough colour. Bounced at full saturation it
17
+ // painted the ship's shadow side the same teal as the water and the hull stopped reading as
18
+ // timber at all.
19
+ scene.add(new HemisphereLight(palette.skyLow, 0x3d6274, 1.05));
17
20
 
18
- const key = new DirectionalLight(palette.player, 3.2);
19
- key.position.set(6, 10, 4);
21
+ // Near-white, not the accent. A strongly tinted key contaminates the canvas, the timber and the
22
+ // sea at once, and no per-material tweak can pull them back apart.
23
+ const key = new DirectionalLight(0xfff4e0, 2.9);
24
+ key.position.set(9, 13, 5);
20
25
  key.castShadow = true;
21
26
  key.shadow.mapSize.set(1024, 1024);
22
27
  key.shadow.camera.near = 0.5;
@@ -28,9 +33,9 @@ export function setupLighting(scene: Scene, renderer: ShadowRenderer): Direction
28
33
  key.shadow.normalBias = 0.04;
29
34
  scene.add(key);
30
35
 
31
- const rim = new DirectionalLight(palette.accent, 1.1);
36
+ const rim = new DirectionalLight(palette.skyLow, 0.7);
32
37
  rim.position.set(-8, 4, -10);
33
38
  scene.add(rim);
34
- scene.add(new AmbientLight(palette.shadow, 0.3));
39
+ scene.add(new AmbientLight(palette.shadow, 0.5));
35
40
  return key;
36
41
  }
@@ -36,7 +36,11 @@ interface ILoadingHost {
36
36
  };
37
37
  readonly renderer: { compileAsync(scene: Scene, camera: Camera): Promise<void> };
38
38
  readonly scene: Scene;
39
- readonly startup: { readonly progress: number; whenReady(): Promise<void> };
39
+ readonly startup: {
40
+ readonly progress: number;
41
+ readonly warmup?: { readonly status: "complete" | "incomplete" | "unavailable" };
42
+ whenReady(): Promise<void>;
43
+ };
40
44
  readonly viewport?: {
41
45
  readonly safeArea: { height: number; width: number; x: number; y: number };
42
46
  };
@@ -231,7 +235,13 @@ export function createLoadingScreen(host: ILoadingHost): ILoadingController {
231
235
  };
232
236
 
233
237
  const updateProgress = (value: number): void => {
234
- progress = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
238
+ const bounded = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
239
+ // A missing or incomplete backend observation cannot prove that all first-use work is done.
240
+ // Keep the bar visibly indeterminate until readiness removes the cover; never turn unknown
241
+ // coverage into a false 100% claim.
242
+ const observationUnknown =
243
+ host.startup.warmup !== undefined && host.startup.warmup.status !== "complete";
244
+ progress = observationUnknown ? Math.min(0.9, bounded) : bounded;
235
245
  setFillUv(fill.geometry, progress, fillBaseU);
236
246
  status?.update(progress);
237
247
  layout();