create-threenative 0.2.2 → 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,133 @@
|
|
|
1
|
+
# Visual baseline — what each `src/render/` file ships, and the traps
|
|
2
|
+
|
|
3
|
+
Companion to the `Visuals` section in this project's `AGENTS.md`. Everything here is ordinary
|
|
4
|
+
Three.js source in this project, yours to rewrite or delete.
|
|
5
|
+
|
|
6
|
+
## What is already there, so you do not rebuild it
|
|
7
|
+
|
|
8
|
+
- `shapes.ts` — `roundedBox`, `block`, `ball`, `tube`, `spike`. **Build props out of these,
|
|
9
|
+
not raw `BoxGeometry`.** A sharp box reads as Minecraft; the same box with a 0.14 corner
|
|
10
|
+
radius reads as a toy, and that is most of the difference between a scene that looks
|
|
11
|
+
designed and one that looks like a test harness. For the seeded randomness that varies a
|
|
12
|
+
run of meshes, the scene builds `createRandom(seed)` and passes it down — nothing in
|
|
13
|
+
`src/render/` may import a framework package, which is what keeps this folder portable.
|
|
14
|
+
- `lighting.ts` — key, sky/ground bounce, **rim**, ambient, with soft shadows and a
|
|
15
|
+
`normalBias` tuned for rounded geometry. The rim is what stops silhouettes reading as
|
|
16
|
+
flat cut-outs; do not delete it while "simplifying".
|
|
17
|
+
- `camera.ts` — `createSpringArm`, a frame-rate-independent follow camera. Its offset and its
|
|
18
|
+
**lead** are the framing: the default aims ahead of the character rather than centring it,
|
|
19
|
+
because a level that runs one way puts half the picture behind the player otherwise.
|
|
20
|
+
- `postprocessing.ts` — the editable presets and `setupPost` delegation.
|
|
21
|
+
- `worldEnvironment.ts` — the editable Godot-named render chain: tone mapping/exposure and
|
|
22
|
+
optional TSL stages, with `createRenderChain` reporting applied or refused stages.
|
|
23
|
+
- `scenery.ts` — `createScenery`, the collider-free half of the world: columns under ledges,
|
|
24
|
+
spires in the middle distance, an unlit ridge on the horizon. **Keep something in all three
|
|
25
|
+
bands.** A lit floor alone in black reads as a test fixture no matter how good the floor
|
|
26
|
+
is, and it is the single cheapest thing to fix in a first screenshot.
|
|
27
|
+
|
|
28
|
+
## Traps
|
|
29
|
+
|
|
30
|
+
Each of these has cost real debugging time. All of them fail *silently* — nothing in
|
|
31
|
+
typecheck, lint, or a playtest catches one, and several look exactly like "the effect is on
|
|
32
|
+
and does nothing".
|
|
33
|
+
|
|
34
|
+
1. **`CanvasTexture` samples black under `WebGPURenderer`.** Procedurally painting a canvas
|
|
35
|
+
and using it as a `map` produces a black surface, silently. Get variety from alternating
|
|
36
|
+
material colours across a run of meshes instead, or from `softCircleDataTexture`, which
|
|
37
|
+
writes sprite pixels straight into a `DataTexture` and is the framework's way around this.
|
|
38
|
+
2. **`flatShading` fights `roundedBox`,** which welds its seams precisely so normals
|
|
39
|
+
interpolate across them. Do not set both.
|
|
40
|
+
3. **Import a render module and then call it.** `setupPost` and `setupLighting` are inert
|
|
41
|
+
if the scene only imports them.
|
|
42
|
+
|
|
43
|
+
### TSL post-processing stages that install and then do nothing
|
|
44
|
+
|
|
45
|
+
4. **`SSRNode.maxDistance` defaults to `1` — one world unit.** On any scene larger than a
|
|
46
|
+
tabletop every reflection ray dies after a metre and returns nothing, on every pixel. This
|
|
47
|
+
reads as "screen-space reflections are on and have no effect". Set it to the distance across
|
|
48
|
+
the scene you actually want reflected.
|
|
49
|
+
5. **`reflectNonMetals` defaults to `false`.** A polished stone, wood, or painted floor is not
|
|
50
|
+
metal, so by default it never reflects — only metals do. A polished floor is the usual
|
|
51
|
+
reason to reach for SSR at all, so this default silently removes the effect you wanted.
|
|
52
|
+
`roughnessNode` left `null` is the mirror-image mistake: every surface is then treated as a
|
|
53
|
+
perfect mirror.
|
|
54
|
+
6. **Do not swizzle the normal you hand a pass.** `ssr()` calls `.sample()` on that node, so it
|
|
55
|
+
needs the whole `TextureNode` from the MRT target; `normal.xyz` produces a plain vec3 and the
|
|
56
|
+
pass dies at shader build with `this.normalNode.sample is not a function`. `@types/three`
|
|
57
|
+
declares the parameter as `Node<"vec3">`, which is exactly what makes the swizzle look
|
|
58
|
+
correct — the types are wrong here and the runtime is right.
|
|
59
|
+
7. **A dangling graph branch renders a blank frame.** When a pass needs a *texture* rather than
|
|
60
|
+
an expression, materialise the chain **once** with `convertToTexture` and reuse that texture
|
|
61
|
+
on both sides of the composite. Passing `convertToTexture(lit)` into the pass while adding
|
|
62
|
+
its result back onto the unconverted `lit` builds two parallel copies of the same graph, one
|
|
63
|
+
rendered into a target and one not — and whether the frame appears then depends on whether
|
|
64
|
+
some *other* stage happens to re-materialise the second copy. Measured on a real scene: it
|
|
65
|
+
rendered with bloom on, rendered with SSR off, rendered with godrays off, and came back as
|
|
66
|
+
the bare background colour only when all three conditions lined up. That is what a dangling
|
|
67
|
+
branch looks like from the outside, and it is not a driver bug.
|
|
68
|
+
|
|
69
|
+
Nothing in the toolchain can see your game. `pnpm test` proves behaviour, never the look —
|
|
70
|
+
so when you change something visual, actually look at it before reporting it done.
|
|
71
|
+
|
|
72
|
+
## The chain, in order — and what each stage costs
|
|
73
|
+
|
|
74
|
+
`postprocessing.ts` builds a `WorldEnvironment` and hands its stages to the engine's render
|
|
75
|
+
chain, which sorts them into one canonical order. The order is not a preference:
|
|
76
|
+
|
|
77
|
+
1. **ambient occlusion** and **SSGI** gather, because both read the depth and normal buffers the
|
|
78
|
+
scene pass wrote and neither can read a composited image.
|
|
79
|
+
2. **denoise** runs inside the gather stage on its AO and GI terms, before they are added to the
|
|
80
|
+
beauty pass — denoising the composite instead smears the geometry it was meant to preserve.
|
|
81
|
+
3. **godrays**, then **SSR**, which add light rather than remove it, so they see the frame the
|
|
82
|
+
gather has already occluded and lit.
|
|
83
|
+
4. **sharpen**, because RCAS is defined on the finished picture and sharpening before bloom
|
|
84
|
+
sharpens edges that bloom then spreads back out.
|
|
85
|
+
5. **bloom**, then **vignette**, then the tone curve — the last thing the frame meets.
|
|
86
|
+
|
|
87
|
+
Exposure is applied as a multiply on the scene pass, ahead of every stage, so the gather, the
|
|
88
|
+
reflections and the bloom threshold all see the same exposed image. `renderer.toneMappingExposure`
|
|
89
|
+
is live too and reaches the frame at the same point, but only when no output node is installed;
|
|
90
|
+
with any stage running, the multiply is the shutter.
|
|
91
|
+
|
|
92
|
+
### Cost
|
|
93
|
+
|
|
94
|
+
Measured on a dense interior (a sandbox cathedral, not one of these templates) at 1600x900 on a
|
|
95
|
+
desktop RTX 2080, browser WebGPU, as GPU time per frame — `gpuMs` in `TN_FRAME_BUDGET`, not the
|
|
96
|
+
CPU `render` phase, which reads ~5.5 ms while the GPU frame is 14.7 ms and therefore cannot see
|
|
97
|
+
this at all:
|
|
98
|
+
|
|
99
|
+
| configuration | gpuMs | fps |
|
|
100
|
+
| --- | --- | --- |
|
|
101
|
+
| every stage on | 14.7 | 56.8 |
|
|
102
|
+
| minus SSGI + denoise | 5.5 | 126.3 |
|
|
103
|
+
| minus SSR | 10.6 | 77.0 |
|
|
104
|
+
| minus bloom | 10.1 | 72.4 |
|
|
105
|
+
| minus denoise only | 12.8 | 60.3 |
|
|
106
|
+
| every stage off | 2.2 | 333.3 |
|
|
107
|
+
|
|
108
|
+
The scene, its shadow map and the overlay together cost 2.2 ms of that frame; the chain costs the
|
|
109
|
+
other 12.5. **SSGI is the expensive one by a wide margin** — the gather is ~7.3 ms and its two
|
|
110
|
+
full-resolution denoise passes ~1.9 ms at `medium` — which is why `ssgiQuality: "high"` (3 slices
|
|
111
|
+
x 16 steps) and full-resolution SSR are the two knobs to reach for first when a frame is late.
|
|
112
|
+
Godrays measured ~0.0 ms here and are off by default for a different reason: a shaft needs a sun,
|
|
113
|
+
an occluder and interior air to read at all, and none of these templates is an interior.
|
|
114
|
+
|
|
115
|
+
Your scene is not this one. Read your own numbers out of `TN_FRAME_BUDGET` before believing any
|
|
116
|
+
row above applies to it.
|
|
117
|
+
|
|
118
|
+
### Turning a stage on
|
|
119
|
+
|
|
120
|
+
Every stage that ships off is one property in the preset object in `postprocessing.ts`:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
gtaoEnabled: true, // contact occlusion in the crevices SSGI's room-scale gather misses
|
|
124
|
+
godraysEnabled: true, // needs the shadow-casting light setupLighting returns; interiors only
|
|
125
|
+
vignetteAmount: 0.25, // corner darkening, as the fraction removed at the extreme corner
|
|
126
|
+
ssgiEnabled: true, // also for mobile: add it to mobilePreset and measure the result
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`TN_WORLD_ENVIRONMENT` prints every run and names each stage as applied, or refused **with a
|
|
130
|
+
reason** — `godraysEnabled is false`, `light 'sun' does not cast shadows`, `renderer:webgl2`. A
|
|
131
|
+
stage you turned on that is not in that line as `applied: true` did not run, and the reason says
|
|
132
|
+
why. An unknown `ssgiQuality` or `tonemapMode` throws at construction rather than quietly
|
|
133
|
+
becoming the default.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# The UI layer — one `src/ui/` in a web view, on every platform
|
|
2
|
+
|
|
3
|
+
`src/ui/` is the whole UI and the same source on every target. On web it is a React tree beside
|
|
4
|
+
the canvas. On native it is the same React tree, loaded by **the platform's own browser-class
|
|
5
|
+
renderer** into a transparent surface composited over the game — not a browser the framework
|
|
6
|
+
ships, and never the game itself. The scene stays in the native runtime; only the UI crosses.
|
|
7
|
+
|
|
8
|
+
| target | what loads `src/ui/main.tsx` | status |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| web | the page itself, beside `GameCanvas` | shipped |
|
|
11
|
+
| Android | a transparent `WebView` over the SDL surface | shipped, proven on a Pixel 8 |
|
|
12
|
+
| desktop (Linux) | a transparent WebKitGTK window over the game window | shipped |
|
|
13
|
+
| desktop (Windows, macOS) | — | no host yet; use `ui: { renderer: "native" }` |
|
|
14
|
+
| iOS | a transparent `WKWebView` over the Metal layer | written, **unproven on hardware** |
|
|
15
|
+
|
|
16
|
+
Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
|
|
17
|
+
and no extra process, and draws `View`/`Text` quads inside the rendered frame instead.
|
|
18
|
+
|
|
19
|
+
## Two things cross the boundary, and nothing else
|
|
20
|
+
|
|
21
|
+
On native the UI is a different process from the game. It cannot hold the game object, call
|
|
22
|
+
`game.pause()`, or import a scene. It reads **published state** and sends **intents**.
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import { UiLayer, useUiIntent, useUiState } from "@threenative/ui";
|
|
26
|
+
|
|
27
|
+
function Hud() {
|
|
28
|
+
const state = useUiState<GameState>();
|
|
29
|
+
const send = useUiIntent();
|
|
30
|
+
// The web view loads this page before the game has run a tick, so this is the normal first
|
|
31
|
+
// paint rather than an error path.
|
|
32
|
+
if (state === undefined) return null;
|
|
33
|
+
return (
|
|
34
|
+
<button data-tn-interactive onClick={() => send("restart")}>
|
|
35
|
+
restart · {state.score}
|
|
36
|
+
</button>
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`src/game.ts` decides what an intent means. This is the whole of the game side:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
game.ui.onIntent((intent, payload) => {
|
|
45
|
+
if (intent === "restart") void game.goto("play");
|
|
46
|
+
if (intent === "pause") game.pause();
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
State flows the other way by itself: whatever the scene writes with `ctx.state.set(...)` is
|
|
51
|
+
published to the UI. It is serialised to compare frames, so keep it small — live numbers, not
|
|
52
|
+
level geometry. Static data the UI needs (a minimap's layout, a weapon table) belongs in a module
|
|
53
|
+
both sides import, and that module must not import `three`, or the renderer lands in the UI
|
|
54
|
+
bundle. If a value only the game can compute must reach the UI, publish it as state.
|
|
55
|
+
|
|
56
|
+
## `data-tn-interactive` is how a press finds its owner
|
|
57
|
+
|
|
58
|
+
Mark every element the player presses. The page publishes those rectangles, normalised to the
|
|
59
|
+
viewport, and the **host** decides on pointer-down whether the press belongs to the UI or falls
|
|
60
|
+
through to the game.
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
<button data-tn-interactive onClick={fire}>fire</button> // takes the press
|
|
64
|
+
<div className="score">{score}</div> // scenery; the press reaches the game
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`pointer-events: none` is **not** the mechanism and cannot be. The platform hands the gesture to
|
|
68
|
+
the web view before any CSS runs; by the time the page could refuse it, the game has already
|
|
69
|
+
missed it.
|
|
70
|
+
|
|
71
|
+
Rectangles are republished while anything moves — a CSS transition, a resize, an element
|
|
72
|
+
appearing — so a button is hit where it is *drawn*, not where it started. You do not call
|
|
73
|
+
anything to make that happen; `UiLayer` observes the tree.
|
|
74
|
+
|
|
75
|
+
## What breaks, and what it looks like
|
|
76
|
+
|
|
77
|
+
Every one of these shipped at least once here, and none of them failed a build.
|
|
78
|
+
|
|
79
|
+
- **A `body` background.** `src/ui/main.tsx` imports your stylesheet, and on native that page is
|
|
80
|
+
composited over the game. `body { background: … }` is an opaque sheet over the frame the game
|
|
81
|
+
just rendered — the HUD looks right and the game is gone. Put the page backdrop on `#root`,
|
|
82
|
+
which exists only in the web document.
|
|
83
|
+
- **Absolute asset URLs.** The UI is served from a subdirectory. A `/assets/app.js` resolves
|
|
84
|
+
outside it and 404s, and the page renders nothing at all — no error, no HUD.
|
|
85
|
+
- **Importing game code.** It works on web and drags the renderer into the UI bundle on native.
|
|
86
|
+
The rule that keeps you honest: `src/ui/` may import types and plain data, never a scene, an
|
|
87
|
+
entity, or anything that imports `three`.
|
|
88
|
+
- **Assuming the first render has state.** It does not. Return `null` until it arrives.
|
|
89
|
+
|
|
90
|
+
## Watching it work
|
|
91
|
+
|
|
92
|
+
Markers, all greppable from the game's output (`adb logcat` on Android):
|
|
93
|
+
|
|
94
|
+
| marker | means |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| `TN_UI_OVERLAY:{"attached":true}` | the host brought the web view up and the page reached it |
|
|
97
|
+
| `TN_UI_OVERLAY:{"attached":false,…}` | it did not, and `reason` says why |
|
|
98
|
+
| `TN_UI_HIT_REGIONS:{"count":N}` | the page published N interactive rectangles |
|
|
99
|
+
|
|
100
|
+
`attached` stays false until the page sends its first message, so a false here means the page
|
|
101
|
+
never loaded — look at the page, not at the host.
|
|
102
|
+
|
|
103
|
+
**The page's console does not reach the game's stdout on desktop.** A `console.log` in a UI
|
|
104
|
+
component is invisible there. Report through an intent when you need to see something, or open the
|
|
105
|
+
same `src/ui/` in a browser, where it is an ordinary page with ordinary devtools.
|
|
106
|
+
|
|
107
|
+
## Proving it
|
|
108
|
+
|
|
109
|
+
A `--target android` playtest drives the real build and asserts what the game received: a press on
|
|
110
|
+
empty HUD space must reach the game, a press on a published rectangle must not, and a drag that
|
|
111
|
+
starts on the game and crosses a button must stay with the game. Assert the game's own counters —
|
|
112
|
+
`pointerDowns`, the intents it handled — rather than what the UI shows, which is the half that can
|
|
113
|
+
lie about the half you care about.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
## Building what you cannot download — sculpt from a reference
|
|
2
|
+
|
|
3
|
+
Choose one branch before writing code: conventional and downloadable — use the asset tools;
|
|
4
|
+
trivial (a platform, a wall) — write it, `BoxGeometry` under 20 lines is the answer; bespoke
|
|
5
|
+
with a reference image — the sculpt tools below; bespoke without one — ask for it, never
|
|
6
|
+
invent a reference.
|
|
7
|
+
|
|
8
|
+
`.mcp.json` launches `threenative-sculpt-mcp`; it does not ship runtime code, it guides the
|
|
9
|
+
source you write: plan with `sculpt_plan`, loop on `sculpt_spec_gate` until every named region
|
|
10
|
+
passes **before writing geometry**, write one factory per pass in `src/render/`, prove each
|
|
11
|
+
pass with `sculpt_compare` plus `sculpt_pass_gate` against a real captured frame (the sculpt
|
|
12
|
+
server never launches a browser), and pull technique topics from `sculpt_grimoire`.
|
|
13
|
+
|
|
14
|
+
A missing or blank capture is a failed run, never a finished model. Add the reference image,
|
|
15
|
+
its creator, license, and source URL to `CREDITS.md` before the turn ends. The branch
|
|
16
|
+
definitions and environment-splitting guidance are `agent-docs/sculpt-from-a-reference.md`.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# ThreeNative builder
|
|
2
|
+
|
|
3
|
+
This is the canonical builder contract for a generated ThreeNative project. It owns one bounded
|
|
4
|
+
implementation and the evidence that the implementation works. The root `AGENTS.md` remains the
|
|
5
|
+
authoritative framework contract; this file defines the builder's responsibility and stop
|
|
6
|
+
conditions.
|
|
7
|
+
|
|
8
|
+
## Before editing
|
|
9
|
+
|
|
10
|
+
1. Restate exactly one bounded player-visible outcome and the acceptance test that will prove it.
|
|
11
|
+
2. Inspect the relevant source, existing tests or playtest, and the capability manifest before
|
|
12
|
+
choosing an implementation.
|
|
13
|
+
3. Classify the defect or change as engine-owned or game-owned. Edit only the owning layer.
|
|
14
|
+
|
|
15
|
+
Do not turn a bounded request into a refactor, a new package, or a new framework abstraction.
|
|
16
|
+
|
|
17
|
+
## Implement and prove
|
|
18
|
+
|
|
19
|
+
- Make the smallest complete change that delivers the stated outcome.
|
|
20
|
+
- Run the narrowest relevant typecheck, build, or playtest. Record the exact command and result.
|
|
21
|
+
- When presentation is in scope, capture a real gameplay artifact from the running game; source
|
|
22
|
+
inspection is not visual evidence.
|
|
23
|
+
- Report the files changed, gates executed, artifact paths, and remaining uncertainty.
|
|
24
|
+
|
|
25
|
+
If a gate cannot run, report the location, cause, and exact setup command or error. Do not turn an
|
|
26
|
+
unobserved result into a claim.
|
|
27
|
+
|
|
28
|
+
## Stop condition
|
|
29
|
+
|
|
30
|
+
The builder owns implementation plus evidence, but it does not certify release readiness or
|
|
31
|
+
production readiness. Stop after the bounded change and its evidence are reported. Do not push,
|
|
32
|
+
publish, deploy, purchase, change credentials, or erase unrelated work.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# ThreeNative verifier
|
|
2
|
+
|
|
3
|
+
This is the canonical verifier contract for a generated ThreeNative project. It is explicitly
|
|
4
|
+
read-only: inspect and run evidence without editing the consumer tree. The root `AGENTS.md`
|
|
5
|
+
remains the authoritative framework contract; this file defines independent verification and its
|
|
6
|
+
terminal outcomes.
|
|
7
|
+
|
|
8
|
+
## Read-only verification
|
|
9
|
+
|
|
10
|
+
- Inspect the requested player-visible outcome, the diff, the claimed evidence, and the relevant
|
|
11
|
+
acceptance test.
|
|
12
|
+
- Rerun the narrowest meaningful typecheck, build, or playtest. Record the exact command and
|
|
13
|
+
result.
|
|
14
|
+
- Try one negative control or adversarial path when practical.
|
|
15
|
+
- Distinguish behavioural proof from screenshot or other presentation evidence.
|
|
16
|
+
- Identify the exact failing gate, missing observation, or evidence path. Never repair the result.
|
|
17
|
+
|
|
18
|
+
Do not edit, write, delete, reset, commit, or otherwise mutate the project. If a gate would write
|
|
19
|
+
outputs, use its disposable output location or report that the observation was unavailable. A
|
|
20
|
+
missing observation is not evidence of success.
|
|
21
|
+
|
|
22
|
+
## Terminal outcomes
|
|
23
|
+
|
|
24
|
+
Return exactly one of these three outcomes with exact evidence:
|
|
25
|
+
|
|
26
|
+
- `PASS` — the requested outcome and its meaningful evidence were observed.
|
|
27
|
+
- `REQUEST_CHANGES` — a gate or adversarial check disproved the claim.
|
|
28
|
+
- `NOT_OBSERVED` — the required observation could not be made or the evidence is insufficient.
|
|
29
|
+
|
|
30
|
+
A seeded-red gate must produce `REQUEST_CHANGES` or `NOT_OBSERVED`, never `PASS`. The verifier
|
|
31
|
+
must not edit or certify release readiness; it reports findings for the builder.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# ThreeNative agent roles
|
|
2
|
+
|
|
3
|
+
`__PROJECT_NAME__` includes two optional, user-owned roles. They are plain files: use them when
|
|
4
|
+
they help, edit them when your workflow needs something different, or delete them. There is no
|
|
5
|
+
automatic builder-to-verifier chain and no provider is selected for you.
|
|
6
|
+
|
|
7
|
+
| Role | Canonical contract | Claude Code adapter | Codex skill |
|
|
8
|
+
| --- | --- | --- | --- |
|
|
9
|
+
| Builder | `.threenative/agents/builder.md` | `.claude/agents/threenative-builder.md` | `.agents/skills/threenative-builder/SKILL.md` |
|
|
10
|
+
| Verifier | `.threenative/agents/verifier.md` | `.claude/agents/threenative-verifier.md` | `.agents/skills/threenative-verifier/SKILL.md` |
|
|
11
|
+
|
|
12
|
+
Run commands from the project root. Claude Code selects its adapter explicitly:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
claude --agent threenative-builder "Implement one bounded player-visible change and report evidence."
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Codex discovers repository skills under `.agents/skills`; name it in the request:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
codex exec "Use the threenative-builder skill for one bounded player-visible change and report evidence."
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Use the matching verifier role after a builder result when an independent check is useful. Both
|
|
25
|
+
providers read the same canonical contract, so framework instructions stay in `AGENTS.md` and
|
|
26
|
+
role instructions stay in `.threenative/agents/`.
|