create-threenative 0.2.8 → 0.2.9

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 (431) hide show
  1. package/agent-docs/references/assertion-reference.md +87 -35
  2. package/agent-docs/references/auto-exposure.md +57 -0
  3. package/agent-docs/references/capability-reference.md +1097 -23
  4. package/agent-docs/references/debug-surface.md +6 -0
  5. package/agent-docs/references/finding-assets.md +46 -10
  6. package/agent-docs/references/performance-basics.md +5 -4
  7. package/agent-docs/references/terrain-authoring.md +140 -0
  8. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  9. package/capabilities.json +1210 -27
  10. package/dist/index.d.ts +28 -3
  11. package/dist/index.js +396 -166
  12. package/dist/threenative.js +986 -235
  13. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  14. package/dist/web-engine-decal-geometry.js +184 -0
  15. package/dist/web-engine-gltf-loader.js +196 -0
  16. package/dist/web-engine-hdr-loader.js +190 -0
  17. package/dist/web-engine-lut-cube-loader.js +122 -0
  18. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  19. package/dist/web-engine-mesh-bvh.js +32 -0
  20. package/dist/web-engine-post-effects.js +168 -0
  21. package/dist/web-engine-runtime.js +42506 -0
  22. package/package.json +11 -8
  23. package/template-assets/autoExposure.ts +225 -0
  24. package/template-assets/exposure.ts +111 -0
  25. package/template-assets/exposureGraph.ts +178 -0
  26. package/template-assets/exposureReadback.ts +79 -0
  27. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  28. package/template-assets/patches/three@0.185.1.patch +6594 -700
  29. package/template-assets/patches/vite@8.2.0.patch +422 -0
  30. package/template-assets/worldEnvironment.ts +433 -30
  31. package/templates/action-rpg/AGENTS.md +11 -10
  32. package/templates/action-rpg/CLAUDE.md +11 -10
  33. package/templates/action-rpg/package.json +11 -9
  34. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  35. package/templates/action-rpg/src/progress.ts +0 -4
  36. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  37. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  38. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  39. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  40. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  41. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  42. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  43. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  44. package/templates/action-rpg/src/render/exposure.ts +111 -0
  45. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  46. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  47. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  48. package/templates/action-rpg/src/render/lighting.ts +26 -1
  49. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  50. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  51. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  52. package/templates/action-rpg/src/render/quality.ts +61 -2
  53. package/templates/action-rpg/src/render/sky.ts +21 -1
  54. package/templates/action-rpg/src/render/vfx.ts +133 -58
  55. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  56. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  57. package/templates/action-rpg/threenative.config.ts +3 -0
  58. package/templates/action-rpg/vite.config.ts +10 -2
  59. package/templates/minimal/AGENTS.md +9 -10
  60. package/templates/minimal/CLAUDE.md +9 -10
  61. package/templates/minimal/package.json +9 -8
  62. package/templates/minimal/playtests/play.playtest.json +7 -1
  63. package/templates/minimal/playtests/sky.playtest.json +10 -1
  64. package/templates/minimal/src/render/autoExposure.ts +225 -0
  65. package/templates/minimal/src/render/backlightControls.ts +66 -0
  66. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  67. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  68. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  69. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  70. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  71. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  72. package/templates/minimal/src/render/exposure.ts +111 -0
  73. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  74. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  75. package/templates/minimal/src/render/heightFog.ts +118 -0
  76. package/templates/minimal/src/render/lighting.ts +25 -1
  77. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  78. package/templates/minimal/src/render/materialLighting.ts +146 -0
  79. package/templates/minimal/src/render/postprocessing.ts +16 -2
  80. package/templates/minimal/src/render/quality.ts +60 -2
  81. package/templates/minimal/src/render/sky.ts +21 -1
  82. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  83. package/templates/minimal/src/scenes/Play.ts +50 -1
  84. package/templates/minimal/vite.config.ts +10 -2
  85. package/templates/platformer/AGENTS.md +7 -5
  86. package/templates/platformer/CLAUDE.md +7 -5
  87. package/templates/platformer/package.json +11 -9
  88. package/templates/platformer/playtests/performance.playtest.json +7 -1
  89. package/templates/platformer/src/render/autoExposure.ts +225 -0
  90. package/templates/platformer/src/render/backlightControls.ts +66 -0
  91. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  92. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  93. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  94. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  95. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  96. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  97. package/templates/platformer/src/render/exposure.ts +111 -0
  98. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  99. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  100. package/templates/platformer/src/render/heightFog.ts +118 -0
  101. package/templates/platformer/src/render/lighting.ts +26 -1
  102. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  103. package/templates/platformer/src/render/materialLighting.ts +155 -0
  104. package/templates/platformer/src/render/materials.ts +7 -2
  105. package/templates/platformer/src/render/palette.ts +3 -3
  106. package/templates/platformer/src/render/postprocessing.ts +17 -2
  107. package/templates/platformer/src/render/quality.ts +61 -2
  108. package/templates/platformer/src/render/sky.ts +72 -23
  109. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  110. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  111. package/templates/platformer/src/scenes/Play.ts +70 -6
  112. package/templates/platformer/vite.config.ts +10 -2
  113. package/templates/puzzle/AGENTS.md +10 -9
  114. package/templates/puzzle/CLAUDE.md +10 -9
  115. package/templates/puzzle/package.json +11 -9
  116. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  117. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  118. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  119. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  120. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  121. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  122. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  123. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  124. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  125. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  126. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  127. package/templates/puzzle/src/render/exposure.ts +111 -0
  128. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  129. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  130. package/templates/puzzle/src/render/heightFog.ts +118 -0
  131. package/templates/puzzle/src/render/lighting.ts +33 -1
  132. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  133. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  134. package/templates/puzzle/src/render/materials.ts +1 -1
  135. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  136. package/templates/puzzle/src/render/quality.ts +62 -1
  137. package/templates/puzzle/src/render/sky.ts +20 -1
  138. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  139. package/templates/puzzle/src/scenes/Play.ts +51 -2
  140. package/templates/puzzle/vite.config.ts +10 -2
  141. package/templates/racing/AGENTS.md +8 -7
  142. package/templates/racing/CLAUDE.md +8 -7
  143. package/templates/racing/package.json +11 -9
  144. package/templates/racing/playtests/performance.playtest.json +7 -1
  145. package/templates/racing/playtests/survives.playtest.json +6 -0
  146. package/templates/racing/src/render/autoExposure.ts +225 -0
  147. package/templates/racing/src/render/backlightControls.ts +66 -0
  148. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  149. package/templates/racing/src/render/environmentContribution.ts +188 -0
  150. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  151. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  152. package/templates/racing/src/render/environmentSampling.ts +193 -0
  153. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  154. package/templates/racing/src/render/exposure.ts +111 -0
  155. package/templates/racing/src/render/exposureGraph.ts +178 -0
  156. package/templates/racing/src/render/exposureReadback.ts +79 -0
  157. package/templates/racing/src/render/heightFog.ts +118 -0
  158. package/templates/racing/src/render/lighting.ts +29 -1
  159. package/templates/racing/src/render/materialAssignments.ts +160 -0
  160. package/templates/racing/src/render/materialLighting.ts +155 -0
  161. package/templates/racing/src/render/palette.ts +1 -10
  162. package/templates/racing/src/render/postprocessing.ts +17 -2
  163. package/templates/racing/src/render/quality.ts +61 -2
  164. package/templates/racing/src/render/shapes.ts +0 -25
  165. package/templates/racing/src/render/sky.ts +21 -1
  166. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  167. package/templates/racing/src/scenes/Race.ts +91 -3
  168. package/templates/racing/src/track/circuit.ts +0 -9
  169. package/templates/racing/vite.config.ts +10 -2
  170. package/templates/rain/AGENTS.md +8 -9
  171. package/templates/rain/CLAUDE.md +8 -9
  172. package/templates/rain/native-playtests/boot.playtest.json +11 -1
  173. package/templates/rain/package.json +12 -9
  174. package/templates/rain/playtests/automation.playtest.json +1 -1
  175. package/templates/rain/playtests/performance.playtest.json +11 -1
  176. package/templates/rain/playtests/tiers.playtest.json +15 -0
  177. package/templates/rain/playtests/weather.playtest.json +1 -1
  178. package/templates/rain/src/game.ts +1 -34
  179. package/templates/rain/src/render/autoExposure.ts +225 -0
  180. package/templates/rain/src/render/exposure.ts +111 -0
  181. package/templates/rain/src/render/exposureGraph.ts +178 -0
  182. package/templates/rain/src/render/exposureReadback.ts +79 -0
  183. package/templates/rain/src/render/postprocessing.ts +3 -0
  184. package/templates/rain/src/render/quality.ts +27 -1
  185. package/templates/rain/src/render/worldEnvironment.ts +433 -30
  186. package/templates/rain/src/scenes/Boot.ts +14 -0
  187. package/templates/rain/src/state.ts +5 -1
  188. package/templates/rain/src/ui/GameUi.tsx +6 -6
  189. package/templates/rain/tools/generate-shaders.mjs +1 -1
  190. package/templates/rain/vite.config.ts +10 -2
  191. package/templates/rts/AGENTS.md +10 -11
  192. package/templates/rts/CLAUDE.md +10 -11
  193. package/templates/rts/package.json +10 -8
  194. package/templates/rts/playtests/performance.playtest.json +7 -1
  195. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  196. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  197. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  198. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  199. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  200. package/templates/rts/src/render/army.ts +10 -2
  201. package/templates/rts/src/render/autoExposure.ts +225 -0
  202. package/templates/rts/src/render/backlightControls.ts +66 -0
  203. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  204. package/templates/rts/src/render/environmentContribution.ts +188 -0
  205. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  206. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  207. package/templates/rts/src/render/environmentSampling.ts +193 -0
  208. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  209. package/templates/rts/src/render/exposure.ts +111 -0
  210. package/templates/rts/src/render/exposureGraph.ts +178 -0
  211. package/templates/rts/src/render/exposureReadback.ts +79 -0
  212. package/templates/rts/src/render/heightFog.ts +118 -0
  213. package/templates/rts/src/render/lighting.ts +26 -1
  214. package/templates/rts/src/render/materialAssignments.ts +160 -0
  215. package/templates/rts/src/render/materialLighting.ts +155 -0
  216. package/templates/rts/src/render/postprocessing.ts +8 -2
  217. package/templates/rts/src/render/quality.ts +61 -2
  218. package/templates/rts/src/render/sky.ts +21 -1
  219. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  220. package/templates/rts/src/scenes/Play.ts +54 -3
  221. package/templates/rts/src/sim/ai.ts +0 -1
  222. package/templates/rts/src/sim/terrain.ts +0 -4
  223. package/templates/rts/vite.config.ts +10 -2
  224. package/templates/runner/AGENTS.md +10 -8
  225. package/templates/runner/CLAUDE.md +10 -8
  226. package/templates/runner/package.json +11 -9
  227. package/templates/runner/playtests/performance.playtest.json +10 -1
  228. package/templates/runner/src/physics.ts +0 -1
  229. package/templates/runner/src/render/autoExposure.ts +225 -0
  230. package/templates/runner/src/render/backlightControls.ts +66 -0
  231. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  232. package/templates/runner/src/render/environmentContribution.ts +188 -0
  233. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  234. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  235. package/templates/runner/src/render/environmentSampling.ts +193 -0
  236. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  237. package/templates/runner/src/render/exposure.ts +111 -0
  238. package/templates/runner/src/render/exposureGraph.ts +178 -0
  239. package/templates/runner/src/render/exposureReadback.ts +79 -0
  240. package/templates/runner/src/render/heightFog.ts +118 -0
  241. package/templates/runner/src/render/lighting.ts +26 -1
  242. package/templates/runner/src/render/materialAssignments.ts +160 -0
  243. package/templates/runner/src/render/materialLighting.ts +155 -0
  244. package/templates/runner/src/render/postprocessing.ts +17 -2
  245. package/templates/runner/src/render/quality.ts +61 -2
  246. package/templates/runner/src/render/sky.ts +21 -1
  247. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  248. package/templates/runner/src/scenes/Run.ts +67 -2
  249. package/templates/runner/threenative.config.ts +3 -0
  250. package/templates/runner/vite.config.ts +10 -2
  251. package/templates/sailing/AGENTS.md +14 -13
  252. package/templates/sailing/CLAUDE.md +14 -13
  253. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  254. package/templates/sailing/package.json +11 -9
  255. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  256. package/templates/sailing/src/entities/Ship.ts +38 -18
  257. package/templates/sailing/src/render/autoExposure.ts +225 -0
  258. package/templates/sailing/src/render/backlightControls.ts +66 -0
  259. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  260. package/templates/sailing/src/render/camera.ts +12 -4
  261. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  262. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  263. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  264. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  265. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  266. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  267. package/templates/sailing/src/render/exposure.ts +111 -0
  268. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  269. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  270. package/templates/sailing/src/render/heightFog.ts +118 -0
  271. package/templates/sailing/src/render/lighting.ts +26 -1
  272. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  273. package/templates/sailing/src/render/materialLighting.ts +155 -0
  274. package/templates/sailing/src/render/ocean.ts +71 -53
  275. package/templates/sailing/src/render/postprocessing.ts +16 -2
  276. package/templates/sailing/src/render/props.ts +0 -45
  277. package/templates/sailing/src/render/quality.ts +61 -1
  278. package/templates/sailing/src/render/sky.ts +21 -1
  279. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  280. package/templates/sailing/src/scenes/Boot.ts +12 -1
  281. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  282. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  283. package/templates/sailing/threenative.config.ts +3 -0
  284. package/templates/sailing/vite.config.ts +10 -2
  285. package/templates/shooter/AGENTS.md +8 -6
  286. package/templates/shooter/CLAUDE.md +8 -6
  287. package/templates/shooter/package.json +11 -9
  288. package/templates/shooter/playtests/performance.playtest.json +7 -1
  289. package/templates/shooter/src/entities/Enemy.ts +0 -15
  290. package/templates/shooter/src/entities/Rifle.ts +38 -1
  291. package/templates/shooter/src/render/autoExposure.ts +225 -0
  292. package/templates/shooter/src/render/backlightControls.ts +66 -0
  293. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  294. package/templates/shooter/src/render/camera.ts +1 -12
  295. package/templates/shooter/src/render/decals.ts +299 -5
  296. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  297. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  298. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  299. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  300. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  301. package/templates/shooter/src/render/exposure.ts +111 -0
  302. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  303. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  304. package/templates/shooter/src/render/gunfx.ts +0 -1
  305. package/templates/shooter/src/render/heightFog.ts +118 -0
  306. package/templates/shooter/src/render/lighting.ts +26 -1
  307. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  308. package/templates/shooter/src/render/materialLighting.ts +155 -0
  309. package/templates/shooter/src/render/postprocessing.ts +17 -2
  310. package/templates/shooter/src/render/quality.ts +61 -2
  311. package/templates/shooter/src/render/scale.ts +2 -93
  312. package/templates/shooter/src/render/sky.ts +21 -1
  313. package/templates/shooter/src/render/vehicles.ts +0 -17
  314. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  315. package/templates/shooter/src/scenes/Play.ts +64 -2
  316. package/templates/shooter/vite.config.ts +10 -2
  317. package/templates/snow/AGENTS.md +8 -6
  318. package/templates/snow/CLAUDE.md +8 -6
  319. package/templates/snow/package.json +11 -9
  320. package/templates/snow/src/render/autoExposure.ts +225 -0
  321. package/templates/snow/src/render/backlightControls.ts +66 -0
  322. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  323. package/templates/snow/src/render/environmentContribution.ts +188 -0
  324. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  325. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/snow/src/render/environmentSampling.ts +193 -0
  327. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  328. package/templates/snow/src/render/exposure.ts +111 -0
  329. package/templates/snow/src/render/exposureGraph.ts +178 -0
  330. package/templates/snow/src/render/exposureReadback.ts +79 -0
  331. package/templates/snow/src/render/heightFog.ts +118 -0
  332. package/templates/snow/src/render/lighting.ts +33 -1
  333. package/templates/snow/src/render/materialAssignments.ts +160 -0
  334. package/templates/snow/src/render/materialLighting.ts +155 -0
  335. package/templates/snow/src/render/postprocessing.ts +16 -2
  336. package/templates/snow/src/render/quality.ts +59 -1
  337. package/templates/snow/src/render/sky.ts +21 -2
  338. package/templates/snow/src/render/worldEnvironment.ts +433 -30
  339. package/templates/snow/src/scenes/Snow.ts +29 -1
  340. package/templates/snow/threenative.config.ts +3 -0
  341. package/templates/snow/vite.config.ts +10 -2
  342. package/templates/starter/AGENTS.md +11 -16
  343. package/templates/starter/CLAUDE.md +11 -16
  344. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  345. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  346. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  347. package/templates/starter/package.json +11 -9
  348. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  349. package/templates/starter/playtests/movement.playtest.json +192 -0
  350. package/templates/starter/playtests/play.playtest.json +18 -2
  351. package/templates/starter/playtests/production-readiness.playtest.json +1 -1
  352. package/templates/starter/public/grade.cube +735 -0
  353. package/templates/starter/src/entities/Crate.ts +4 -0
  354. package/templates/starter/src/entities/Player.ts +79 -18
  355. package/templates/starter/src/game.ts +1 -0
  356. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  357. package/templates/starter/src/render/autoExposure.ts +225 -0
  358. package/templates/starter/src/render/backlightControls.ts +66 -0
  359. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  360. package/templates/starter/src/render/environmentContribution.ts +188 -0
  361. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  362. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  363. package/templates/starter/src/render/environmentSampling.ts +193 -0
  364. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  365. package/templates/starter/src/render/exposure.ts +111 -0
  366. package/templates/starter/src/render/exposureGraph.ts +178 -0
  367. package/templates/starter/src/render/exposureReadback.ts +79 -0
  368. package/templates/starter/src/render/grade.ts +157 -0
  369. package/templates/starter/src/render/heightFog.ts +118 -0
  370. package/templates/starter/src/render/lighting.ts +26 -1
  371. package/templates/starter/src/render/materialAssignments.ts +160 -0
  372. package/templates/starter/src/render/materialLighting.ts +155 -0
  373. package/templates/starter/src/render/postprocessing.ts +84 -4
  374. package/templates/starter/src/render/quality.ts +80 -8
  375. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  376. package/templates/starter/src/render/rendererGate.ts +36 -0
  377. package/templates/starter/src/render/sky.ts +23 -1
  378. package/templates/starter/src/render/temporalAA.ts +197 -0
  379. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  380. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  381. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  382. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  383. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  384. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  385. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  386. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  387. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  388. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  389. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  390. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  391. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  392. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  393. package/templates/starter/src/render/temporalResolve.ts +139 -0
  394. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  395. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  396. package/templates/starter/src/render/volumetricFog.ts +124 -0
  397. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  398. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  399. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  400. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  401. package/templates/starter/src/scenes/Play.ts +110 -1
  402. package/templates/starter/src/state.ts +1 -0
  403. package/templates/starter/src/ui/Hud.tsx +1 -1
  404. package/templates/starter/src/ui/Menu.tsx +1 -1
  405. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  406. package/templates/starter/vite.config.ts +10 -2
  407. package/templates/tower-defense/AGENTS.md +10 -9
  408. package/templates/tower-defense/CLAUDE.md +10 -9
  409. package/templates/tower-defense/package.json +11 -9
  410. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  411. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  412. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  413. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  414. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  415. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  416. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  417. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  418. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  419. package/templates/tower-defense/src/render/exposure.ts +111 -0
  420. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  421. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  422. package/templates/tower-defense/src/render/lighting.ts +33 -1
  423. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  424. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  425. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  426. package/templates/tower-defense/src/render/quality.ts +61 -2
  427. package/templates/tower-defense/src/render/shapes.ts +0 -3
  428. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  429. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  430. package/templates/tower-defense/vite.config.ts +10 -2
  431. package/templates/minimal/src/scenes/Boot.ts +0 -5
