create-threenative 0.2.4 → 0.2.6

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 (58) hide show
  1. package/README.md +23 -1
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/capability-reference.md +972 -66
  4. package/agent-docs/references/finding-assets.md +8 -1
  5. package/agent-docs/references/performance-basics.md +114 -0
  6. package/agent-docs/references/rigging-characters.md +51 -0
  7. package/agent-docs/references/webview-ui.md +3 -2
  8. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
  10. package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
  11. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  12. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  13. package/agent-files/.claude/settings.json +38 -0
  14. package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
  15. package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
  16. package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
  17. package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.codex/hooks.json +40 -0
  19. package/capabilities.json +1344 -88
  20. package/dist/index.d.ts +10 -1
  21. package/dist/index.js +186 -1
  22. package/dist/threenative.js +660 -150
  23. package/package.json +6 -6
  24. package/template-assets/patches/three@0.185.1.patch +179 -19
  25. package/templates/action-rpg/AGENTS.md +5 -5
  26. package/templates/action-rpg/CLAUDE.md +5 -5
  27. package/templates/action-rpg/package.json +8 -8
  28. package/templates/defense/AGENTS.md +5 -5
  29. package/templates/defense/CLAUDE.md +5 -5
  30. package/templates/defense/package.json +8 -8
  31. package/templates/minimal/AGENTS.md +5 -5
  32. package/templates/minimal/CLAUDE.md +5 -5
  33. package/templates/minimal/package.json +7 -7
  34. package/templates/minimal/threenative.config.ts +1 -0
  35. package/templates/platformer/AGENTS.md +5 -5
  36. package/templates/platformer/CLAUDE.md +5 -5
  37. package/templates/platformer/package.json +9 -9
  38. package/templates/puzzle/AGENTS.md +5 -5
  39. package/templates/puzzle/CLAUDE.md +5 -5
  40. package/templates/puzzle/package.json +8 -8
  41. package/templates/racing/AGENTS.md +5 -5
  42. package/templates/racing/CLAUDE.md +5 -5
  43. package/templates/racing/package.json +8 -8
  44. package/templates/runner/AGENTS.md +5 -5
  45. package/templates/runner/CLAUDE.md +5 -5
  46. package/templates/runner/package.json +8 -8
  47. package/templates/sailing/AGENTS.md +6 -6
  48. package/templates/sailing/CLAUDE.md +6 -6
  49. package/templates/sailing/package.json +8 -8
  50. package/templates/shooter/AGENTS.md +5 -5
  51. package/templates/shooter/CLAUDE.md +5 -5
  52. package/templates/shooter/package.json +8 -8
  53. package/templates/starter/AGENTS.md +8 -8
  54. package/templates/starter/CLAUDE.md +8 -8
  55. package/templates/starter/package.json +9 -9
  56. package/templates/starter/playtests/production-readiness.playtest.json +96 -0
  57. package/templates/starter/src/ui/Hud.tsx +2 -2
  58. package/templates/starter/src/ui/Menu.tsx +5 -1
@@ -7,13 +7,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
7
7
  ## Ownership
8
8
 
9
9
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the track, the runner, the obstacles, the dust, the HUD and the
10
- look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
10
+ look; `src/game.ts` is portable and React mounts only 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.
11
11
 
12
12
  ## Start every change
13
13
 
14
14
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
15
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
17
17
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
18
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
19
  3. Treat returned constraints as binding. No navmesh is imported, so this kit runs on every
@@ -40,7 +40,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
40
40
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
41
41
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
42
42
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
43
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
43
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
44
44
 
45
45
  ## Commands and map
46
46
 
@@ -91,8 +91,8 @@ supposed to be touching. Two loading conventions come from `@threenative/core`,
91
91
  Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
92
92
  tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
93
93
  `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
94
- reports the source. A scenario with no assertions or missing observations fails; open a real capture.
94
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture. 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 beside the frame rate; `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.
95
95
 
96
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
96
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
97
97
  ## Optional multiplayer transport
