create-threenative 0.2.17 → 0.2.18

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 (310) hide show
  1. package/agent-docs/kit-mcp.md +1 -1
  2. package/agent-docs/kit-router.md +1 -1
  3. package/agent-docs/references/assertion-reference.md +54 -110
  4. package/agent-docs/references/capability-reference.md +580 -22
  5. package/agent-docs/references/conventions.md +28 -0
  6. package/agent-docs/references/performance-basics.md +8 -4
  7. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  8. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +7 -4
  9. package/agent-files/.claude/hooks/discovery-gate.mjs +2 -2
  10. package/dist/index.d.ts +97 -6
  11. package/dist/index.js +769 -277
  12. package/dist/threenative.js +96 -17
  13. package/dist/web-engine-ccd-ik-solver.js +127 -0
  14. package/dist/web-engine-gltf-loader.js +52 -14
  15. package/dist/web-engine-post-effects.js +5 -10
  16. package/dist/web-engine-runtime.js +3648 -546
  17. package/package.json +8 -7
  18. package/template-assets/clearwater/README.md +1 -1
  19. package/template-assets/patches/manifest.json +18 -0
  20. package/template-assets/terrain/alpine/assets.json +12 -0
  21. package/template-assets/terrain/alpine/bake.mjs +6 -0
  22. package/template-assets/terrain/alpine/credits.json +164 -0
  23. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  24. package/template-assets/terrain/alpine/recipe.json +119 -0
  25. package/template-assets/terrain/alpine/surface.json +53 -0
  26. package/template-assets/terrain/coastal/assets.json +11 -0
  27. package/template-assets/terrain/coastal/bake.mjs +6 -0
  28. package/template-assets/terrain/coastal/credits.json +117 -0
  29. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  30. package/template-assets/terrain/coastal/recipe.json +113 -0
  31. package/template-assets/terrain/coastal/surface.json +41 -0
  32. package/template-assets/terrain/desert/assets.json +12 -0
  33. package/template-assets/terrain/desert/bake.mjs +6 -0
  34. package/template-assets/terrain/desert/credits.json +164 -0
  35. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  36. package/template-assets/terrain/desert/recipe.json +108 -0
  37. package/template-assets/terrain/desert/surface.json +54 -0
  38. package/template-assets/terrain/forest/assets.json +65 -0
  39. package/template-assets/terrain/forest/bake.mjs +8 -0
  40. package/template-assets/terrain/forest/credits.json +225 -0
  41. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  42. package/template-assets/terrain/forest/recipe.json +350 -0
  43. package/template-assets/terrain/forest/surface.json +79 -0
  44. package/template-assets/terrain/tundra/assets.json +12 -0
  45. package/template-assets/terrain/tundra/bake.mjs +6 -0
  46. package/template-assets/terrain/tundra/credits.json +164 -0
  47. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  48. package/template-assets/terrain/tundra/recipe.json +277 -0
  49. package/template-assets/terrain/tundra/surface.json +54 -0
  50. package/templates/action-rpg/AGENTS.md +8 -4
  51. package/templates/action-rpg/CLAUDE.md +8 -4
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/src/game.ts +1 -1
  54. package/templates/action-rpg/src/render/atmosphere.ts +6 -0
  55. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  56. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  57. package/templates/action-rpg/src/render/clouds.ts +13 -0
  58. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  59. package/templates/action-rpg/src/render/quality.ts +7 -32
  60. package/templates/action-rpg/src/scenes/Play.ts +4 -1
  61. package/templates/action-rpg/src/style.css +4 -0
  62. package/templates/action-rpg/vite.config.ts +2 -0
  63. package/templates/adventure/AGENTS.md +7 -2
  64. package/templates/adventure/CLAUDE.md +7 -2
  65. package/templates/adventure/kit.json +5 -1
  66. package/templates/adventure/package.json +7 -7
  67. package/templates/adventure/src/game.ts +1 -1
  68. package/templates/adventure/src/style.css +4 -0
  69. package/templates/adventure/tsconfig.json +1 -1
  70. package/templates/adventure/vite.config.ts +2 -0
  71. package/templates/collectathon/AGENTS.md +7 -2
  72. package/templates/collectathon/CLAUDE.md +7 -2
  73. package/templates/collectathon/package.json +7 -7
  74. package/templates/collectathon/src/game.ts +1 -1
  75. package/templates/collectathon/src/level/Course.ts +55 -9
  76. package/templates/collectathon/src/level/terrain.ts +27 -6
  77. package/templates/collectathon/src/main.ts +1 -0
  78. package/templates/collectathon/src/render/foliage.ts +359 -98
  79. package/templates/collectathon/src/render/sky.ts +76 -12
  80. package/templates/collectathon/src/render/water.ts +32 -10
  81. package/templates/collectathon/src/scenes/Play.ts +18 -5
  82. package/templates/collectathon/src/style.css +4 -0
  83. package/templates/collectathon/tsconfig.json +1 -1
  84. package/templates/collectathon/vite.config.ts +2 -0
  85. package/templates/kart/AGENTS.md +7 -2
  86. package/templates/kart/CLAUDE.md +7 -2
  87. package/templates/kart/package.json +6 -6
  88. package/templates/kart/src/game.ts +1 -1
  89. package/templates/kart/src/main.ts +1 -0
  90. package/templates/kart/src/style.css +4 -0
  91. package/templates/kart/tsconfig.json +1 -1
  92. package/templates/kart/vite.config.ts +2 -0
  93. package/templates/minimal/AGENTS.md +8 -3
  94. package/templates/minimal/CLAUDE.md +8 -3
  95. package/templates/minimal/package.json +6 -6
  96. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  97. package/templates/minimal/src/game.ts +1 -1
  98. package/templates/minimal/src/render/atmosphere.ts +6 -0
  99. package/templates/minimal/src/render/backlightControls.ts +10 -0
  100. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  101. package/templates/minimal/src/render/camera.ts +13 -2
  102. package/templates/minimal/src/render/clouds.ts +13 -0
  103. package/templates/minimal/src/render/lighting.ts +4 -2
  104. package/templates/minimal/src/render/materialLighting.ts +5 -5
  105. package/templates/minimal/src/render/materials.ts +10 -0
  106. package/templates/minimal/src/render/quality.ts +7 -32
  107. package/templates/minimal/src/scenes/Play.ts +4 -1
  108. package/templates/minimal/vite.config.ts +7 -1
  109. package/templates/platformer/AGENTS.md +9 -4
  110. package/templates/platformer/CLAUDE.md +9 -4
  111. package/templates/platformer/index.html +1 -1
  112. package/templates/platformer/main.html +12 -0
  113. package/templates/platformer/package.json +7 -7
  114. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  115. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  116. package/templates/platformer/src/entities/Fox.ts +21 -6
  117. package/templates/platformer/src/game.ts +1 -1
  118. package/templates/platformer/src/main.ts +1 -0
  119. package/templates/platformer/src/render/backlightControls.ts +10 -0
  120. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  121. package/templates/platformer/src/render/materialLighting.ts +5 -5
  122. package/templates/platformer/src/render/quality.ts +7 -32
  123. package/templates/platformer/src/scenes/Play.ts +2 -1
  124. package/templates/platformer/src/style.css +4 -0
  125. package/templates/platformer/src/worker-page.ts +29 -0
  126. package/templates/platformer/src/worker.ts +5 -0
  127. package/templates/platformer/tsconfig.json +1 -1
  128. package/templates/platformer/vite.config.ts +4 -0
  129. package/templates/puzzle/AGENTS.md +7 -2
  130. package/templates/puzzle/CLAUDE.md +7 -2
  131. package/templates/puzzle/package.json +7 -7
  132. package/templates/puzzle/src/game.ts +1 -1
  133. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  134. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  135. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  136. package/templates/puzzle/src/render/quality.ts +7 -32
  137. package/templates/puzzle/src/scenes/Play.ts +1 -1
  138. package/templates/puzzle/src/style.css +4 -0
  139. package/templates/puzzle/tsconfig.json +1 -1
  140. package/templates/puzzle/vite.config.ts +2 -0
  141. package/templates/racing/AGENTS.md +7 -2
  142. package/templates/racing/CLAUDE.md +7 -2
  143. package/templates/racing/package.json +7 -7
  144. package/templates/racing/src/game.ts +1 -1
  145. package/templates/racing/src/render/atmosphere.ts +6 -0
  146. package/templates/racing/src/render/backlightControls.ts +10 -0
  147. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  148. package/templates/racing/src/render/clouds.ts +13 -0
  149. package/templates/racing/src/render/materialLighting.ts +5 -5
  150. package/templates/racing/src/render/quality.ts +7 -32
  151. package/templates/racing/src/scenes/Race.ts +4 -1
  152. package/templates/racing/src/style.css +4 -0
  153. package/templates/racing/tsconfig.json +1 -1
  154. package/templates/racing/vite.config.ts +2 -0
  155. package/templates/rain/AGENTS.md +6 -2
  156. package/templates/rain/CLAUDE.md +6 -2
  157. package/templates/rain/package.json +6 -6
  158. package/templates/rain/src/game.ts +1 -1
  159. package/templates/rain/vite.config.ts +6 -0
  160. package/templates/rts/AGENTS.md +6 -2
  161. package/templates/rts/CLAUDE.md +6 -2
  162. package/templates/rts/package.json +6 -6
  163. package/templates/rts/src/game.ts +1 -1
  164. package/templates/rts/src/render/backlightControls.ts +10 -0
  165. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  166. package/templates/rts/src/render/materialLighting.ts +5 -5
  167. package/templates/rts/src/render/quality.ts +7 -31
  168. package/templates/rts/src/scenes/Play.ts +1 -1
  169. package/templates/rts/src/style.css +4 -0
  170. package/templates/rts/vite.config.ts +2 -0
  171. package/templates/runner/AGENTS.md +7 -2
  172. package/templates/runner/CLAUDE.md +7 -2
  173. package/templates/runner/package.json +7 -7
  174. package/templates/runner/src/game.ts +1 -1
  175. package/templates/runner/src/render/atmosphere.ts +6 -0
  176. package/templates/runner/src/render/backlightControls.ts +10 -0
  177. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  178. package/templates/runner/src/render/clouds.ts +13 -0
  179. package/templates/runner/src/render/materialLighting.ts +5 -5
  180. package/templates/runner/src/render/quality.ts +7 -32
  181. package/templates/runner/src/scenes/Run.ts +4 -1
  182. package/templates/runner/src/style.css +4 -0
  183. package/templates/runner/tsconfig.json +1 -1
  184. package/templates/runner/vite.config.ts +2 -0
  185. package/templates/sailing/AGENTS.md +7 -2
  186. package/templates/sailing/CLAUDE.md +7 -2
  187. package/templates/sailing/package.json +7 -7
  188. package/templates/sailing/src/game.ts +1 -1
  189. package/templates/sailing/src/render/backlightControls.ts +10 -0
  190. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  191. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  192. package/templates/sailing/src/render/materialLighting.ts +5 -5
  193. package/templates/sailing/src/render/quality.ts +7 -32
  194. package/templates/sailing/src/style.css +5 -0
  195. package/templates/sailing/vite.config.ts +6 -0
  196. package/templates/shooter/AGENTS.md +6 -2
  197. package/templates/shooter/CLAUDE.md +6 -2
  198. package/templates/shooter/package.json +7 -7
  199. package/templates/shooter/src/game.ts +3 -2
  200. package/templates/shooter/src/render/atmosphere.ts +6 -0
  201. package/templates/shooter/src/render/backlightControls.ts +10 -0
  202. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  203. package/templates/shooter/src/render/clouds.ts +13 -0
  204. package/templates/shooter/src/render/materialLighting.ts +5 -5
  205. package/templates/shooter/src/render/quality.ts +7 -32
  206. package/templates/shooter/src/scenes/Play.ts +4 -1
  207. package/templates/shooter/src/style.css +4 -0
  208. package/templates/shooter/vite.config.ts +2 -0
  209. package/templates/snow/AGENTS.md +7 -2
  210. package/templates/snow/CLAUDE.md +7 -2
  211. package/templates/snow/package.json +7 -7
  212. package/templates/snow/src/game.ts +1 -1
  213. package/templates/snow/src/render/backlightControls.ts +10 -0
  214. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  215. package/templates/snow/src/render/materialLighting.ts +5 -5
  216. package/templates/snow/src/render/quality.ts +7 -32
  217. package/templates/snow/src/style.css +5 -0
  218. package/templates/snow/vite.config.ts +6 -0
  219. package/templates/starter/AGENTS.md +8 -3
  220. package/templates/starter/CLAUDE.md +8 -3
  221. package/templates/starter/package.json +7 -7
  222. package/templates/starter/src/entities/Crate.ts +5 -2
  223. package/templates/starter/src/game.ts +4 -3
  224. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  225. package/templates/starter/src/render/atmosphere.ts +6 -0
  226. package/templates/starter/src/render/backlightControls.ts +10 -0
  227. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  228. package/templates/starter/src/render/clouds.ts +13 -0
  229. package/templates/starter/src/render/contactShadow.ts +1 -1
  230. package/templates/starter/src/render/materialLighting.ts +5 -5
  231. package/templates/starter/src/render/postprocessing.ts +11 -10
  232. package/templates/starter/src/render/quality.ts +14 -1
  233. package/templates/starter/src/scenes/Play.ts +12 -3
  234. package/templates/starter/src/state.ts +2 -0
  235. package/templates/starter/src/style.css +4 -0
  236. package/templates/starter/src/ui/Menu.tsx +5 -1
  237. package/templates/starter/vite.config.ts +2 -0
  238. package/templates/tower-defense/AGENTS.md +7 -2
  239. package/templates/tower-defense/CLAUDE.md +7 -2
  240. package/templates/tower-defense/package.json +7 -7
  241. package/templates/tower-defense/src/game.ts +1 -1
  242. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  243. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  244. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  245. package/templates/tower-defense/src/render/quality.ts +7 -32
  246. package/templates/tower-defense/src/scenes/Battle.ts +1 -1
  247. package/templates/tower-defense/src/style.css +4 -0
  248. package/templates/tower-defense/tsconfig.json +1 -1
  249. package/templates/tower-defense/vite.config.ts +2 -0
  250. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  251. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  252. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  253. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  254. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  255. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  256. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  257. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  258. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  259. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  260. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  261. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  262. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  263. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  264. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  265. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  266. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  267. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  268. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  269. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  270. package/templates/racing/src/render/environmentContribution.ts +0 -188
  271. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  272. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  273. package/templates/racing/src/render/environmentSampling.ts +0 -193
  274. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  275. package/templates/rts/src/render/environmentContribution.ts +0 -188
  276. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  277. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  278. package/templates/rts/src/render/environmentSampling.ts +0 -193
  279. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  280. package/templates/runner/src/render/environmentContribution.ts +0 -188
  281. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  282. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  283. package/templates/runner/src/render/environmentSampling.ts +0 -193
  284. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  285. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  286. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  287. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  288. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  289. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  290. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  291. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  292. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  293. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  294. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  295. package/templates/snow/src/render/environmentContribution.ts +0 -188
  296. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  297. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  298. package/templates/snow/src/render/environmentSampling.ts +0 -193
  299. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  300. package/templates/starter/src/render/environmentContribution.ts +0 -188
  301. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  302. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  303. package/templates/starter/src/render/environmentSampling.ts +0 -193
  304. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  305. package/templates/starter/src/render/rendererGate.ts +0 -36
  306. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  307. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  308. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  309. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  310. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -92,7 +92,7 @@ const smooth = (from: number, to: number, value: number): number => {
92
92
  * flatten toward the horizon. Each is lit by where its density climbs: a texel whose deck is
93
93
  * denser toward the sun, or above it on screen, is on the cloud's shaded side or its flat base.
94
94
  */
95
- export function skyTexture(saturation = 1, width = 2048): DataTexture {
95
+ export function skyPixels(saturation = 1, width = 2048): Uint8Array {
96
96
  // three's PMREM sizes its cube from width / 4 and needs at least 16: keep width >= 64.
97
97
  const height = width / 2;
98
98
  const data = new Uint8Array(width * height * 4);
@@ -109,6 +109,14 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
109
109
  let baseR = 0;
110
110
  let baseG = 0;
111
111
  let baseB = 0;
112
+ // Each column's azimuth terms, once: the same numbers every row reads.
113
+ const cosAzimuth = new Float64Array(width);
114
+ const sinAzimuth = new Float64Array(width);
115
+ for (let column = 0; column < width; column += 1) {
116
+ const azimuth = (column / width - 0.5) * Math.PI * 2;
117
+ cosAzimuth[column] = Math.cos(azimuth);
118
+ sinAzimuth[column] = Math.sin(azimuth);
119
+ }
112
120
  // Pass 1: the deck's density under every cloud-band texel, once (the shading reads neighbours).
113
121
  const deck = new Float32Array(width * height);
114
122
  const bands = new Float32Array(height);
@@ -120,8 +128,10 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
120
128
  // Flattened less than a true deck would be: cumulus heaps stand tall, they are not a sheet.
121
129
  const reach = (1 / (Math.tan(elevation) + 0.1)) ** 0.7 * 0.75;
122
130
  for (let column = 0; column < width; column += 1) {
123
- const azimuth = (column / width - 0.5) * Math.PI * 2;
124
- deck[row * width + column] = density(Math.cos(azimuth) * reach, Math.sin(azimuth) * reach);
131
+ deck[row * width + column] = density(
132
+ (cosAzimuth[column] as number) * reach,
133
+ (sinAzimuth[column] as number) * reach,
134
+ );
125
135
  }
126
136
  }
127
137
  // The cumulus banks over the far hills, per column: where a bank stands (`cluster`), its heaped
@@ -142,6 +152,12 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
142
152
  const step = Math.max(1, Math.round(width / 512));
143
153
  const sunAzimuth = Math.atan2(SUN_DIRECTION.z, SUN_DIRECTION.x);
144
154
  const sunElevation = Math.asin(SUN_DIRECTION.y);
155
+ // Which way the sun lies from each column, once.
156
+ const sunward = new Int8Array(width);
157
+ for (let column = 0; column < width; column += 1) {
158
+ const azimuth = (column / width - 0.5) * Math.PI * 2;
159
+ sunward[column] = Math.sin(sunAzimuth - azimuth) > 0 ? 1 : -1;
160
+ }
145
161
  for (let row = 0; row < height; row += 1) {
146
162
  const elevation = (row / (height - 1) - 0.5) * Math.PI;
147
163
  const up = Math.sin(elevation);
@@ -171,9 +187,10 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
171
187
  );
172
188
  for (let column = 0; column < width; column += 1) {
173
189
  // three's equirectangular u: azimuth from +X toward +Z, u = 0.5 on +X.
174
- const azimuth = (column / width - 0.5) * Math.PI * 2;
175
- const tx = Math.cos(azimuth) * cosE;
176
- const tz = Math.sin(azimuth) * cosE;
190
+ const cosA = cosAzimuth[column] as number;
191
+ const sinA = sinAzimuth[column] as number;
192
+ const tx = cosA * cosE;
193
+ const tz = sinA * cosE;
177
194
  // The sun's halo: a warm glow round its direction, wider than the disc the lens never sees.
178
195
  const sun = Math.max(0, tx * SUN_DIRECTION.x + up * SUN_DIRECTION.y + tz * SUN_DIRECTION.z);
179
196
  const halo = 0.6 * sun ** 32 + 0.22 * sun ** 5;
@@ -183,7 +200,7 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
183
200
  const d = deck[row * width + column] ?? 0;
184
201
  const cover = band > 0 ? smooth(0.43, 0.54, d) * band : 0;
185
202
  if (cover > 0.002) {
186
- const turn = Math.sin(sunAzimuth - azimuth) > 0 ? step : -step;
203
+ const turn = (sunward[column] as number) * step;
187
204
  const towardColumn = (column + turn + width) % width;
188
205
  // Denser a step toward the sun: the far side of a heap. Denser a step up the sky: its base.
189
206
  const toward = (deck[towardRow * width + towardColumn] ?? 0) - d;
@@ -202,8 +219,7 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
202
219
  if (elevation > foot && elevation < top + 0.05) {
203
220
  // Billowed outline: finer noise lifts and bites the heap's top edge.
204
221
  // Elevation moves radially and azimuth round the circle: round puffs, and azimuth wraps.
205
- const puff = (e: number) =>
206
- fbm(Math.cos(azimuth) * (14 + e * 15), Math.sin(azimuth) * (14 + e * 15), 3);
222
+ const puff = (e: number) => fbm(cosA * (14 + e * 15), sinA * (14 + e * 15), 3);
207
223
  const lump = puff(elevation);
208
224
  const below = top + (lump - 0.5) * 0.11 - elevation;
209
225
  const inside = smooth(0, 0.02, below) * smooth(foot, foot + 0.012, elevation);
@@ -225,12 +241,27 @@ export function skyTexture(saturation = 1, width = 2048): DataTexture {
225
241
  }
226
242
  const grey = r * 0.2126 + g * 0.7152 + b * 0.0722;
227
243
  const i = (row * width + column) * 4;
228
- data[i] = Math.round(255 * linearToSrgb(r + (grey - r) * (1 - saturation)));
229
- data[i + 1] = Math.round(255 * linearToSrgb(g + (grey - g) * (1 - saturation)));
230
- data[i + 2] = Math.round(255 * linearToSrgb(b + (grey - b) * (1 - saturation)));
244
+ data[i] = srgbByte(r + (grey - r) * (1 - saturation));
245
+ data[i + 1] = srgbByte(g + (grey - g) * (1 - saturation));
246
+ data[i + 2] = srgbByte(b + (grey - b) * (1 - saturation));
231
247
  data[i + 3] = 255;
232
248
  }
233
249
  }
250
+ return data;
251
+ }
252
+
253
+ /**
254
+ * The sky as a texture. `data` is `skyPixels(saturation, width)`; the scene passes the copy it kept
255
+ * from the last run (`ctx.assets.memo`), because painting four million texels costs a run ~0.3 s.
256
+ */
257
+ export function skyTexture(
258
+ saturation = 1,
259
+ width = 2048,
260
+ data: Uint8Array = skyPixels(saturation, width),
261
+ ): DataTexture {
262
+ const height = width / 2;
263
+ if (data.length !== width * height * 4)
264
+ throw new Error(`sky pixels are ${data.length} bytes, expected ${width * height * 4}.`);
234
265
  const sky = new DataTexture(data, width, height, RGBAFormat, UnsignedByteType);
235
266
  sky.mapping = EquirectangularReflectionMapping;
236
267
  sky.colorSpace = SRGBColorSpace;
@@ -247,6 +278,39 @@ function linearToSrgb(value: number): number {
247
278
  return v < 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
248
279
  }
249
280
 
281
+ /**
282
+ * `Math.round(255 * linearToSrgb(value))` for millions of texels: the byte only steps up as the
283
+ * value grows, so the smallest value of each step, found once, gives the same byte with no power.
284
+ */
285
+ const SRGB_STEPS = (() => {
286
+ const byte = (value: number) => Math.round(255 * linearToSrgb(value));
287
+ const steps = new Float64Array(256);
288
+ for (let level = 1; level < 256; level += 1) {
289
+ let low = 0;
290
+ let high = 1;
291
+ // Halve until the two ends are adjacent doubles: `high` is then the step's first value.
292
+ for (;;) {
293
+ const middle = low + (high - low) / 2;
294
+ if (middle === low || middle === high) break;
295
+ if (byte(middle) >= level) high = middle;
296
+ else low = middle;
297
+ }
298
+ steps[level] = high;
299
+ }
300
+ return steps;
301
+ })();
302
+
303
+ function srgbByte(value: number): number {
304
+ let low = 0;
305
+ let high = 255;
306
+ while (low < high) {
307
+ const middle = (low + high + 1) >> 1;
308
+ if (value >= (SRGB_STEPS[middle] as number)) low = middle;
309
+ else high = middle - 1;
310
+ }
311
+ return low;
312
+ }
313
+
250
314
  /** `fill` is the environment light: by default the sky itself, in this game `skyTexture(0.3, 128)`. */
251
315
  export function setupSky(scene: Scene, sky: DataTexture, fill: DataTexture = sky): void {
252
316
  scene.background = sky;
@@ -85,12 +85,39 @@ function depthMap(floor: ISeaFloor): DataTexture {
85
85
  }
86
86
 
87
87
  /** Tiling ripples: periodic value noise, its slope in red/green and its height in alpha. */
88
+ const RIPPLE_SIZE = 256;
89
+ let primedRipples: Uint8Array | undefined;
90
+ /** Hand the ripple pixels back from a store (`ctx.assets.memo`), so `seaMaterial` skips painting them. */
91
+ export function primeRipplePixels(pixels: Uint8Array): void {
92
+ if (pixels.length !== RIPPLE_SIZE * RIPPLE_SIZE * 4)
93
+ throw new Error("ripple pixels do not match RIPPLE_SIZE.");
94
+ primedRipples = pixels;
95
+ }
88
96
  function rippleMap(): DataTexture {
89
- const n = 256;
97
+ const n = RIPPLE_SIZE;
98
+ const map = new DataTexture(primedRipples ?? ripplePixels(), n, n);
99
+ map.wrapS = RepeatWrapping;
100
+ map.wrapT = RepeatWrapping;
101
+ map.magFilter = LinearFilter;
102
+ map.minFilter = LinearMipmapLinearFilter;
103
+ map.generateMipmaps = true;
104
+ map.needsUpdate = true;
105
+ return map;
106
+ }
107
+ /** The sea's ripple normal (RG) and height (A), the same every run: no input, no randomness. */
108
+ export function ripplePixels(): Uint8Array {
109
+ const n = RIPPLE_SIZE;
90
110
  const hash = (x: number, z: number): number => {
91
111
  const a = Math.sin(x * 127.1 + z * 311.7) * 43758.5453;
92
112
  return a - Math.floor(a);
93
113
  };
114
+ // Each octave's lattice is k x k whole points, hashed once: a texel reads 64 of them.
115
+ const lattices = new Map<number, Float64Array>();
116
+ for (const k of [8, 16, 32, 64]) {
117
+ const lattice = new Float64Array(k * k);
118
+ for (let x = 0; x < k; x += 1) for (let z = 0; z < k; z += 1) lattice[x * k + z] = hash(x, z);
119
+ lattices.set(k, lattice);
120
+ }
94
121
  const noise = (u: number, v: number, k: number): number => {
95
122
  const x = u * k;
96
123
  const z = v * k;
@@ -100,7 +127,9 @@ function rippleMap(): DataTexture {
100
127
  let b = z - j;
101
128
  a = a * a * a * (a * (a * 6 - 15) + 10);
102
129
  b = b * b * b * (b * (b * 6 - 15) + 10);
103
- const h = (hx: number, hz: number): number => hash(((hx % k) + k) % k, ((hz % k) + k) % k);
130
+ const lattice = lattices.get(k) as Float64Array;
131
+ const h = (hx: number, hz: number): number =>
132
+ lattice[(((hx % k) + k) % k) * k + (((hz % k) + k) % k)] as number;
104
133
  return (
105
134
  (h(i, j) * (1 - a) + h(i + 1, j) * a) * (1 - b) +
106
135
  (h(i, j + 1) * (1 - a) + h(i + 1, j + 1) * a) * b
@@ -126,14 +155,7 @@ function rippleMap(): DataTexture {
126
155
  data[at + 3] = height(u, v) * 255;
127
156
  }
128
157
  }
129
- const map = new DataTexture(data, n, n);
130
- map.wrapS = RepeatWrapping;
131
- map.wrapT = RepeatWrapping;
132
- map.magFilter = LinearFilter;
133
- map.minFilter = LinearMipmapLinearFilter;
134
- map.generateMipmaps = true;
135
- map.needsUpdate = true;
136
- return map;
158
+ return data;
137
159
  }
138
160
 
139
161
  export function seaMaterial(floor: ISeaFloor, swell: ISwell): MeshStandardNodeMaterial {
@@ -25,9 +25,10 @@ import { setupLighting } from "../render/lighting.js";
25
25
  import { createLoadingScreen } from "../render/loading.js";
26
26
  import { postTier, setupPost } from "../render/postprocessing.js";
27
27
  import { GRASS_SHARE } from "../render/quality.js";
28
- import { setupSky, skyTexture } from "../render/sky.js";
28
+ import { setupSky, skyPixels, skyTexture } from "../render/sky.js";
29
29
  import { loadSurfaces, updateSurfaceSampling } from "../render/surface.js";
30
30
  import { TouchControls } from "../render/touch-controls.js";
31
+ import { primeRipplePixels, ripplePixels } from "../render/water.js";
31
32
  import { type GameState, HUD_PILL } from "../state.js";
32
33
 
33
34
  export type { GameCtx };
@@ -90,16 +91,28 @@ export class Play extends Scene<GameState, IPhysicsContext> {
90
91
  this.#loading = createLoadingScreen(ctx);
91
92
  // The HUD is page UI the cover cannot hide, so it waits for the same readiness.
92
93
  void ctx.startup.whenReady().then(() => ctx.state.set({ loaded: true }));
93
- const surfaces = await loadSurfaces(ctx.assets);
94
- this.#sky = skyTexture();
95
- this.#fill = skyTexture(0.3, 128);
94
+ // The sky is the same every run of this build: paint it once, then read the pixels back. A first
95
+ // visit paints it (~600 ms on a laptop) while the surface textures download, not after them.
96
+ const [surfaces, painted] = await Promise.all([
97
+ loadSurfaces(ctx.assets),
98
+ ctx.assets.memo("sky", () => ({
99
+ fill: skyPixels(0.3, 128),
100
+ ripples: ripplePixels(),
101
+ sky: skyPixels(),
102
+ })),
103
+ ]);
104
+ primeRipplePixels(painted.ripples);
105
+ this.#sky = skyTexture(1, 2048, painted.sky);
106
+ this.#fill = skyTexture(0.3, 128, painted.fill);
96
107
  setupSky(ctx.scene, this.#sky, this.#fill);
97
108
  const tier = postTier({
98
109
  gpuClass: ctx.renderer.gpuClass?.class,
99
110
  mobile: isMobile(),
100
111
  software: ctx.renderer.softwareAdapter !== undefined,
101
112
  });
102
- const course = buildCourse(makeRng(6402), surfaces, GRASS_SHARE[tier]);
113
+ // The island is the same every run of this build: the first run draws it, a repeat reads it
114
+ // back from `ctx.assets.memo` (~105 ms of the load on a laptop).
115
+ const course = await buildCourse(makeRng(6402), surfaces, GRASS_SHARE[tier], ctx.assets.memo);
103
116
  this.#course = course;
104
117
  ctx.add(course.group);
105
118
  ctx.entities.add("course", { debug: () => course.audit });
@@ -2,6 +2,10 @@
2
2
 
3
3
  @source "../index.html";
4
4
  @source "./";
5
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
6
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
7
+ profile failure. Tailwind scans what it is told to scan. */
8
+ @source not "./render";
5
9
 
6
10
  @theme {
7
11
  --color-ink: #1d3a5c;
@@ -13,5 +13,5 @@
13
13
  "verbatimModuleSyntax": true,
14
14
  "isolatedModules": true
15
15
  },
16
- "include": ["src/**/*.ts", "src/**/*.tsx", "*.ts"]
16
+ "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "*.ts"]
17
17
  }
@@ -2,6 +2,7 @@ import tailwindcss from "@tailwindcss/vite";
2
2
  import { watchAssets } from "@threenative/assets";
3
3
  import react from "@vitejs/plugin-react";
4
4
  import {
5
+ createEngineCatalogPlugin,
5
6
  createEngineFreshnessPlugin,
6
7
  createWebBrandPlugin,
7
8
  webRuntimeDecoders,
@@ -36,6 +37,7 @@ export default defineConfig({
36
37
  plugins: [
37
38
  createEngineFreshnessPlugin(),
38
39
  createWebBrandPlugin(),
40
+ createEngineCatalogPlugin(),
39
41
  react(),
40
42
  tailwindcss(),
41
43
  assetsWatchPlugin(),
@@ -11,7 +11,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
11
11
 
12
12
  1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
13
13
  2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
14
- 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
14
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
15
15
  4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
16
16
  5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
17
17
  6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
@@ -30,7 +30,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
30
30
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
31
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
32
  - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
33
- - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
33
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
34
34
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
35
  <!-- /shared -->
36
36
 
@@ -54,6 +54,7 @@ pnpm test # typecheck, lint, format, then every playtest
54
54
  pnpm build --target desktop # also: web, android, ios
55
55
  pnpm studio # open the game in Studio
56
56
  npx threenative doctor # build, import, device or blank-frame failure
57
+ npx threenative doctor --fix # refresh agent files
57
58
  ```
58
59
  <!-- /shared -->
59
60
 
@@ -63,6 +64,7 @@ npx threenative doctor # build, import, device or blank-frame failure
63
64
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
64
65
 
65
66
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
67
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
66
68
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
67
69
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
68
70
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -80,11 +82,14 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
80
82
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
81
83
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
82
84
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
85
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
83
86
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
84
87
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
88
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
85
89
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
86
90
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
87
91
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
92
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
88
93
  <!-- /shared -->
89
94
 
90
95
  <!-- shared: kit-stuck -->
@@ -13,7 +13,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
13
13
 
14
14
  1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
15
15
  2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
16
- 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
17
  4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
18
18
  5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
19
19
  6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
@@ -32,7 +32,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
32
32
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
33
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
34
  - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
35
- - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
36
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
37
  <!-- /shared -->
38
38
 
@@ -56,6 +56,7 @@ pnpm test # typecheck, lint, format, then every playtest
56
56
  pnpm build --target desktop # also: web, android, ios
57
57
  pnpm studio # open the game in Studio
58
58
  npx threenative doctor # build, import, device or blank-frame failure
59
+ npx threenative doctor --fix # refresh agent files
59
60
  ```
60
61
  <!-- /shared -->
61
62
 
@@ -65,6 +66,7 @@ npx threenative doctor # build, import, device or blank-frame failure
65
66
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
66
67
 
67
68
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
69
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
68
70
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
69
71
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
70
72
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -82,11 +84,14 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
82
84
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
83
85
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
84
86
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
87
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
85
88
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
86
89
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
90
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
87
91
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
88
92
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
89
93
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
94
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
90
95
  <!-- /shared -->
91
96
 
92
97
  <!-- shared: kit-stuck -->
@@ -19,8 +19,8 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.12",
23
- "@threenative/ui": "0.3.12",
22
+ "@threenative/core": "0.3.13",
23
+ "@threenative/ui": "0.3.13",
24
24
  "react": "19.2.0",
25
25
  "react-dom": "19.2.0",
26
26
  "three": "0.187.0"
@@ -29,11 +29,11 @@
29
29
  "@tailwindcss/vite": "4.3.3",
30
30
  "@vitejs/plugin-react": "6.0.5",
31
31
  "@types/three": "0.187.0",
32
- "@threenative/assets": "0.3.13",
33
- "@threenative/playtest": "0.3.12",
32
+ "@threenative/assets": "0.3.14",
33
+ "@threenative/playtest": "0.3.13",
34
34
  "@types/react": "19.2.0",
35
35
  "@types/react-dom": "19.2.0",
36
- "create-threenative": "0.2.17",
36
+ "create-threenative": "0.2.18",
37
37
  "esbuild": "0.27.0",
38
38
  "playwright": "1.62.1",
39
39
  "tailwindcss": "4.3.3",
@@ -44,7 +44,7 @@
44
44
  "eslint": "10.13.0"
45
45
  },
46
46
  "optionalDependencies": {
47
- "@threenative/runtime-native": "0.3.12"
47
+ "@threenative/runtime-native": "0.3.13"
48
48
  },
49
49
  "overrides": {
50
50
  "sharp": ">=0.35.4",
@@ -21,7 +21,7 @@ const game = defineGame<GameState>({
21
21
  },
22
22
  plugins: [playtest({ events })],
23
23
  display: config.display,
24
- render: config.renderer,
24
+ renderer: config.renderer,
25
25
  scenes: { race: Race },
26
26
  seed: 734,
27
27
  start: "race",
@@ -4,6 +4,7 @@ import { createRoot } from "react-dom/client";
4
4
  import game from "./game.js";
5
5
  import { App } from "./ui/App.js";
6
6
  import "./style.css";
7
+
7
8
  import.meta.hot?.accept();
8
9
  acceptHotUpdate(game, import.meta.hot);
9
10
  const root = document.getElementById("root");
@@ -2,6 +2,10 @@
2
2
 
3
3
  @source "../index.html";
4
4
  @source "./";
5
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
6
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
7
+ profile failure. Tailwind scans what it is told to scan. */
8
+ @source not "./render";
5
9
 
6
10
  @theme {
7
11
  --color-ink: #1d3a5c;
@@ -13,5 +13,5 @@
13
13
  "verbatimModuleSyntax": true,
14
14
  "isolatedModules": true
15
15
  },
16
- "include": ["src/**/*.ts", "src/**/*.tsx", "*.ts"]
16
+ "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "*.ts"]
17
17
  }
@@ -2,6 +2,7 @@ import tailwindcss from "@tailwindcss/vite";
2
2
  import { watchAssets } from "@threenative/assets";
3
3
  import react from "@vitejs/plugin-react";
4
4
  import {
5
+ createEngineCatalogPlugin,
5
6
  createEngineFreshnessPlugin,
6
7
  createWebBrandPlugin,
7
8
  webRuntimeDecoders,
@@ -36,6 +37,7 @@ export default defineConfig({
36
37
  plugins: [
37
38
  createEngineFreshnessPlugin(),
38
39
  createWebBrandPlugin(),
40
+ createEngineCatalogPlugin(),
39
41
  react(),
40
42
  tailwindcss(),
41
43
  assetsWatchPlugin(),
@@ -11,7 +11,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
11
11
 
12
12
  1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
13
13
  2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
14
- 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
14
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
15
15
  4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
16
16
  5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
17
17
  6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
@@ -30,7 +30,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
30
30
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
31
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
32
  - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
33
- - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
33
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
34
34
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
35
  <!-- /shared -->
36
36
 
@@ -38,7 +38,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
38
38
 
39
39
  <!-- shared: kit-files -->
40
40
  Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`.
41
- 6 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
41
+ 7 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
42
  Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
43
43
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-minimal.md`.
44
44
  <!-- /shared -->
@@ -55,6 +55,7 @@ pnpm test # typecheck, lint, format, then every playtest
55
55
  pnpm build --target desktop # also: web, android, ios
56
56
  pnpm studio # open the game in Studio
57
57
  npx threenative doctor # build, import, device or blank-frame failure
58
+ npx threenative doctor --fix # refresh agent files
58
59
  ```
59
60
  <!-- /shared -->
60
61
 
@@ -64,6 +65,7 @@ npx threenative doctor # build, import, device or blank-frame failure
64
65
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
65
66
 
66
67
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
68
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
67
69
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
68
70
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
69
71
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -90,12 +92,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
90
92
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
91
93
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
92
94
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
95
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
93
96
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
94
97
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
98
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
95
99
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
96
100
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
97
101
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
98
102
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
103
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
99
104
  <!-- /shared -->
100
105
 
101
106
  <!-- shared: kit-stuck -->
@@ -13,7 +13,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
13
13
 
14
14
  1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
15
15
  2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
16
- 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
17
  4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
18
18
  5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
19
19
  6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
@@ -32,7 +32,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
32
32
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
33
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
34
  - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
35
- - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
36
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
37
  <!-- /shared -->
38
38
 
@@ -40,7 +40,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
40
40
 
41
41
  <!-- shared: kit-files -->
42
42
  Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`.
43
- 6 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
43
+ 7 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
44
44
  Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
45
45
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-minimal.md`.
46
46
  <!-- /shared -->
@@ -57,6 +57,7 @@ pnpm test # typecheck, lint, format, then every playtest
57
57
  pnpm build --target desktop # also: web, android, ios
58
58
  pnpm studio # open the game in Studio
59
59
  npx threenative doctor # build, import, device or blank-frame failure
60
+ npx threenative doctor --fix # refresh agent files
60
61
  ```
61
62
  <!-- /shared -->
62
63
 
@@ -66,6 +67,7 @@ npx threenative doctor # build, import, device or blank-frame failure
66
67
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
67
68
 
68
69
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
70
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
69
71
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
70
72
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
71
73
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -92,12 +94,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
92
94
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
93
95
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
94
96
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
97
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
95
98
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
96
99
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
100
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
97
101
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
98
102
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
99
103
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
100
104
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
105
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
101
106
  <!-- /shared -->
102
107
 
103
108
  <!-- shared: kit-stuck -->