@@ -5,6 +5,7 @@ import {
5
5
  Scene,
6
6
  type SceneFrame,
7
7
  afterPhysics,
8
+ getPlatform,
8
9
  isMobile,
9
10
  isTouchscreenAvailable,
10
11
  } from "@threenative/core";
@@ -13,9 +14,16 @@ import { type IRunnerModel, Runner } from "../entities/Runner.js";
13
14
  import type { RunnerPhysics } from "../physics.js";
14
15
  import { chaseRunner, setupCamera } from "../render/camera.js";
15
16
  import { createDustTrail } from "../render/dust.js";
17
+ import { type IEnvironmentSample, sampleEnvironment } from "../render/environmentSampling.js";
16
18
  import { setupLighting } from "../render/lighting.js";
17
19
  import { createLoadingScreen } from "../render/loading.js";
20
+ import { createMaterialLighting } from "../render/materialLighting.js";
18
21
  import { setupPost } from "../render/postprocessing.js";
22
+ import {
23
+ type QualityTier,
24
+ isWebGLFallbackRenderer,
25
+ materialLightingEnabled,
26
+ } from "../render/quality.js";
19
27
  import { setupSky } from "../render/sky.js";
20
28
  import { TouchControls } from "../render/touch-controls.js";
21
29
  import { type GameState, INITIAL_STATE } from "../state.js";
