create-threenative 0.2.6 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (622) hide show
  1. package/README.md +2 -2
  2. package/agent-docs/references/build-profiles.md +126 -0
  3. package/agent-docs/references/capability-reference.md +431 -20
  4. package/agent-docs/references/performance-basics.md +8 -5
  5. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  6. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  7. package/agent-docs/references/visual-baseline.md +8 -4
  8. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +5 -5
  10. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/threenative-context/SKILL.md +1 -1
  12. package/agent-files/.agents/skills/threenative-performance/SKILL.md +3 -3
  13. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  14. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  15. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  16. package/capabilities.json +555 -21
  17. package/dist/index.d.ts +30 -1
  18. package/dist/index.js +294 -55
  19. package/dist/threenative.js +714 -154
  20. package/package.json +6 -6
  21. package/template-assets/assets/mannequin-combat.glb +0 -0
  22. package/template-assets/assets/mannequin.glb +0 -0
  23. package/template-assets/assets/player-viewmodel.glb +0 -0
  24. package/template-assets/assets/sky.jpg +0 -0
  25. package/template-assets/clearwater/README.md +141 -0
  26. package/template-assets/clearwater/install.mjs +50 -0
  27. package/template-assets/clearwater/src/clearwater.ts +180 -0
  28. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  29. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  30. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  31. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  32. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  33. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  34. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  35. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  36. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  37. package/template-assets/patches/three@0.185.1.patch +2101 -138
  38. package/template-assets/worldEnvironment.ts +52 -1
  39. package/templates/action-rpg/AGENTS.md +42 -42
  40. package/templates/action-rpg/CLAUDE.md +42 -42
  41. package/templates/action-rpg/kit.json +1 -1
  42. package/templates/action-rpg/package.json +13 -7
  43. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  44. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  45. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  46. package/templates/action-rpg/src/conventions.ts +24 -18
  47. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  48. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  49. package/templates/action-rpg/src/entities/Player.ts +102 -32
  50. package/templates/action-rpg/src/game.ts +3 -3
  51. package/templates/action-rpg/src/render/camera.ts +18 -16
  52. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  53. package/templates/action-rpg/src/render/lighting.ts +45 -28
  54. package/templates/action-rpg/src/render/loading.ts +4 -4
  55. package/templates/action-rpg/src/render/materials.ts +191 -47
  56. package/templates/action-rpg/src/render/palette.ts +14 -13
  57. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  58. package/templates/action-rpg/src/render/props.ts +117 -0
  59. package/templates/action-rpg/src/render/quality.ts +40 -82
  60. package/templates/action-rpg/src/render/sky.ts +36 -13
  61. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  62. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  63. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  64. package/templates/action-rpg/src/style.css +9 -7
  65. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  66. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  67. package/templates/action-rpg/threenative.config.ts +14 -1
  68. package/templates/action-rpg/vite.config.ts +4 -1
  69. package/templates/minimal/AGENTS.md +10 -10
  70. package/templates/minimal/CLAUDE.md +10 -10
  71. package/templates/minimal/package.json +12 -6
  72. package/templates/minimal/playtests/play.playtest.json +6 -5
  73. package/templates/minimal/playtests/sky.playtest.json +27 -0
  74. package/templates/minimal/src/conventions.ts +6 -3
  75. package/templates/minimal/src/entities/Player.ts +73 -27
  76. package/templates/minimal/src/main.ts +2 -3
  77. package/templates/minimal/src/render/camera.ts +22 -4
  78. package/templates/minimal/src/render/lighting.ts +24 -48
  79. package/templates/minimal/src/render/materials.ts +158 -13
  80. package/templates/minimal/src/render/palette.ts +10 -7
  81. package/templates/minimal/src/render/postprocessing.ts +12 -25
  82. package/templates/minimal/src/render/quality.ts +35 -69
  83. package/templates/minimal/src/render/sky.ts +35 -54
  84. package/templates/minimal/src/render/touch-controls.ts +1 -1
  85. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  86. package/templates/minimal/src/scenes/Play.ts +121 -111
  87. package/templates/minimal/src/state.ts +0 -4
  88. package/templates/minimal/src/style.css +0 -10
  89. package/templates/minimal/threenative.config.ts +14 -1
  90. package/templates/minimal/vite.config.ts +4 -1
  91. package/templates/platformer/AGENTS.md +18 -56
  92. package/templates/platformer/CLAUDE.md +18 -56
  93. package/templates/platformer/kit.json +2 -2
  94. package/templates/platformer/package.json +13 -9
  95. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  96. package/templates/platformer/playtests/collect.playtest.json +8 -34
  97. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  98. package/templates/platformer/playtests/damage.playtest.json +40 -15
  99. package/templates/platformer/playtests/hud.playtest.json +34 -0
  100. package/templates/platformer/playtests/move.playtest.json +24 -0
  101. package/templates/platformer/playtests/performance.playtest.json +24 -7
  102. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  103. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  104. package/templates/platformer/playtests/survives.playtest.json +3 -19
  105. package/templates/platformer/playtests/world.playtest.json +26 -0
  106. package/templates/platformer/src/entities/Fox.ts +273 -0
  107. package/templates/platformer/src/entities/Pickup.ts +43 -60
  108. package/templates/platformer/src/entities/Walker.ts +88 -0
  109. package/templates/platformer/src/game.ts +11 -8
  110. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  111. package/templates/platformer/src/level/Stage.ts +469 -0
  112. package/templates/platformer/src/render/blocks.ts +94 -0
  113. package/templates/platformer/src/render/camera.ts +28 -3
  114. package/templates/platformer/src/render/fox.ts +196 -0
  115. package/templates/platformer/src/render/lighting.ts +42 -33
  116. package/templates/platformer/src/render/materials.ts +115 -5
  117. package/templates/platformer/src/render/palette.ts +68 -53
  118. package/templates/platformer/src/render/pickups.ts +142 -0
  119. package/templates/platformer/src/render/postprocessing.ts +12 -2
  120. package/templates/platformer/src/render/props.ts +147 -0
  121. package/templates/platformer/src/render/quality.ts +47 -99
  122. package/templates/platformer/src/render/scenery.ts +172 -0
  123. package/templates/platformer/src/render/sky.ts +120 -31
  124. package/templates/platformer/src/render/touch-controls.ts +5 -2
  125. package/templates/platformer/src/render/walkers.ts +96 -0
  126. package/templates/platformer/src/render/waterfall.ts +85 -0
  127. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  128. package/templates/platformer/src/scenes/Boot.ts +3 -4
  129. package/templates/platformer/src/scenes/Play.ts +362 -0
  130. package/templates/platformer/src/state.ts +16 -14
  131. package/templates/platformer/src/style.css +9 -8
  132. package/templates/platformer/src/ui/Hud.tsx +62 -29
  133. package/templates/platformer/src/ui/Menu.tsx +2 -2
  134. package/templates/platformer/threenative.config.ts +14 -1
  135. package/templates/platformer/vite.config.ts +4 -1
  136. package/templates/puzzle/AGENTS.md +19 -20
  137. package/templates/puzzle/CLAUDE.md +19 -20
  138. package/templates/puzzle/assets/native-proof.glb +0 -0
  139. package/templates/puzzle/assets/native-proof.png +0 -0
  140. package/templates/puzzle/kit.json +1 -1
  141. package/templates/puzzle/package.json +13 -7
  142. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  143. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  144. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  145. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  146. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  147. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  148. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  149. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  150. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  151. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  152. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  153. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  154. package/templates/puzzle/src/entities/Crate.ts +99 -42
  155. package/templates/puzzle/src/entities/Seal.ts +69 -0
  156. package/templates/puzzle/src/entities/Warden.ts +135 -0
  157. package/templates/puzzle/src/game.ts +15 -11
  158. package/templates/puzzle/src/render/camera.ts +66 -31
  159. package/templates/puzzle/src/render/crateShape.ts +70 -0
  160. package/templates/puzzle/src/render/lighting.ts +41 -41
  161. package/templates/puzzle/src/render/loading.ts +4 -4
  162. package/templates/puzzle/src/render/materials.ts +131 -27
  163. package/templates/puzzle/src/render/palette.ts +19 -29
  164. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  165. package/templates/puzzle/src/render/quality.ts +71 -80
  166. package/templates/puzzle/src/render/shapes.ts +109 -108
  167. package/templates/puzzle/src/render/sky.ts +18 -10
  168. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  169. package/templates/puzzle/src/render/vault.ts +315 -0
  170. package/templates/puzzle/src/render/warden.ts +46 -0
  171. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  172. package/templates/puzzle/src/scenes/Play.ts +793 -0
  173. package/templates/puzzle/src/state.ts +55 -24
  174. package/templates/puzzle/src/style.css +7 -8
  175. package/templates/puzzle/src/ui/App.tsx +2 -2
  176. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  177. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  178. package/templates/puzzle/threenative.config.ts +14 -1
  179. package/templates/puzzle/vite.config.ts +4 -1
  180. package/templates/racing/AGENTS.md +19 -20
  181. package/templates/racing/CLAUDE.md +19 -20
  182. package/templates/racing/package.json +13 -7
  183. package/templates/racing/playtests/boost.playtest.json +33 -12
  184. package/templates/racing/playtests/outcome.playtest.json +32 -50
  185. package/templates/racing/playtests/performance.playtest.json +2 -1
  186. package/templates/racing/playtests/ranking.playtest.json +5 -14
  187. package/templates/racing/playtests/rescue.playtest.json +2 -2
  188. package/templates/racing/playtests/reverse.playtest.json +30 -8
  189. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  190. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  191. package/templates/racing/src/entities/CarBody.ts +327 -0
  192. package/templates/racing/src/entities/LineDriver.ts +220 -0
  193. package/templates/racing/src/entities/RacingCar.ts +150 -89
  194. package/templates/racing/src/entities/Rival.ts +61 -24
  195. package/templates/racing/src/game.ts +5 -0
  196. package/templates/racing/src/render/camera.ts +49 -7
  197. package/templates/racing/src/render/lighting.ts +36 -37
  198. package/templates/racing/src/render/materials.ts +239 -19
  199. package/templates/racing/src/render/palette.ts +19 -21
  200. package/templates/racing/src/render/postprocessing.ts +12 -2
  201. package/templates/racing/src/render/quality.ts +43 -82
  202. package/templates/racing/src/render/shapes.ts +20 -6
  203. package/templates/racing/src/render/sky.ts +47 -39
  204. package/templates/racing/src/render/touch-controls.ts +1 -1
  205. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  206. package/templates/racing/src/scenes/Race.ts +107 -54
  207. package/templates/racing/src/state.ts +2 -0
  208. package/templates/racing/src/track/Checkline.ts +22 -7
  209. package/templates/racing/src/track/Lap.ts +64 -36
  210. package/templates/racing/src/track/Ranking.ts +20 -11
  211. package/templates/racing/src/track/Track.ts +809 -361
  212. package/templates/racing/src/track/TrackSector.ts +40 -11
  213. package/templates/racing/src/track/circuit.ts +477 -0
  214. package/templates/racing/src/track/rescue.ts +16 -4
  215. package/templates/racing/threenative.config.ts +14 -1
  216. package/templates/racing/vite.config.ts +4 -1
  217. package/templates/rts/AGENTS.md +96 -0
  218. package/templates/rts/CLAUDE.md +98 -0
  219. package/templates/rts/kit.json +7 -0
  220. package/templates/{defense → rts}/package.json +13 -7
  221. package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
  222. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  223. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  224. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  225. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  226. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  227. package/templates/rts/playtests/survives.playtest.json +58 -0
  228. package/templates/rts/public/favicon.svg +4 -0
  229. package/templates/rts/src/game.ts +64 -0
  230. package/templates/rts/src/orders.ts +22 -0
  231. package/templates/rts/src/render/army.ts +346 -0
  232. package/templates/rts/src/render/camera.ts +123 -0
  233. package/templates/rts/src/render/lighting.ts +61 -0
  234. package/templates/rts/src/render/loading.ts +33 -0
  235. package/templates/rts/src/render/materials.ts +152 -0
  236. package/templates/rts/src/render/models.ts +705 -0
  237. package/templates/rts/src/render/palette.ts +17 -0
  238. package/templates/rts/src/render/picking.ts +93 -0
  239. package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
  240. package/templates/rts/src/render/quality.ts +128 -0
  241. package/templates/rts/src/render/resources.ts +141 -0
  242. package/templates/rts/src/render/sky.ts +44 -0
  243. package/templates/rts/src/render/terrain.ts +116 -0
  244. package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
  245. package/templates/rts/src/scenes/Play.ts +650 -0
  246. package/templates/rts/src/sim/ai.ts +1140 -0
  247. package/templates/rts/src/sim/combat.ts +416 -0
  248. package/templates/rts/src/sim/construction.ts +374 -0
  249. package/templates/rts/src/sim/economy.ts +167 -0
  250. package/templates/rts/src/sim/game.ts +1082 -0
  251. package/templates/rts/src/sim/movement.ts +371 -0
  252. package/templates/rts/src/sim/nav.ts +276 -0
  253. package/templates/rts/src/sim/production.ts +180 -0
  254. package/templates/rts/src/sim/terrain.ts +170 -0
  255. package/templates/rts/src/sim/types.ts +647 -0
  256. package/templates/rts/src/sim/vision.ts +46 -0
  257. package/templates/rts/src/state.ts +100 -0
  258. package/templates/{defense → rts}/src/style.css +21 -8
  259. package/templates/rts/src/ui/App.tsx +21 -0
  260. package/templates/rts/src/ui/Commands.tsx +129 -0
  261. package/templates/rts/src/ui/GameUi.tsx +22 -0
  262. package/templates/rts/src/ui/Hud.tsx +165 -0
  263. package/templates/rts/src/ui/Minimap.tsx +84 -0
  264. package/templates/rts/tailwind.config.ts +2 -0
  265. package/templates/rts/threenative.config.ts +56 -0
  266. package/templates/rts/tsconfig.json +17 -0
  267. package/templates/{defense → rts}/vite.config.ts +4 -1
  268. package/templates/runner/AGENTS.md +6 -10
  269. package/templates/runner/CLAUDE.md +6 -10
  270. package/templates/runner/README.md +3 -3
  271. package/templates/runner/package.json +13 -7
  272. package/templates/runner/playtests/performance.playtest.json +2 -2
  273. package/templates/runner/src/conventions.ts +4 -3
  274. package/templates/runner/src/entities/Runner.ts +54 -7
  275. package/templates/runner/src/game.ts +2 -0
  276. package/templates/runner/src/render/camera.ts +4 -2
  277. package/templates/runner/src/render/dust.ts +5 -2
  278. package/templates/runner/src/render/lighting.ts +41 -45
  279. package/templates/runner/src/render/loading.ts +2 -2
  280. package/templates/runner/src/render/materials.ts +165 -25
  281. package/templates/runner/src/render/palette.ts +17 -28
  282. package/templates/runner/src/render/postprocessing.ts +12 -2
  283. package/templates/runner/src/render/quality.ts +42 -96
  284. package/templates/runner/src/render/shapes.ts +59 -37
  285. package/templates/runner/src/render/sky.ts +32 -41
  286. package/templates/runner/src/render/touch-controls.ts +1 -1
  287. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  288. package/templates/runner/src/scenes/Run.ts +26 -6
  289. package/templates/runner/src/track.ts +6 -1
  290. package/templates/runner/threenative.config.ts +14 -1
  291. package/templates/runner/vite.config.ts +4 -1
  292. package/templates/sailing/AGENTS.md +12 -12
  293. package/templates/sailing/CLAUDE.md +12 -12
  294. package/templates/sailing/assets/ship.glb +0 -0
  295. package/templates/sailing/package.json +13 -7
  296. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  297. package/templates/sailing/playtests/sails.playtest.json +33 -0
  298. package/templates/sailing/playtests/win.playtest.json +156 -8
  299. package/templates/sailing/src/conventions.ts +29 -2
  300. package/templates/sailing/src/entities/Ship.ts +381 -57
  301. package/templates/sailing/src/game.ts +14 -0
  302. package/templates/sailing/src/render/camera.ts +63 -9
  303. package/templates/sailing/src/render/lighting.ts +49 -27
  304. package/templates/sailing/src/render/materials.ts +50 -15
  305. package/templates/sailing/src/render/ocean.ts +647 -60
  306. package/templates/sailing/src/render/palette.ts +16 -12
  307. package/templates/sailing/src/render/postprocessing.ts +12 -2
  308. package/templates/sailing/src/render/props.ts +316 -442
  309. package/templates/sailing/src/render/quality.ts +14 -4
  310. package/templates/sailing/src/render/sky.ts +116 -23
  311. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  312. package/templates/sailing/src/scenes/Boot.ts +21 -0
  313. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  314. package/templates/sailing/src/state.ts +6 -0
  315. package/templates/sailing/src/ui/Hud.tsx +41 -9
  316. package/templates/sailing/threenative.config.ts +14 -1
  317. package/templates/sailing/vite.config.ts +4 -1
  318. package/templates/shooter/AGENTS.md +27 -42
  319. package/templates/shooter/CLAUDE.md +27 -42
  320. package/templates/shooter/index.html +1 -0
  321. package/templates/shooter/package.json +13 -7
  322. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  323. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  324. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  325. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  326. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  327. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  328. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  329. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  330. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  331. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  332. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  333. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  334. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  335. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  336. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  337. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  338. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  339. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  340. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  341. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  342. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  343. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  344. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  345. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  346. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  347. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  348. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  349. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  350. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  351. package/templates/shooter/playtests/performance.playtest.json +62 -26
  352. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  353. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  354. package/templates/shooter/playtests/survives.playtest.json +36 -30
  355. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  356. package/templates/shooter/src/entities/Breakables.ts +412 -0
  357. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  358. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  359. package/templates/shooter/src/entities/Rifle.ts +442 -0
  360. package/templates/shooter/src/entities/Target.ts +199 -83
  361. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  362. package/templates/shooter/src/game.ts +75 -41
  363. package/templates/shooter/src/main.ts +0 -1
  364. package/templates/shooter/src/postPhysics.ts +36 -0
  365. package/templates/shooter/src/render/camera.ts +78 -74
  366. package/templates/shooter/src/render/decals.ts +142 -82
  367. package/templates/shooter/src/render/facade.ts +1373 -0
  368. package/templates/shooter/src/render/gunfx.ts +704 -0
  369. package/templates/shooter/src/render/lighting.ts +52 -38
  370. package/templates/shooter/src/render/loading.ts +2 -2
  371. package/templates/shooter/src/render/materials.ts +100 -88
  372. package/templates/shooter/src/render/occlusion.ts +108 -0
  373. package/templates/shooter/src/render/palette.ts +10 -10
  374. package/templates/shooter/src/render/palm.ts +455 -0
  375. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  376. package/templates/shooter/src/render/postprocessing.ts +15 -3
  377. package/templates/shooter/src/render/quality.ts +40 -82
  378. package/templates/shooter/src/render/scale.ts +148 -15
  379. package/templates/shooter/src/render/shapes.ts +138 -613
  380. package/templates/shooter/src/render/sky.ts +35 -35
  381. package/templates/shooter/src/render/town-schematic.ts +120 -0
  382. package/templates/shooter/src/render/town.ts +986 -0
  383. package/templates/shooter/src/render/townMaterials.ts +160 -0
  384. package/templates/shooter/src/render/vehicles.ts +741 -0
  385. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  386. package/templates/shooter/src/scenes/Play.ts +727 -650
  387. package/templates/shooter/src/state.ts +26 -41
  388. package/templates/shooter/src/style.css +207 -11
  389. package/templates/shooter/src/surfaces.ts +131 -0
  390. package/templates/shooter/src/ui/App.tsx +9 -10
  391. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  392. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  393. package/templates/shooter/src/ui/Hud.tsx +428 -39
  394. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  395. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  396. package/templates/shooter/src/ui/main.tsx +2 -3
  397. package/templates/shooter/threenative.config.ts +14 -1
  398. package/templates/shooter/vite.config.ts +4 -1
  399. package/templates/starter/AGENTS.md +17 -17
  400. package/templates/starter/CLAUDE.md +17 -17
  401. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  402. package/templates/starter/package.json +13 -7
  403. package/templates/starter/playtests/play.playtest.json +2 -1
  404. package/templates/starter/playtests/survives.playtest.json +1 -1
  405. package/templates/starter/src/conventions.ts +6 -3
  406. package/templates/starter/src/entities/Goal.ts +35 -42
  407. package/templates/starter/src/entities/Player.ts +99 -16
  408. package/templates/starter/src/render/arena.ts +131 -0
  409. package/templates/starter/src/render/lighting.ts +27 -44
  410. package/templates/starter/src/render/materials.ts +164 -35
  411. package/templates/starter/src/render/palette.ts +16 -16
  412. package/templates/starter/src/render/postprocessing.ts +6 -7
  413. package/templates/starter/src/render/quality.ts +43 -101
  414. package/templates/starter/src/render/shapes.ts +1 -1
  415. package/templates/starter/src/render/sky.ts +39 -45
  416. package/templates/starter/src/render/touch-controls.ts +3 -1
  417. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  418. package/templates/starter/src/scenes/Play.ts +82 -81
  419. package/templates/starter/threenative.config.ts +14 -1
  420. package/templates/starter/vite.config.ts +4 -1
  421. package/templates/tower-defense/.codex/config.toml +19 -0
  422. package/templates/tower-defense/.cursor/mcp.json +32 -0
  423. package/templates/tower-defense/.gemini/settings.json +32 -0
  424. package/templates/tower-defense/.mcp.json +32 -0
  425. package/templates/tower-defense/.vscode/mcp.json +36 -0
  426. package/templates/tower-defense/.zed/settings.json +36 -0
  427. package/templates/{defense → tower-defense}/AGENTS.md +14 -12
  428. package/templates/{defense → tower-defense}/CLAUDE.md +14 -12
  429. package/templates/tower-defense/README.md +16 -0
  430. package/templates/tower-defense/index.html +12 -0
  431. package/templates/tower-defense/kit.json +7 -0
  432. package/templates/tower-defense/opencode.json +41 -0
  433. package/templates/tower-defense/package.json +56 -0
  434. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  435. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  436. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  437. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  438. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  439. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  440. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  441. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  442. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  443. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  444. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  445. package/templates/tower-defense/src/balance.ts +187 -0
  446. package/templates/tower-defense/src/board/Board.ts +100 -0
  447. package/templates/tower-defense/src/board/Route.ts +84 -0
  448. package/templates/tower-defense/src/camera-rig.ts +62 -0
  449. package/templates/tower-defense/src/economy.ts +64 -0
  450. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  451. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  452. package/templates/tower-defense/src/game.ts +72 -0
  453. package/templates/tower-defense/src/intents.ts +21 -0
  454. package/templates/tower-defense/src/main.ts +15 -0
  455. package/templates/tower-defense/src/physics.ts +6 -0
  456. package/templates/tower-defense/src/render/camera.ts +38 -0
  457. package/templates/tower-defense/src/render/lighting.ts +42 -0
  458. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  459. package/templates/tower-defense/src/render/materials.ts +103 -0
  460. package/templates/tower-defense/src/render/palette.ts +58 -0
  461. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  462. package/templates/tower-defense/src/render/quality.ts +128 -0
  463. package/templates/tower-defense/src/render/shapes.ts +550 -0
  464. package/templates/tower-defense/src/render/sky.ts +27 -0
  465. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  466. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  467. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  468. package/templates/tower-defense/src/state.ts +88 -0
  469. package/templates/tower-defense/src/style.css +137 -0
  470. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  471. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  472. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  473. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  474. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  475. package/templates/tower-defense/src/ui/main.tsx +14 -0
  476. package/templates/tower-defense/src/waves.ts +90 -0
  477. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  478. package/templates/tower-defense/vite.config.ts +41 -0
  479. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  480. package/agent-files/.claude/skills/ponytail/SKILL.md +0 -68
  481. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  482. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -53
  483. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  484. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -65
  485. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -58
  486. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  487. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  488. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  489. package/agent-files/AGENT-ROLES.md +0 -26
  490. package/templates/action-rpg/src/render/shapes.ts +0 -269
  491. package/templates/action-rpg/src/render/types.ts +0 -3
  492. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  493. package/templates/defense/README.md +0 -10
  494. package/templates/defense/kit.json +0 -7
  495. package/templates/defense/playtests/leak.playtest.json +0 -23
  496. package/templates/defense/playtests/placement.playtest.json +0 -40
  497. package/templates/defense/playtests/scan.playtest.json +0 -20
  498. package/templates/defense/playtests/survive.playtest.json +0 -45
  499. package/templates/defense/playtests/survives.playtest.json +0 -36
  500. package/templates/defense/src/attackers/Attacker.ts +0 -120
  501. package/templates/defense/src/board/Route.ts +0 -94
  502. package/templates/defense/src/conventions.ts +0 -18
  503. package/templates/defense/src/economy.ts +0 -36
  504. package/templates/defense/src/entities/Player.ts +0 -52
  505. package/templates/defense/src/game.ts +0 -51
  506. package/templates/defense/src/physics.ts +0 -13
  507. package/templates/defense/src/placement/Buildable.ts +0 -49
  508. package/templates/defense/src/render/camera.ts +0 -16
  509. package/templates/defense/src/render/lighting.ts +0 -37
  510. package/templates/defense/src/render/materials.ts +0 -22
  511. package/templates/defense/src/render/palette.ts +0 -28
  512. package/templates/defense/src/render/quality.ts +0 -170
  513. package/templates/defense/src/render/shapes.ts +0 -246
  514. package/templates/defense/src/render/sky.ts +0 -45
  515. package/templates/defense/src/scenes/Boot.ts +0 -12
  516. package/templates/defense/src/scenes/Defense.ts +0 -231
  517. package/templates/defense/src/state.ts +0 -56
  518. package/templates/defense/src/towers/Tower.ts +0 -95
  519. package/templates/defense/src/towers/targeting.ts +0 -53
  520. package/templates/defense/src/ui/Hud.tsx +0 -62
  521. package/templates/defense/src/ui/Menu.tsx +0 -7
  522. package/templates/defense/src/waves.ts +0 -40
  523. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  524. package/templates/minimal/src/render/hud.ts +0 -69
  525. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  526. package/templates/platformer/playtests/chase.playtest.json +0 -21
  527. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  528. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  529. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  530. package/templates/platformer/playtests/physics.playtest.json +0 -14
  531. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  532. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  533. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  534. package/templates/platformer/src/conventions.ts +0 -18
  535. package/templates/platformer/src/entities/Character.ts +0 -286
  536. package/templates/platformer/src/entities/Chaser.ts +0 -118
  537. package/templates/platformer/src/entities/Patrol.ts +0 -93
  538. package/templates/platformer/src/level/Platform.ts +0 -46
  539. package/templates/platformer/src/render/rig.ts +0 -60
  540. package/templates/platformer/src/render/terrain.ts +0 -31
  541. package/templates/platformer/src/scenes/Level.ts +0 -241
  542. package/templates/puzzle/README.md +0 -43
  543. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  544. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  545. package/templates/puzzle/src/conventions.ts +0 -25
  546. package/templates/puzzle/src/entities/Ball.ts +0 -70
  547. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  548. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  549. package/templates/puzzle/src/physics.ts +0 -19
  550. package/templates/puzzle/src/room.ts +0 -83
  551. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  552. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  553. package/templates/shooter/playtests/combat.playtest.json +0 -48
  554. package/templates/shooter/playtests/fail.playtest.json +0 -31
  555. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  556. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  557. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  558. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  559. package/templates/shooter/src/combat/damage.ts +0 -40
  560. package/templates/shooter/src/conventions.ts +0 -51
  561. package/templates/shooter/src/entities/Pickup.ts +0 -70
  562. package/templates/shooter/src/entities/Player.ts +0 -310
  563. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  564. package/templates/shooter/src/playtest-events.ts +0 -15
  565. package/templates/shooter/src/render/touch-controls.ts +0 -305
  566. package/templates/shooter/src/render/types.ts +0 -3
  567. package/templates/shooter/src/render/ui.css +0 -330
  568. package/templates/shooter/src/render/ui.ts +0 -75
  569. package/templates/shooter/src/render/vfx.ts +0 -215
  570. package/templates/shooter/src/ui/Menu.tsx +0 -41
  571. package/templates/shooter/src/waves.ts +0 -50
  572. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  573. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  574. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  575. package/templates/starter/playtests/assets.playtest.json +0 -65
  576. package/templates/starter/playtests/buffer.playtest.json +0 -79
  577. package/templates/starter/playtests/cloth.playtest.json +0 -113
  578. package/templates/starter/playtests/coyote.playtest.json +0 -87
  579. package/templates/starter/playtests/gameover.playtest.json +0 -66
  580. package/templates/starter/playtests/goal.playtest.json +0 -67
  581. package/templates/starter/playtests/look.playtest.json +0 -175
  582. package/templates/starter/playtests/models-baseline.png +0 -0
  583. package/templates/starter/playtests/models.playtest.json +0 -74
  584. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  585. package/templates/starter/playtests/odometer.playtest.json +0 -54
  586. package/templates/starter/playtests/restart.playtest.json +0 -91
  587. package/templates/starter/playtests/seed.playtest.json +0 -54
  588. package/templates/starter/playtests/textures-baseline.png +0 -0
  589. package/templates/starter/playtests/textures.playtest.json +0 -74
  590. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  591. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  592. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  593. package/templates/starter/src/render/coast.ts +0 -199
  594. package/templates/starter/src/render/hero.ts +0 -88
  595. package/templates/starter/src/render/implicitSurface.ts +0 -199
  596. package/templates/starter/src/render/kuwahara.ts +0 -174
  597. package/templates/starter/src/render/outline.ts +0 -141
  598. package/templates/starter/src/render/painterly.ts +0 -86
  599. package/templates/starter/src/render/rockRidge.ts +0 -198
  600. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  601. package/templates/starter/src/render/scenery.ts +0 -40
  602. package/templates/starter/src/render/textureLifetime.ts +0 -53
  603. package/templates/starter/src/render/water.ts +0 -38
  604. package/templates/starter/src/render/watercolor.ts +0 -85
  605. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  606. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  607. /package/templates/{defense → rts}/.codex/config.toml +0 -0
  608. /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
  609. /package/templates/{defense → rts}/.gemini/settings.json +0 -0
  610. /package/templates/{defense → rts}/.mcp.json +0 -0
  611. /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
  612. /package/templates/{defense → rts}/.zed/settings.json +0 -0
  613. /package/templates/{defense → rts}/index.html +0 -0
  614. /package/templates/{defense → rts}/opencode.json +0 -0
  615. /package/templates/{defense → rts}/src/main.ts +0 -0
  616. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  617. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  618. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  619. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  620. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  621. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  622. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