98
98
  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`.
@@ -11,13 +11,13 @@
11
11
  "build:android": "threenative build --target android",
12
12
  "build:ios": "threenative build --target ios",
13
13
  "pretest": "playwright install chromium",
14
- "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
14
+ "test": "pnpm build:web && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm exec vite preview --host 127.0.0.1 --port $PORT --strictPort\"",
15
15
  "typecheck": "tsc --noEmit -p tsconfig.json"
16
16
  },
17
17
  "dependencies": {
18
- "@threenative/core": "0.3.1",
19
- "@threenative/physics": "0.3.1",
20
- "@threenative/ui": "0.3.1",
18
+ "@threenative/core": "0.3.3",
19
+ "@threenative/physics": "0.3.3",
20
+ "@threenative/ui": "0.3.3",
21
21
  "react": "19.2.0",
22
22
  "react-dom": "19.2.0",
23
23
  "three": "0.185.1"
@@ -25,13 +25,13 @@
25
25
  "devDependencies": {
26
26
  "@gltf-transform/cli": "4.4.2",
27
27
  "@tailwindcss/vite": "4.3.3",
28
- "@threenative/assets": "0.3.1",
29
- "@threenative/playtest": "0.3.1",
28
+ "@threenative/assets": "0.3.3",
29
+ "@threenative/playtest": "0.3.3",
30
30
  "@types/react": "19.2.0",
31
31
  "@types/react-dom": "19.2.0",
32
32
  "@types/three": "0.185.3",
33
33
  "@vitejs/plugin-react": "6.0.5",
34
- "create-threenative": "0.2.4",
34
+ "create-threenative": "0.2.6",
35
35
  "esbuild": "0.27.0",
36
36
  "playwright": "1.62.1",
37
37
  "tailwindcss": "4.3.3",
@@ -39,7 +39,7 @@
39
39
  "vite": "8.2.0"
40
40
  },
41
41
  "optionalDependencies": {
42
- "@threenative/runtime-native": "0.3.1"
42
+ "@threenative/runtime-native": "0.3.3"
43
43
  },
44
44
  "pnpm": {
45
45
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -5,13 +5,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
5
5
  ## Ownership
6
6
 
7
7
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns ship handling, the sea's look and tuning, `Buoyancy3D`, course order, HUD,
8
- water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`.
8
+ water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way.
9
9
 
10
10
  ## Start every change
11
11
 
12
12
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
13
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
14
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
14
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
15
15
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
16
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
17
17
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -37,7 +37,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
37
37
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
38
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
39
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
41
41
 
42
42
  ## Commands and map
43
43
 
@@ -52,7 +52,7 @@ pnpm test:native
52
52
 
53
53
  The sea is `SpectralOcean`, added with `ctx.add` so the compute registry runs its passes. It draws nothing: `src/render/ocean.ts` owns the mesh, the material 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 — summed onto one small grid and read back, not sampled a second way — so the hull floats on the surface that is drawn. Two fields would leave the ship riding water nothing renders, with every assertion here still green.
54
54
 
55
- Three 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. 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.
55
+ Three 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. 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. `WaveField.sample(x, z, time)` returns height and analytic normal and allocates to do it; `heightAt(x, z, time)` returns the height alone from the same arithmetic, agreeing exactly, with no warp jacobian, no normalisation and no allocation — ask it for floats, splash and wake queries, 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 at the CFL stability limit for its resolution and celerity, whichever is smaller, so `new RippleField({ resolution, size })` needs no other option; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that on the same object, and a `step` above the limit is rejected with the limit in the message rather than quietly clamped. Its rim absorbs, so `recenter` it on whatever the player is watching; it carries no obstacle mask, because a mask is only right for a body that never moves.
56
56
 
57
57
  Tune the sea state in `src/render/ocean.ts`, hull points in `src/entities/Ship.ts`, and course
58
58
  order in `src/scenes/Sailing.ts`. The single React HUD reads published state; keep
@@ -88,8 +88,8 @@ supposed to be touching. Two loading conventions come from `@threenative/core`,
88
88
 
89
89
  Reference-driven authoring starts at `agent-docs/dream-loop.md`.
90
90
 
