create-threenative 0.2.1 → 0.2.3
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/LICENSE +21 -0
- package/README.md +10 -2
- package/agent-docs/asset-mcp-loop.md +33 -0
- package/agent-docs/ctx-surface.md +69 -0
- package/agent-docs/engine-capabilities.md +4 -0
- package/agent-docs/framework-blocks-you.md +60 -0
- package/agent-docs/look-at-it-and-budget-the-look.md +27 -0
- package/agent-docs/performance-default.md +42 -0
- package/agent-docs/pixel-budget.md +20 -0
- package/agent-docs/playtest-fail-closed.md +23 -0
- package/agent-docs/references/assertion-reference.md +652 -0
- package/agent-docs/references/capability-reference.md +3279 -0
- package/agent-docs/references/capture-the-frame.md +53 -0
- package/agent-docs/references/ctx-cookbook.md +51 -0
- package/agent-docs/references/debug-surface.md +63 -0
- package/agent-docs/references/finding-assets.md +147 -0
- package/agent-docs/references/gameplay-recipes.md +54 -0
- package/agent-docs/references/menu-screens.md +69 -0
- package/agent-docs/references/mobile-memory-budget.md +87 -0
- package/agent-docs/references/sculpt-from-a-reference.md +39 -0
- package/agent-docs/references/visual-baseline.md +133 -0
- package/agent-docs/references/webview-ui.md +113 -0
- package/agent-docs/sculpt-loop.md +16 -0
- package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
- package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
- package/agent-files/.claude/agents/threenative-builder.md +7 -0
- package/agent-files/.claude/agents/threenative-verifier.md +7 -0
- package/agent-files/.threenative/agents/builder.md +32 -0
- package/agent-files/.threenative/agents/verifier.md +31 -0
- package/agent-files/AGENT-ROLES.md +26 -0
- package/capabilities.json +3542 -0
- package/dist/index.d.ts +191 -3
- package/dist/index.js +1707 -73
- package/dist/threenative.d.ts +9 -2
- package/dist/threenative.js +1825 -148
- package/package.json +30 -6
- package/template-assets/loading.ts +315 -0
- package/template-assets/patches/three@0.185.1.patch +287 -0
- package/templates/action-rpg/.codex/config.toml +15 -0
- package/templates/action-rpg/.mcp.json +6 -2
- package/templates/action-rpg/AGENTS.md +370 -6
- package/templates/action-rpg/CLAUDE.md +370 -6
- package/templates/action-rpg/index.html +0 -1
- package/templates/action-rpg/package.json +15 -11
- package/templates/action-rpg/playtests/combat.playtest.json +23 -9
- package/templates/action-rpg/playtests/fail.playtest.json +3 -3
- package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
- package/templates/action-rpg/playtests/performance.playtest.json +22 -0
- package/templates/action-rpg/playtests/progress.playtest.json +18 -13
- package/templates/action-rpg/playtests/win.playtest.json +10 -4
- package/templates/action-rpg/public/icon.png +0 -0
- package/templates/action-rpg/src/entities/Enemy.ts +14 -4
- package/templates/action-rpg/src/game.ts +21 -0
- package/templates/action-rpg/src/render/lighting.ts +6 -1
- package/templates/action-rpg/src/render/loading.ts +267 -42
- package/templates/action-rpg/src/render/postprocessing.ts +68 -15
- package/templates/action-rpg/src/render/worldEnvironment.ts +583 -0
- package/templates/action-rpg/src/scenes/Play.ts +49 -19
- package/templates/action-rpg/src/state.ts +4 -0
- package/templates/action-rpg/src/style.css +45 -1
- package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
- package/templates/action-rpg/src/ui/App.tsx +9 -8
- package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
- package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
- package/templates/action-rpg/src/ui/Hud.tsx +10 -8
- package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
- package/templates/action-rpg/src/ui/main.tsx +14 -0
- package/templates/action-rpg/threenative.config.ts +21 -8
- package/templates/action-rpg/vite.config.ts +32 -2
- package/templates/defense/.codex/config.toml +15 -0
- package/templates/defense/.mcp.json +6 -2
- package/templates/defense/AGENTS.md +371 -8
- package/templates/defense/CLAUDE.md +371 -8
- package/templates/defense/README.md +2 -1
- package/templates/defense/index.html +0 -1
- package/templates/defense/package.json +16 -12
- package/templates/defense/playtests/leak.playtest.json +9 -4
- package/templates/defense/playtests/performance.playtest.json +22 -0
- package/templates/defense/playtests/placement.playtest.json +5 -5
- package/templates/defense/playtests/pointer-placement.playtest.json +89 -0
- package/templates/defense/playtests/scan.playtest.json +3 -3
- package/templates/defense/playtests/survive.playtest.json +11 -6
- package/templates/defense/public/icon.png +0 -0
- package/templates/defense/src/attackers/Attacker.ts +28 -12
- package/templates/defense/src/game.ts +24 -2
- package/templates/defense/src/render/lighting.ts +6 -1
- package/templates/defense/src/render/loading.ts +263 -37
- package/templates/defense/src/render/postprocessing.ts +70 -13
- package/templates/defense/src/render/shapes.ts +38 -0
- package/templates/defense/src/render/worldEnvironment.ts +583 -0
- package/templates/defense/src/scenes/Defense.ts +109 -50
- package/templates/defense/src/state.ts +6 -0
- package/templates/defense/src/style.css +45 -1
- package/templates/defense/src/ui/App.tsx +9 -4
- package/templates/defense/src/ui/GameUi.tsx +20 -0
- package/templates/defense/src/ui/Hud.tsx +6 -5
- package/templates/defense/src/ui/main.tsx +14 -0
- package/templates/defense/threenative.config.ts +21 -8
- package/templates/defense/vite.config.ts +34 -1
- package/templates/minimal/.codex/config.toml +15 -0
- package/templates/minimal/.mcp.json +6 -2
- package/templates/minimal/AGENTS.md +360 -255
- package/templates/minimal/CLAUDE.md +360 -255
- package/templates/minimal/index.html +0 -1
- package/templates/minimal/package.json +14 -11
- package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
- package/templates/minimal/playtests/play.playtest.json +17 -5
- package/templates/minimal/public/icon.png +0 -0
- package/templates/minimal/src/game.ts +1 -0
- package/templates/minimal/src/render/camera.ts +1 -1
- package/templates/minimal/src/render/hud.ts +24 -8
- package/templates/minimal/src/render/lighting.ts +23 -2
- package/templates/minimal/src/render/loading.ts +23 -103
- package/templates/minimal/src/render/postprocessing.ts +92 -14
- package/templates/minimal/src/render/sky.ts +37 -32
- package/templates/minimal/src/render/worldEnvironment.ts +583 -0
- package/templates/minimal/src/scenes/Play.ts +91 -13
- package/templates/minimal/src/state.ts +8 -1
- package/templates/minimal/threenative.config.ts +15 -10
- package/templates/minimal/vite.config.ts +28 -1
- package/templates/platformer/.codex/config.toml +15 -0
- package/templates/platformer/.mcp.json +6 -2
- package/templates/platformer/AGENTS.md +385 -130
- package/templates/platformer/CLAUDE.md +385 -130
- package/templates/platformer/index.html +0 -1
- package/templates/platformer/package.json +17 -14
- package/templates/platformer/playtests/avoidance.playtest.json +6 -1
- package/templates/platformer/playtests/branding.playtest.json +29 -0
- package/templates/platformer/playtests/buffer.playtest.json +1 -1
- package/templates/platformer/playtests/collect.playtest.json +1 -1
- package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
- package/templates/platformer/playtests/coyote.playtest.json +42 -8
- package/templates/platformer/playtests/damage.playtest.json +4 -1
- package/templates/platformer/playtests/dash.playtest.json +2 -2
- package/templates/platformer/playtests/jump.playtest.json +2 -3
- package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
- package/templates/platformer/playtests/oneway.playtest.json +1 -1
- package/templates/platformer/playtests/performance.playtest.json +6 -5
- package/templates/platformer/playtests/respawn.playtest.json +2 -2
- package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
- package/templates/platformer/playtests/stomp.playtest.json +11 -3
- package/templates/platformer/playtests/terminal-loop-fail.playtest.json +13 -4
- package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
- package/templates/platformer/playtests/touch-controls-web.playtest.json +46 -0
- package/templates/platformer/public/icon.png +0 -0
- package/templates/platformer/src/entities/Character.ts +16 -10
- package/templates/platformer/src/entities/Patrol.ts +5 -0
- package/templates/platformer/src/game.ts +24 -1
- package/templates/platformer/src/render/lighting.ts +6 -1
- package/templates/platformer/src/render/loading.ts +270 -61
- package/templates/platformer/src/render/postprocessing.ts +68 -15
- package/templates/platformer/src/render/touch-controls.ts +54 -36
- package/templates/platformer/src/render/worldEnvironment.ts +583 -0
- package/templates/platformer/src/scenes/Level.ts +47 -22
- package/templates/platformer/src/state.ts +4 -0
- package/templates/platformer/src/style.css +45 -1
- package/templates/platformer/src/ui/App.tsx +9 -4
- package/templates/platformer/src/ui/GameUi.tsx +20 -0
- package/templates/platformer/src/ui/Hud.tsx +6 -5
- package/templates/platformer/src/ui/main.tsx +14 -0
- package/templates/platformer/threenative.config.ts +20 -10
- package/templates/platformer/vite.config.ts +34 -1
- package/templates/racing/.codex/config.toml +15 -0
- package/templates/racing/.mcp.json +6 -2
- package/templates/racing/AGENTS.md +370 -6
- package/templates/racing/CLAUDE.md +370 -6
- package/templates/racing/index.html +0 -1
- package/templates/racing/package.json +16 -12
- package/templates/racing/playtests/boost.playtest.json +5 -5
- package/templates/racing/playtests/outcome.playtest.json +14 -4
- package/templates/racing/playtests/performance.playtest.json +22 -0
- package/templates/racing/playtests/ranking.playtest.json +2 -2
- package/templates/racing/playtests/rescue.playtest.json +12 -6
- package/templates/racing/playtests/reverse.playtest.json +3 -3
- package/templates/racing/playtests/shortcut.playtest.json +3 -3
- package/templates/racing/public/icon.png +0 -0
- package/templates/racing/src/game.ts +24 -1
- package/templates/racing/src/render/camera.ts +10 -6
- package/templates/racing/src/render/lighting.ts +6 -1
- package/templates/racing/src/render/loading.ts +291 -34
- package/templates/racing/src/render/postprocessing.ts +70 -13
- package/templates/racing/src/render/worldEnvironment.ts +583 -0
- package/templates/racing/src/scenes/Race.ts +68 -36
- package/templates/racing/src/state.ts +4 -0
- package/templates/racing/src/style.css +45 -1
- package/templates/racing/src/track/Lap.ts +20 -9
- package/templates/racing/src/track/Ranking.ts +53 -14
- package/templates/racing/src/track/Track.ts +29 -16
- package/templates/racing/src/track/TrackSector.ts +14 -4
- package/templates/racing/src/ui/App.tsx +9 -4
- package/templates/racing/src/ui/GameUi.tsx +20 -0
- package/templates/racing/src/ui/Hud.tsx +6 -5
- package/templates/racing/src/ui/main.tsx +14 -0
- package/templates/racing/threenative.config.ts +21 -8
- package/templates/racing/vite.config.ts +34 -1
- package/templates/sailing/.codex/config.toml +15 -0
- package/templates/sailing/.mcp.json +20 -0
- package/templates/sailing/AGENTS.md +388 -0
- package/templates/sailing/CLAUDE.md +390 -0
- package/templates/sailing/README.md +25 -0
- package/templates/sailing/index.html +12 -0
- package/templates/sailing/kit.json +7 -0
- package/templates/sailing/native-playtests/survives.playtest.json +21 -0
- package/templates/sailing/package.json +52 -0
- package/templates/sailing/playtests/fail.playtest.json +24 -0
- package/templates/sailing/playtests/performance.playtest.json +21 -0
- package/templates/sailing/playtests/survives.playtest.json +38 -0
- package/templates/sailing/playtests/win.playtest.json +31 -0
- package/templates/sailing/public/favicon.svg +5 -0
- package/templates/sailing/public/icon.png +0 -0
- package/templates/sailing/src/entities/Ship.ts +96 -0
- package/templates/sailing/src/game.ts +40 -0
- package/templates/sailing/src/main.ts +15 -0
- package/templates/sailing/src/render/camera.ts +21 -0
- package/templates/sailing/src/render/lighting.ts +36 -0
- package/templates/sailing/src/render/loading.ts +315 -0
- package/templates/sailing/src/render/materials.ts +28 -0
- package/templates/sailing/src/render/palette.ts +24 -0
- package/templates/sailing/src/render/postprocessing.ts +33 -0
- package/templates/sailing/src/render/props.ts +52 -0
- package/templates/sailing/src/render/sky.ts +32 -0
- package/templates/sailing/src/render/water-material.ts +14 -0
- package/templates/sailing/src/render/water-shaders.ts +12 -0
- package/templates/sailing/src/render/wave-nodes.ts +10 -0
- package/templates/sailing/src/render/worldEnvironment.ts +590 -0
- package/templates/sailing/src/scenes/Boot.ts +12 -0
- package/templates/sailing/src/scenes/Sailing.ts +106 -0
- package/templates/sailing/src/state.ts +10 -0
- package/templates/sailing/src/style.css +61 -0
- package/templates/sailing/src/ui/App.tsx +15 -0
- package/templates/sailing/src/ui/GameUi.tsx +12 -0
- package/templates/sailing/src/ui/Hud.tsx +55 -0
- package/templates/sailing/src/ui/Menu.tsx +30 -0
- package/templates/sailing/src/ui/main.tsx +7 -0
- package/templates/sailing/tailwind.config.ts +2 -0
- package/templates/sailing/threenative.config.ts +34 -0
- package/templates/sailing/tsconfig.json +17 -0
- package/templates/sailing/vite.config.ts +34 -0
- package/templates/shooter/.codex/config.toml +15 -0
- package/templates/shooter/.mcp.json +6 -2
- package/templates/shooter/AGENTS.md +373 -7
- package/templates/shooter/CLAUDE.md +373 -7
- package/templates/shooter/index.html +0 -1
- package/templates/shooter/package.json +16 -11
- package/templates/shooter/playtests/fail.playtest.json +5 -4
- package/templates/shooter/playtests/input-control.playtest.json +131 -0
- package/templates/shooter/playtests/per-item.playtest.json +59 -0
- package/templates/shooter/playtests/performance.playtest.json +22 -0
- package/templates/shooter/playtests/shooter.playtest.json +22 -18
- package/templates/shooter/playtests/survives.playtest.json +1 -1
- package/templates/shooter/public/favicon.svg +1 -1
- package/templates/shooter/public/icon.png +0 -0
- package/templates/shooter/src/game.ts +24 -1
- package/templates/shooter/src/main.ts +3 -13
- package/templates/shooter/src/render/camera.ts +62 -12
- package/templates/shooter/src/render/lighting.ts +6 -1
- package/templates/shooter/src/render/loading.ts +262 -33
- package/templates/shooter/src/render/palette.ts +1 -1
- package/templates/shooter/src/render/postprocessing.ts +68 -16
- package/templates/shooter/src/render/shapes.ts +178 -0
- package/templates/shooter/src/render/ui.css +34 -1
- package/templates/shooter/src/render/worldEnvironment.ts +583 -0
- package/templates/shooter/src/scenes/Play.ts +246 -73
- package/templates/shooter/src/state.ts +13 -0
- package/templates/shooter/src/style.css +26 -0
- package/templates/shooter/src/ui/App.tsx +10 -12
- package/templates/shooter/src/ui/GameUi.tsx +20 -0
- package/templates/shooter/src/ui/Hud.tsx +8 -10
- package/templates/shooter/src/ui/Menu.tsx +24 -9
- package/templates/shooter/src/ui/main.tsx +15 -0
- package/templates/shooter/src/weapons/Projectile.ts +21 -10
- package/templates/shooter/threenative.config.ts +21 -8
- package/templates/shooter/vite.config.ts +32 -2
- package/templates/starter/.codex/config.toml +15 -0
- package/templates/starter/.mcp.json +6 -2
- package/templates/starter/AGENTS.md +429 -326
- package/templates/starter/CLAUDE.md +429 -326
- package/templates/starter/assets/pickup.wav +0 -0
- package/templates/starter/gitignore +4 -0
- package/templates/starter/index.html +0 -1
- package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
- package/templates/starter/native-playtests/render-chain.playtest.json +12 -0
- package/templates/starter/package.json +16 -12
- package/templates/starter/playtests/assets.playtest.json +65 -0
- package/templates/starter/playtests/buffer.playtest.json +59 -9
- package/templates/starter/playtests/cloth.playtest.json +113 -0
- package/templates/starter/playtests/coyote.playtest.json +60 -8
- package/templates/starter/playtests/forward.playtest.json +29 -4
- package/templates/starter/playtests/gameover.playtest.json +66 -0
- package/templates/starter/playtests/goal.playtest.json +67 -0
- package/templates/starter/playtests/hot-reload.playtest.json +48 -8
- package/templates/starter/playtests/look.playtest.json +34 -6
- package/templates/starter/playtests/models-baseline.png +0 -0
- package/templates/starter/playtests/models.playtest.json +74 -0
- package/templates/starter/playtests/monitoring.playtest.json +38 -7
- package/templates/starter/playtests/odometer.playtest.json +54 -0
- package/templates/starter/playtests/pause.playtest.json +27 -4
- package/templates/starter/playtests/play.playtest.json +43 -7
- package/templates/starter/playtests/respawn.playtest.json +46 -6
- package/templates/starter/playtests/restart.playtest.json +65 -10
- package/templates/starter/playtests/seed.playtest.json +44 -8
- package/templates/starter/playtests/survives.playtest.json +27 -4
- package/templates/starter/playtests/textures-baseline.png +0 -0
- package/templates/starter/playtests/textures.playtest.json +74 -0
- package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
- package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
- package/templates/starter/public/icon.png +0 -0
- package/templates/starter/src/entities/Goal.ts +122 -0
- package/templates/starter/src/entities/Player.ts +40 -2
- package/templates/starter/src/game.ts +25 -0
- package/templates/starter/src/render/camera.ts +31 -5
- package/templates/starter/src/render/easing.ts +5 -0
- package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
- package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
- package/templates/starter/src/render/effects/sparkle.ts +49 -0
- package/templates/starter/src/render/lighting.ts +6 -1
- package/templates/starter/src/render/loading.ts +315 -0
- package/templates/starter/src/render/materials.ts +17 -1
- package/templates/starter/src/render/pennant.ts +54 -0
- package/templates/starter/src/render/postprocessing.ts +46 -15
- package/templates/starter/src/render/scenery.ts +83 -0
- package/templates/starter/src/render/shapes.ts +9 -21
- package/templates/starter/src/render/worldEnvironment.ts +583 -0
- package/templates/starter/src/scenes/Play.ts +146 -36
- package/templates/starter/src/state.ts +12 -0
- package/templates/starter/src/style.css +45 -1
- package/templates/starter/src/ui/App.tsx +9 -6
- package/templates/starter/src/ui/GameUi.tsx +20 -0
- package/templates/starter/src/ui/Hud.tsx +52 -29
- package/templates/starter/src/ui/Menu.tsx +25 -23
- package/templates/starter/src/ui/main.tsx +14 -0
- package/templates/starter/threenative.config.ts +27 -9
- package/templates/starter/tools/look.mjs +109 -0
- package/templates/starter/vite.config.ts +32 -2
- package/templates/minimal/assets/.gitkeep +0 -0
- package/templates/minimal/public/.gitkeep +0 -0
- package/templates/platformer/assets/.gitkeep +0 -0
- package/templates/platformer/public/.gitkeep +0 -0
- package/templates/starter/assets/.gitkeep +0 -0
- package/templates/starter/public/.gitkeep +0 -0
- package/templates/starter/public/pickup.ogg +0 -0
- /package/templates/starter/{public → assets}/native-proof.glb +0 -0
- /package/templates/starter/{public → assets}/native-proof.png +0 -0
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Capture the frame — screenshots that actually render WebGPU
|
|
2
|
+
|
|
3
|
+
Companion to the `Budget real time for the look` section in this project's `AGENTS.md`. Run
|
|
4
|
+
`pnpm dev`, then get eyes on the game. In rough order of preference:
|
|
5
|
+
|
|
6
|
+
1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
|
|
7
|
+
or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
|
|
8
|
+
a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
|
|
9
|
+
console in the same loop you are already coding in. Drive the game, do not just load the
|
|
10
|
+
menu.
|
|
11
|
+
2. **`npx @threenative/playtest <scenario> --browser-recipe webgpu --headed`.** The recipe
|
|
12
|
+
carries the Chromium flags a WebGPU capture needs, including `--enable-features=Vulkan`.
|
|
13
|
+
Do not hand-roll the flag list: without that one flag Chromium never reaches the Linux
|
|
14
|
+
Vulkan driver and serves WebGPU from SwiftShader, its CPU rasteriser — no error, healthy
|
|
15
|
+
limits, and a software renderer's picture. The runner fails such a run with
|
|
16
|
+
`TN_PLAYTEST_SOFTWARE_ADAPTER` and prints the adapter it got; `--allow-software` accepts
|
|
17
|
+
the fallback if you truly want it.
|
|
18
|
+
3. **Ask the user to look**, and say specifically what you want them to check.
|
|
19
|
+
|
|
20
|
+
## Virtual displays
|
|
21
|
+
|
|
22
|
+
On a machine with no screen, run any of those under a virtual display. **Do not use
|
|
23
|
+
`xvfb-run`:** on `xorg-server-xvfb` 21.1.x its cleanup `kill` fails after Xvfb has already
|
|
24
|
+
exited and that failing kill's status replaces the real one, so
|
|
25
|
+
`xvfb-run -a -s '-screen 0 1600x900x24' true` exits `1`. Every gate wrapped in it reports
|
|
26
|
+
failure whether it passed or not. Start `Xvfb` yourself on a free display and export
|
|
27
|
+
`DISPLAY`, or check the command's own exit code separately.
|
|
28
|
+
|
|
29
|
+
## Headless Chromium usually cannot render WebGPU
|
|
30
|
+
|
|
31
|
+
The page loads, the HUD paints, and the 3D canvas comes out blank or black. That looks
|
|
32
|
+
exactly like a bug in your scene, and it is not. Symptoms are `Instance dropped in
|
|
33
|
+
popErrorScope` and `createBuffer failed, size (N) is too large for the implementation` in
|
|
34
|
+
the console.
|
|
35
|
+
|
|
36
|
+
So: if a screenshot comes back black or empty, suspect the capture before you rewrite the
|
|
37
|
+
scene. Confirm the renderer works at all before you go debugging your materials.
|
|
38
|
+
|
|
39
|
+
## The silhouette checklist
|
|
40
|
+
|
|
41
|
+
1. **Look at it.** Boot the game, get the thing on screen, take a screenshot, open the
|
|
42
|
+
screenshot. Reading your own diff is not looking at it.
|
|
43
|
+
2. **Silhouette first.** Can you tell what it is from its outline alone? Break up long
|
|
44
|
+
straight edges — overhangs, fringes, props crossing the line.
|
|
45
|
+
3. **Give it depth.** Something bright behind it, something dark under it. Contact shadows
|
|
46
|
+
and a rim make a prop sit in the world instead of floating on top of it.
|
|
47
|
+
4. **Make it move.** Idle bob, a squash on impact, a particle on pickup, a screen shake on
|
|
48
|
+
damage. A few frames of motion is the cheapest quality-per-line in the whole project.
|
|
49
|
+
5. **Finish the HUD too.** Spacing, hierarchy, a transition on every number that changes.
|
|
50
|
+
|
|
51
|
+
When you think you are done, ask yourself, honestly: *would a player screenshot this?* If
|
|
52
|
+
the answer is no, you are not finished — and no command in this project is going to tell
|
|
53
|
+
you that.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# The ctx cookbook — recipes behind the `ctx` surface table
|
|
2
|
+
|
|
3
|
+
Companion to the `The ctx surface` section in this project's `AGENTS.md`. The table there is
|
|
4
|
+
the contract; this page is the how and the why.
|
|
5
|
+
|
|
6
|
+
## Pointer picking with `ctx.raycast()`
|
|
7
|
+
|
|
8
|
+
It defaults to the current pointer position and the whole scene, returns the nearest
|
|
9
|
+
`THREE.Intersection`, and stays under a millisecond on meshes large enough that a plain
|
|
10
|
+
`Raycaster` visibly stutters — it keeps an acceleration structure per geometry and rebuilds it
|
|
11
|
+
when that geometry's positions change. Pass `{ origin, direction }` for a world ray, `{ far }`
|
|
12
|
+
to cap its distance, `{ exclude }` to remove subtrees, and `{ targets }` to narrow it. Use
|
|
13
|
+
`raycastAll` when occlusion or another query needs every hit; results are sorted nearest first.
|
|
14
|
+
`{ screen }` tests a point that is not the pointer. Skinned, instanced and morphed meshes fall
|
|
15
|
+
back to the stock Three.js path automatically, so the result always matches
|
|
16
|
+
`Raycaster.intersectObject`.
|
|
17
|
+
|
|
18
|
+
When scene collapse runs on a large static scene, a mesh with non-empty `userData` stays as the
|
|
19
|
+
original object in the live graph. Put the target or entity metadata you already use for picking
|
|
20
|
+
on the mesh; `ctx.raycast()` then still returns that mesh and its metadata. Meshes without
|
|
21
|
+
`userData` may be merged into fewer draws.
|
|
22
|
+
|
|
23
|
+
## Scene rebuild semantics
|
|
24
|
+
|
|
25
|
+
Calling `ctx.goto("<scene-name>")` from inside the matching scene tears it down and rebuilds
|
|
26
|
+
it: `exit()` runs, scheduled callbacks are cleared, registered entities are cleared, the Three
|
|
27
|
+
scene is emptied, then a fresh instance runs `load()` and `enter()`. Values in `ctx.state` —
|
|
28
|
+
health, score, inventory, or any other game-owned state — survive this scene rebuild. When
|
|
29
|
+
death-and-retry should reset gameplay, reset your own state explicitly before calling
|
|
30
|
+
`ctx.goto()`.
|
|
31
|
+
|
|
32
|
+
Do **not** write a `#reset()` that walks your entities putting them back. It is ~15 lines that
|
|
33
|
+
look right and quietly miss the scheduler and anything you spawned after `enter()`, so the
|
|
34
|
+
second playthrough behaves differently from the first — and no gate in this project will catch
|
|
35
|
+
that.
|
|
36
|
+
|
|
37
|
+
## Timing with `ctx.tween` and `ctx.after`
|
|
38
|
+
|
|
39
|
+
**`ctx.tween` is for timing, not for looks.** Use it for the *when* — a pickup rising over
|
|
40
|
+
0.4s, a door opening, a hit flash — and keep the *what* (colour, shape, easing feel) in
|
|
41
|
+
`src/render/`. Motion driven by a persistent `Math.sin(elapsed)` in `update()` is still the
|
|
42
|
+
right tool for a continuous idle bob; `tween` is for anything that starts, runs once, and
|
|
43
|
+
finishes. `ctx.after(seconds, fn)` and `ctx.every(fn)` schedule on the same clock the scene
|
|
44
|
+
runs on; both handles are cleared when the scene exits.
|
|
45
|
+
|
|
46
|
+
## Seeded randomness
|
|
47
|
+
|
|
48
|
+
**`ctx.random` is deterministic only when `defineGame({ seed })` is configured.** Check
|
|
49
|
+
`src/game.ts`: a declared seed gives replayable values for spawn positions, patrol offsets,
|
|
50
|
+
and level variation; without one, `ctx.random` falls back to `Math.random()`. Add a fixed
|
|
51
|
+
seed when a playtest needs replayable randomness.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# The debug surface — probing a running game
|
|
2
|
+
|
|
3
|
+
The bridge globals exist but were discovered by trial: six throwaway probe scripts in one
|
|
4
|
+
day, each re-finding the shapes through TypeErrors. This page lists every global a running
|
|
5
|
+
game exposes, what it returns, and how to read it from the browser console. All of them are
|
|
6
|
+
read-only observation surfaces; none exists to drive gameplay.
|
|
7
|
+
|
|
8
|
+
## `window.__THREENATIVE__` — entity snapshot (dev builds only)
|
|
9
|
+
|
|
10
|
+
Installed by `defineGame` when the dev-server flag is on (`installDevTools`); absent in
|
|
11
|
+
production builds.
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
window.__THREENATIVE__.snapshot()
|
|
15
|
+
// → { entities: [{ id, kind?, ...entity debug fields }], ... }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`snapshot()` prefers an entity's own `debug()` and falls back to `autoFields`. This is the
|
|
19
|
+
fastest "what does the game think exists" probe; playtest assertions and the dev overlay
|
|
20
|
+
read the same registry.
|
|
21
|
+
|
|
22
|
+
## `window.__THREENATIVE_PLAYTEST_BRIDGE__` — the harness channel
|
|
23
|
+
|
|
24
|
+
Installed by `playtest()` (core plugin) or `installThreePlaytestBridge`
|
|
25
|
+
(`@threenative/playtest/three`). One object, JSON-safe in and out:
|
|
26
|
+
|
|
27
|
+
| Member | Shape | Use |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| `describe()` | `{ name, protocolVersion, capabilities, limits }` | First call. Tells you what this game's bridge supports and the protocol limits. |
|
|
30
|
+
| `ready()` | `{ ready: true }` | Liveness check before sampling. |
|
|
31
|
+
| `sample(request)` | JSON-safe observation snapshot (entities, camera, renderer stats, resources, components) | The main probe. Pass `{}` for the default sample; `request.include` names optional series such as `physicsDebugSeries`. |
|
|
32
|
+
| `advance(ticks)` | fixed-step bridges only: advances exactly N ticks and returns `{ clock, ticks }`; throws if the step count mismatches | Deterministic stepping without wall-clock waits. Throws when the bridge is render-frame. |
|
|
33
|
+
| `applySetup(request)` | applies scenario `setup` placements/resources through the registry | What scenario setup uses; also usable by hand for one-off staging. |
|
|
34
|
+
| `drainEvents(limit)` | event-queue bridges only: returns up to `limit` queued events | Reads events shorter than one state flush. |
|
|
35
|
+
|
|
36
|
+
A console one-liner that works on any bridged game:
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
await window.__THREENATIVE_PLAYTEST_BRIDGE__.describe()
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Missing global means no bridge is installed — semantic assertions against that page fail
|
|
43
|
+
`TN_PLAYTEST_BRIDGE_MISSING`, which is the harness being right, not a bug to work around.
|
|
44
|
+
|
|
45
|
+
## `window.__THREENATIVE_NATIVE__` — native host channel
|
|
46
|
+
|
|
47
|
+
Present only under the native runtime. The host injects its side; core's viewport and
|
|
48
|
+
`@threenative/playtest/three`'s device reporting read it (adapter identity, host snapshot).
|
|
49
|
+
On web this global does not exist — do not probe for it in portable code.
|
|
50
|
+
|
|
51
|
+
## Runner-side markers
|
|
52
|
+
|
|
53
|
+
Two further globals are set by tooling, not the game, and are named here so a stray
|
|
54
|
+
assignment is recognisable: `__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__` (core's playtest
|
|
55
|
+
plugin marks the expected runner contract) and `__THREENATIVE_FRAMEBUFFER_COVERAGE_PROBE__`
|
|
56
|
+
(the framebufferCoverage assertion installs its sampler). Leave both alone in game code.
|
|
57
|
+
|
|
58
|
+
## What does not exist
|
|
59
|
+
|
|
60
|
+
There is no `__THREENATIVE_SCENE__` global. Scene-graph inspection goes through
|
|
61
|
+
`sample()` (which reports counts, extents and visibility) or through your own
|
|
62
|
+
registered entities' `debug()` output — never by reaching into three.js objects from
|
|
63
|
+
the console and treating what you find as an observation surface.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Finding assets — the full MCP tool loop
|
|
2
|
+
|
|
3
|
+
Companion to the short `Finding assets` section in this project's `AGENTS.md`. Reach for the
|
|
4
|
+
asset tools when the asset is conventional; build anything specific to this game yourself in
|
|
5
|
+
`src/render/`. A fetched asset has to match what the game needs, not merely exist.
|
|
6
|
+
|
|
7
|
+
Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
|
|
8
|
+
your host lists its tools alongside your own. Your host reads that file from the directory it was
|
|
9
|
+
launched in: start the session in this project, not in a parent of it. It advertises 34; these 8
|
|
10
|
+
are the loop you will use for nearly everything:
|
|
11
|
+
|
|
12
|
+
1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
|
|
13
|
+
source with its license summary, attribution requirement, browse URL, and whether an agent
|
|
14
|
+
can complete a download from it. **That output is the authority on what is reachable** —
|
|
15
|
+
not your memory of some other project.
|
|
16
|
+
2. `polyhaven_search_assets` (CC0 models, textures, HDRIs), `ambientcg_search_assets` (CC0
|
|
17
|
+
materials and textures), or `audio_search_assets` (Kenney, Sonniss).
|
|
18
|
+
3. `polyhaven_list_files` / `ambientcg_list_files` — the license, official URL, byte size and
|
|
19
|
+
md5 of every resolution and format. **Read this before downloading, not after**, and pick a
|
|
20
|
+
sane one: Poly Haven lists 16k PNGs over 1 GB beside 8k JPEGs at 28 MB. A game does not
|
|
21
|
+
need the 16k.
|
|
22
|
+
4. `asset_download_file` for textures and models, `audio_download_asset` for audio. Both take
|
|
23
|
+
`acceptLicense: true` — you are asserting you read step 3. **They ignore any path you pass
|
|
24
|
+
and write to the directories `.mcp.json` sets** (`public/assets/<provider>/<sha>/` and
|
|
25
|
+
`public/audio/<source>/<pack>/`); without that config they would write to `~/Downloads` and
|
|
26
|
+
never reach the game.
|
|
27
|
+
5. Append the file, its source, its license and its URL to `CREDITS.md` **before the turn
|
|
28
|
+
ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
|
|
29
|
+
CC0 per asset page, and audio and bundle licenses are per pack.
|
|
30
|
+
|
|
31
|
+
**Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
|
|
32
|
+
`ambientcg_search_assets` did not tell you, you do not know it.
|
|
33
|
+
|
|
34
|
+
## What arrives is usually a ZIP, not a texture
|
|
35
|
+
|
|
36
|
+
ambientCG and Kenney ship archives: unpack one, keep only the maps you actually use (`_Color`,
|
|
37
|
+
`_NormalGL`, `_Roughness` — not the `.blend`, `.usdc` or displacement), and put those beside
|
|
38
|
+
your code under `public/`. A 1K JPEG set is right for a game; the 8K set of the same material
|
|
39
|
+
is 200 MB.
|
|
40
|
+
|
|
41
|
+
## Two argument shapes that bite
|
|
42
|
+
|
|
43
|
+
Both learned the hard way: `ambientcg_search_assets` takes lowercase `type` values (`material`,
|
|
44
|
+
`hdri`, `3d-model`), and the audio catalog is **pack-level** — `audio_search_assets` matches
|
|
45
|
+
pack names, so `query: "pickup coin"` returns nothing while `kind: "sfx"` returns the packs
|
|
46
|
+
that exist. Pick a pack, download it, unzip it, and choose a file yourself.
|
|
47
|
+
|
|
48
|
+
## Fab: searching, and importing an Unreal asset you own
|
|
49
|
+
|
|
50
|
+
Most Fab listings ship Unreal-only — 272 `.uasset` files and no `.glb` anywhere — so Fab is two
|
|
51
|
+
steps, not one: find the listing, then convert it.
|
|
52
|
+
|
|
53
|
+
**1. Search free first.** `fab_search_assets` talks to Fab's public API anonymously; no account is
|
|
54
|
+
involved. Its default `priceMode: "free"` is the right default and should stay your first query —
|
|
55
|
+
a free asset is one anybody who clones this project can fetch too.
|
|
56
|
+
|
|
57
|
+
```jsonc
|
|
58
|
+
// fab_search_assets
|
|
59
|
+
{
|
|
60
|
+
"query": "cave rocks",
|
|
61
|
+
"formats": ["unreal-engine"], // "gltf", "fbx", "obj", "unity" ... omit for every format
|
|
62
|
+
"priceMode": "any", // SEE BELOW — the default is "free"
|
|
63
|
+
"sort": "relevance", // or rating, newest, price_asc, recently_updated
|
|
64
|
+
"limit": 24
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Then look at what the account already owns.** A paid listing sitting in the library costs
|
|
69
|
+
nothing further to use, and it will never appear in a free search — `priceMode: "free"` returns a
|
|
70
|
+
different result set than `"any"` does. `fab_list_owned` answers that directly, without guessing
|
|
71
|
+
at search terms:
|
|
72
|
+
|
|
73
|
+
```jsonc
|
|
74
|
+
// fab_list_owned
|
|
75
|
+
{ "unrealOnly": true, "query": "vegetation" } // both optional; unrealOnly drops engine installs
|
|
76
|
+
// and plugins the importer cannot take
|
|
77
|
+
// -> [{ listingId, title, url, categories, engineVersions, hasUnrealArtifact }]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Reach for `priceMode: "any"` in `fab_search_assets` only when you mean to look at paid listings
|
|
81
|
+
the account does *not* own yet — buying is not something these tools can do for you.
|
|
82
|
+
|
|
83
|
+
Each item carries a `title` and an `id` — that `id` is the listing UID the next two tools take.
|
|
84
|
+
`fab_list_filters` returns the usable `formats`, `categories` and `tags` slugs; guessing them
|
|
85
|
+
silently narrows the search instead of erroring.
|
|
86
|
+
|
|
87
|
+
**2. Check the licence.** Search results carry **no licence** — Fab's search endpoint omits it, so
|
|
88
|
+
every item comes back with an empty `licenses` array. `fab_get_asset` is where the slugs live:
|
|
89
|
+
|
|
90
|
+
```jsonc
|
|
91
|
+
{ "listingIdOrUrl": "75f42402-40bb-4a1b-b557-18e2c9604273" }
|
|
92
|
+
// -> licenses: [{ slug: "personal" }, { slug: "professional" }], freeLicenseSlugs: [...]
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**3. Import.** `fab_import_asset` verifies the entitlement itself, downloads through the FabCLI
|
|
96
|
+
session, converts every static mesh, and writes source GLBs into your `assets/`:
|
|
97
|
+
|
|
98
|
+
```jsonc
|
|
99
|
+
// fab_import_asset
|
|
100
|
+
{
|
|
101
|
+
"listingIdOrUrl": "https://www.fab.com/listings/<uid>",
|
|
102
|
+
"outputDir": "assets/fab/soul-cave",
|
|
103
|
+
"packages": ["SM_S_Soul_Statue"], // omit to convert every static mesh — packs run to gigabytes
|
|
104
|
+
"maxTextureSize": 2048, // omit to keep Unreal's own resolution
|
|
105
|
+
"acceptFabEula": true
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Then load the returned path the ordinary way:
|
|
110
|
+
`ctx.assets.model("fab/soul-cave/.../SM_S_Soul_Statue.glb")`. The normal asset compiler picks the
|
|
111
|
+
GLBs up from `assets/` with no extra configuration.
|
|
112
|
+
|
|
113
|
+
What the import will and will not do:
|
|
114
|
+
|
|
115
|
+
- **Only assets you already own**, and only under **Fab Standard (Personal or Professional) or
|
|
116
|
+
CC-BY**. Unreal-Engine-only and legacy entitlements are refused, and a licence it cannot read is
|
|
117
|
+
refused too. It never logs in, claims, or purchases — run `fabcli auth login` yourself once.
|
|
118
|
+
Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
|
|
119
|
+
authenticated path it is guarding.
|
|
120
|
+
- **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
|
|
121
|
+
`THREENATIVE_TOOLCHAIN_AUTOINSTALL=0` to require you install them instead. Linux and Windows only.
|
|
122
|
+
- **`packages` is not optional in practice.** A marketplace pack converts to many gigabytes of
|
|
123
|
+
GLBs; name the handful of meshes your scene uses. Run it once without `packages` against a
|
|
124
|
+
scratch directory if you need to see what a pack contains, then re-run with the names.
|
|
125
|
+
- **Read `import-report.json` before trusting the result.** It reports `materials: "complete"` or
|
|
126
|
+
`"degraded"`, counts textured against total sections, and names every mesh it skipped and every
|
|
127
|
+
texture it could not map. Unreal shader graphs have no glTF equivalent, so some sections arrive
|
|
128
|
+
with a neutral grey and say so. `.umap` levels, Blueprints, Niagara and foliage placement are
|
|
129
|
+
reported as unsupported, never silently dropped.
|
|
130
|
+
- `asset_import_unreal` takes a local `sourceDir` instead of a listing, for a pack you already
|
|
131
|
+
downloaded by any means.
|
|
132
|
+
|
|
133
|
+
`fab_download_free_asset` is the unrelated older path: it downloads a directly-available free
|
|
134
|
+
`glb`/`fbx`/`obj`/`unity` file with no account at all. Use it when the listing already ships a
|
|
135
|
+
format you can load, and the importer only when it does not.
|
|
136
|
+
|
|
137
|
+
## The narrower tools
|
|
138
|
+
|
|
139
|
+
The directory spells out the conditions on each. The Fab tools are covered above; the server
|
|
140
|
+
never purchases anything on any path. `smithsonian_search_assets` returns museum scans at scan resolution, which this project has no
|
|
141
|
+
pipeline to decimate — that geometry is the wrong shape for a game. When in doubt check
|
|
142
|
+
`asset_search_sources` first; its `caution` and license fields are the current truth for the
|
|
143
|
+
pinned version, and they change between versions.
|
|
144
|
+
|
|
145
|
+
Load what you downloaded the ordinary way — `ctx.assets.model("crate.glb")`,
|
|
146
|
+
`ctx.assets.texture(...)`, `ctx.assets.audio(...)` — and write your own material and lighting
|
|
147
|
+
around it in `src/render/`. The framework ships no asset and picks none for you.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Gameplay recipes — movement, input, physics-step timing, and saves
|
|
2
|
+
|
|
3
|
+
Companion to the gameplay sections in this project's `AGENTS.md`.
|
|
4
|
+
|
|
5
|
+
## Forward is -z, and the mapping happens once
|
|
6
|
+
|
|
7
|
+
`input.vector("move").y` is +up; map it to world-space -z for forward with one explicit
|
|
8
|
+
`-move.y` conversion in the player movement code. One conversion site per entity — a second
|
|
9
|
+
one flips the controls.
|
|
10
|
+
|
|
11
|
+
## A gamepad already drives this game
|
|
12
|
+
|
|
13
|
+
`vector` adds the left stick to the action literally named `move`, and
|
|
14
|
+
`jump: { buttons: [0] }` in `src/game.ts` is that pad's south face button — `buttons` is the
|
|
15
|
+
gamepad, `mouseButtons` is the mouse. Two consequences worth knowing before you debug either:
|
|
16
|
+
the stick reaches **only** an action called `move`, so renaming that action or adding a second
|
|
17
|
+
stick-driven one (a `look` axis, say) gets you nothing, and there is no deadzone, so a worn
|
|
18
|
+
stick's resting drift is added every frame and the character creeps. Subtract your own deadzone
|
|
19
|
+
in the entity if that shows up.
|
|
20
|
+
|
|
21
|
+
## moveAndSlide queues motion for the shared physics step
|
|
22
|
+
|
|
23
|
+
`CharacterBody3D.moveAndSlide(dt)` owns gravity through `body.velocity` and queues motion for
|
|
24
|
+
the shared bulk physics step rather than moving its object immediately. Because
|
|
25
|
+
`THREE.Vector3` is mutable, use `const before = mesh.position.clone()` (or copy its `x`, `y`,
|
|
26
|
+
and `z` scalars) before the call, then compare `mesh.position.distanceTo(before)` on the next
|
|
27
|
+
update, after the step. Storing `mesh.position` itself aliases the live transform and reports
|
|
28
|
+
zero. Keep coyote-time and jump-buffer timers in the entity so jump feel stays game-owned.
|
|
29
|
+
|
|
30
|
+
## Save only declared state
|
|
31
|
+
|
|
32
|
+
The framework does not serialize entities, scene graphs, or physics handles, and it never
|
|
33
|
+
will; save those fields in your own object literal:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
const save = JSON.stringify({ state: ctx.state.getState(), playerX: player.mesh.position.x });
|
|
37
|
+
const loaded = JSON.parse(save) as { state: GameState; playerX: number };
|
|
38
|
+
ctx.state.set(loaded.state);
|
|
39
|
+
player.body.teleport({ x: loaded.playerX, y: player.mesh.position.y, z: player.mesh.position.z });
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Hot reload carries JSON-shaped state only
|
|
43
|
+
|
|
44
|
+
`main.ts` calls `acceptHotUpdate(game, import.meta.hot)` for development reloads. The
|
|
45
|
+
framework preserves only store state; seed entities from the carried values such as
|
|
46
|
+
`playerX` in `enter()`, because the scene graph, physics world, audio voices, particles, and
|
|
47
|
+
renderer are rebuilt on every update.
|
|
48
|
+
|
|
49
|
+
## The state bridge throttles
|
|
50
|
+
|
|
51
|
+
The bridge flushes every 100 ms by default: write `ctx.state.set({...})` from `update()` at
|
|
52
|
+
loop rate — it coalesces — and read it from HUD components at ~10 Hz. Per-frame visual
|
|
53
|
+
feedback belongs in scene-owned Three.js objects. If an event must appear in the HUD, give
|
|
54
|
+
it a decay longer than one flush interval.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Menu screens: scenes are the screens
|
|
2
|
+
|
|
3
|
+
Use a scene for every screen that needs a world, camera, lighting, or ordinary Three.js art. Put
|
|
4
|
+
the chrome in `src/ui/` so the same React tree runs beside the web canvas and in the native web
|
|
5
|
+
view.
|
|
6
|
+
|
|
7
|
+
## The flow
|
|
8
|
+
|
|
9
|
+
1. Give the menu scene a static `initialState` with `screen: "menu"` and all fields the game
|
|
10
|
+
state needs.
|
|
11
|
+
2. Render a form in a UI component with `useUiState` and `useUiIntent`. Mark every input and
|
|
12
|
+
button with `data-tn-interactive`.
|
|
13
|
+
3. Validate the intent payload in `src/game.ts`. The game owns the transition:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
if (intent === "start-game" && name.length > 0) {
|
|
17
|
+
void game.goto("play", { carry: { characterName: name } });
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`game.goto()` resets to the destination scene's `initialState`, then merges the serializable
|
|
22
|
+
`carry` patch. `ctx.goto()` rebuilds without resetting state; use it only when the current run
|
|
23
|
+
should survive the rebuild.
|
|
24
|
+
|
|
25
|
+
4. Give the played scene its own initial state with `screen: "playing"`. The carried values are
|
|
26
|
+
available in `enter()` through `ctx.state.getState()` and are also visible to the UI and
|
|
27
|
+
playtest bridge.
|
|
28
|
+
5. Switch the chrome from the published `screen` value. The menu component returns `null` outside
|
|
29
|
+
the menu, and the HUD/menu bar return `null` outside play.
|
|
30
|
+
|
|
31
|
+
## Add a settings screen
|
|
32
|
+
|
|
33
|
+
To insert settings between the menu and play screens, extend the state union with `"settings"`,
|
|
34
|
+
add a `Settings` scene whose `initialState.screen` is `"settings"`, and add a `SettingsUi` form
|
|
35
|
+
that follows the same `useUiState`/`useUiIntent` pattern. Register the scene, render the form
|
|
36
|
+
when `screen === "settings"`, and keep navigation in `src/game.ts`:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
if (intent === "open-settings") void game.goto("settings");
|
|
40
|
+
if (intent === "start-game") {
|
|
41
|
+
void game.goto("play", { carry: { characterName: name, difficulty } });
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The menu's settings button and the settings form's start button both carry
|
|
46
|
+
`data-tn-interactive`. Prove the complete flow with viewport-pixel clicks and assert the carried
|
|
47
|
+
settings resource after the final scene transition.
|
|
48
|
+
|
|
49
|
+
## Prove it with a click scenario
|
|
50
|
+
|
|
51
|
+
`click` uses viewport pixels and emits a real pointer-down/up pair on the web target:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{ "kind": "click", "at": { "x": 640, "y": 365 }, "label": "name-field" }
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Click the form field, use ordinary `input` steps for the text, click submit, then assert the
|
|
58
|
+
carried value through `resources`:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{ "equals": "axo", "id": "state", "path": "characterName" }
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The bridge samples the state after the transition settles. A missing bridge or an unobserved
|
|
65
|
+
entity click target is a named failure, never a skipped step.
|
|
66
|
+
|
|
67
|
+
The native renderer draws quads and has no text input today. Form screens therefore use the shared
|
|
68
|
+
webview UI; `ui: { renderer: "native" }` is appropriate only when the screen does not need text
|
|
69
|
+
entry.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# What memory a phone actually gives you
|
|
2
|
+
|
|
3
|
+
Everything here was measured on a **physical Pixel 8** (Mali-G715, Vulkan, 2400x1080 surface) on
|
|
4
|
+
2026-08-23, running a real game through this framework. No estimates, no emulator.
|
|
5
|
+
|
|
6
|
+
## The headline
|
|
7
|
+
|
|
8
|
+
The game asked the GPU for 393 MiB of textures and buffers. Here is what that turned into:
|
|
9
|
+
|
|
10
|
+
| | |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| What the game asked `createTexture`/`createBuffer` for | 393 MiB |
|
|
13
|
+
| What the driver held (`dumpsys meminfo`: `GL mtrack` + `EGL mtrack`) | ~899 MiB |
|
|
14
|
+
| Process `VmRSS` | ~1.4 GiB |
|
|
15
|
+
|
|
16
|
+
That looks like the driver doubling everything you allocate. **It is not.** About **480 MiB was
|
|
17
|
+
already held at the first presented frame**, before the game had uploaded a single texture, and
|
|
18
|
+
across the entire asset load the driver then grew by *less* than the game requested.
|
|
19
|
+
|
|
20
|
+
So budget like this:
|
|
21
|
+
|
|
22
|
+
> **a ~500 MiB fixed floor, plus roughly the bytes you ask for.**
|
|
23
|
+
|
|
24
|
+
Not as a multiplier on your own textures. The practical consequence is that shaving 50 MiB off
|
|
25
|
+
your textures really does save about 50 MiB — but you start 500 MiB in the hole, and a phone
|
|
26
|
+
begins killing apps well under 2 GiB.
|
|
27
|
+
|
|
28
|
+
## Your sky is charged twice, and the second charge is the expensive one
|
|
29
|
+
|
|
30
|
+
Assigning one equirect to both `scene.background` and `scene.environment` looks free. It is not.
|
|
31
|
+
`scene.environment` builds an image-based light, and three.js sizes that light's render targets
|
|
32
|
+
from the **source equirect's width** — `cubeSize = width / 4`, rounded *down* to a power of two,
|
|
33
|
+
then two render targets of `3 x max(cubeSize, 112)` by `4 x cubeSize` in `rgba16float`.
|
|
34
|
+
|
|
35
|
+
Measured, on a real WebGPU adapter:
|
|
36
|
+
|
|
37
|
+
| equirect width | PMREM pair allocated | cost |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| 3072 | 1536x2048 rgba16float x2 | **48 MiB** |
|
|
40
|
+
| 2048 | 1536x2048 rgba16float x2 | **48 MiB** |
|
|
41
|
+
| 1024 | 768x1024 rgba16float x2 | **12 MiB** |
|
|
42
|
+
| 512 | 384x512 rgba16float x2 | **3 MiB** |
|
|
43
|
+
|
|
44
|
+
Two things fall out of that table.
|
|
45
|
+
|
|
46
|
+
**Halving a 3072 sky to 2048 saves nothing.** The cost moves in power-of-two steps, so only
|
|
47
|
+
crossing a step changes anything. Resizing an asset "a bit smaller" is wasted work.
|
|
48
|
+
|
|
49
|
+
**Split the two uses.** The background is what the player looks at and wants every pixel it has.
|
|
50
|
+
The light does not: PMREM immediately convolves its source into roughness mips, so everything it
|
|
51
|
+
contributes is low-frequency, and the only detail that survives is a mirror reflection. Give the
|
|
52
|
+
environment its own smaller copy of the same image:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// One 3072-wide photograph, downsampled once to 1024 for the light.
|
|
56
|
+
scene.background = skyEquirect; // full resolution — this is the visible sky
|
|
57
|
+
scene.environment = skyEquirectSmall; // 1024x512 copy — this is only ever blurred
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
That is 36 MiB back for a 2.7 MiB texture, with nothing visible changing. Pick 1024 over 512 if
|
|
61
|
+
your scene has polished metal or still water in it, since 512 halves the mirror again.
|
|
62
|
+
|
|
63
|
+
**Do this before you reach for texture compression.** It is one line, it costs nothing at
|
|
64
|
+
runtime, and it is larger than most compression wins on a small texture set.
|
|
65
|
+
|
|
66
|
+
## Where the rest of your budget goes
|
|
67
|
+
|
|
68
|
+
Ordinary things that are bigger than people expect, all from the same measured run:
|
|
69
|
+
|
|
70
|
+
- **Full-screen render targets scale with your device's real resolution, not your design
|
|
71
|
+
resolution.** At 2400x1080 a single `rgba16float` colour target is 19 MiB and a `depth24plus`
|
|
72
|
+
is 9.5 MiB. Post-processing chains multiply that by how many you keep alive.
|
|
73
|
+
- **Mip chains add a third.** A 2048x2048 `rgba8unorm-srgb` with a full mip pyramid is 21 MiB,
|
|
74
|
+
not 16 MiB. Eight 1024x1024 maps with mips are 42 MiB between them.
|
|
75
|
+
- **Buffers are almost never the problem.** In that run, 3038 buffers came to 14 MiB total —
|
|
76
|
+
under 4 % of the footprint. Do not spend your optimisation budget there.
|
|
77
|
+
- **A cubemap conversion is not free.** Setting `scene.background` to an equirect makes the
|
|
78
|
+
renderer build a cubemap from it; at 3072x1536 that cubemap was 54 MiB on its own, separate
|
|
79
|
+
from the 23 MiB source texture and separate again from the image-based light.
|
|
80
|
+
|
|
81
|
+
## How to check your own game
|
|
82
|
+
|
|
83
|
+
On native, the runtime prints its own accounting beside the present tick — watch `logcat` for
|
|
84
|
+
`TN_GPU_TEXTURES` and `TN_GPU_BUFFERS`, which bucket every texture by dimensions, format and mip
|
|
85
|
+
count so you can see which allocation is the big one rather than guessing. Read those numbers as
|
|
86
|
+
*what the game requested*; the driver's own total is a separate figure, and the floor above is why
|
|
87
|
+
the two never match.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Building what you cannot download — sculpt from a reference
|
|
2
|
+
|
|
3
|
+
Companion to the short `Building what you cannot download` section in this project's
|
|
4
|
+
`AGENTS.md`.
|
|
5
|
+
|
|
6
|
+
## Choose one branch before writing code
|
|
7
|
+
|
|
8
|
+
- **Conventional and downloadable** — a crate, an oak plank texture, a click. Use the asset
|
|
9
|
+
tools. Sculpting one of these is slower and worse.
|
|
10
|
+
- **Trivial** — a platform, a wall, a pickup ring. Write it. If `BoxGeometry` finishes the
|
|
11
|
+
job in under 20 lines, that is the answer.
|
|
12
|
+
- **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
|
|
13
|
+
landmark, scenery composition, or environment set piece whose silhouette must match. Use
|
|
14
|
+
the sculpt tools to turn that reference into editable `src/render/` source.
|
|
15
|
+
- **Bespoke, without a reference image** — ask for one, or write it and accept that it will
|
|
16
|
+
be generic. Do not invent a reference: comparison without evidence is unguided iteration.
|
|
17
|
+
|
|
18
|
+
For a full environment, split the decision: sculpt the signature landmark or bounded scene
|
|
19
|
+
kit that makes the reference recognisable; use the asset tools for interchangeable trees,
|
|
20
|
+
rocks, textures, HDRIs, and sounds around it. Do not sculpt an entire world as one object.
|
|
21
|
+
|
|
22
|
+
## The gate loop
|
|
23
|
+
|
|
24
|
+
`.mcp.json` launches `threenative-sculpt-mcp` beside the asset server. It does not generate
|
|
25
|
+
or ship runtime code; it guides the source you write:
|
|
26
|
+
|
|
27
|
+
1. Call `sculpt_plan` with the image path and a one-line intent, then read the returned
|
|
28
|
+
grimoire resources.
|
|
29
|
+
2. Write the returned object contract and loop on `sculpt_spec_gate` until every named
|
|
30
|
+
region and depth requirement passes. Do not write geometry before this gate is green.
|
|
31
|
+
3. For each ordered pass, write or extend one factory in `src/render/`. Capture the real
|
|
32
|
+
frame with `npx @threenative/playtest`; the sculpt server never launches a browser.
|
|
33
|
+
4. Call `sculpt_compare` with the reference and captured frame, then give that evidence to
|
|
34
|
+
`sculpt_pass_gate`. Advance only when it says advance; ambiguity means retry.
|
|
35
|
+
5. Use `sculpt_grimoire` for a named technique topic. It rejects pages containing concrete
|
|
36
|
+
paste-ready material or shader recipes so the tool never owns this game's look.
|
|
37
|
+
|
|
38
|
+
A missing or blank capture is a failed run, never a finished model. Add the reference image,
|
|
39
|
+
its creator, license, and source URL to `CREDITS.md` before the turn ends.
|