@@ -34,11 +42,23 @@ export class Run extends Scene<GameState, RunnerPhysics> {
34
42
  #model: IRunnerModel | undefined;
35
43
  #sky: Texture | undefined;
36
44
 
45
+ #post: ReturnType<typeof setupPost> | undefined;
46
+ #environmentSample: IEnvironmentSample | undefined;
47
+ #materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
48
+
37
49
  override async load(ctx: GameCtx): Promise<void> {
38
50
  [this.#model, this.#sky] = await Promise.all([
39
51
  ctx.assets.model<IRunnerModel>("mannequin.glb"),
40
52
  ctx.assets.texture("sky.jpg"),
41
53
  ]);
54
+ setupSky(ctx.scene, this.#sky);
55
+ this.#environmentSample = await sampleEnvironment(ctx.renderer.raw, ctx.scene, {
56
+ web: getPlatform().runtime === "web",
57
+ rendererKind: ctx.renderer.kind,
58
+ webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
59
+ mobile: isMobile(),
60
+ software: ctx.renderer.softwareAdapter !== undefined,
61
+ });
42
62
  }
43
63
 
44
64
  override enter(ctx: GameCtx): SceneFrame<GameState, RunnerPhysics> {
@@ -52,10 +72,23 @@ export class Run extends Scene<GameState, RunnerPhysics> {
52
72
  );
53
73
  // isMobile() arrives as an argument because src/render/ imports no framework package: the
54
74
  // platform decision is made here, in portable game code.
55
- setupPost(ctx.renderer, ctx.scene, ctx.camera, {
75
+ const materialEnvironment = {
76
+ web: getPlatform().runtime === "web",
77
+ rendererKind: ctx.renderer.kind,
78
+ webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
79
+ mobile: isMobile(),
80
+ software: ctx.renderer.softwareAdapter !== undefined,
81
+ };
82
+ let materialTier: QualityTier = "low";
83
+ this.#post = setupPost(ctx.renderer, ctx.scene, ctx.camera, {
84
+ onTierChanged: (tier) => {
85
+ materialTier = tier;
86
+ this.#materialLighting?.setEnabled(materialLightingEnabled(tier, materialEnvironment));
87
+ },
56
88
  godraysLight: key,
57
89
  mobile: isMobile(),
58
90
  software: ctx.renderer.softwareAdapter !== undefined,
91
+ gpuClass: ctx.renderer.gpuClass?.class,
59
92
  });
60
93
  const camera = ctx.camera as PerspectiveCamera;
61
94
  setupCamera(camera);
@@ -70,7 +103,11 @@ export class Run extends Scene<GameState, RunnerPhysics> {
70
103
  // `ctx.random` is the seeded source `defineGame({ seed })` installed, so the same seed builds
71
104
  // the same track — which is what makes a runner's scenario reproducible at all.
72
105
  const chunkContext = {
73
- add: (object: Parameters<typeof ctx.add>[0]) => ctx.add(object),
106
+ add: (object: Parameters<typeof ctx.add>[0]) => {
107
+ const added = ctx.add(object);
108
+ this.#materialLighting?.enroll(object);
109
+ return added;
110
+ },
74
111
  physics: ctx.physics,
75
112
  random: () => ctx.random(),
76
113
  };
@@ -101,6 +138,25 @@ export class Run extends Scene<GameState, RunnerPhysics> {
101
138
  dust.position.set(runner.mesh.position.x, 0.15, runner.mesh.position.z + 0.6);
102
139
  });
103
140
 
141
+ // Collect only after the loaded character and scene receivers are attached.
142
+ this.#materialLighting = ctx.entities.add(
143
+ "material-lighting",
144
+ createMaterialLighting(ctx.scene, ctx.camera, key, {
145
+ ...materialEnvironment,
146
+ enabled: materialLightingEnabled(materialTier, materialEnvironment),
147
+ overrides: { fillGain: 0 },
148
+ }),
149
+ );
150
+ if (this.#environmentSample !== undefined) {
151
+ const sample = this.#environmentSample;
152
+ this.#materialLighting.setEnvironmentMeasurement(
153
+ sample.measurement,
154
+ sample.source,
155
+ sample.intensity,
156
+ sample,
157
+ );
158
+ }
159
+
104
160
  return (frameCtx, dt) => {
105
161
  loading.update();
106
162
  if (frameCtx.input.justPressed("restart")) {
@@ -159,4 +215,13 @@ export class Run extends Scene<GameState, RunnerPhysics> {
159
215
  frameCtx.state.set(next);
160
216
  };
161
217
  }
218
+
219
+ override exit(ctx: GameCtx): void {
220
+ this.#materialLighting?.dispose();
221
+ this.#materialLighting = undefined;
222
+ this.#post?.dispose();
223
+ this.#post = undefined;
224
+ this.#environmentSample = undefined;
225
+ super.exit(ctx);
226
+ }
162
227
  }
