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.
- package/agent-docs/kit-mcp.md +10 -0
- package/agent-docs/kit-router.md +14 -0
- package/agent-docs/kit-stuck.md +7 -0
- package/agent-docs/references/capability-reference.md +958 -30
- package/agent-docs/references/conventions.md +271 -0
- package/agent-docs/references/kit-action-rpg.md +40 -0
- package/agent-docs/references/kit-adventure.md +40 -0
- package/agent-docs/references/kit-collectathon.md +38 -0
- package/agent-docs/references/kit-kart.md +31 -0
- package/agent-docs/references/kit-minimal.md +29 -0
- package/agent-docs/references/kit-platformer.md +34 -0
- package/agent-docs/references/kit-puzzle.md +22 -0
- package/agent-docs/references/kit-racing.md +26 -0
- package/agent-docs/references/kit-rain.md +31 -0
- package/agent-docs/references/kit-rts.md +34 -0
- package/agent-docs/references/kit-runner.md +32 -0
- package/agent-docs/references/kit-sailing.md +41 -0
- package/agent-docs/references/kit-shooter.md +33 -0
- package/agent-docs/references/kit-snow.md +33 -0
- package/agent-docs/references/kit-starter.md +55 -0
- package/agent-docs/references/kit-tower-defense.md +27 -0
- package/agent-docs/references/terrain-authoring.md +2 -1
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
- package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/.claude/settings.json +25 -0
- package/agent-files/.codex/hooks.json +18 -1
- package/dist/index.js +256 -120
- package/dist/terrain-kit.d.ts +7 -0
- package/dist/terrain-kit.js +82 -0
- package/dist/threenative.js +23 -4
- package/dist/web-engine-gltf-loader.js +20 -7
- package/dist/web-engine-post-effects.js +34 -4
- package/dist/web-engine-runtime.js +6119 -3311
- package/package.json +13 -8
- package/template-assets/patches/three@0.187.0.patch +2004 -407
- package/templates/action-rpg/AGENTS.md +99 -84
- package/templates/action-rpg/CLAUDE.md +99 -84
- package/templates/action-rpg/kit.json +1 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/spells.playtest.json +20 -0
- package/templates/action-rpg/src/game.ts +1 -0
- package/templates/action-rpg/src/render/atmosphere.ts +5 -16
- package/templates/action-rpg/src/render/gpuSky.ts +4 -7
- package/templates/action-rpg/src/render/quality.ts +3 -1
- package/templates/action-rpg/src/scenes/Play.ts +26 -0
- package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
- package/templates/action-rpg/threenative.config.ts +0 -3
- package/templates/adventure/AGENTS.md +87 -44
- package/templates/adventure/CLAUDE.md +87 -44
- package/templates/adventure/package.json +7 -7
- package/templates/collectathon/AGENTS.md +88 -42
- package/templates/collectathon/CLAUDE.md +88 -42
- package/templates/collectathon/package.json +7 -7
- package/templates/kart/AGENTS.md +82 -42
- package/templates/kart/CLAUDE.md +82 -42
- package/templates/kart/package.json +6 -6
- package/templates/minimal/AGENTS.md +100 -84
- package/templates/minimal/CLAUDE.md +100 -84
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/src/render/atmosphere.ts +5 -16
- package/templates/minimal/src/render/gpuSky.ts +4 -7
- package/templates/platformer/AGENTS.md +90 -46
- package/templates/platformer/CLAUDE.md +90 -46
- package/templates/platformer/package.json +7 -7
- package/templates/puzzle/AGENTS.md +92 -80
- package/templates/puzzle/CLAUDE.md +92 -80
- package/templates/puzzle/package.json +7 -7
- package/templates/racing/AGENTS.md +95 -82
- package/templates/racing/CLAUDE.md +95 -82
- package/templates/racing/package.json +7 -7
- package/templates/racing/src/render/atmosphere.ts +5 -16
- package/templates/racing/src/render/gpuSky.ts +4 -7
- package/templates/rain/AGENTS.md +92 -84
- package/templates/rain/CLAUDE.md +92 -84
- package/templates/rain/native-playtests/lightning.playtest.json +85 -10
- package/templates/rain/package.json +6 -6
- package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
- package/templates/rain/src/scenes/Boot.ts +1 -0
- package/templates/rain/src/state.ts +7 -0
- package/templates/rain/src/ui/GameUi.tsx +7 -1
- package/templates/rts/AGENTS.md +96 -85
- package/templates/rts/CLAUDE.md +96 -85
- package/templates/rts/package.json +6 -6
- package/templates/runner/AGENTS.md +92 -80
- package/templates/runner/CLAUDE.md +92 -80
- package/templates/runner/package.json +7 -7
- package/templates/runner/playtests/performance.playtest.json +1 -1
- package/templates/runner/src/render/atmosphere.ts +5 -16
- package/templates/runner/src/render/gpuSky.ts +4 -7
- package/templates/runner/src/render/lighting.ts +53 -11
- package/templates/runner/src/scenes/Run.ts +4 -3
- package/templates/runner/threenative.config.ts +0 -3
- package/templates/sailing/AGENTS.md +91 -79
- package/templates/sailing/CLAUDE.md +91 -79
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/playtests/sails.playtest.json +1 -0
- package/templates/sailing/src/render/sky.ts +4 -0
- package/templates/sailing/threenative.config.ts +0 -3
- package/templates/shooter/AGENTS.md +93 -68
- package/templates/shooter/CLAUDE.md +93 -68
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/render/atmosphere.ts +5 -16
- package/templates/shooter/src/render/gpuSky.ts +4 -7
- package/templates/shooter/src/render/quality.ts +3 -1
- package/templates/snow/AGENTS.md +90 -76
- package/templates/snow/CLAUDE.md +90 -76
- package/templates/snow/package.json +7 -7
- package/templates/snow/threenative.config.ts +0 -3
- package/templates/starter/AGENTS.md +104 -88
- package/templates/starter/CLAUDE.md +104 -88
- package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
- package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Player.ts +10 -22
- package/templates/starter/src/render/atmosphere.ts +5 -16
- package/templates/starter/src/render/gpuSky.ts +4 -7
- package/templates/starter/src/render/lighting.ts +54 -4
- package/templates/starter/src/render/temporalAA.ts +8 -7
- package/templates/starter/src/render/temporalAAFrame.ts +30 -9
- package/templates/starter/src/render/temporalAAResolve.ts +15 -1
- package/templates/starter/src/render/temporalClampRelease.ts +183 -0
- package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
- package/templates/starter/src/render/temporalMoire.ts +190 -0
- package/templates/starter/src/render/temporalResolve.ts +75 -16
- package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
- package/templates/starter/src/scenes/Play.ts +41 -29
- package/templates/tower-defense/AGENTS.md +92 -81
- package/templates/tower-defense/CLAUDE.md +92 -81
- package/templates/tower-defense/package.json +7 -7
- package/capabilities.json +0 -9197
- package/templates/AGENTS.md +0 -21
- package/templates/CLAUDE.md +0 -23
- package/templates/action-rpg/.codex/config.toml +0 -23
- package/templates/action-rpg/.cursor/mcp.json +0 -38
- package/templates/action-rpg/.gemini/settings.json +0 -38
- package/templates/action-rpg/.mcp.json +0 -38
- package/templates/action-rpg/.vscode/mcp.json +0 -43
- package/templates/action-rpg/.zed/settings.json +0 -43
- package/templates/action-rpg/opencode.json +0 -49
- package/templates/adventure/.codex/config.toml +0 -23
- package/templates/adventure/.cursor/mcp.json +0 -38
- package/templates/adventure/.gemini/settings.json +0 -38
- package/templates/adventure/.mcp.json +0 -38
- package/templates/adventure/.vscode/mcp.json +0 -43
- package/templates/adventure/.zed/settings.json +0 -43
- package/templates/adventure/opencode.json +0 -49
- package/templates/collectathon/.codex/config.toml +0 -23
- package/templates/collectathon/.cursor/mcp.json +0 -38
- package/templates/collectathon/.gemini/settings.json +0 -38
- package/templates/collectathon/.mcp.json +0 -38
- package/templates/collectathon/.vscode/mcp.json +0 -43
- package/templates/collectathon/.zed/settings.json +0 -43
- package/templates/collectathon/opencode.json +0 -49
- package/templates/kart/.codex/config.toml +0 -23
- package/templates/kart/.cursor/mcp.json +0 -38
- package/templates/kart/.gemini/settings.json +0 -38
- package/templates/kart/.mcp.json +0 -38
- package/templates/kart/.vscode/mcp.json +0 -43
- package/templates/kart/.zed/settings.json +0 -43
- package/templates/kart/opencode.json +0 -49
- package/templates/minimal/.codex/config.toml +0 -23
- package/templates/minimal/.cursor/mcp.json +0 -38
- package/templates/minimal/.gemini/settings.json +0 -38
- package/templates/minimal/.mcp.json +0 -38
- package/templates/minimal/.vscode/mcp.json +0 -43
- package/templates/minimal/.zed/settings.json +0 -43
- package/templates/minimal/opencode.json +0 -49
- package/templates/platformer/.codex/config.toml +0 -23
- package/templates/platformer/.cursor/mcp.json +0 -38
- package/templates/platformer/.gemini/settings.json +0 -38
- package/templates/platformer/.mcp.json +0 -38
- package/templates/platformer/.vscode/mcp.json +0 -43
- package/templates/platformer/.zed/settings.json +0 -43
- package/templates/platformer/opencode.json +0 -49
- package/templates/puzzle/.codex/config.toml +0 -23
- package/templates/puzzle/.cursor/mcp.json +0 -38
- package/templates/puzzle/.gemini/settings.json +0 -38
- package/templates/puzzle/.mcp.json +0 -38
- package/templates/puzzle/.vscode/mcp.json +0 -43
- package/templates/puzzle/.zed/settings.json +0 -43
- package/templates/puzzle/opencode.json +0 -49
- package/templates/racing/.codex/config.toml +0 -23
- package/templates/racing/.cursor/mcp.json +0 -38
- package/templates/racing/.gemini/settings.json +0 -38
- package/templates/racing/.mcp.json +0 -38
- package/templates/racing/.vscode/mcp.json +0 -43
- package/templates/racing/.zed/settings.json +0 -43
- package/templates/racing/opencode.json +0 -49
- package/templates/rain/.codex/config.toml +0 -23
- package/templates/rain/.cursor/mcp.json +0 -38
- package/templates/rain/.gemini/settings.json +0 -38
- package/templates/rain/.mcp.json +0 -38
- package/templates/rain/.vscode/mcp.json +0 -43
- package/templates/rain/.zed/settings.json +0 -43
- package/templates/rain/opencode.json +0 -49
- package/templates/rts/.codex/config.toml +0 -23
- package/templates/rts/.cursor/mcp.json +0 -38
- package/templates/rts/.gemini/settings.json +0 -38
- package/templates/rts/.mcp.json +0 -38
- package/templates/rts/.vscode/mcp.json +0 -43
- package/templates/rts/.zed/settings.json +0 -43
- package/templates/rts/opencode.json +0 -49
- package/templates/runner/.codex/config.toml +0 -23
- package/templates/runner/.cursor/mcp.json +0 -38
- package/templates/runner/.gemini/settings.json +0 -38
- package/templates/runner/.mcp.json +0 -38
- package/templates/runner/.vscode/mcp.json +0 -43
- package/templates/runner/.zed/settings.json +0 -43
- package/templates/runner/README.md +0 -43
- package/templates/runner/opencode.json +0 -49
- package/templates/sailing/.codex/config.toml +0 -23
- package/templates/sailing/.cursor/mcp.json +0 -38
- package/templates/sailing/.gemini/settings.json +0 -38
- package/templates/sailing/.mcp.json +0 -38
- package/templates/sailing/.vscode/mcp.json +0 -43
- package/templates/sailing/.zed/settings.json +0 -43
- package/templates/sailing/README.md +0 -28
- package/templates/sailing/opencode.json +0 -49
- package/templates/shooter/.codex/config.toml +0 -23
- package/templates/shooter/.cursor/mcp.json +0 -38
- package/templates/shooter/.gemini/settings.json +0 -38
- package/templates/shooter/.mcp.json +0 -38
- package/templates/shooter/.vscode/mcp.json +0 -43
- package/templates/shooter/.zed/settings.json +0 -43
- package/templates/shooter/opencode.json +0 -49
- package/templates/snow/.codex/config.toml +0 -23
- package/templates/snow/.cursor/mcp.json +0 -38
- package/templates/snow/.gemini/settings.json +0 -38
- package/templates/snow/.mcp.json +0 -38
- package/templates/snow/.vscode/mcp.json +0 -43
- package/templates/snow/.zed/settings.json +0 -43
- package/templates/snow/README.md +0 -26
- package/templates/snow/opencode.json +0 -49
- package/templates/starter/.codex/config.toml +0 -23
- package/templates/starter/.cursor/mcp.json +0 -38
- package/templates/starter/.gemini/settings.json +0 -38
- package/templates/starter/.mcp.json +0 -38
- package/templates/starter/.vscode/mcp.json +0 -43
- package/templates/starter/.zed/settings.json +0 -43
- package/templates/starter/opencode.json +0 -49
- package/templates/tower-defense/.codex/config.toml +0 -23
- package/templates/tower-defense/.cursor/mcp.json +0 -38
- package/templates/tower-defense/.gemini/settings.json +0 -38
- package/templates/tower-defense/.mcp.json +0 -38
- package/templates/tower-defense/.vscode/mcp.json +0 -43
- package/templates/tower-defense/.zed/settings.json +0 -43
- package/templates/tower-defense/README.md +0 -16
- package/templates/tower-defense/opencode.json +0 -49
|
@@ -1,58 +1,104 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- shared: kit-identity -->
|
|
2
|
+
# AGENTS.md — __PROJECT_NAME__ (Hop Garden, the collectathon kit)
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
A stout sprout-keeper in a knit beanie runs one free-roam island with a triple jump, long jump, backflip, side flip, wall kick, dive, ground pound and ledge grab, collecting three Sunseeds past bumblets, hoppers and spiked thornbacks. Routing words: collectathon, mario, sm64, super-mario, 3d-platformer. `CLAUDE.md` is a copy of this file.
|
|
5
|
+
<!-- /shared -->
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<!-- shared: kit-router -->
|
|
8
|
+
## Authoring flow
|
|
6
9
|
|
|
7
|
-
|
|
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).
|
|
8
11
|
|
|
9
|
-
|
|
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.
|
|
10
20
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this course needs no navigation: walkers chase in a straight line inside a leash, and the course is authored geometry, so the hero collides with exactly the triangles it sees and desktop/native stays honest.
|
|
14
|
-
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. 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.
|
|
21
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
22
|
+
<!-- /shared -->
|
|
15
23
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
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); never stall the game.
|
|
24
|
+
<!-- shared: kit-mcp -->
|
|
25
|
+
## MCP servers
|
|
19
26
|
|
|
20
|
-
|
|
21
|
-
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
22
|
-
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
|
|
23
|
-
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
24
|
-
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
25
|
-
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
26
|
-
- `.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.
|
|
27
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
28
|
-
- 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 runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
|
|
29
|
-
## Commands and map
|
|
30
|
-
|
|
31
|
-
```sh
|
|
32
|
-
pnpm dev
|
|
33
|
-
pnpm build
|
|
34
|
-
pnpm build --target desktop
|
|
35
|
-
pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
|
|
36
|
-
pnpm typecheck
|
|
37
|
-
```
|
|
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.
|
|
38
28
|
|
|
39
|
-
|
|
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 -->
|
|
40
36
|
|
|
41
|
-
|
|
37
|
+
## This kit
|
|
42
38
|
|
|
43
|
-
|
|
44
|
-
|
|
39
|
+
<!-- shared: kit-files -->
|
|
40
|
+
Source in `src/`: `entities/`, `game.ts`, `level/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
|
|
41
|
+
23 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
42
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-collectathon.md`.
|
|
43
|
+
<!-- /shared -->
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
`HERO_FEEL` in `src/entities/Hero.ts` is the one table of metres and seconds the course is laid out from; change a number and a gap in `src/level/Course.ts` changes meaning. The camera and sun are written in `afterPhysics`.
|
|
46
|
+
Every model and animation is procedural. Tiling textures are `assets/tex-*.webp`, loaded by `loadSurfaces(ctx.assets)` in `src/render/surface.ts`. Keep `assets/` at most 1.5 MB.
|
|
47
|
+
`buildStaticColliders` builds collision from the tagged course meshes; this course needs no navigation, so walkers chase in a straight line.
|
|
47
48
|
|
|
48
|
-
|
|
49
|
+
<!-- shared: kit-commands -->
|
|
50
|
+
## Commands
|
|
49
51
|
|
|
50
|
-
|
|
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 studio # open the game in Studio
|
|
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
|
+
- **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
|
|
80
|
+
- **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
|
|
81
|
+
- **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
|
|
82
|
+
- **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
|
|
83
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
84
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
85
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
86
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
87
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
88
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
89
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
90
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
91
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
92
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
93
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
94
|
+
<!-- /shared -->
|
|
95
|
+
|
|
96
|
+
<!-- shared: kit-stuck -->
|
|
97
|
+
## When the framework blocks you, write plain Three.js
|
|
51
98
|
|
|
52
|
-
|
|
53
|
-
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. 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.
|
|
99
|
+
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.
|
|
54
100
|
|
|
55
|
-
|
|
101
|
+
## Stuck
|
|
56
102
|
|
|
57
|
-
|
|
58
|
-
|
|
103
|
+
`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.
|
|
104
|
+
<!-- /shared -->
|
|
@@ -1,60 +1,106 @@
|
|
|
1
1
|
<!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<!-- shared: kit-identity -->
|
|
4
|
+
# AGENTS.md — __PROJECT_NAME__ (Hop Garden, the collectathon kit)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
A stout sprout-keeper in a knit beanie runs one free-roam island with a triple jump, long jump, backflip, side flip, wall kick, dive, ground pound and ledge grab, collecting three Sunseeds past bumblets, hoppers and spiked thornbacks. Routing words: collectathon, mario, sm64, super-mario, 3d-platformer. `CLAUDE.md` is a copy of this file.
|
|
7
|
+
<!-- /shared -->
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
<!-- shared: kit-router -->
|
|
10
|
+
## Authoring flow
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
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).
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
|
|
15
|
+
2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
|
|
16
|
+
3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
|
|
17
|
+
4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
|
|
18
|
+
5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
|
|
19
|
+
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.
|
|
20
|
+
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`).
|
|
21
|
+
8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
|
|
12
22
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM, and this course needs no navigation: walkers chase in a straight line inside a leash, and the course is authored geometry, so the hero collides with exactly the triangles it sees and desktop/native stays honest.
|
|
16
|
-
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. 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.
|
|
23
|
+
A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
|
|
24
|
+
<!-- /shared -->
|
|
17
25
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
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); never stall the game.
|
|
26
|
+
<!-- shared: kit-mcp -->
|
|
27
|
+
## MCP servers
|
|
21
28
|
|
|
22
|
-
|
|
23
|
-
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
24
|
-
- `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
|
|
25
|
-
- `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
|
|
26
|
-
- `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
|
|
27
|
-
- `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
|
|
28
|
-
- `.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.
|
|
29
|
-
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI. `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
30
|
-
- 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 runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. Android and iOS use the legacy host.
|
|
31
|
-
## Commands and map
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
pnpm dev
|
|
35
|
-
pnpm build
|
|
36
|
-
pnpm build --target desktop
|
|
37
|
-
pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
|
|
38
|
-
pnpm typecheck
|
|
39
|
-
```
|
|
29
|
+
`.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.
|
|
40
30
|
|
|
41
|
-
|
|
31
|
+
- `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`.
|
|
32
|
+
- `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
|
|
33
|
+
- `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
|
|
34
|
+
- `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
|
|
35
|
+
- `threenative-terrain`: a starter terrain kit. `terrain_generate`.
|
|
36
|
+
- `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
|
|
37
|
+
<!-- /shared -->
|
|
42
38
|
|
|
43
|
-
|
|
39
|
+
## This kit
|
|
44
40
|
|
|
45
|
-
|
|
46
|
-
|
|
41
|
+
<!-- shared: kit-files -->
|
|
42
|
+
Source in `src/`: `entities/`, `game.ts`, `level/`, `main.ts`, `playtest-events.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
|
|
43
|
+
23 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
|
|
44
|
+
Kit notes: `node_modules/create-threenative/agent-docs/references/kit-collectathon.md`.
|
|
45
|
+
<!-- /shared -->
|
|
47
46
|
|
|
48
|
-
|
|
47
|
+
`HERO_FEEL` in `src/entities/Hero.ts` is the one table of metres and seconds the course is laid out from; change a number and a gap in `src/level/Course.ts` changes meaning. The camera and sun are written in `afterPhysics`.
|
|
48
|
+
Every model and animation is procedural. Tiling textures are `assets/tex-*.webp`, loaded by `loadSurfaces(ctx.assets)` in `src/render/surface.ts`. Keep `assets/` at most 1.5 MB.
|
|
49
|
+
`buildStaticColliders` builds collision from the tagged course meshes; this course needs no navigation, so walkers chase in a straight line.
|
|
49
50
|
|
|
50
|
-
|
|
51
|
+
<!-- shared: kit-commands -->
|
|
52
|
+
## Commands
|
|
51
53
|
|
|
52
|
-
|
|
54
|
+
```sh
|
|
55
|
+
pnpm dev # play in the browser
|
|
56
|
+
pnpm test # typecheck, lint, format, then every playtest
|
|
57
|
+
pnpm build --target desktop # also: web, android, ios
|
|
58
|
+
pnpm studio # open the game in Studio
|
|
59
|
+
npx threenative doctor # build, import, device or blank-frame failure
|
|
60
|
+
```
|
|
61
|
+
<!-- /shared -->
|
|
62
|
+
|
|
63
|
+
<!-- shared: kit-conventions -->
|
|
64
|
+
## Conventions
|
|
65
|
+
|
|
66
|
+
Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
|
|
67
|
+
|
|
68
|
+
- **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
|
|
69
|
+
- **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
|
|
70
|
+
- **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
|
|
71
|
+
- **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
|
|
72
|
+
- **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
|
|
73
|
+
- **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
|
|
74
|
+
- **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
|
|
75
|
+
- **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
|
|
76
|
+
- **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
|
|
77
|
+
- **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
|
|
78
|
+
- **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
|
|
79
|
+
- **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
|
|
80
|
+
- **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
|
|
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
|
+
- **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
|
|
86
|
+
- **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
|
|
87
|
+
- **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
|
|
88
|
+
- **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
|
|
89
|
+
- **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
|
|
90
|
+
- **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
|
|
91
|
+
- **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
|
|
92
|
+
- **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
|
|
93
|
+
- **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
|
|
94
|
+
- **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
|
|
95
|
+
- **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
|
|
96
|
+
<!-- /shared -->
|
|
97
|
+
|
|
98
|
+
<!-- shared: kit-stuck -->
|
|
99
|
+
## When the framework blocks you, write plain Three.js
|
|
53
100
|
|
|
54
|
-
|
|
55
|
-
Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`. 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.
|
|
101
|
+
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.
|
|
56
102
|
|
|
57
|
-
|
|
103
|
+
## Stuck
|
|
58
104
|
|
|
59
|
-
|
|
60
|
-
|
|
105
|
+
`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.
|
|
106
|
+
<!-- /shared -->
|
|
@@ -19,9 +19,9 @@
|
|
|
19
19
|
"format:check": "biome format src"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@threenative/core": "0.3.
|
|
23
|
-
"@threenative/physics": "0.3.
|
|
24
|
-
"@threenative/ui": "0.3.
|
|
22
|
+
"@threenative/core": "0.3.12",
|
|
23
|
+
"@threenative/physics": "0.3.12",
|
|
24
|
+
"@threenative/ui": "0.3.12",
|
|
25
25
|
"react": "19.2.0",
|
|
26
26
|
"react-dom": "19.2.0",
|
|
27
27
|
"three": "0.187.0"
|
|
@@ -30,11 +30,11 @@
|
|
|
30
30
|
"@tailwindcss/vite": "4.3.3",
|
|
31
31
|
"@vitejs/plugin-react": "6.0.5",
|
|
32
32
|
"@types/three": "0.187.0",
|
|
33
|
-
"@threenative/assets": "0.3.
|
|
34
|
-
"@threenative/playtest": "0.3.
|
|
33
|
+
"@threenative/assets": "0.3.13",
|
|
34
|
+
"@threenative/playtest": "0.3.12",
|
|
35
35
|
"@types/react": "19.2.0",
|
|
36
36
|
"@types/react-dom": "19.2.0",
|
|
37
|
-
"create-threenative": "0.2.
|
|
37
|
+
"create-threenative": "0.2.17",
|
|
38
38
|
"esbuild": "0.27.0",
|
|
39
39
|
"playwright": "1.62.1",
|
|
40
40
|
"tailwindcss": "4.3.3",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"eslint": "10.13.0"
|
|
46
46
|
},
|
|
47
47
|
"optionalDependencies": {
|
|
48
|
-
"@threenative/runtime-native": "0.3.
|
|
48
|
+
"@threenative/runtime-native": "0.3.12"
|
|
49
49
|
},
|
|
50
50
|
"overrides": {
|
|
51
51
|
"sharp": ">=0.35.4",
|