create-threenative 0.2.14 → 0.2.17

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 (251) hide show
  1. package/agent-docs/kit-mcp.md +10 -0
  2. package/agent-docs/kit-router.md +14 -0
  3. package/agent-docs/kit-stuck.md +7 -0
  4. package/agent-docs/references/capability-reference.md +958 -30
  5. package/agent-docs/references/conventions.md +271 -0
  6. package/agent-docs/references/kit-action-rpg.md +40 -0
  7. package/agent-docs/references/kit-adventure.md +40 -0
  8. package/agent-docs/references/kit-collectathon.md +38 -0
  9. package/agent-docs/references/kit-kart.md +31 -0
  10. package/agent-docs/references/kit-minimal.md +29 -0
  11. package/agent-docs/references/kit-platformer.md +34 -0
  12. package/agent-docs/references/kit-puzzle.md +22 -0
  13. package/agent-docs/references/kit-racing.md +26 -0
  14. package/agent-docs/references/kit-rain.md +31 -0
  15. package/agent-docs/references/kit-rts.md +34 -0
  16. package/agent-docs/references/kit-runner.md +32 -0
  17. package/agent-docs/references/kit-sailing.md +41 -0
  18. package/agent-docs/references/kit-shooter.md +33 -0
  19. package/agent-docs/references/kit-snow.md +33 -0
  20. package/agent-docs/references/kit-starter.md +55 -0
  21. package/agent-docs/references/kit-tower-defense.md +27 -0
  22. package/agent-docs/references/terrain-authoring.md +2 -1
  23. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  24. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  25. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
  26. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  27. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  28. package/agent-files/.claude/settings.json +25 -0
  29. package/agent-files/.codex/hooks.json +18 -1
  30. package/dist/index.js +256 -120
  31. package/dist/terrain-kit.d.ts +7 -0
  32. package/dist/terrain-kit.js +82 -0
  33. package/dist/threenative.js +23 -4
  34. package/dist/web-engine-gltf-loader.js +20 -7
  35. package/dist/web-engine-post-effects.js +34 -4
  36. package/dist/web-engine-runtime.js +6119 -3311
  37. package/package.json +13 -8
  38. package/template-assets/patches/three@0.187.0.patch +2004 -407
  39. package/templates/action-rpg/AGENTS.md +99 -84
  40. package/templates/action-rpg/CLAUDE.md +99 -84
  41. package/templates/action-rpg/kit.json +1 -0
  42. package/templates/action-rpg/package.json +7 -7
  43. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  44. package/templates/action-rpg/src/game.ts +1 -0
  45. package/templates/action-rpg/src/render/atmosphere.ts +5 -16
  46. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  47. package/templates/action-rpg/src/render/quality.ts +3 -1
  48. package/templates/action-rpg/src/scenes/Play.ts +26 -0
  49. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  50. package/templates/action-rpg/threenative.config.ts +0 -3
  51. package/templates/adventure/AGENTS.md +87 -44
  52. package/templates/adventure/CLAUDE.md +87 -44
  53. package/templates/adventure/package.json +7 -7
  54. package/templates/collectathon/AGENTS.md +88 -42
  55. package/templates/collectathon/CLAUDE.md +88 -42
  56. package/templates/collectathon/package.json +7 -7
  57. package/templates/kart/AGENTS.md +82 -42
  58. package/templates/kart/CLAUDE.md +82 -42
  59. package/templates/kart/package.json +6 -6
  60. package/templates/minimal/AGENTS.md +100 -84
  61. package/templates/minimal/CLAUDE.md +100 -84
  62. package/templates/minimal/package.json +6 -6
  63. package/templates/minimal/src/render/atmosphere.ts +5 -16
  64. package/templates/minimal/src/render/gpuSky.ts +4 -7
  65. package/templates/platformer/AGENTS.md +90 -46
  66. package/templates/platformer/CLAUDE.md +90 -46
  67. package/templates/platformer/package.json +7 -7
  68. package/templates/puzzle/AGENTS.md +92 -80
  69. package/templates/puzzle/CLAUDE.md +92 -80
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/racing/AGENTS.md +95 -82
  72. package/templates/racing/CLAUDE.md +95 -82
  73. package/templates/racing/package.json +7 -7
  74. package/templates/racing/src/render/atmosphere.ts +5 -16
  75. package/templates/racing/src/render/gpuSky.ts +4 -7
  76. package/templates/rain/AGENTS.md +92 -84
  77. package/templates/rain/CLAUDE.md +92 -84
  78. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  79. package/templates/rain/package.json +6 -6
  80. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  81. package/templates/rain/src/scenes/Boot.ts +1 -0
  82. package/templates/rain/src/state.ts +7 -0
  83. package/templates/rain/src/ui/GameUi.tsx +7 -1
  84. package/templates/rts/AGENTS.md +96 -85
  85. package/templates/rts/CLAUDE.md +96 -85
  86. package/templates/rts/package.json +6 -6
  87. package/templates/runner/AGENTS.md +92 -80
  88. package/templates/runner/CLAUDE.md +92 -80
  89. package/templates/runner/package.json +7 -7
  90. package/templates/runner/playtests/performance.playtest.json +1 -1
  91. package/templates/runner/src/render/atmosphere.ts +5 -16
  92. package/templates/runner/src/render/gpuSky.ts +4 -7
  93. package/templates/runner/src/render/lighting.ts +53 -11
  94. package/templates/runner/src/scenes/Run.ts +4 -3
  95. package/templates/runner/threenative.config.ts +0 -3
  96. package/templates/sailing/AGENTS.md +91 -79
  97. package/templates/sailing/CLAUDE.md +91 -79
  98. package/templates/sailing/package.json +7 -7
  99. package/templates/sailing/playtests/sails.playtest.json +1 -0
  100. package/templates/sailing/src/render/sky.ts +4 -0
  101. package/templates/sailing/threenative.config.ts +0 -3
  102. package/templates/shooter/AGENTS.md +93 -68
  103. package/templates/shooter/CLAUDE.md +93 -68
  104. package/templates/shooter/package.json +7 -7
  105. package/templates/shooter/src/render/atmosphere.ts +5 -16
  106. package/templates/shooter/src/render/gpuSky.ts +4 -7
  107. package/templates/shooter/src/render/quality.ts +3 -1
  108. package/templates/snow/AGENTS.md +90 -76
  109. package/templates/snow/CLAUDE.md +90 -76
  110. package/templates/snow/package.json +7 -7
  111. package/templates/snow/threenative.config.ts +0 -3
  112. package/templates/starter/AGENTS.md +104 -88
  113. package/templates/starter/CLAUDE.md +104 -88
  114. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  115. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  116. package/templates/starter/package.json +7 -7
  117. package/templates/starter/src/entities/Player.ts +10 -22
  118. package/templates/starter/src/render/atmosphere.ts +5 -16
  119. package/templates/starter/src/render/gpuSky.ts +4 -7
  120. package/templates/starter/src/render/lighting.ts +54 -4
  121. package/templates/starter/src/render/temporalAA.ts +8 -7
  122. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  123. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  124. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  125. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  126. package/templates/starter/src/render/temporalMoire.ts +190 -0
  127. package/templates/starter/src/render/temporalResolve.ts +75 -16
  128. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  129. package/templates/starter/src/scenes/Play.ts +41 -29
  130. package/templates/tower-defense/AGENTS.md +92 -81
  131. package/templates/tower-defense/CLAUDE.md +92 -81
  132. package/templates/tower-defense/package.json +7 -7
  133. package/capabilities.json +0 -9197
  134. package/templates/AGENTS.md +0 -21
  135. package/templates/CLAUDE.md +0 -23
  136. package/templates/action-rpg/.codex/config.toml +0 -23
  137. package/templates/action-rpg/.cursor/mcp.json +0 -38
  138. package/templates/action-rpg/.gemini/settings.json +0 -38
  139. package/templates/action-rpg/.mcp.json +0 -38
  140. package/templates/action-rpg/.vscode/mcp.json +0 -43
  141. package/templates/action-rpg/.zed/settings.json +0 -43
  142. package/templates/action-rpg/opencode.json +0 -49
  143. package/templates/adventure/.codex/config.toml +0 -23
  144. package/templates/adventure/.cursor/mcp.json +0 -38
  145. package/templates/adventure/.gemini/settings.json +0 -38
  146. package/templates/adventure/.mcp.json +0 -38
  147. package/templates/adventure/.vscode/mcp.json +0 -43
  148. package/templates/adventure/.zed/settings.json +0 -43
  149. package/templates/adventure/opencode.json +0 -49
  150. package/templates/collectathon/.codex/config.toml +0 -23
  151. package/templates/collectathon/.cursor/mcp.json +0 -38
  152. package/templates/collectathon/.gemini/settings.json +0 -38
  153. package/templates/collectathon/.mcp.json +0 -38
  154. package/templates/collectathon/.vscode/mcp.json +0 -43
  155. package/templates/collectathon/.zed/settings.json +0 -43
  156. package/templates/collectathon/opencode.json +0 -49
  157. package/templates/kart/.codex/config.toml +0 -23
  158. package/templates/kart/.cursor/mcp.json +0 -38
  159. package/templates/kart/.gemini/settings.json +0 -38
  160. package/templates/kart/.mcp.json +0 -38
  161. package/templates/kart/.vscode/mcp.json +0 -43
  162. package/templates/kart/.zed/settings.json +0 -43
  163. package/templates/kart/opencode.json +0 -49
  164. package/templates/minimal/.codex/config.toml +0 -23
  165. package/templates/minimal/.cursor/mcp.json +0 -38
  166. package/templates/minimal/.gemini/settings.json +0 -38
  167. package/templates/minimal/.mcp.json +0 -38
  168. package/templates/minimal/.vscode/mcp.json +0 -43
  169. package/templates/minimal/.zed/settings.json +0 -43
  170. package/templates/minimal/opencode.json +0 -49
  171. package/templates/platformer/.codex/config.toml +0 -23
  172. package/templates/platformer/.cursor/mcp.json +0 -38
  173. package/templates/platformer/.gemini/settings.json +0 -38
  174. package/templates/platformer/.mcp.json +0 -38
  175. package/templates/platformer/.vscode/mcp.json +0 -43
  176. package/templates/platformer/.zed/settings.json +0 -43
  177. package/templates/platformer/opencode.json +0 -49
  178. package/templates/puzzle/.codex/config.toml +0 -23
  179. package/templates/puzzle/.cursor/mcp.json +0 -38
  180. package/templates/puzzle/.gemini/settings.json +0 -38
  181. package/templates/puzzle/.mcp.json +0 -38
  182. package/templates/puzzle/.vscode/mcp.json +0 -43
  183. package/templates/puzzle/.zed/settings.json +0 -43
  184. package/templates/puzzle/opencode.json +0 -49
  185. package/templates/racing/.codex/config.toml +0 -23
  186. package/templates/racing/.cursor/mcp.json +0 -38
  187. package/templates/racing/.gemini/settings.json +0 -38
  188. package/templates/racing/.mcp.json +0 -38
  189. package/templates/racing/.vscode/mcp.json +0 -43
  190. package/templates/racing/.zed/settings.json +0 -43
  191. package/templates/racing/opencode.json +0 -49
  192. package/templates/rain/.codex/config.toml +0 -23
  193. package/templates/rain/.cursor/mcp.json +0 -38
  194. package/templates/rain/.gemini/settings.json +0 -38
  195. package/templates/rain/.mcp.json +0 -38
  196. package/templates/rain/.vscode/mcp.json +0 -43
  197. package/templates/rain/.zed/settings.json +0 -43
  198. package/templates/rain/opencode.json +0 -49
  199. package/templates/rts/.codex/config.toml +0 -23
  200. package/templates/rts/.cursor/mcp.json +0 -38
  201. package/templates/rts/.gemini/settings.json +0 -38
  202. package/templates/rts/.mcp.json +0 -38
  203. package/templates/rts/.vscode/mcp.json +0 -43
  204. package/templates/rts/.zed/settings.json +0 -43
  205. package/templates/rts/opencode.json +0 -49
  206. package/templates/runner/.codex/config.toml +0 -23
  207. package/templates/runner/.cursor/mcp.json +0 -38
  208. package/templates/runner/.gemini/settings.json +0 -38
  209. package/templates/runner/.mcp.json +0 -38
  210. package/templates/runner/.vscode/mcp.json +0 -43
  211. package/templates/runner/.zed/settings.json +0 -43
  212. package/templates/runner/README.md +0 -43
  213. package/templates/runner/opencode.json +0 -49
  214. package/templates/sailing/.codex/config.toml +0 -23
  215. package/templates/sailing/.cursor/mcp.json +0 -38
  216. package/templates/sailing/.gemini/settings.json +0 -38
  217. package/templates/sailing/.mcp.json +0 -38
  218. package/templates/sailing/.vscode/mcp.json +0 -43
  219. package/templates/sailing/.zed/settings.json +0 -43
  220. package/templates/sailing/README.md +0 -28
  221. package/templates/sailing/opencode.json +0 -49
  222. package/templates/shooter/.codex/config.toml +0 -23
  223. package/templates/shooter/.cursor/mcp.json +0 -38
  224. package/templates/shooter/.gemini/settings.json +0 -38
  225. package/templates/shooter/.mcp.json +0 -38
  226. package/templates/shooter/.vscode/mcp.json +0 -43
  227. package/templates/shooter/.zed/settings.json +0 -43
  228. package/templates/shooter/opencode.json +0 -49
  229. package/templates/snow/.codex/config.toml +0 -23
  230. package/templates/snow/.cursor/mcp.json +0 -38
  231. package/templates/snow/.gemini/settings.json +0 -38
  232. package/templates/snow/.mcp.json +0 -38
  233. package/templates/snow/.vscode/mcp.json +0 -43
  234. package/templates/snow/.zed/settings.json +0 -43
  235. package/templates/snow/README.md +0 -26
  236. package/templates/snow/opencode.json +0 -49
  237. package/templates/starter/.codex/config.toml +0 -23
  238. package/templates/starter/.cursor/mcp.json +0 -38
  239. package/templates/starter/.gemini/settings.json +0 -38
  240. package/templates/starter/.mcp.json +0 -38
  241. package/templates/starter/.vscode/mcp.json +0 -43
  242. package/templates/starter/.zed/settings.json +0 -43
  243. package/templates/starter/opencode.json +0 -49
  244. package/templates/tower-defense/.codex/config.toml +0 -23
  245. package/templates/tower-defense/.cursor/mcp.json +0 -38
  246. package/templates/tower-defense/.gemini/settings.json +0 -38
  247. package/templates/tower-defense/.mcp.json +0 -38
  248. package/templates/tower-defense/.vscode/mcp.json +0 -43
  249. package/templates/tower-defense/.zed/settings.json +0 -43
  250. package/templates/tower-defense/README.md +0 -16
  251. package/templates/tower-defense/opencode.json +0 -49