@@ -1,6 +1,9 @@
1
1
  import type { IThreeNativeConfig } from "@threenative/core";
2
2
 
3
3
  const config: IThreeNativeConfig = {
4
+ // Pinned to the legacy engine: the native engine does not bind three/tsl deltaTime yet (PRD-573 slice 8).
5
+ // Delete this line when `pnpm build --target desktop` passes without it, and the game runs on the native engine.
6
+ engine: "threejs",
4
7
  app: {
5
8
  id: "com.threenative.__PROJECT_ID__",
6
9
  name: "__PROJECT_NAME__",
@@ -1,7 +1,11 @@
1
1
  import tailwindcss from "@tailwindcss/vite";
2
2
  import { watchAssets } from "@threenative/assets";
3
3
  import react from "@vitejs/plugin-react";
4
- import { createEngineFreshnessPlugin, createWebBrandPlugin } from "create-threenative";
4
+ import {
5
+ createEngineFreshnessPlugin,
6
+ createWebBrandPlugin,
7
+ webRuntimeDecoders,
8
+ } from "create-threenative";
5
9
  import { defineConfig } from "vite";
6
10
  import type { Plugin } from "vite";
7
11
  import config from "./threenative.config.js";
@@ -15,7 +19,11 @@ function assetsWatchPlugin(): Plugin {
15
19
  name: "threenative-assets-watch",
16
20
  apply: "serve",
17
21
  async configureServer(server) {
18
- const handle = watchAssets({ config: config.assets, cwd: server.config.root });
22
+ const handle = watchAssets({
23
+ config: config.assets,
24
+ cwd: server.config.root,
25
+ runtimeDecoders: webRuntimeDecoders(config),
26
+ });
19
27
  server.httpServer?.once("close", () => handle.close());
20
28
  // Nothing is served before the first cook settles: until it does, `public/` has no
21
29
  // `assets.manifest.json` and every asset answers from its source fallback.
@@ -3,9 +3,8 @@
3
3
  Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
4
4
 
5
5
  ## Ownership
6
-
7
6
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns ship handling, the sea's look and tuning, `Buoyancy3D`, course order, HUD,
8
- water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way.
7
+ water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
9
8
 
10
9
  ## Start every change
11
10
 
@@ -37,7 +36,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
37
36
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
37
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
38
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
39
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
41
40
 
42
41
  ## Commands and map
43
42
 
@@ -46,20 +45,22 @@ pnpm dev
46
45
  pnpm build
47
46
  pnpm build --target desktop
48
47
  pnpm test:native
48
+ pnpm exec threenative-playtest --scenario playtests/live/render-motion.playtest.json --live-clock --browser-recipe webgpu --headed --server-command "pnpm dev --host 127.0.0.1 --port $PORT --strictPort"
49
49
  ```
50
50
 
51
51
  Four course marks around the headland, a helm and a set of sheets, 120 seconds of wind. The hull and rig are `assets/ship.glb` — Poly Haven's `dutch_ship_medium` (CC0; James Ray Cock, Rico Cilliers, Nicolò Zubbini) — fetched by `Boot.load()` (`props.ts#loadShipModel`, alongside the sky) and read back synchronously in `Sailing.enter()` (`props.ts#getShipModel`), then oriented by `props.ts#createShipModel`: a scene-level `load()` on `Sailing` itself would still leave the registry empty the instant `enter()` returns, since `Boot.enter()` calls `goto("sailing")` without awaiting it. `conventions.ts#measureHull` reads the physics body's box and `Buoyancy3D` hull points off the loaded model rather than a hand-tuned constant, so a different hull model never needs those numbers touched by hand. `SHIP_SAILS` in `props.ts` stays simulated cloth: the GLB's own baked sail mesh is stripped at cook time so the two never double up. `Ship.ts` uses `RigidBody3D` plus `Buoyancy3D`, and reads the hull's attitude off four swell samples rotated by the heading rather than leaving it to the solver: `Buoyancy3D`'s drag comes from the body's *linear* velocity and so damps no rotation at all, and a free body capsizes inside seconds. A helm and sheets are two axes, not one stick: `vector("move")` clamps its diagonal to unit length, which is right for a thumb and wrong for a ship that must hold full sail and hard over at once.
52
52
 
53
53
  The sea is `SpectralOcean`, added with `ctx.add` so the compute registry runs its passes. It draws nothing: `src/render/ocean.ts` owns the mesh, the material, the mirror and every colour, and is the only file to edit for the water's look. The cascade buffers the vertex stage reads are the ones the CPU height query is copied from, so the hull floats on the surface that is drawn; two fields would leave the ship riding water nothing renders, with every assertion here still green.
54
54
 
55
- Five details are load-bearing. The material is `MeshStandardNodeMaterial`, not a basic one: a basic material takes no lights, so the sun on the water has to be faked with a `pow()` term, and the sea cannot agree with the hull floating on it. `normalNode` overrides `normalView`, so feed it a view-space normal or the reflection becomes a column of glare that follows the camera. The surface is a **logarithmic disc** centred on the ship, the cascade lookup adding the disc's own offset back: a square patch either ends inside the haze as a visible rectangular hem, or reaches the horizon with 300 m quads beside the hull. The ripple normals fade on the **pixel footprint** (`dFdx`/`dFdy` of the world position) and the slope they lose is spent as roughness, or every sea past 130 m is a mirror. And the CPU height is a coarse throttled copy: `readbackResolution` over the largest `patchSize` is the spacing between samples, and make that spacing wider than the waves and the ship sits at a smoothed mean sea level, hanging over its own troughs. It is also `undefined` until the first copy lands, which `Ship.ts` handles by falling back to mean sea level, and `surfaceHeight(ocean, x, z, dt)` is the call anything that floats should use rather than `sampleHeight` raw: it samples upwind by however far the swell will have run during the copy's age, so a hull is not left riding water the renderer stopped drawing. `WaveField.sample(x, z, time)` returns height and normal and allocates; `heightAt(x, z, time)` is the same arithmetic without the jacobian and without an allocation — ask it for floats, splash and wake, and keep `sample` where you shade with the normal. `RippleField` is the sea answering back: a finite patch carrying only the disturbance, so add its `heightAt` to the sea height and its `foamAt` to the foam and never use it in place of a sea. It steps at display rate or the CFL limit, whichever is smaller; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that, and a `step` over the limit is rejected with the limit in the message. Its rim absorbs, so `recenter` it on whatever the player is watching.
55
+ The initial loading curtain also waits for the first finite CPU height in `src/scenes/ocean-readiness.ts`. It registers the existing startup hold synchronously, dispatches once after framework readiness, and releases on a real sample, including zero. The existing 45 s hold budget bounds the wait; timeout or compute failure emits `TN_SAILING_HEIGHT_READBACK_FAILED` before the gate fails open. Exit cancels the observer; restarts after startup use the ordinary compute lifecycle. This gate does not guarantee the timing of later throttled copies.
56
+
57
+ Five details are load-bearing. The material is `MeshStandardNodeMaterial`, not a basic one: a basic material takes no lights, so the sun on the water has to be faked with a `pow()` term, and the sea cannot agree with the hull floating on it. `normalNode` overrides `normalView`, so feed it a view-space normal or the reflection becomes a column of glare that follows the camera. The surface is a **logarithmic disc** centred on the ship, the cascade lookup adding the disc's own offset back: a square patch either ends inside the haze as a visible rectangular hem, or reaches the horizon with 300 m quads beside the hull. The ripple normals fade on the **pixel footprint** (`dFdx`/`dFdy` of the world position) and the slope they lose is spent as roughness, or every sea past 130 m is a mirror. And the CPU height is a coarse throttled copy: `readbackResolution` over the largest `patchSize` is the spacing between samples, and make that spacing wider than the waves and the ship sits at a smoothed mean sea level, hanging over its own troughs. It is also `undefined` until the first copy lands, which `Ship.ts` handles by falling back to mean sea level, and `surfaceHeight(ocean, x, z, dt)` is the call anything that floats should use rather than `sampleHeight` raw: it predicts the height from the same sample's measured vertical velocity and age. The hull additionally owns a `createHeightReconciler()` history: a new copy preserves the previous predicted height and velocity, then completes its correction over the measured interval between copies. `surfacePredictionCorrection` and `maxSurfacePredictionCorrection` report the waterline offset honestly; wave velocity and the attitude probes keep their measured inputs. `WaveField.sample(x, z, time)` returns height and normal and allocates; `heightAt(x, z, time)` is the same arithmetic without the jacobian and without an allocation — ask it for floats, splash and wake, and keep `sample` where you shade with the normal. `RippleField` is the sea answering back: a finite patch carrying only the disturbance, so add its `heightAt` to the sea height and its `foamAt` to the foam and never use it in place of a sea. It steps at display rate or the CFL limit, whichever is smaller; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that, and a `step` over the limit is rejected with the limit in the message. Its rim absorbs, so `recenter` it on whatever the player is watching.
56
58
 
57
- The sky is `assets/sky.jpg` (Poly Haven, CC0), fetched in `Boot.load` beside the ship — a scene's `load` is the one method allowed to await, and `Sailing.enter` must stay synchronous, because a playtest runner reads the registry the instant `enter()` returns. `sky.ts` draws it at `SKY_RANGE` and lights the scene at `FILL_RANGE`, and those are different numbers on purpose: half that photograph is a flat grey placeholder where a panorama's lower hemisphere should be, and at full range it becomes the largest term in every surface's light budget. Reflection is one half-res `WaterSurface3D` pass, with `markReflected` naming what the mirror may draw — it is a second draw of the world, so the sea stays off it, the sky arrives in the same texture, and there is no second sky lookup to blend against it.
59
+ The sky is `assets/sky.jpg` (Poly Haven, CC0), fetched in `Boot.load` beside the ship — a scene's `load` is the one method allowed to await, and `Sailing.enter` must stay synchronous, because a playtest runner reads the registry the instant `enter()` returns. `sky.ts` draws it at `SKY_RANGE` and lights the scene at `FILL_RANGE`, and those are different numbers on purpose: half that photograph is a flat grey placeholder where a panorama's lower hemisphere should be, and at full range it becomes the largest term in every surface's light budget. Reflection is one half-res `WaterSurface3D` pass, with `markReflected` naming what the mirror may draw — it is a second draw of the world, so the sea stays off it, the sky arrives in the same texture, and there is no second sky lookup to blend against it. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment.
58
60
 
59
61
  Tune the sea state in `src/render/ocean.ts`, the rig and hull in `src/render/props.ts` and `src/entities/Ship.ts`, and the course in `src/scenes/Sailing.ts`. The React HUD reads published state; keep `playtests/survives.playtest.json` as smoke proof and native scenarios honest.
60
62
 
61
- On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts`
62
- adds a left stick whose vector `Sailing` adds into both the helm and the sheets; keyboard is the fallback.
63
+ On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left stick whose vector `Sailing` adds into both the helm and the sheets; keyboard is the fallback.
63
64
 
64
65
  ## Portable authoring contracts
65
66
 
@@ -73,23 +74,23 @@ state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy
73
74
  is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
74
75
  state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
75
76
 
76
- `src/render/quality.ts` owns `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
77
- the source. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
77
+ WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports the source. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
78
78
 
79
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
80
- retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
79
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
81
80
  own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
82
81
  caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
83
82
  (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
84
83
  `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
85
84
  clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
86
- supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches 256 per presented frame so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
85
+ supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
87
86
  ## Budget real time for the look
88
87
 
89
88
  Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
90
89
 
91
90
  Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
92
91
 
93
- Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
92
+ For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
94
93
  ## Optional multiplayer transport
95
94
  For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
95
+ Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
96
+ `src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
@@ -5,9 +5,8 @@
5
5
  Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
6
6
 
7
7
  ## Ownership
8
-
9
8
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns ship handling, the sea's look and tuning, `Buoyancy3D`, course order, HUD,
10
- water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way.
9
+ water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
11
10
 
12
11
  ## Start every change
13
12
 
@@ -39,7 +38,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
39
38
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
40
39
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
41
40
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
42
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
41
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
43
42
 
44
43
  ## Commands and map
45
44
 
@@ -48,20 +47,22 @@ pnpm dev
48
47
  pnpm build
49
48
  pnpm build --target desktop
50
49
  pnpm test:native
50
+ pnpm exec threenative-playtest --scenario playtests/live/render-motion.playtest.json --live-clock --browser-recipe webgpu --headed --server-command "pnpm dev --host 127.0.0.1 --port $PORT --strictPort"
51
51
  ```
52
52
 
53
53
  Four course marks around the headland, a helm and a set of sheets, 120 seconds of wind. The hull and rig are `assets/ship.glb` — Poly Haven's `dutch_ship_medium` (CC0; James Ray Cock, Rico Cilliers, Nicolò Zubbini) — fetched by `Boot.load()` (`props.ts#loadShipModel`, alongside the sky) and read back synchronously in `Sailing.enter()` (`props.ts#getShipModel`), then oriented by `props.ts#createShipModel`: a scene-level `load()` on `Sailing` itself would still leave the registry empty the instant `enter()` returns, since `Boot.enter()` calls `goto("sailing")` without awaiting it. `conventions.ts#measureHull` reads the physics body's box and `Buoyancy3D` hull points off the loaded model rather than a hand-tuned constant, so a different hull model never needs those numbers touched by hand. `SHIP_SAILS` in `props.ts` stays simulated cloth: the GLB's own baked sail mesh is stripped at cook time so the two never double up. `Ship.ts` uses `RigidBody3D` plus `Buoyancy3D`, and reads the hull's attitude off four swell samples rotated by the heading rather than leaving it to the solver: `Buoyancy3D`'s drag comes from the body's *linear* velocity and so damps no rotation at all, and a free body capsizes inside seconds. A helm and sheets are two axes, not one stick: `vector("move")` clamps its diagonal to unit length, which is right for a thumb and wrong for a ship that must hold full sail and hard over at once.
54
54
 
55
55
  The sea is `SpectralOcean`, added with `ctx.add` so the compute registry runs its passes. It draws nothing: `src/render/ocean.ts` owns the mesh, the material, the mirror and every colour, and is the only file to edit for the water's look. The cascade buffers the vertex stage reads are the ones the CPU height query is copied from, so the hull floats on the surface that is drawn; two fields would leave the ship riding water nothing renders, with every assertion here still green.
56
56
 
57
- Five details are load-bearing. The material is `MeshStandardNodeMaterial`, not a basic one: a basic material takes no lights, so the sun on the water has to be faked with a `pow()` term, and the sea cannot agree with the hull floating on it. `normalNode` overrides `normalView`, so feed it a view-space normal or the reflection becomes a column of glare that follows the camera. The surface is a **logarithmic disc** centred on the ship, the cascade lookup adding the disc's own offset back: a square patch either ends inside the haze as a visible rectangular hem, or reaches the horizon with 300 m quads beside the hull. The ripple normals fade on the **pixel footprint** (`dFdx`/`dFdy` of the world position) and the slope they lose is spent as roughness, or every sea past 130 m is a mirror. And the CPU height is a coarse throttled copy: `readbackResolution` over the largest `patchSize` is the spacing between samples, and make that spacing wider than the waves and the ship sits at a smoothed mean sea level, hanging over its own troughs. It is also `undefined` until the first copy lands, which `Ship.ts` handles by falling back to mean sea level, and `surfaceHeight(ocean, x, z, dt)` is the call anything that floats should use rather than `sampleHeight` raw: it samples upwind by however far the swell will have run during the copy's age, so a hull is not left riding water the renderer stopped drawing. `WaveField.sample(x, z, time)` returns height and normal and allocates; `heightAt(x, z, time)` is the same arithmetic without the jacobian and without an allocation — ask it for floats, splash and wake, and keep `sample` where you shade with the normal. `RippleField` is the sea answering back: a finite patch carrying only the disturbance, so add its `heightAt` to the sea height and its `foamAt` to the foam and never use it in place of a sea. It steps at display rate or the CFL limit, whichever is smaller; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that, and a `step` over the limit is rejected with the limit in the message. Its rim absorbs, so `recenter` it on whatever the player is watching.
57
+ The initial loading curtain also waits for the first finite CPU height in `src/scenes/ocean-readiness.ts`. It registers the existing startup hold synchronously, dispatches once after framework readiness, and releases on a real sample, including zero. The existing 45 s hold budget bounds the wait; timeout or compute failure emits `TN_SAILING_HEIGHT_READBACK_FAILED` before the gate fails open. Exit cancels the observer; restarts after startup use the ordinary compute lifecycle. This gate does not guarantee the timing of later throttled copies.
58
+
59
+ Five details are load-bearing. The material is `MeshStandardNodeMaterial`, not a basic one: a basic material takes no lights, so the sun on the water has to be faked with a `pow()` term, and the sea cannot agree with the hull floating on it. `normalNode` overrides `normalView`, so feed it a view-space normal or the reflection becomes a column of glare that follows the camera. The surface is a **logarithmic disc** centred on the ship, the cascade lookup adding the disc's own offset back: a square patch either ends inside the haze as a visible rectangular hem, or reaches the horizon with 300 m quads beside the hull. The ripple normals fade on the **pixel footprint** (`dFdx`/`dFdy` of the world position) and the slope they lose is spent as roughness, or every sea past 130 m is a mirror. And the CPU height is a coarse throttled copy: `readbackResolution` over the largest `patchSize` is the spacing between samples, and make that spacing wider than the waves and the ship sits at a smoothed mean sea level, hanging over its own troughs. It is also `undefined` until the first copy lands, which `Ship.ts` handles by falling back to mean sea level, and `surfaceHeight(ocean, x, z, dt)` is the call anything that floats should use rather than `sampleHeight` raw: it predicts the height from the same sample's measured vertical velocity and age. The hull additionally owns a `createHeightReconciler()` history: a new copy preserves the previous predicted height and velocity, then completes its correction over the measured interval between copies. `surfacePredictionCorrection` and `maxSurfacePredictionCorrection` report the waterline offset honestly; wave velocity and the attitude probes keep their measured inputs. `WaveField.sample(x, z, time)` returns height and normal and allocates; `heightAt(x, z, time)` is the same arithmetic without the jacobian and without an allocation — ask it for floats, splash and wake, and keep `sample` where you shade with the normal. `RippleField` is the sea answering back: a finite patch carrying only the disturbance, so add its `heightAt` to the sea height and its `foamAt` to the foam and never use it in place of a sea. It steps at display rate or the CFL limit, whichever is smaller; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that, and a `step` over the limit is rejected with the limit in the message. Its rim absorbs, so `recenter` it on whatever the player is watching.
58
60
 
59
- The sky is `assets/sky.jpg` (Poly Haven, CC0), fetched in `Boot.load` beside the ship — a scene's `load` is the one method allowed to await, and `Sailing.enter` must stay synchronous, because a playtest runner reads the registry the instant `enter()` returns. `sky.ts` draws it at `SKY_RANGE` and lights the scene at `FILL_RANGE`, and those are different numbers on purpose: half that photograph is a flat grey placeholder where a panorama's lower hemisphere should be, and at full range it becomes the largest term in every surface's light budget. Reflection is one half-res `WaterSurface3D` pass, with `markReflected` naming what the mirror may draw — it is a second draw of the world, so the sea stays off it, the sky arrives in the same texture, and there is no second sky lookup to blend against it.
61
+ The sky is `assets/sky.jpg` (Poly Haven, CC0), fetched in `Boot.load` beside the ship — a scene's `load` is the one method allowed to await, and `Sailing.enter` must stay synchronous, because a playtest runner reads the registry the instant `enter()` returns. `sky.ts` draws it at `SKY_RANGE` and lights the scene at `FILL_RANGE`, and those are different numbers on purpose: half that photograph is a flat grey placeholder where a panorama's lower hemisphere should be, and at full range it becomes the largest term in every surface's light budget. Reflection is one half-res `WaterSurface3D` pass, with `markReflected` naming what the mirror may draw — it is a second draw of the world, so the sea stays off it, the sky arrives in the same texture, and there is no second sky lookup to blend against it. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment.
60
62
 
61
63
  Tune the sea state in `src/render/ocean.ts`, the rig and hull in `src/render/props.ts` and `src/entities/Ship.ts`, and the course in `src/scenes/Sailing.ts`. The React HUD reads published state; keep `playtests/survives.playtest.json` as smoke proof and native scenarios honest.
62
64
 
63
- On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts`
64
- adds a left stick whose vector `Sailing` adds into both the helm and the sheets; keyboard is the fallback.
65
+ On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left stick whose vector `Sailing` adds into both the helm and the sheets; keyboard is the fallback.
65
66
 
66
67
  ## Portable authoring contracts
67
68
 
@@ -75,23 +76,23 @@ state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy
75
76
  is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
76
77
  state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
77
78
 
78
- `src/render/quality.ts` owns `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
79
- the source. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
79
+ WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports the source. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
80
80
 
81
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
82
- retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
81
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
83
82
  own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
84
83
  caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
85
84
  (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
86
85
  `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
87
86
  clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
88
- supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches 256 per presented frame so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
87
+ supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
89
88
  ## Budget real time for the look
90
89
 
91
90
  Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
92
91
 
93
92
  Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
94
93
 
95
- Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
94
+ For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
96
95
  ## Optional multiplayer transport
97
96
  For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
97
+ Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
98
+ `src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
@@ -30,6 +30,13 @@
30
30
  },
31
31
  "renderChain": {
32
32
  "tier": "high",
33
+ "perAdapter": {
34
+ "integrated": { "stages": { "includes": ["bloom"] }, "tier": "medium" },
35
+ "mobile-high": { "stages": { "includes": ["bloom"] }, "tier": "medium" },
36
+ "mobile-low": { "stages": { "includes": ["bloom"] }, "tier": "low" },
37
+ "mobile-mid": { "stages": { "includes": ["bloom"] }, "tier": "low" },
38
+ "software": { "stages": { "includes": ["bloom"] }, "tier": "low" }
39
+ },
33
40
  "stages": {
34
41
  "includes": ["bloom"]
35
42
  }
@@ -16,9 +16,9 @@
16
16
  "typecheck": "tsc --noEmit -p tsconfig.json"
17
17
  },
18
18
  "dependencies": {
19
- "@threenative/core": "0.3.4",
20
- "@threenative/physics": "0.3.4",
21
- "@threenative/ui": "0.3.4",
19
+ "@threenative/core": "0.3.5",
20
+ "@threenative/physics": "0.3.5",
21
+ "@threenative/ui": "0.3.5",
22
22
  "react": "19.2.0",
23
23
  "react-dom": "19.2.0",
24
24
  "react-reconciler": "0.33.0",
@@ -26,22 +26,22 @@
26
26
  },
27
27
  "devDependencies": {
28
28
  "@tailwindcss/vite": "4.3.3",
29
- "@threenative/assets": "0.3.5",
30
- "@threenative/playtest": "0.3.4",
29
+ "@threenative/assets": "0.3.6",
30
+ "@threenative/playtest": "0.3.5",
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.8",
35
+ "create-threenative": "0.2.9",
36
36
  "esbuild": "0.27.0",
37
37
  "playwright": "1.62.1",
38
38
  "tailwindcss": "4.3.3",
39
- "typescript": "5.9.3",
39
+ "typescript": "7.0.2",
40
40
  "vite": "8.2.0",
41
41
  "@gltf-transform/cli": "4.4.2"
42
42
  },
43
43
  "optionalDependencies": {
44
- "@threenative/runtime-native": "0.3.4"
44
+ "@threenative/runtime-native": "0.3.5"
45
45
  },
46
46
  "overrides": {
47
47
  "sharp": ">=0.35.4"
@@ -52,7 +52,9 @@
52
52
  },
53
53
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
54
54
  "patchedDependencies": {
55
- "three@0.185.1": "patches/three@0.185.1.patch"
55
+ "three@0.185.1": "patches/three@0.185.1.patch",
56
+ "vite@8.2.0": "patches/vite@8.2.0.patch",
57
+ "@tailwindcss/node@4.3.3": "patches/@tailwindcss__node@4.3.3.patch"
56
58
  }
57
59
  }
58
60
  }
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "sailing-rendered-hull-motion",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 40,
7
+ "subject": "player",
8
+ "steps": [{ "kind": "wait", "label": "live-swell", "waitTicks": 2400, "release": true }],
9
+ "assert": {
10
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
11
+ "components": [
12
+ { "entity": "player", "component": "renderFrames", "gte": 600, "changed": true },
13
+ { "entity": "player", "component": "fractionalRenderFrames", "gte": 300, "changed": true },
14
+ { "entity": "player", "component": "renderedReadbacks", "gte": 100, "changed": true },
15
+ { "entity": "player", "component": "renderedHullVerticalRange", "gte": 0.2, "changed": true },
16
+ {
17
+ "entity": "player",
18
+ "component": "seaHeight",
19
+ "changed": true,
20
+ "allowTrivial": "The sampled ocean must evolve while the actually rendered hull travels vertically; frozen water or a frozen hull cannot satisfy the motion proof."
21
+ },
22
+ {
23
+ "entity": "player",
24
+ "component": "maxRenderJitterPixels",
25
+ "lte": 1,
26
+ "allowTrivial": "One pixel of unexplained projected velocity change per 60 Hz frame is the visible-shake limit. This measures the actually drawn hull and camera inside Scene.render; separate frame, fractional-alpha and landed-readback floors reject frozen or counted-clock runs."
27
+ }
28
+ ]
29
+ }
30
+ }