@@ -1,20 +1,29 @@
1
1
  import type { ICtx } from "@threenative/core";
2
- import type { SpectralOcean } from "@threenative/core";
2
+ import { SoftBody3D, 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, MathUtils } from "three";
10
- import { prepareShipConventions } from "../conventions.js";
9
+ import { Euler, Group, MathUtils, type Object3D, Quaternion, Vector3 } from "three";
10
+ import { measureHull, prepareShipConventions } from "../conventions.js";
11
11
  import { createMaterials } from "../render/materials.js";
12
- import { createShipModel } from "../render/props.js";
12
+ import { surfaceHeight } from "../render/ocean.js";
13
+ import { SHIP_SAILS, createSails, createShipModel } from "../render/props.js";
13
14
  import type { ITouchInput } from "../render/touch-controls.js";
14
15
  import type { GameState } from "../state.js";
15
16
 
17
+ /** What `Sailing.load()` hands the entity: `ship.glb`'s loaded scene. */
18
+ export interface IShipModel {
19
+ readonly scene: Object3D;
20
+ }
21
+
16
22
  type GameCtx = ICtx<GameState, IPhysicsContext>;
17
23
 
24
+ /** Scratch for composing a sail's rest rotation with the hull's. Allocating per tick is not free. */
25
+ const REST = new Quaternion();
26
+
18
27
  /**
19
28
  * `SpectralOcean` as the water surface `Buoyancy3D` measures against.
20
29
  *
@@ -24,16 +33,38 @@ type GameCtx = ICtx<GameState, IPhysicsContext>;
24
33
  * to give — `Buoyancy3D` rejects a non-finite height by name, so returning nothing is not an
25
34
  * option and returning `NaN` would take the whole scene down on frame one.
26
35
  */