91
- Open a capture after visual changes. A scenario with no assertions or missing observations fails.
91
+ 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 beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
92
92
 
93
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
93
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
94
94
  ## Optional multiplayer transport
95
95
  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`.
@@ -7,13 +7,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
7
7
  ## Ownership
8
8
 
9
9
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns ship handling, the sea's look and tuning, `Buoyancy3D`, course order, HUD,
10
- water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`.
10
+ water, and look; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way.
11
11
 
12
12
  ## Start every change
13
13
 
14
14
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
15
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
17
17
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
18
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
19
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -39,7 +39,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
39
39
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
40
40
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
41
41
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
42
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
42
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
43
43
 
44
44
  ## Commands and map
45
45
 
@@ -54,7 +54,7 @@ pnpm test:native
54
54
 
55
55
  The sea is `SpectralOcean`, added with `ctx.add` so the compute registry runs its passes. It draws nothing: `src/render/ocean.ts` owns the mesh, the material 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 — summed onto one small grid and read back, not sampled a second way — so the hull floats on the surface that is drawn. Two fields would leave the ship riding water nothing renders, with every assertion here still green.
56
56
 
57
- Three 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. 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.
57
+ Three 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. 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. `WaveField.sample(x, z, time)` returns height and analytic normal and allocates to do it; `heightAt(x, z, time)` returns the height alone from the same arithmetic, agreeing exactly, with no warp jacobian, no normalisation and no allocation — ask it for floats, splash and wake queries, 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 at the CFL stability limit for its resolution and celerity, whichever is smaller, so `new RippleField({ resolution, size })` needs no other option; `speed`, `damping`, `foamHalfLife`, `current`, `step` and `maxSteps` override that on the same object, and a `step` above the limit is rejected with the limit in the message rather than quietly clamped. Its rim absorbs, so `recenter` it on whatever the player is watching; it carries no obstacle mask, because a mask is only right for a body that never moves.
58
58
 
59
59
  Tune the sea state in `src/render/ocean.ts`, hull points in `src/entities/Ship.ts`, and course
60
60
  order in `src/scenes/Sailing.ts`. The single React HUD reads published state; keep
@@ -90,8 +90,8 @@ supposed to be touching. Two loading conventions come from `@threenative/core`,
90
90
 
91
91
  Reference-driven authoring starts at `agent-docs/dream-loop.md`.
92
92
 
93
- Open a capture after visual changes. A scenario with no assertions or missing observations fails.
93
+ 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 beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
94
94
 
95
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
95
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
96
96
  ## Optional multiplayer transport