@@ -5,7 +5,11 @@
5
5
  // sun misses — so there is no hemisphere or ambient light stacked on top to flatten the frame.
6
6
  // The rig is returned because `WorldEnvironment`'s godrays stage raymarches against a shadow map,
7
7
  // so `setupPost` needs the key light itself; a shadowless one is refused by name.
8
- import { Color, DirectionalLight, PCFSoftShadowMap, type Scene, Vector3 } from "three";
8
+ //
9
+ // The sun's shadow box travels with the runner. The track is endless, so a box left at the start
10
+ // line covers the first stretch and nothing after it: past it the runner, the obstacles and the
11
+ // rails cast no shadow at all. `follow` aims the box at the ground the chase camera sees.
12
+ import { Color, DirectionalLight, Matrix4, PCFSoftShadowMap, type Scene, Vector3 } from "three";
9
13
  import {
10
14
  SUN_ILLUMINANCE,
11
15
  SUN_KELVIN,
@@ -30,13 +34,26 @@ function atmosphereSun(): DirectionalLight {
30
34
  return key;
31
35
  }
32
36
 
37
+ /** How far up its own ray the sun sits. The shadow camera's depth range starts at that distance. */
38
+ const SUN_DISTANCE = 30;
39
+ /** How far ahead of the runner the shadow box is centred: the ground the chase camera sees. */
40
+ const LEAD = 12;
41
+ const UP = new Vector3(0, 1, 0);
42
+ const ORIGIN = new Vector3();
43
+
33
44
  type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
34
45
 
35
- export function setupLighting(
36
- scene: Scene,
37
- renderer: ShadowRenderer,
38
- mobile = false,
39
- ): { key: DirectionalLight; fill: DirectionalLight } {
46
+ export interface ILighting {
47
+ readonly key: DirectionalLight;
48
+ readonly fill: DirectionalLight;
49
+ /**
50
+ * Put the sun's shadow box on the runner, so the ground in frame keeps its shadows all run long.
51
+ * The track runs down -Z, so the box leads the runner there. Call it once per rendered frame.
52
+ */
53
+ follow(target: Vector3): void;
54
+ }
55
+
56
+ export function setupLighting(scene: Scene, renderer: ShadowRenderer, mobile = false): ILighting {
40
57
  renderer.shadowMap.enabled = true;
41
58
  renderer.shadowMap.type = PCFSoftShadowMap;
42
59
 
@@ -44,16 +61,17 @@ export function setupLighting(
44
61
  // down-track so it rakes across the obstacles and throws each one's shadow back toward the
45
62
  // The photo sky keeps the warm white matched by eye to its photographed midday sun.
46
63
  const key = SKY_OPTIONS.sky === "photo" ? new DirectionalLight(0xfff1e0, 4.5) : atmosphereSun();
47
- key.position.copy(SUN_DIRECTION).multiplyScalar(30);
64
+ const offset = SUN_DIRECTION.clone().multiplyScalar(SUN_DISTANCE);
65
+ key.position.copy(offset);
48
66
  key.castShadow = true;
49
- // One map fitted to what the chase camera can see from the runner: 4096² is well under a
50
- // centimetre a texel, so every shadow has the same softness. Phones take 2048².
67
+ // One map fitted to what the chase camera can see from the runner: 4096² is about a centimetre a
68
+ // texel, so every shadow has the same softness. Phones take 2048².
51
69
  const size = mobile ? 2048 : 4096;
52
70
  key.shadow.mapSize.set(size, size);
53
71
  key.shadow.radius = 2;
54
72
  key.shadow.camera.near = 1;
55
73
  key.shadow.camera.far = 140;
56
- const extent = 28;
74
+ const extent = mobile ? 16 : 24;
57
75
  key.shadow.camera.left = -extent;
58
76
  key.shadow.camera.right = extent;
59
77
  key.shadow.camera.top = extent;
@@ -62,6 +80,9 @@ export function setupLighting(
62
80
  key.shadow.bias = -0.0002;
63
81
  key.shadow.normalBias = 0.005;
64
82
  scene.add(key);
83
+ // three reads the target's world matrix, which only a scene traversal refreshes: a target left
84
+ // out of the graph stays at the origin however its position reads.
85
+ scene.add(key.target);
65
86
 
66
87
  // The sky alone leaves every down-track face in its own shade, so the runner reads as a dark
67
88
  // silhouette against the obstacle it is about to hit — the one comparison the game asks the
@@ -71,7 +92,28 @@ export function setupLighting(
71
92
  fill.position.set(0, 8, 20);
72
93
  scene.add(fill);
73
94
 
74
- return { key, fill };
95
+ // A shadow map is a grid in the light's own frame. Slide the box by a fraction of a texel and every
96
+ // sample lands between texels, so the whole map crawls with the runner. Both ends snap to whole
97
+ // texels of that grid instead, which leaves every texel on one fixed cell of the world however the
98
+ // runner moves. The sun never turns, so the frame is built once.
99
+ const texel = (2 * extent) / size;
100
+ const intoLight = new Matrix4().lookAt(offset, ORIGIN, UP).invert();
101
+ const outOfLight = intoLight.clone().invert();
102
+ const centre = new Vector3();
103
+
104
+ return {
105
+ key,
106
+ fill,
107
+ follow(target: Vector3): void {
108
+ centre.set(target.x, 0, target.z - LEAD).applyMatrix4(intoLight);
109
+ centre.x = Math.round(centre.x / texel) * texel;
110
+ centre.y = Math.round(centre.y / texel) * texel;
111
+ centre.applyMatrix4(outOfLight);
112
+ key.target.position.copy(centre);
113
+ key.target.updateMatrixWorld();
114
+ key.position.copy(centre).add(offset);
115
+ },
116
+ };
75
117
  }
76
118
 
77
119
  /** Material conventions are game-owned; each scene gets independent mutable controls. */
@@ -69,7 +69,7 @@ export class Run extends Scene<GameState, RunnerPhysics> {
69
69
  if (this.#model === undefined)
70
70
  throw new Error("Run.enter ran before load() loaded mannequin.glb.");
71
71
  setupSky(ctx.scene, this.#sky, ctx.renderer.softwareAdapter !== undefined);
72
- const { key } = setupLighting(
72
+ const lighting = setupLighting(
73
73
  ctx.scene,
74
74
  ctx.renderer.raw as Parameters<typeof setupLighting>[1],
75
75
  isMobile(),
@@ -89,7 +89,7 @@ export class Run extends Scene<GameState, RunnerPhysics> {
89
89
  materialTier = tier;
90
90
  this.#materialLighting?.setEnabled(materialLightingEnabled(tier, materialEnvironment));
91
91
  },
92
- godraysLight: key,
92
+ godraysLight: lighting.key,
93
93
  mobile: isMobile(),
94
94
  software: ctx.renderer.softwareAdapter !== undefined,
95
95
  gpuClass: ctx.renderer.gpuClass?.class,
@@ -139,13 +139,14 @@ export class Run extends Scene<GameState, RunnerPhysics> {
139
139
  afterPhysics(ctx, (dt) => {
140
140
  const offset = shake.update(dt);
141
141
  chaseRunner(camera, runner.mesh.position, dt, offset.position);
142
+ lighting.follow(runner.mesh.position);
142
143
  dust.position.set(runner.mesh.position.x, 0.15, runner.mesh.position.z + 0.6);
143
144
  });
144
145
 
145
146
  // Collect only after the loaded character and scene receivers are attached.
146
147
  this.#materialLighting = ctx.entities.add(
147
148
  "material-lighting",
148
- createMaterialLighting(ctx.scene, ctx.camera, key, {
149
+ createMaterialLighting(ctx.scene, ctx.camera, lighting.key, {
149
150
  ...materialEnvironment,
150
151
  enabled: materialLightingEnabled(materialTier, materialEnvironment),
151
152
  overrides: { fillGain: 0 },
@@ -1,9 +1,6 @@
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",
7
4
  app: {
8
5
  id: "com.threenative.__PROJECT_ID__",
9
6
  name: "__PROJECT_NAME__",
@@ -1,95 +1,107 @@
1
- # AGENTS.md — __PROJECT_NAME__ sailing
1
+ <!-- shared: kit-identity -->
2
+ # AGENTS.md — __PROJECT_NAME__ (Sailing, the sailing kit)
2
3
 
3
- Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
4
+ A wind-and-wave sailing starter with buoyancy, ordered course buoys, and a ship you can reshape. Routing words: sailing. `CLAUDE.md` is a copy of this file.
5
+ <!-- /shared -->
4
6
 
5
- ## Ownership
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, 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).
7
+ <!-- shared: kit-router -->
8
+ ## Authoring flow
7
9
 
8
- ## Start every change
10
+ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
9
11
 
10
- 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
11
- 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints,
12
- direct the user to review it, and wait for explicit approval plus an instruction to implement it.
13
- 3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
14
- this kit uses its analytic wave field and measured hull points instead.
15
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
16
- `npx @threenative/playtest doctor`; missing observations are not zero.
17
- For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
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
+ 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/`.
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
+ 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
+ 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.
18
+ 7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
19
+ 8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
18
20
 
19
- ## When the framework blocks you, write plain Three.js
20
-
21
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
22
- piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
23
- bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
24
- (API, expectation, result, replacement); never stall the game.
25
-
26
- ## Workflow skills
27
-
28
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
29
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
30
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
31
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
32
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
33
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
34
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
35
- - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
36
- - 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.
37
-
38
- ## Commands and map
39
-
40
- ```sh
41
- pnpm dev
42
- pnpm build
43
- pnpm build --target desktop
44
- pnpm test:native
45
- 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"
46
- ```
21
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
22
+ <!-- /shared -->
47
23
 
48
- 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.
24
+ <!-- shared: kit-mcp -->
25
+ ## MCP servers
49
26
 
50
- 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.
27
+ `.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
51
28
 
52
- 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.
29
+ - `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
30
+ - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
+ - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
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`.
34
+ - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
+ <!-- /shared -->
53
36
 
54
- 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.
37
+ ## This kit
55
38
 
56
- 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.
39
+ <!-- shared: kit-files -->
40
+ Source in `src/`: `conventions.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
41
+ 8 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
+ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
43
+ Kit notes: `node_modules/create-threenative/agent-docs/references/kit-sailing.md`.
44
+ <!-- /shared -->
57
45
 
58
- 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.
46
+ Four course marks around the headland, a helm and sheets, 120 seconds of wind. The hull is `assets/ship.glb` (Poly Haven `dutch_ship_medium`, CC0), loaded in `Boot.load()`.
47
+ The sea is `SpectralOcean`; `src/render/ocean.ts` owns its look. `Buoyancy3D` floats the ship on the drawn surface.
59
48
 
60
- 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.
49
+ <!-- shared: kit-commands -->
50
+ ## Commands
61
51
 
62
- ## Portable authoring contracts
63
-
64
- Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
65
-
66
- Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
67
- Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Generated conventions call `normaliseToMetres` for authored ship scale; buoyancy owns water contact.
68
- `input.vector("move").y` is +up and means forward wind; use one explicit `-move.y` conversion.
69
- Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game
70
- state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
71
- is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
72
- state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
73
-
74
- 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. `high` draws 4x MSAA and `medium` and `low` SMAA; `temporalAA: true` is the named opt-in. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js.
75
-
76
- 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
77
- own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
78
- caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
79
- (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
80
- `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
81
- clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
82
- 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.
83
- `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
84
- ## Budget real time for the look
85
- Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
52
+ ```sh
53
+ pnpm dev # play in the browser
54
+ pnpm test # typecheck, lint, format, then every playtest
55
+ pnpm build --target desktop # also: web, android, ios
56
+ pnpm test:native # native proof
57
+ npx threenative doctor # build, import, device or blank-frame failure
58
+ ```
59
+ <!-- /shared -->
60
+
61
+ <!-- shared: kit-conventions -->
62
+ ## Conventions
63
+
64
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
65
+
66
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
67
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
68
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
69
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
70
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
71
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
72
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
73
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
74
+ - **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
75
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
76
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
77
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
78
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
79
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
80
+ - **One metre is one metre** `#scale`: `normaliseToMetres`. Override: per-call options.
81
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
82
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
83
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
84
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
85
+ - **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
86
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
87
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
88
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
89
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
90
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
91
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
92
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
93
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
94
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
95
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
96
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
97
+ <!-- /shared -->
98
+
99
+ <!-- shared: kit-stuck -->
100
+ ## When the framework blocks you, write plain Three.js
86
101
 
87
- 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.
102
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
88
103
 
89
- 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`.
90
- ## Optional multiplayer transport
91
- 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`.
92
- 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.
93
- `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. 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.
104
+ ## Stuck
94
105
 
95
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. The filmic curve and metered auto exposure are on by default here. `quality.ts` names one cost override, reported as `TN_RENDER_CHAIN_COST_OVERRIDE`: no final gather, SSGI or SSR (the frame is the water, and screen-space reflections over moving water read as smear) and no motion blur (it smeared the chase-camera ship and its sails). Set `tonemapMode: "aces"` or `autoExposureEnabled: false` with a fixed `exposure` on the same preset to override the curve or the meter.
106
+ `npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
107
+ <!-- /shared -->