27
- function oceanSurface(ocean: SpectralOcean): { sample(x: number, z: number): { height: number } } {
36
+ function oceanSurface(
37
+ ocean: SpectralOcean,
38
+ step: () => number,
39
+ ): { sample(x: number, z: number): { height: number } } {
28
40
  return {
29
- sample: (x, z) => ({ height: ocean.sampleHeight(x, z)?.height ?? 0 }),
41
+ // The same age-corrected read the drawn hull uses, so the solver pushes against the water the
42
+ // player can see rather than against the water of several frames ago. `step` is a closure
43
+ // because `Buoyancy3D` calls this from inside the physics step and has no delta to hand over.
44
+ sample: (x, z) => ({ height: surfaceHeight(ocean, x, z, step()) ?? 0 }),
30
45
  };
31
46
  }
32
47
 
33
- const MAX_SPEED = 3.8;
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;
48
+ /** Hull speed at full wind, in metres per second — about nine knots at the 4.6 m convention. */
49
+ const MAX_SPEED = 4.6;
50
+ /** Rate of turn with full way on and the rudder hard over, in radians per second. */
51
+ const TURN_RATE = 0.78;
52
+ /** How quickly the hull picks up and loses way, as an exponential rate. Ships are heavy. */
53
+ const WAY_RATE = 0.9;
54
+ /**
55
+ * How far the model rides above its own origin, so the sea meets it lower down the topsides.
56
+ *
57
+ * `ship.glb`'s own origin is Poly Haven's design waterline, so this starts at 0 rather than the
58
+ * caravel's hand-tuned 0.5 — override it here if the real hull needs trimming for the look.
59
+ */
60
+ const FREEBOARD_TRIM = 0;
61
+ /**
62
+ * How hard a full wind presses on a sail, as a local-space acceleration.
63
+ *
64
+ * Local, so it is in the model's own units rather than metres, and aft because that is where a
65
+ * following wind fills a square course from.
66
+ */
67
+ const SAIL_PRESS = 12;
37
68
 
38
69
  export class Ship {
39
70
  /** The physics body's transform. Heave comes from here; attitude does not. */
@@ -45,19 +76,102 @@ export class Ship {
45
76
  #capsized = false;
46
77
  #normaliseFactor: number;
47
78
  #heading = 0;
79
+ /** The extremes of `sailBelly` seen so far, for the one number that proves the canvas moves. */
80
+ #bellyLow = Number.POSITIVE_INFINITY;
81
+ #bellyHigh = 0;
82
+ /** Way on, in metres per second along the bow. The hull carries it; the keys only ask for it. */
83
+ #speed = 0;
84
+ /** What the hull is actually making good over the ground, measured off the body. */
85
+ #groundSpeed = 0;
86
+ /** The last fixed step, in seconds, for readers that are called without one. */
87
+ #step = 1 / 60;
88
+ /** Heel, eased. A ship leans away from its turn and to leeward under press of sail. */
89
+ #heel = 0;
90
+ /** The blade on the stern post, kept out of the merged hull so it can answer the helm. */
91
+ readonly #rudder: Object3D | undefined;
92
+ /**
93
+ * The cloth, and where on the ship each piece of it hangs.
94
+ *
95
+ * These are not children of the hull. `SoftBody3D` disposes itself the moment it leaves the
96
+ * scene, and `ctx.add` — the call that attaches it to the renderer at all — puts it at the
97
+ * scene root, so parenting it to the ship afterwards would tear it down on the same frame.
98
+ * They are carried to their yards each tick instead, which costs three matrix updates.
99
+ */
100
+ readonly #sails: { body: SoftBody3D; anchor: Vector3; rest: Euler }[] = [];
101
+ /** The hull inside `visual`. Its transform carries the metre normalisation the yards are in. */
102
+ readonly #model: Group;
48
103
  #elapsed = 0;
49
104
  #immersion = 0.5;
50
105
  #seaHeight = 0;
51
106
  #staleFrames = -1;
52
107
  readonly #ocean: SpectralOcean;
108
+ /** Half the hull's length and beam, measured off `ship.glb` rather than assumed. */
109
+ readonly #halfLength: number;
110
+ readonly #halfBeam: number;
111
+ /** The hull's draught, measured the same way. */
112
+ readonly #draft: number;
53
113
 
54
- constructor(ctx: GameCtx, ocean: SpectralOcean) {
114
+ constructor(ctx: GameCtx, ocean: SpectralOcean, shipModel: IShipModel) {
55
115
  this.#ocean = ocean;
56
116
  this.mesh.position.set(0, 0.24, 7);
57
117
  this.visual.position.set(0, 0.24, 7);
58
118
  this.mesh.castShadow = true;
59
- const model = createShipModel(createMaterials());
119
+ const model = createShipModel(shipModel);
120
+ this.#model = model;
121
+ // `ship.glb` has no articulated rudder — its hull is one static mesh — so this is `undefined`
122
+ // and the helm's rudder-angle feedback below is silently skipped rather than crashing.
123
+ this.#rudder = model.getObjectByName("rudder");
60
124
  this.#normaliseFactor = prepareShipConventions(model);
125
+ const hull = measureHull(model);
126
+ this.#halfLength = hull.halfLength;
127
+ this.#halfBeam = hull.halfBeam;
128
+ // Floored: `immersion` divides by this, and a mismeasured hull (the named node missing, say)
129
+ // must not turn into a division by zero.
130
+ this.#draft = Math.max(0.1, hull.draft);
131
+ // `ship.glb`'s own origin is Poly Haven's design waterline, unlike the caravel this replaces
132
+ // (built about y = 0 with its keel at -0.73), so no lift is needed by default —
133
+ // `FREEBOARD_TRIM` is the look-only override if the real hull needs trimming.
134
+ model.position.y = FREEBOARD_TRIM;
135
+
136
+ // The canvas. `belliedSail` baked the belly into the vertices, so the sails looked exactly as
137
+ // full in a dying breeze as in a fresh one — on a passage whose entire fail state is running
138
+ // out of wind, and whose HUD counts that wind down in percent, the rig was the one thing on
139
+ // screen that never mentioned it.
140
+ for (const [index, cloth] of createSails(createMaterials()).entries()) {
141
+ const sail = SHIP_SAILS[index];
142
+ if (sail === undefined) continue;
143
+ const body = new SoftBody3D(cloth.mesh, {
144
+ damping: 2.2,
145
+ // Local-space, so metres per second squared divided by the model's own scale. Handing the
146
+ // solver 9.81 in a model normalised to 0.57 gives cloth on a body nearly twice the size of
147
+ // the world it is in, and the sails hang like chainmail.
148
+ gravity: [0, -9.81 / this.#normaliseFactor, 0],
149
+ pinned: cloth.pinned,
150
+ // A throttled copy of the cloth's own vertices, so a scenario can assert that the canvas is
151
+ // actually filling rather than that three quads exist. A still sail passes every visual
152
+ // assertion this template has.
153
+ //
154
+ // The fore course alone, and only every twelfth frame. Three sails copying ninety-nine
155
+ // vec4s off the GPU every fourth frame is three copies buying one number.
156
+ readbackEveryFrames: index === 0 ? 12 : 0,
157
+ // Canvas, and a long way stiffer than it looks like it should need. Spring acceleration is
158
+ // stiffness times stretch, so the top row has to carry eight rows of cloth against a local
159
+ // gravity of seventeen: at 52 that balanced at three quarters of a unit of stretch and the
160
+ // sails hung to the waterline. This holds them to within a few per cent of their cut, and
161
+ // 1/60 is still far inside the explicit solver's stability limit of 2/sqrt(k).
162
+ stiffness: 1_200,
163
+ wind: [0, 0, 0],
164
+ });
165
+ body.name = `sail-${index}`;
166
+ body.castShadow = true;
167
+ body.scale.setScalar(this.#normaliseFactor);
168
+ ctx.add(body);
169
+ this.#sails.push({
170
+ anchor: new Vector3(sail.x, sail.y, sail.z),
171
+ body,
172
+ rest: new Euler(sail.pitch, sail.yaw, 0),
173
+ });
174
+ }
61
175
  // The hull hangs off `visual`, not off the physics body.
62
176
  //
63
177
  // `Buoyancy3D` applies its displaced-volume force at each hull point, so a point that is
@@ -83,49 +197,155 @@ export class Ship {
83
197
  mass: 420,
84
198
  object: this.mesh,
85
199
  physics: ctx.physics,
86
- shape: CollisionShape3D.box(1.4, 0.7, 2.4),
200
+ // Half-extents, from the measured hull rather than the caravel's hand-tuned box: the real
201
+ // ship is narrower for its length (beam 0.97 m against 1.9 m), and a box sized for the old
202
+ // hull would give the wrong moment of inertia for this one.
203
+ shape: CollisionShape3D.box(this.#halfBeam, 0.6, this.#halfLength),
87
204
  });
88
205
  this.buoyancy = new Buoyancy3D({
89
206
  body: this.body,
90
207
  density: 1_000,
91
208
  drag: 12,
92
- field: oceanSurface(ocean),
209
+ field: oceanSurface(ocean, () => this.#step),
93
210
  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.
211
+ // All four points sit **below** the body's centre, at the hull's bottom corners, scaled from
212
+ // the caravel's tuned positions by the measured beam and length so they stay inside the real
213
+ // hull's footprint instead of poking out past its sides. `volume` stays the caravel's own
214
+ // figure: it is a buoyancy-feel tuning constant, not a literal displacement, and the mass and
215
+ // drag above were tuned against it.
99
216
  hullPoints: [
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 },
217
+ { position: [-this.#halfBeam * 0.47, -0.3, -this.#halfLength * 0.44], volume: 0.275 },
218
+ { position: [this.#halfBeam * 0.47, -0.3, -this.#halfLength * 0.44], volume: 0.275 },
219
+ { position: [-this.#halfBeam * 0.47, -0.3, this.#halfLength * 0.44], volume: 0.275 },
220
+ { position: [this.#halfBeam * 0.47, -0.3, this.#halfLength * 0.44], volume: 0.275 },
104
221
  ],
105
222
  pointSpacing: 0.64,
106
223
  volume: 1.1,
107
224
  });
108
225
  }
109
226
 
227
+ /** The unit vector the bow points along. The model's stem is at **-Z**, so both terms negate. */
228
+ get forward(): { x: number; z: number } {
229
+ return { x: -Math.sin(this.#heading), z: -Math.cos(this.#heading) };
230
+ }
231
+
232
+ /** The unit vector out over the starboard rail: the bow turned ninety degrees to the right. */
233
+ get starboard(): { x: number; z: number } {
234
+ return { x: Math.cos(this.#heading), z: -Math.sin(this.#heading) };
235
+ }
236
+
237
+ get heading(): number {
238
+ return this.#heading;
239
+ }
240
+
241
+ /** Speed made good over the ground. This is the number the HUD shows. */
242
+ get speed(): number {
243
+ return this.#groundSpeed;
244
+ }
245
+
246
+ /** Speed the sails are asking for, before the water has its say. */
247
+ get demandedSpeed(): number {
248
+ return this.#speed;
249
+ }
250
+
251
+ /**
252
+ * Steer a ship, rather than slide a box around the world axes.
253
+ *
254
+ * What this replaces drove the body's velocity straight from the input — `x` from the left and
255
+ * right keys, `z` from forward — and then turned the *drawn* hull by a slow separate angle that
256
+ * nothing else read. So the ship crabbed: it visibly pointed one way and travelled another, the
257
+ * rudder had no effect on where it went, and the four course marks could be collected by
258
+ * strafing past them broadside. The heading is now the only direction the ship can make way
259
+ * along, which is what makes steering a mechanic instead of a decoration.
260
+ */
110
261
  update(ctx: GameCtx, deltaTime: number, wind: number, touch?: ITouchInput): void {
111
262
  this.#elapsed += deltaTime;
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
- }
118
- const speed = MAX_SPEED * Math.max(0, Math.min(1, wind));
119
- const targetX = move.x * STEERING_SPEED * Math.max(0.4, wind);
120
- const targetZ = -move.y * speed;
121
- const blend = Math.min(1, Math.max(0, deltaTime) * 8);
263
+ this.#step = deltaTime;
264
+ // Two axes, read separately — see the binding comment in `game.ts` for why this is not
265
+ // `vector("move")`. The touch stick *is* a stick, so it stays clamped and adds into both.
266
+ const helm = ctx.input.vector("helm");
267
+ const sheets = ctx.input.vector("sheets");
268
+ const press = Math.max(0, Math.min(1, wind));
269
+ // `sheets.y` is +up and means forward: the one conversion to the model's -Z bow happens in
270
+ // `forward`, not here. Astern input spills the sails rather than driving the ship backwards —
271
+ // a square rig cannot make sternway, so it reads as a brake.
272
+ const throttle = MathUtils.clamp(sheets.y + (touch?.move.y ?? 0), -1, 1);
273
+ const rudder = MathUtils.clamp(helm.x + (touch?.move.x ?? 0), -1, 1);
274
+ const target = MAX_SPEED * press * Math.max(0, throttle);
275
+ // Losing way is faster than gaining it when the sails are spilled, and much faster than the
276
+ // hull's own drag would manage on its own.
277
+ const rate = target < this.#speed ? WAY_RATE * (throttle < 0 ? 3.4 : 1.6) : WAY_RATE;
278
+ this.#speed += (target - this.#speed) * Math.min(1, Math.max(0, deltaTime) * rate * 2);
279
+
280
+ // A rudder is a foil: it only bites on water flowing past it. Standing still, the ship swings
281
+ // slowly on its sails alone, and the floor keeps that from being a dead helm.
282
+ const authority = Math.max(0.2, Math.min(1, this.#speed / (MAX_SPEED * 0.55)));
283
+ this.#heading -= rudder * TURN_RATE * authority * deltaTime;
284
+
285
+ const forward = this.forward;
122
286
  const velocity = this.body.linearVelocity;
287
+ // Read **before** it is overwritten, so this is what the last physics step actually left the
288
+ // hull doing rather than what the sails asked for. The two differ: `Buoyancy3D` applies a drag
289
+ // term from the body's linear velocity, which opposes the drive horizontally as well as
290
+ // vertically. Reporting the demanded speed as though it were the achieved one puts a number in
291
+ // the HUD that the ship never makes good.
292
+ this.#groundSpeed = Math.hypot(velocity.x, velocity.z);
123
293
  this.body.linearVelocity = {
124
- x: velocity.x + (targetX - velocity.x) * blend,
294
+ x: forward.x * this.#speed,
295
+ // Heave stays the buoyancy solver's. Overwriting it here would be the game deciding how far
296
+ // the sea can lift its own hull.
125
297
  y: velocity.y,
126
- z: velocity.z + (targetZ - velocity.z) * blend,
298
+ z: forward.z * this.#speed,
127
299
  };
128
- this.#heading += move.x * deltaTime * 0.35;
300
+
301
+ // Heel: outward in a turn, and a constant lean to leeward under press of sail. Positive
302
+ // `rotation.z` lifts the starboard rail, so a turn to starboard leans the ship to port.
303
+ const heelTarget = rudder * authority * 0.13 + press * 0.04;
304
+ this.#heel += (heelTarget - this.#heel) * Math.min(1, Math.max(0, deltaTime) * 2.4);
305
+ // The rig shows the helm's decision, not only the weather. Spilling the sheets takes the press
306
+ // off the canvas: the sails go slack, the ship loses way, and the two happen together — which
307
+ // is the feedback that makes `S` read as spilling wind rather than as a brake pedal. A quarter
308
+ // of the press stays because a square course does not vanish when it is not drawing.
309
+ this.#trimSails(press * (0.25 + 0.75 * Math.max(0, throttle)));
310
+ // Hard over is about thirty-five degrees on a real ship, and the blade eases across rather
311
+ // than snapping: a rudder that teleports between its stops is the tell that the helm is a
312
+ // number rather than a thing hanging in the water.
313
+ if (this.#rudder !== undefined) {
314
+ const blade = -rudder * 0.6;
315
+ this.#rudder.rotation.y += (blade - this.#rudder.rotation.y) * Math.min(1, deltaTime * 6);
316
+ }
317
+ this.#rideTheSwell(deltaTime);
318
+ }
319
+
320
+ /**
321
+ * Carry each sail to its yard, and put the wind into it.
322
+ *
323
+ * The wind vector is in the cloth's **own** space, which is what makes this three numbers rather
324
+ * than a rotation: a square course is turned to face forward, so pressing it along its local +Z
325
+ * fills it aft whatever course the ship is steering; the mizzen lateen is turned side-on by its
326
+ * own rest rotation, so the same +Z presses it to leeward. The gust term is not decoration —
327
+ * canvas that holds one shape is canvas the simulation is not moving, and a still sail on a
328
+ * moving ship reads as a bug.
329
+ */
330
+ #trimSails(press: number): void {
331
+ for (const sail of this.#sails) {
332
+ // Through the **model's** matrix, not the visual's. The yard coordinates in `SHIP_SAILS`
333
+ // are in the hull's own authored units, and the model sits inside `visual` carrying the
334
+ // metre normalisation and the freeboard trim: read through `visual` alone, a yard at y=4.27
335
+ // put the sail 4.27 *metres* above the sea with the masts bare underneath it.
336
+ this.#model.updateMatrixWorld(true);
337
+ sail.body.position.copy(sail.anchor).applyMatrix4(this.#model.matrixWorld);
338
+ sail.body.quaternion.copy(this.visual.quaternion).multiply(REST.setFromEuler(sail.rest));
339
+ const gust = 1 + Math.sin(this.#elapsed * 1.7 + sail.anchor.z) * 0.16;
340
+ // Placement is taken from the drawn hull rather than the physics body, so the rig rides on
341
+ // the ship the player can see.
342
+ sail.body.wind.set(0, press * SAIL_PRESS * 0.12, press * SAIL_PRESS * gust);
343
+ }
344
+ const belly = this.sailBelly;
345
+ if (belly > 0) {
346
+ this.#bellyLow = Math.min(this.#bellyLow, belly);
347
+ this.#bellyHigh = Math.max(this.#bellyHigh, belly);
348
+ }
129
349
  }
130
350
 
131
351
  /**
@@ -133,32 +353,51 @@ export class Ship {
133
353
  *
134
354
  * Two samples a boat-length apart give the pitch, two across the beam give the roll. Both are
135
355
  * 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
356
  */
142
- updateVisual(deltaTime: number): void {
357
+ #rideTheSwell(deltaTime: number): void {
143
358
  if (this.#capsized) return;
144
359
  const { x, z } = this.mesh.position;
145
360
  // `SpectralOcean` has no closed form, so its CPU height is a throttled copy of what the GPU
146
361
  // produced and can be `undefined` until the first readback lands. Falling back to the mean
147
362
  // sea level for those frames is the whole handling this needs — a boat sitting flat at y = 0
148
363
  // for the first fraction of a second is invisible, and throwing is not.
364
+ //
365
+ // Every probe is taken **upwind** by however far the swell will have run during the copy's
366
+ // age. `sampleHeight` hands back a height from a GPU copy that is `staleFrames` old, and a
367
+ // hull floated straight onto that number rides water the renderer stopped drawing several
368
+ // frames ago: the ship visibly cut down through a crest and hung above the following trough,
369
+ // and the waterline reading swung between a third and two thirds of the hull between two
370
+ // captures a second apart. Deep-water waves travel, so reading the stale field a little
371
+ // upwind reads what this patch of sea is about to become.
149
372
  const heightAt = (sampleX: number, sampleZ: number): number =>
150
- this.#ocean.sampleHeight(sampleX, sampleZ)?.height ?? 0;
373
+ surfaceHeight(this.#ocean, sampleX, sampleZ, deltaTime) ?? 0;
151
374
  // Sampled across the hull's real length and beam, not a token metre. The height copy is a
152
375
  // bilinear read of a grid about three metres across, so two probes closer together than that
153
376
  // 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);
377
+ //
378
+ // Probed along the **ship's** axes, not the world's. Sampling a fixed north-south pair gave a
379
+ // hull that pitched into swell it was running along the length of and rolled to seas it was
380
+ // meeting head on: turn ninety degrees and the pitch and the roll swapped over. Rotating the
381
+ // four probes by the heading is what makes the attitude belong to this ship rather than to
382
+ // the compass.
383
+ const forward = this.forward;
384
+ const starboard = this.starboard;
385
+ const aheadHeight = heightAt(
386
+ x + forward.x * this.#halfLength,
387
+ z + forward.z * this.#halfLength,
388
+ );
389
+ const asternHeight = heightAt(
390
+ x - forward.x * this.#halfLength,
391
+ z - forward.z * this.#halfLength,
392
+ );
393
+ const starboardHeight = heightAt(
394
+ x + starboard.x * this.#halfBeam,
395
+ z + starboard.z * this.#halfBeam,
396
+ );
397
+ const portHeight = heightAt(x - starboard.x * this.#halfBeam, z - starboard.z * this.#halfBeam);
158
398
  const hereHeight = heightAt(x, z);
159
- const probe = this.#ocean.sampleHeight(x, z);
160
399
  this.#seaHeight = hereHeight;
161
- this.#staleFrames = probe === undefined ? -1 : probe.staleFrames;
400
+ this.#staleFrames = this.#ocean.sampleHeight(x, z)?.staleFrames ?? -1;
162
401
  // The ship's bow is at **-Z**, so a positive `rotation.x` lifts it — which means the pitch is
163
402
  // driven by how much higher the water *ahead* is, not the water astern. Written the other way
164
403
  // round the bow rose over troughs and drove into the face of every wave, and the ship
@@ -167,25 +406,42 @@ export class Ship {
167
406
  // Clamped, because the height field is a copy of a GPU buffer read on a grid coarser than the
168
407
  // hull: two probes can disagree by more than the sea actually does, and without a limit one
169
408
  // 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);
409
+ // Eight degrees, not seventeen. The clamp exists because the height copy is a grid coarser
410
+ // than the hull, and at the old limit a bad pair of probes threw a 4.6 m caravel onto its
411
+ // bilge every few seconds, which reads as a ship in danger rather than as a boat in a swell.
412
+ const pitch = MathUtils.clamp(
413
+ Math.atan2(aheadHeight - asternHeight, this.#halfLength * 2),
414
+ -0.14,
415
+ 0.14,
416
+ );
171
417
  // How deep the bow is in the water it is meeting. This is the number the HUD's waterline
172
418
  // shows: `Buoyancy3D.submergedFraction` measures its hull points through the body's own
173
419
  // quaternion, and with the body free to tumble that reading swings between 0 and 1 with
174
420
  // nothing to do with what the player can see.
175
421
  this.#immersion = Math.min(
176
422
  1,
177
- Math.max(0, 0.5 + (aheadHeight - this.visual.position.y) / DESIGN_DRAUGHT),
423
+ Math.max(0, 0.5 + (aheadHeight - this.visual.position.y) / this.#draft),
178
424
  );
179
- const roll = MathUtils.clamp(Math.atan2(starboardHeight - portHeight, 1.9), -0.26, 0.26);
425
+ // Seven degrees for the same reason, and a caravel's working ballast is amidships: she stands
426
+ // up to a sea rather than lying over into it.
427
+ const roll =
428
+ MathUtils.clamp(Math.atan2(starboardHeight - portHeight, this.#halfBeam * 2), -0.12, 0.12) +
429
+ this.#heel;
180
430
  const blend = Math.min(1, Math.max(0, deltaTime) * 3.2);
181
431
  this.visual.position.x = this.mesh.position.x;
182
432
  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.
433
+ // The design waterline sits **on** the surface, not eased towards it.
434
+ //
435
+ // Easing at 3.2 per second is a third of a second of lag, and against a sea whose surface
436
+ // rises at three metres a second that is nearly half a metre of hull hanging in the air over
437
+ // its own trough — most of this ship's draught. A boat this size has no such lag: it is a
438
+ // float, and a float is wherever the water is. The inertia that *is* real lives in the
439
+ // attitude below, where a hull's mass genuinely resists being rolled.
188
440
  this.visual.position.y = hereHeight;
441
+ // `YXZ`: yaw, then pitch and roll about the ship's **own** axes. In the default `XYZ` order
442
+ // the pitch is applied in world space and the heel goes wherever the heading happens to point
443
+ // it, so a ship on a westerly course rolled when it should have pitched.
444
+ this.visual.rotation.order = "YXZ";
189
445
  this.visual.rotation.y = this.#heading;
190
446
  this.visual.rotation.x += (pitch - this.visual.rotation.x) * blend;
191
447
  this.visual.rotation.z += (roll - this.visual.rotation.z) * blend;
@@ -201,6 +457,66 @@ export class Ship {
201
457
  return this.#capsized;
202
458
  }
203
459
 
460
+ /**
461
+ * How far the canvas has blown out of its cut, in the cloth's own units.
462
+ *
463
+ * The sails are authored dead flat, so every millimetre of this is the simulation's. It is the
464
+ * only number that separates cloth from three static quads, and it is the one a dying wind has
465
+ * to bring down.
466
+ */
467
+ get sailBelly(): number {
468
+ let furthest = 0;
469
+ for (const sail of this.#sails) {
470
+ const sample = sail.body.sample;
471
+ if (sample === undefined) continue;
472
+ for (let index = 2; index < sample.data.length; index += 3) {
473
+ const z = sample.data[index];
474
+ if (z === undefined || !Number.isFinite(z)) continue;
475
+ furthest = Math.max(furthest, Math.abs(z));
476
+ }
477
+ }
478
+ return furthest;
479
+ }
480
+
481
+ /**
482
+ * How far the canvas has travelled between its slackest and its fullest, in the cloth's units.
483
+ *
484
+ * Zero before anything has been observed, and it only grows — which is the whole reason it
485
+ * exists. `sailBelly` on its own is a large number from the first frame the sails have filled,
486
+ * so a threshold on it is already true before a scenario starts and proves nothing; this is
487
+ * false at the start by construction and can only become true if the wind is actually moving
488
+ * the cloth.
489
+ *
490
+ * **Zero also means "not measured yet" until two readbacks have landed**, and `sailSamples`
491
+ * is how a scenario tells those apart. One copy makes the slackest and the fullest the same
492
+ * frame, so the difference is zero by arithmetic rather than by observation, and a bound on it
493
+ * passed a run whose canvas had never been read twice. Do not read a zero here as a still sail
494
+ * without the sample count beside it.
495
+ */
496
+ get sailMotion(): number {
497
+ if (this.#bellyLow > this.#bellyHigh) return 0;
498
+ return this.#bellyHigh - this.#bellyLow;
499
+ }
500
+
501
+ /**
502
+ * How many cloth readbacks have landed, so `sailMotion` is not read as a measured zero.
503
+ *
504
+ * Counted from the readback that produced the extremes rather than per tick, because the two
505
+ * are not the same number: `GPUReadback` keeps one copy in flight and drops requests made while
506
+ * it is pending, so a landed copy is *reused* for every tick until the next one arrives. On a
507
+ * CPU rasteriser one copy lands every two to six **seconds** while hundreds of ticks pass, and a
508
+ * per-tick count would report thousands of samples from a single frame's worth of bytes.
509
+ *
510
+ * `sailBelly` needs this context: on a CPU adapter the copy is a `mapAsync` round trip, so how
511
+ * many land inside a scenario is a property of the adapter's readback latency and not of the
512
+ * scenario's tick count. A scenario that binds `sailMotion` should bind this too. Two is the
513
+ * floor: with one copy the range is zero whatever the cloth did.
514
+ */
515
+ get sailSamples(): number {
516
+ const debug = this.#sails[0]?.body.debug() as { readbackStats?: { lands: number } } | undefined;
517
+ return debug?.readbackStats?.lands ?? 0;
518
+ }
519
+
204
520
  /** Fraction of the hull the sea is over, from the swell the ship is actually sitting in. */
205
521
  get immersion(): number {
206
522
  return this.#capsized ? 1 : this.#immersion;
@@ -212,12 +528,19 @@ export class Ship {
212
528
  capsized: this.#capsized,
213
529
  linearVelocity: [velocity.x, velocity.y, velocity.z],
214
530
  normaliseFactor: this.#normaliseFactor,
531
+ demandedSpeed: this.#speed,
532
+ groundSpeed: this.#groundSpeed,
215
533
  position: this.mesh.position.toArray(),
216
534
  immersion: this.#immersion,
217
535
  // The three numbers a scenario needs to prove the ship is *floating* rather than merely
218
536
  // existing: the sea under it, how far the drawn hull sits off that surface, and whether the
219
537
  // height copy is arriving at all. A screenshot cannot tell a still ocean from a moving one.
220
538
  seaHeight: this.#seaHeight,
539
+ sailBelly: this.sailBelly,
540
+ sailMotion: this.sailMotion,
541
+ // Beside `sailMotion` on purpose: one landed readback makes that number a zero by
542
+ // arithmetic, and a screenshot cannot tell a canvas that was never sampled from a still one.
543
+ sailSamples: this.sailSamples,
221
544
  floatGap: this.visual.position.y - this.#seaHeight,
222
545
  readbackStaleFrames: this.#staleFrames,
223
546
  oceanSteps: this.#ocean.steps,
@@ -226,6 +549,7 @@ export class Ship {
226
549
  }
227
550
 
228
551
  dispose(): void {
552
+ for (const sail of this.#sails) sail.body.removeFromParent();
229
553
  this.body.dispose();
230
554
  this.mesh.removeFromParent();
231
555
  this.visual.removeFromParent();
@@ -9,12 +9,26 @@ import type { GameState } from "./state.js";
9
9
 
10
10
  const game = defineGame<GameState, IPhysicsContext>({
11
11
  input: {
12
+ // Three bindings over the same keys, and the split is deliberate.
13
+ //
14
+ // `vector()` ends in `clampLength(0, 1)`, which is exactly right for a thumbstick and exactly
15
+ // wrong for a ship: a stick pushed into a corner is one direction and must not exceed unit
16
+ // length, but a helm and a set of sheets are two independent controls. Read through `move`,
17
+ // holding forward *and* starboard handed the ship 0.707 of each — so the one input a player
18
+ // holds for the entire passage was also the one that could never reach full sail or full
19
+ // rudder, and the ship felt mushy in every turn it ever made.
20
+ //
21
+ // `move` is kept for the touch stick, where the clamp is the correct behaviour.
12
22
  move: {
13
23
  down: ["ArrowDown", "KeyS"],
14
24
  left: ["ArrowLeft", "KeyA"],
15
25
  right: ["ArrowRight", "KeyD"],
16
26
  up: ["ArrowUp", "KeyW"],
17
27
  },
28
+ /** The helm, on its own axis: hard over is hard over whatever the sails are doing. */
29
+ helm: { left: ["ArrowLeft", "KeyA"], right: ["ArrowRight", "KeyD"] },
30
+ /** The sheets, on their own axis: full sail is full sail whatever the helm is doing. */
31
+ sheets: { down: ["ArrowDown", "KeyS"], up: ["ArrowUp", "KeyW"] },
18
32
  capsize: { keys: ["KeyC"] },
19
33
  restart: { keys: ["KeyR"] },
20
34
  },