97
97
  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`.
@@ -12,13 +12,13 @@
12
12
  "build:ios": "threenative build --target ios",
13
13
  "test:native": "pnpm build:desktop && threenative-playtest --scenario native-playtests/survives.playtest.json --scenario native-playtests/float.playtest.json --target desktop --executable dist-native/__PROJECT_NAME__",
14
14
  "pretest": "playwright install chromium",
15
- "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
15
+ "test": "pnpm build:web && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm exec vite preview --host 127.0.0.1 --port $PORT --strictPort\"",
16
16
  "typecheck": "tsc --noEmit -p tsconfig.json"
17
17
  },
18
18
  "dependencies": {
19
- "@threenative/core": "0.3.1",
20
- "@threenative/physics": "0.3.1",
21
- "@threenative/ui": "0.3.1",
19
+ "@threenative/core": "0.3.3",
20
+ "@threenative/physics": "0.3.3",
21
+ "@threenative/ui": "0.3.3",
22
22
  "react": "19.2.0",
23
23
  "react-dom": "19.2.0",
24
24
  "react-reconciler": "0.33.0",
@@ -26,13 +26,13 @@
26
26
  },
27
27
  "devDependencies": {
28
28
  "@tailwindcss/vite": "4.3.3",
29
- "@threenative/assets": "0.3.1",
30
- "@threenative/playtest": "0.3.1",
29
+ "@threenative/assets": "0.3.3",
30
+ "@threenative/playtest": "0.3.3",
31
31
  "@types/react": "19.2.0",
32
32
  "@types/react-dom": "19.2.0",
33
33
  "@types/three": "0.185.3",
34
34
  "@vitejs/plugin-react": "6.0.5",
35
- "create-threenative": "0.2.4",
35
+ "create-threenative": "0.2.6",
36
36
  "esbuild": "0.27.0",
37
37
  "playwright": "1.62.1",
38
38
  "tailwindcss": "4.3.3",
@@ -41,7 +41,7 @@
41
41
  "@gltf-transform/cli": "4.4.2"
42
42
  },
43
43
  "optionalDependencies": {
44
- "@threenative/runtime-native": "0.3.1"
44
+ "@threenative/runtime-native": "0.3.3"
45
45
  },
46
46
  "pnpm": {
47
47
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -5,13 +5,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
5
5
  ## Ownership
6
6
 
7
7
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the arena, weapons, waves, HUD and look; `src/game.ts` is
8
- portable, `src/main.ts` is the web-only React mount.
8
+ portable, `src/main.ts` is the web-only React mount. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way.
9
9
 
10
10
  ## Start every change
11
11
 
12
12
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
13
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect matches
14
- with `engine_capability_detail`, and record a capability or no-match for the plan.
14
+ with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
15
15
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
16
  direct the user to review it, and wait for explicit approval plus an instruction to implement.
17
17
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -37,7 +37,7 @@ result, replacement); never stall the game.
37
37
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
38
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
39
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
41
41
 
42
42
  ## Commands and map
43
43
 
@@ -88,9 +88,9 @@ Open a capture after visual changes; a scenario with no assertions or missing ob
88
88
  VFX appearance belongs in `src/render/vfx.ts`: its TSL material, geometry, colour, blend, curves,
89
89
  timing and capacity. Gameplay creates `GPUParticles3D` or an `IComputeDriven` object once, adds it
90
90
  with `ctx.add`, and calls `restart()` from the real fire or hit path; never move appearance into
91
- core or replace the event with a demo-only caller.
91
+ core or replace the event with a demo-only caller. 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 beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
92
92
 
93
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
93
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
94
94
  On a touch-primary device, `src/render/touch-controls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints. Keyboard is the fallback.
95
95
  ## Optional multiplayer transport
96
96
  For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
@@ -7,13 +7,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
7
7
  ## Ownership
8
8
 
9
9
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the arena, weapons, waves, HUD and look; `src/game.ts` is
10
- portable, `src/main.ts` is the web-only React mount.
10
+ portable, `src/main.ts` is the web-only React mount. 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.
11
11
 
12
12
  ## Start every change
13
13
 
14
14
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
15
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect matches
16
- with `engine_capability_detail`, and record a capability or no-match for the plan.
16
+ with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
17
17
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
18
  direct the user to review it, and wait for explicit approval plus an instruction to implement.
19
19
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -39,7 +39,7 @@ result, replacement); never stall the game.
39
39
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
40
40
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
41
41
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
42
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
42
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
43
43
 
44
44
  ## Commands and map
45
45
 
@@ -90,9 +90,9 @@ Open a capture after visual changes; a scenario with no assertions or missing ob
90
90
  VFX appearance belongs in `src/render/vfx.ts`: its TSL material, geometry, colour, blend, curves,
91
91
  timing and capacity. Gameplay creates `GPUParticles3D` or an `IComputeDriven` object once, adds it
92
92
  with `ctx.add`, and calls `restart()` from the real fire or hit path; never move appearance into
93
- core or replace the event with a demo-only caller.
93
+ core or replace the event with a demo-only caller. 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 beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
94
94
 
95
- Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
95
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
96
96
  On a touch-primary device, `src/render/touch-controls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints. Keyboard is the fallback.
97
97
  ## Optional multiplayer transport
98
98
  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`.
@@ -12,13 +12,13 @@
12
12
  "build:ios": "threenative build --target ios",
13
13
  "test:native": "pnpm build:desktop && node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs",
14
14
  "pretest": "playwright install chromium",
15
- "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
15
+ "test": "pnpm build:web && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm exec vite preview --host 127.0.0.1 --port $PORT --strictPort\"",
16
16
  "typecheck": "tsc --noEmit -p tsconfig.json"
17
17
  },
18
18
  "dependencies": {
19
- "@threenative/core": "0.3.1",
20
- "@threenative/physics": "0.3.1",
21
- "@threenative/ui": "0.3.1",
19
+ "@threenative/core": "0.3.3",
20
+ "@threenative/physics": "0.3.3",
21
+ "@threenative/ui": "0.3.3",
22
22
  "react": "19.2.0",
23
23
  "react-dom": "19.2.0",
24
24
  "three": "0.185.1"
@@ -27,12 +27,12 @@
27
27
  "@tailwindcss/vite": "4.3.3",
28
28
  "@types/three": "0.185.3",
29
29
  "@vitejs/plugin-react": "6.0.5",
30
- "@threenative/assets": "0.3.1",
31
- "@threenative/playtest": "0.3.1",
30
+ "@threenative/assets": "0.3.3",
31
+ "@threenative/playtest": "0.3.3",
32
32
  "@types/react": "19.2.0",
33
33
  "@types/react-dom": "19.2.0",
34
34
  "playwright": "1.62.1",
35
- "create-threenative": "0.2.4",
35
+ "create-threenative": "0.2.6",
36
36
  "esbuild": "0.27.0",
37
37
  "tailwindcss": "4.3.3",
38
38
  "typescript": "5.9.3",
@@ -40,7 +40,7 @@
40
40
  "@gltf-transform/cli": "4.4.2"
41
41
  },
42
42
  "optionalDependencies": {
43
- "@threenative/runtime-native": "0.3.1"
43
+ "@threenative/runtime-native": "0.3.3"
44
44
  },
45
45
  "pnpm": {
46
46
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -5,13 +5,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
5
5
  ## Ownership
6
6
 
7
7
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
8
- `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`.
8
+ `src/scenes/`, and `src/ui/`; `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. `src/render/hero.ts` merges the hero's primitives into one buffer with `mergeParts`; pass `{ preserve: ["uv", "normal"] }` to keep authored texture coordinates and normals, and prepare any missing channel in the pieces first.
9
9
 
10
10
  ## Start every change
11
11
 
12
12
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
13
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
14
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
14
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
15
15
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
16
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
17
17
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -35,7 +35,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
35
35
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
36
36
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
37
37
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
38
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
38
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
39
39
 
40
40
  ## Commands and map
41
41
 
@@ -61,8 +61,8 @@ On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src
61
61
  Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `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.
62
62
 
63
63
  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.
64
- Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
65
- React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
64
+ Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale. `ctx.beforeRender(fn)` registers scene work that runs once per actual world draw, after the frame's last fixed update and before the projection packs, so `fn` reads the frame's final state; a held loader frame draws no world and dispatches nothing, and the registration clears on scene change and stop like `ctx.afterPhysics`. Automatic drawing resolution (`render.resolutionScale: "auto"` on `defineGame`) reads fresh GPU cost before presentation timing, so a host delay alone does not spend pixels while GPU headroom is observed and sustained headroom restores resolution; missing or stale GPU timing probes one rung and refunds it unless fewer pixels earn a better frame rate, oscillation holds are temporary, a numeric `resolutionScale` is the named pin override, and `TN_FRAME_BUDGET` reports the actual scale, its source, the GPU time as a mean/p50/p95/max series over resolved frames (`gpu`, with `gpuStale` counting frames that had no fresh reading and `gpu` absent rather than zero when there were none), and the draw calls and triangles each render pass submitted (main, shadow, reflection) under either policy. The engine's scene-render projection — an internal mirror that collapses repeated draws — is on by default; `render.projection: false` is the named opt-out and builds no mirror, so a game that measured it as a loss pays nothing to decline it, reported as `TN_RENDER_PROJECTION` reasonCode `disabled`. A water surface's mirrored pass redraws every frame by default; `reflection.refreshInterval: N` redraws it every Nth presented frame and samples the previous reflection target in between, which halves the pass's cost at the price of up to `N - 1` frames of lag while the camera moves.
65
+ React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`, and style `[data-tn-native-select]` / `[data-tn-native-select-option]` if the game has a `<select>`: on desktop the UI is drawn into the game's own frame with no view for a native popup to open into, so the engine renders the list in the page and the project gives it a look, the same division as `[data-threenative-debug-overlay]`. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
66
66
  `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then
67
67
  `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch.
68
68
  `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded
@@ -83,14 +83,14 @@ After changing bounds, field, or resolution, run three fixed seeds and require t
83
83
  `src/render/quality.ts` owns `low`, `medium`, `high`; platform selects the boot tier, and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
84
84
  `setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit.
85
85
  The starter's painterly look is generated source (`outline.ts`, `kuwahara.ts`, `watercolor.ts`) reached by `worldEnvironment.ts`; `quality.ts` owns tier, radius, resolution, and strength; `TN_RENDER_CHAIN` names each independently, and a missing stage observation is a failure.
86
- `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes.
86
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
87
87
 
88
88
  ## One shadow for a big outdoor level
89
89
  When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. For movers call `trackCaster(object)` — tracking or untracking refreshes the cached levels once, then movement draws a per-level mover map every frame without invalidating them; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
90
90
 
91
91
  ## Budget real time for the look — see `agent-docs/dream-loop.md`
92
92
 
93
- The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule.
94
- Long recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
93
+ The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule. 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 beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
94
+ Long recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
95
95
  ## Optional multiplayer transport
96
96
  For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
@@ -7,13 +7,13 @@ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit
7
7
  ## Ownership
8
8
 
9
9
  ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
10
- `src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`.
10
+ `src/scenes/`, and `src/ui/`; `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. `src/render/hero.ts` merges the hero's primitives into one buffer with `mergeParts`; pass `{ preserve: ["uv", "normal"] }` to keep authored texture coordinates and normals, and prepare any missing channel in the pieces first.
11
11
 
12
12
  ## Start every change
13
13
 
14
14
  1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
15
  `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
- matches with `engine_capability_detail`, and record a capability or no-match for the plan.
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
17
17
  2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
18
  direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
19
  3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
@@ -37,7 +37,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
37
37
  - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
38
  - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
39
  - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
41
41
 
42
42
  ## Commands and map
43
43
 
@@ -63,8 +63,8 @@ On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src
63
63
  Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `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.
64
64
 
65
65
  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.
66
- Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
67
- React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
66
+ Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale. `ctx.beforeRender(fn)` registers scene work that runs once per actual world draw, after the frame's last fixed update and before the projection packs, so `fn` reads the frame's final state; a held loader frame draws no world and dispatches nothing, and the registration clears on scene change and stop like `ctx.afterPhysics`. Automatic drawing resolution (`render.resolutionScale: "auto"` on `defineGame`) reads fresh GPU cost before presentation timing, so a host delay alone does not spend pixels while GPU headroom is observed and sustained headroom restores resolution; missing or stale GPU timing probes one rung and refunds it unless fewer pixels earn a better frame rate, oscillation holds are temporary, a numeric `resolutionScale` is the named pin override, and `TN_FRAME_BUDGET` reports the actual scale, its source, the GPU time as a mean/p50/p95/max series over resolved frames (`gpu`, with `gpuStale` counting frames that had no fresh reading and `gpu` absent rather than zero when there were none), and the draw calls and triangles each render pass submitted (main, shadow, reflection) under either policy. The engine's scene-render projection — an internal mirror that collapses repeated draws — is on by default; `render.projection: false` is the named opt-out and builds no mirror, so a game that measured it as a loss pays nothing to decline it, reported as `TN_RENDER_PROJECTION` reasonCode `disabled`. A water surface's mirrored pass redraws every frame by default; `reflection.refreshInterval: N` redraws it every Nth presented frame and samples the previous reflection target in between, which halves the pass's cost at the price of up to `N - 1` frames of lag while the camera moves.
67
+ React never touches the scene graph. Native UI reads published state and sends intents; mark every touch target `data-tn-interactive`, and style `[data-tn-native-select]` / `[data-tn-native-select-option]` if the game has a `<select>`: on desktop the UI is drawn into the game's own frame with no view for a native popup to open into, so the engine renders the list in the page and the project gives it a look, the same division as `[data-threenative-debug-overlay]`. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity.
68
68
  `ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then
69
69
  `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch.
70
70
  `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's state. Seeded
@@ -85,14 +85,14 @@ After changing bounds, field, or resolution, run three fixed seeds and require t
85
85
  `src/render/quality.ts` owns `low`, `medium`, `high`; platform selects the boot tier, and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
86
86
  `setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit.
87
87
  The starter's painterly look is generated source (`outline.ts`, `kuwahara.ts`, `watercolor.ts`) reached by `worldEnvironment.ts`; `quality.ts` owns tier, radius, resolution, and strength; `TN_RENDER_CHAIN` names each independently, and a missing stage observation is a failure.
88
- `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes.
88
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
89
89
 
90
90
  ## One shadow for a big outdoor level
91
91
  When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. For movers call `trackCaster(object)` — tracking or untracking refreshes the cached levels once, then movement draws a per-level mover map every frame without invalidating them; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
92
92
 
93
93
  ## Budget real time for the look — see `agent-docs/dream-loop.md`
94
94
 
95
- The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule.
96
- Long recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
95
+ The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule. 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 beside the frame rate; `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.
96
+ Long recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/performance-basics.md`, `agent-docs/rigging-characters.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
97
97
  ## Optional multiplayer transport
98
98
  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`.
@@ -11,15 +11,15 @@
11
11
  "build:desktop": "threenative build --target desktop",
12
12
  "build:android": "threenative build --target android",
13
13
  "build:ios": "threenative build --target ios",
14
- "test:native": "pnpm build:desktop && node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs",
14
+ "test:native": "pnpm build:desktop && node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs && node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs --consumer --target desktop --project .",
15
15
  "pretest": "playwright install chromium",
16
- "test": "vite build && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm dev --host 127.0.0.1 --port $PORT --strictPort\"",
16
+ "test": "pnpm build:web && threenative-playtest --scenario \"playtests/*.playtest.json\" --browser-recipe webgpu --headed --server-command \"pnpm exec vite preview --host 127.0.0.1 --port $PORT --strictPort\"",
17
17
  "typecheck": "tsc --noEmit -p tsconfig.json"
18
18
  },
19
19
  "dependencies": {
20
- "@threenative/core": "0.3.1",
21
- "@threenative/physics": "0.3.1",
22
- "@threenative/ui": "0.3.1",
20
+ "@threenative/core": "0.3.3",
21
+ "@threenative/physics": "0.3.3",
22
+ "@threenative/ui": "0.3.3",
23
23
  "react": "19.2.0",
24
24
  "react-dom": "19.2.0",
25
25
  "react-reconciler": "0.33.0",
@@ -27,13 +27,13 @@
27
27
  },
28
28
  "devDependencies": {
29
29
  "@tailwindcss/vite": "4.3.3",
30
- "@threenative/assets": "0.3.1",
31
- "@threenative/playtest": "0.3.1",
30
+ "@threenative/assets": "0.3.3",
31
+ "@threenative/playtest": "0.3.3",
32
32
  "@types/react": "19.2.0",
33
33
  "@types/react-dom": "19.2.0",
34
34
  "@types/three": "0.185.3",
35
35
  "@vitejs/plugin-react": "6.0.5",
36
- "create-threenative": "0.2.4",
36
+ "create-threenative": "0.2.6",
37
37
  "esbuild": "0.27.0",
38
38
  "playwright": "1.62.1",
39
39
  "tailwindcss": "4.3.3",
@@ -42,7 +42,7 @@
42
42
  "@gltf-transform/cli": "4.4.2"
43
43
  },
44
44
  "optionalDependencies": {
45
- "@threenative/runtime-native": "0.3.1"
45
+ "@threenative/runtime-native": "0.3.3"
46
46
  },
47
47
  "pnpm": {
48
48
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],