create-threenative 0.2.10 → 0.2.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-docs/references/assertion-reference.md +109 -3
- package/agent-docs/references/auto-exposure.md +28 -45
- package/agent-docs/references/build-profiles.md +1 -1
- package/agent-docs/references/capability-reference.md +527 -44
- package/agent-docs/references/debug-surface.md +64 -0
- package/agent-docs/references/finding-assets.md +11 -12
- package/agent-docs/references/performance-basics.md +19 -0
- package/agent-docs/references/trace-a-slow-frame.md +21 -0
- package/agent-docs/references/visual-baseline.md +23 -4
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +17 -6
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +87 -23
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +12 -11
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/scripts/reference.mjs +9 -4
- package/capabilities.json +739 -50
- package/dist/index.d.ts +40 -6
- package/dist/index.js +227 -34
- package/dist/quality.d.ts +12 -0
- package/dist/quality.js +166747 -0
- package/dist/threenative.js +60 -44
- package/dist/web-engine-gltf-loader.js +2 -0
- package/dist/web-engine-mesh-bvh-webgpu.js +1 -1
- package/dist/web-engine-mesh-bvh.js +7 -0
- package/dist/web-engine-post-effects.js +645 -19
- package/dist/web-engine-runtime.js +3528 -343
- package/package.json +19 -9
- package/template-assets/assets/bay-PROVENANCE.md +21 -0
- package/template-assets/assets/bay-ground.webp +0 -0
- package/template-assets/assets/bay-metal.webp +0 -0
- package/template-assets/assets/bay-pavement-normal.webp +0 -0
- package/template-assets/assets/bay-pavement.webp +0 -0
- package/template-assets/assets/bay-plaster-normal.webp +0 -0
- package/template-assets/assets/bay-plaster.webp +0 -0
- package/template-assets/assets/bay-wood-normal.webp +0 -0
- package/template-assets/assets/bay-wood.webp +0 -0
- package/template-assets/assets/tex-PROVENANCE.md +25 -0
- package/template-assets/assets/tex-bark-normal.webp +0 -0
- package/template-assets/assets/tex-bark.webp +0 -0
- package/template-assets/assets/tex-birch-bark.webp +0 -0
- package/template-assets/assets/tex-grass.webp +0 -0
- package/template-assets/assets/tex-planks-normal.webp +0 -0
- package/template-assets/assets/tex-planks.webp +0 -0
- package/template-assets/assets/tex-rock-normal.webp +0 -0
- package/template-assets/assets/tex-rock.webp +0 -0
- package/template-assets/assets/tex-roof-tiles-normal.webp +0 -0
- package/template-assets/assets/tex-roof-tiles.webp +0 -0
- package/template-assets/assets/tex-sand-normal.webp +0 -0
- package/template-assets/assets/tex-sand.webp +0 -0
- package/template-assets/assets/tex-stone-wall-normal.webp +0 -0
- package/template-assets/assets/tex-stone-wall.webp +0 -0
- package/template-assets/kitExposure.ts +20 -0
- package/template-assets/patches/three@0.185.1.patch +481 -272
- package/template-assets/quality/biome.json +7 -0
- package/template-assets/quality/eslint.config.js +3 -0
- package/template-assets/realistic-ocean/README.md +113 -0
- package/template-assets/realistic-ocean/install.mjs +56 -0
- package/template-assets/realistic-ocean/src/realisticOcean.ts +151 -0
- package/template-assets/realistic-ocean/src/realisticOceanLifetime.ts +29 -0
- package/template-assets/realistic-ocean/src/render/REALISTIC-OCEAN-LICENSE.txt +25 -0
- package/template-assets/realistic-ocean/src/render/realisticSea.ts +642 -0
- package/template-assets/realistic-ocean/src/render/realisticSeaMaps.ts +311 -0
- package/template-assets/realistic-ocean/src/render/realisticSpectrum.ts +289 -0
- package/templates/AGENTS.md +21 -0
- package/templates/CLAUDE.md +23 -0
- package/templates/action-rpg/.codex/config.toml +6 -2
- package/templates/action-rpg/.cursor/mcp.json +8 -2
- package/templates/action-rpg/.gemini/settings.json +8 -2
- package/templates/action-rpg/.mcp.json +8 -2
- package/templates/action-rpg/.vscode/mcp.json +9 -2
- package/templates/action-rpg/.zed/settings.json +9 -2
- package/templates/action-rpg/AGENTS.md +11 -11
- package/templates/action-rpg/CLAUDE.md +11 -11
- package/templates/action-rpg/opencode.json +10 -2
- package/templates/action-rpg/package.json +15 -10
- package/templates/action-rpg/playtests/combat.playtest.json +6 -0
- package/templates/action-rpg/playtests/inventory.playtest.json +22 -0
- package/templates/action-rpg/playtests/performance.playtest.json +1 -1
- package/templates/action-rpg/playtests/roll.playtest.json +112 -0
- package/templates/action-rpg/playtests/swing.playtest.json +55 -0
- package/templates/action-rpg/playtests/win.playtest.json +4 -4
- package/templates/action-rpg/src/entities/Fighter.ts +44 -4
- package/templates/action-rpg/src/entities/Player.ts +64 -12
- package/templates/action-rpg/src/render/atmosphere.ts +444 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +49 -18
- package/templates/action-rpg/src/render/clouds.ts +605 -0
- package/templates/action-rpg/src/render/dungeon.ts +8 -6
- package/templates/action-rpg/src/render/exposure.ts +11 -109
- package/templates/action-rpg/src/render/gpuSky.ts +752 -0
- package/templates/action-rpg/src/render/lighting.ts +27 -4
- package/templates/action-rpg/src/render/materialLighting.ts +2 -11
- package/templates/action-rpg/src/render/palette.ts +1 -0
- package/templates/action-rpg/src/render/postprocessing.ts +4 -4
- package/templates/action-rpg/src/render/props.ts +10 -8
- package/templates/action-rpg/src/render/quality.ts +56 -108
- package/templates/action-rpg/src/render/sky.ts +74 -1
- package/templates/action-rpg/src/scenes/Play.ts +16 -12
- package/templates/action-rpg/src/ui/CharacterPanel.tsx +7 -2
- package/templates/action-rpg/src/ui/Hud.tsx +5 -7
- package/templates/action-rpg/src/ui/InventoryPanel.tsx +14 -14
- package/templates/action-rpg/threenative.config.ts +3 -0
- package/templates/adventure/.codex/config.toml +23 -0
- package/templates/adventure/.cursor/mcp.json +38 -0
- package/templates/adventure/.gemini/settings.json +38 -0
- package/templates/adventure/.mcp.json +38 -0
- package/templates/adventure/.vscode/mcp.json +43 -0
- package/templates/adventure/.zed/settings.json +43 -0
- package/templates/adventure/AGENTS.md +60 -0
- package/templates/adventure/CLAUDE.md +62 -0
- package/templates/adventure/index.html +14 -0
- package/templates/adventure/kit.json +8 -0
- package/templates/adventure/native-playtests/survives.playtest.json +52 -0
- package/templates/adventure/opencode.json +49 -0
- package/templates/adventure/package.json +65 -0
- package/templates/adventure/playtests/boss.playtest.json +406 -0
- package/templates/adventure/playtests/combat.playtest.json +342 -0
- package/templates/adventure/playtests/controls.playtest.json +142 -0
- package/templates/adventure/playtests/explore.playtest.json +45 -0
- package/templates/adventure/playtests/flicker.playtest.json +206 -0
- package/templates/adventure/playtests/hearts.playtest.json +171 -0
- package/templates/adventure/playtests/lockon.playtest.json +256 -0
- package/templates/adventure/playtests/look.playtest.json +72 -0
- package/templates/adventure/playtests/move-hollow.playtest.json +106 -0
- package/templates/adventure/playtests/move.playtest.json +84 -0
- package/templates/adventure/playtests/performance.playtest.json +55 -0
- package/templates/adventure/playtests/puzzle.playtest.json +250 -0
- package/templates/adventure/playtests/stride.playtest.json +67 -0
- package/templates/adventure/playtests/survives.playtest.json +171 -0
- package/templates/adventure/playtests/thornback.playtest.json +267 -0
- package/templates/adventure/public/favicon.svg +4 -0
- package/templates/adventure/src/entities/Block.ts +114 -0
- package/templates/adventure/src/entities/Chest.ts +69 -0
- package/templates/adventure/src/entities/Door.ts +81 -0
- package/templates/adventure/src/entities/Dummy.ts +69 -0
- package/templates/adventure/src/entities/Flicker.ts +239 -0
- package/templates/adventure/src/entities/Hero.ts +561 -0
- package/templates/adventure/src/entities/LockOn.ts +180 -0
- package/templates/adventure/src/entities/Mossling.ts +249 -0
- package/templates/adventure/src/entities/Switch.ts +49 -0
- package/templates/adventure/src/entities/Thornback.ts +238 -0
- package/templates/adventure/src/entities/Warden.ts +196 -0
- package/templates/adventure/src/game.ts +65 -0
- package/templates/adventure/src/interact.ts +63 -0
- package/templates/adventure/src/level/Hollow.ts +240 -0
- package/templates/adventure/src/level/Vale.ts +383 -0
- package/templates/adventure/src/main.ts +18 -0
- package/templates/adventure/src/render/camera.ts +416 -0
- package/templates/adventure/src/render/creatures.ts +405 -0
- package/templates/adventure/src/render/effects.ts +333 -0
- package/templates/adventure/src/render/foliage.ts +1072 -0
- package/templates/adventure/src/render/hero.ts +1447 -0
- package/templates/adventure/src/render/kitExposure.ts +20 -0
- package/templates/adventure/src/render/lighting.ts +74 -0
- package/templates/adventure/src/render/loading.ts +332 -0
- package/templates/adventure/src/render/materials.ts +179 -0
- package/templates/adventure/src/render/palette.ts +137 -0
- package/templates/adventure/src/render/postprocessing.ts +70 -0
- package/templates/adventure/src/render/props.ts +383 -0
- package/templates/adventure/src/render/quality.ts +46 -0
- package/templates/adventure/src/render/sky.ts +271 -0
- package/templates/adventure/src/render/surface.ts +259 -0
- package/templates/adventure/src/render/touch-controls.ts +137 -0
- package/templates/adventure/src/scenes/Play.ts +959 -0
- package/templates/adventure/src/state.ts +113 -0
- package/templates/adventure/src/style.css +98 -0
- package/templates/adventure/src/ui/App.tsx +22 -0
- package/templates/adventure/src/ui/GameUi.tsx +20 -0
- package/templates/adventure/src/ui/Hud.tsx +70 -0
- package/templates/adventure/src/ui/Menu.tsx +15 -0
- package/templates/adventure/src/ui/main.tsx +14 -0
- package/templates/adventure/tailwind.config.ts +2 -0
- package/templates/adventure/threenative.config.ts +62 -0
- package/templates/adventure/tsconfig.json +17 -0
- package/templates/adventure/vite.config.ts +49 -0
- package/templates/collectathon/.codex/config.toml +23 -0
- package/templates/collectathon/.cursor/mcp.json +38 -0
- package/templates/collectathon/.gemini/settings.json +38 -0
- package/templates/collectathon/.mcp.json +38 -0
- package/templates/collectathon/.vscode/mcp.json +43 -0
- package/templates/collectathon/.zed/settings.json +43 -0
- package/templates/collectathon/AGENTS.md +58 -0
- package/templates/collectathon/CLAUDE.md +60 -0
- package/templates/collectathon/index.html +14 -0
- package/templates/collectathon/kit.json +8 -0
- package/templates/collectathon/native-playtests/survives.playtest.json +52 -0
- package/templates/collectathon/opencode.json +49 -0
- package/templates/collectathon/package.json +65 -0
- package/templates/collectathon/playtests/acrobatics.playtest.json +238 -0
- package/templates/collectathon/playtests/camera.playtest.json +80 -0
- package/templates/collectathon/playtests/clipped-probe.playtest.json +101 -0
- package/templates/collectathon/playtests/collect.playtest.json +196 -0
- package/templates/collectathon/playtests/combat.playtest.json +246 -0
- package/templates/collectathon/playtests/double-tap-air.playtest.json +198 -0
- package/templates/collectathon/playtests/double-tap.playtest.json +136 -0
- package/templates/collectathon/playtests/effects.playtest.json +124 -0
- package/templates/collectathon/playtests/enemies.playtest.json +295 -0
- package/templates/collectathon/playtests/explore.playtest.json +45 -0
- package/templates/collectathon/playtests/hop-reach.playtest.json +117 -0
- package/templates/collectathon/playtests/jump-chain.playtest.json +274 -0
- package/templates/collectathon/playtests/ledge-angle.playtest.json +107 -0
- package/templates/collectathon/playtests/ledge-too-high.playtest.json +115 -0
- package/templates/collectathon/playtests/ledge.playtest.json +100 -0
- package/templates/collectathon/playtests/look.playtest.json +64 -0
- package/templates/collectathon/playtests/performance.playtest.json +55 -0
- package/templates/collectathon/playtests/stride.playtest.json +111 -0
- package/templates/collectathon/playtests/survives.playtest.json +123 -0
- package/templates/collectathon/playtests/telegraphs.playtest.json +132 -0
- package/templates/collectathon/playtests/thornback.playtest.json +157 -0
- package/templates/collectathon/playtests/wall-kick.playtest.json +206 -0
- package/templates/collectathon/playtests/win.playtest.json +166 -0
- package/templates/collectathon/public/favicon.svg +4 -0
- package/templates/collectathon/src/entities/Hero.ts +915 -0
- package/templates/collectathon/src/entities/Pickup.ts +63 -0
- package/templates/collectathon/src/entities/Walker.ts +248 -0
- package/templates/collectathon/src/game.ts +51 -0
- package/templates/collectathon/src/level/Course.ts +590 -0
- package/templates/collectathon/src/level/terrain.ts +144 -0
- package/templates/collectathon/src/main.ts +14 -0
- package/templates/collectathon/src/playtest-events.ts +15 -0
- package/templates/collectathon/src/render/camera.ts +163 -0
- package/templates/collectathon/src/render/castle.ts +408 -0
- package/templates/collectathon/src/render/effects.ts +284 -0
- package/templates/collectathon/src/render/foliage.ts +744 -0
- package/templates/collectathon/src/render/ground.ts +139 -0
- package/templates/collectathon/src/render/hero.ts +452 -0
- package/templates/collectathon/src/render/kitExposure.ts +20 -0
- package/templates/collectathon/src/render/lighting.ts +65 -0
- package/templates/collectathon/src/render/loading.ts +332 -0
- package/templates/collectathon/src/render/materials.ts +196 -0
- package/templates/collectathon/src/render/palette.ts +82 -0
- package/templates/collectathon/src/render/postprocessing.ts +79 -0
- package/templates/collectathon/src/render/props.ts +218 -0
- package/templates/collectathon/src/render/quality.ts +54 -0
- package/templates/collectathon/src/render/sky.ts +262 -0
- package/templates/collectathon/src/render/surface.ts +269 -0
- package/templates/collectathon/src/render/touch-controls.ts +179 -0
- package/templates/collectathon/src/render/touch-layout.ts +48 -0
- package/templates/collectathon/src/render/water.ts +191 -0
- package/templates/collectathon/src/scenes/Play.ts +481 -0
- package/templates/collectathon/src/state.ts +38 -0
- package/templates/collectathon/src/style.css +106 -0
- package/templates/collectathon/src/ui/App.tsx +22 -0
- package/templates/collectathon/src/ui/GameUi.tsx +20 -0
- package/templates/collectathon/src/ui/Hud.tsx +77 -0
- package/templates/collectathon/src/ui/Menu.tsx +13 -0
- package/templates/collectathon/src/ui/main.tsx +14 -0
- package/templates/collectathon/tailwind.config.ts +2 -0
- package/templates/collectathon/threenative.config.ts +62 -0
- package/templates/collectathon/tsconfig.json +17 -0
- package/templates/collectathon/vite.config.ts +49 -0
- package/templates/kart/.codex/config.toml +23 -0
- package/templates/kart/.cursor/mcp.json +38 -0
- package/templates/kart/.gemini/settings.json +38 -0
- package/templates/kart/.mcp.json +38 -0
- package/templates/kart/.vscode/mcp.json +43 -0
- package/templates/kart/.zed/settings.json +43 -0
- package/templates/kart/AGENTS.md +58 -0
- package/templates/kart/CLAUDE.md +60 -0
- package/templates/kart/index.html +14 -0
- package/templates/kart/kit.json +8 -0
- package/templates/kart/native-playtests/survives.playtest.json +65 -0
- package/templates/kart/opencode.json +49 -0
- package/templates/kart/package.json +64 -0
- package/templates/kart/playtests/drift.playtest.json +226 -0
- package/templates/kart/playtests/explore.playtest.json +45 -0
- package/templates/kart/playtests/hit-stays-above-road.playtest.json +92 -0
- package/templates/kart/playtests/item-key.playtest.json +108 -0
- package/templates/kart/playtests/items.playtest.json +143 -0
- package/templates/kart/playtests/lap-times.playtest.json +138 -0
- package/templates/kart/playtests/laps.playtest.json +149 -0
- package/templates/kart/playtests/performance.playtest.json +57 -0
- package/templates/kart/playtests/race.playtest.json +294 -0
- package/templates/kart/playtests/restart.playtest.json +87 -0
- package/templates/kart/playtests/rocket-start.playtest.json +56 -0
- package/templates/kart/playtests/smooth-drive.playtest.json +101 -0
- package/templates/kart/playtests/surfaces.playtest.json +113 -0
- package/templates/kart/playtests/survives.playtest.json +116 -0
- package/templates/kart/playtests/wall.playtest.json +118 -0
- package/templates/kart/public/favicon.svg +4 -0
- package/templates/kart/src/entities/Driver.ts +123 -0
- package/templates/kart/src/entities/Items.ts +194 -0
- package/templates/kart/src/entities/Kart.ts +517 -0
- package/templates/kart/src/game.ts +45 -0
- package/templates/kart/src/main.ts +14 -0
- package/templates/kart/src/playtest-events.ts +15 -0
- package/templates/kart/src/render/camera.ts +83 -0
- package/templates/kart/src/render/course.ts +579 -0
- package/templates/kart/src/render/effects.ts +266 -0
- package/templates/kart/src/render/items.ts +163 -0
- package/templates/kart/src/render/kart.ts +256 -0
- package/templates/kart/src/render/kitExposure.ts +20 -0
- package/templates/kart/src/render/lighting.ts +58 -0
- package/templates/kart/src/render/loading.ts +332 -0
- package/templates/kart/src/render/materials.ts +119 -0
- package/templates/kart/src/render/palette.ts +74 -0
- package/templates/kart/src/render/postprocessing.ts +79 -0
- package/templates/kart/src/render/quality.ts +54 -0
- package/templates/kart/src/render/skids.ts +86 -0
- package/templates/kart/src/render/sky.ts +105 -0
- package/templates/kart/src/render/touch-controls.ts +168 -0
- package/templates/kart/src/render/touch-layout.ts +48 -0
- package/templates/kart/src/scenes/Race.ts +850 -0
- package/templates/kart/src/state.ts +53 -0
- package/templates/kart/src/style.css +106 -0
- package/templates/kart/src/track/Course.ts +276 -0
- package/templates/kart/src/track/Race.ts +133 -0
- package/templates/kart/src/ui/App.tsx +21 -0
- package/templates/kart/src/ui/GameUi.tsx +20 -0
- package/templates/kart/src/ui/Hud.tsx +172 -0
- package/templates/kart/src/ui/Menu.tsx +13 -0
- package/templates/kart/src/ui/main.tsx +14 -0
- package/templates/kart/tailwind.config.ts +2 -0
- package/templates/kart/threenative.config.ts +62 -0
- package/templates/kart/tsconfig.json +17 -0
- package/templates/kart/vite.config.ts +49 -0
- package/templates/minimal/.codex/config.toml +6 -2
- package/templates/minimal/.cursor/mcp.json +8 -2
- package/templates/minimal/.gemini/settings.json +8 -2
- package/templates/minimal/.mcp.json +8 -2
- package/templates/minimal/.vscode/mcp.json +9 -2
- package/templates/minimal/.zed/settings.json +9 -2
- package/templates/minimal/AGENTS.md +11 -13
- package/templates/minimal/CLAUDE.md +11 -13
- package/templates/minimal/opencode.json +10 -2
- package/templates/minimal/package.json +14 -9
- package/templates/minimal/playtests/camera-wall.playtest.json +36 -0
- package/templates/minimal/playtests/jump.playtest.json +45 -0
- package/templates/minimal/playtests/play.playtest.json +1 -1
- package/templates/minimal/src/game.ts +2 -0
- package/templates/minimal/src/render/atmosphere.ts +444 -0
- package/templates/minimal/src/render/backlightMaterial.ts +49 -18
- package/templates/minimal/src/render/camera.ts +35 -4
- package/templates/minimal/src/render/clouds.ts +605 -0
- package/templates/minimal/src/render/exposure.ts +7 -111
- package/templates/minimal/src/render/gpuSky.ts +752 -0
- package/templates/minimal/src/render/lighting.ts +26 -4
- package/templates/minimal/src/render/materialLighting.ts +2 -10
- package/templates/minimal/src/render/postprocessing.ts +4 -4
- package/templates/minimal/src/render/quality.ts +10 -116
- package/templates/minimal/src/render/sky.ts +73 -1
- package/templates/minimal/src/scenes/Play.ts +18 -7
- package/templates/platformer/.codex/config.toml +6 -2
- package/templates/platformer/.cursor/mcp.json +8 -2
- package/templates/platformer/.gemini/settings.json +8 -2
- package/templates/platformer/.mcp.json +8 -2
- package/templates/platformer/.vscode/mcp.json +9 -2
- package/templates/platformer/.zed/settings.json +9 -2
- package/templates/platformer/AGENTS.md +13 -9
- package/templates/platformer/CLAUDE.md +13 -9
- package/templates/platformer/opencode.json +10 -2
- package/templates/platformer/package.json +15 -10
- package/templates/platformer/playtests/dash-jump.playtest.json +34 -0
- package/templates/platformer/playtests/finish.playtest.json +58 -0
- package/templates/platformer/playtests/idle.playtest.json +44 -0
- package/templates/platformer/playtests/performance.playtest.json +1 -1
- package/templates/platformer/src/entities/Fox.ts +19 -6
- package/templates/platformer/src/game.ts +1 -0
- package/templates/platformer/src/level/Stage.ts +4 -1
- package/templates/platformer/src/render/backlightMaterial.ts +49 -18
- package/templates/platformer/src/render/camera.ts +30 -1
- package/templates/platformer/src/render/exposure.ts +6 -111
- package/templates/platformer/src/render/fox.ts +5 -2
- package/templates/platformer/src/render/kitExposure.ts +20 -0
- package/templates/platformer/src/render/materialLighting.ts +2 -11
- package/templates/platformer/src/render/postprocessing.ts +4 -4
- package/templates/platformer/src/render/props.ts +1 -2
- package/templates/platformer/src/render/quality.ts +10 -118
- package/templates/platformer/src/scenes/Play.ts +31 -15
- package/templates/platformer/src/ui/Menu.tsx +1 -1
- package/templates/puzzle/.codex/config.toml +6 -2
- package/templates/puzzle/.cursor/mcp.json +8 -2
- package/templates/puzzle/.gemini/settings.json +8 -2
- package/templates/puzzle/.mcp.json +8 -2
- package/templates/puzzle/.vscode/mcp.json +9 -2
- package/templates/puzzle/.zed/settings.json +9 -2
- package/templates/puzzle/AGENTS.md +14 -17
- package/templates/puzzle/CLAUDE.md +14 -17
- package/templates/puzzle/opencode.json +10 -2
- package/templates/puzzle/package.json +15 -10
- package/templates/puzzle/playtests/performance.playtest.json +1 -1
- package/templates/puzzle/playtests/replay-keeps-progress.playtest.json +78 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +49 -18
- package/templates/puzzle/src/render/exposure.ts +11 -109
- package/templates/puzzle/src/render/lighting.ts +3 -3
- package/templates/puzzle/src/render/materialLighting.ts +2 -11
- package/templates/puzzle/src/render/palette.ts +1 -1
- package/templates/puzzle/src/render/postprocessing.ts +4 -4
- package/templates/puzzle/src/render/quality.ts +44 -153
- package/templates/puzzle/src/render/vault.ts +18 -6
- package/templates/puzzle/src/scenes/Play.ts +6 -1
- package/templates/puzzle/src/ui/Hud.tsx +8 -43
- package/templates/racing/.codex/config.toml +6 -2
- package/templates/racing/.cursor/mcp.json +8 -2
- package/templates/racing/.gemini/settings.json +8 -2
- package/templates/racing/.mcp.json +8 -2
- package/templates/racing/.vscode/mcp.json +9 -2
- package/templates/racing/.zed/settings.json +9 -2
- package/templates/racing/AGENTS.md +10 -12
- package/templates/racing/CLAUDE.md +10 -12
- package/templates/racing/opencode.json +10 -2
- package/templates/racing/package.json +15 -10
- package/templates/racing/playtests/brake.playtest.json +54 -0
- package/templates/racing/playtests/outcome.playtest.json +19 -0
- package/templates/racing/playtests/performance.playtest.json +1 -1
- package/templates/racing/playtests/stopped-car-is-not-rescued.playtest.json +59 -0
- package/templates/racing/src/entities/RacingCar.ts +12 -3
- package/templates/racing/src/entities/Rival.ts +11 -2
- package/templates/racing/src/render/atmosphere.ts +444 -0
- package/templates/racing/src/render/backlightMaterial.ts +49 -18
- package/templates/racing/src/render/clouds.ts +605 -0
- package/templates/racing/src/render/exposure.ts +6 -111
- package/templates/racing/src/render/gpuSky.ts +752 -0
- package/templates/racing/src/render/kitExposure.ts +20 -0
- package/templates/racing/src/render/lighting.ts +26 -4
- package/templates/racing/src/render/materialLighting.ts +2 -11
- package/templates/racing/src/render/materials.ts +2 -1
- package/templates/racing/src/render/postprocessing.ts +4 -4
- package/templates/racing/src/render/quality.ts +27 -115
- package/templates/racing/src/render/sky.ts +72 -1
- package/templates/racing/src/scenes/Race.ts +9 -7
- package/templates/racing/src/track/TrackSector.ts +5 -2
- package/templates/racing/src/ui/Hud.tsx +12 -7
- package/templates/rain/.codex/config.toml +6 -2
- package/templates/rain/.cursor/mcp.json +8 -2
- package/templates/rain/.gemini/settings.json +8 -2
- package/templates/rain/.mcp.json +8 -2
- package/templates/rain/.vscode/mcp.json +9 -2
- package/templates/rain/.zed/settings.json +9 -2
- package/templates/rain/AGENTS.md +12 -12
- package/templates/rain/CLAUDE.md +12 -12
- package/templates/rain/opencode.json +10 -2
- package/templates/rain/package.json +14 -9
- package/templates/rain/playtests/performance.playtest.json +1 -1
- package/templates/rain/src/game.ts +1 -1
- package/templates/rain/src/render/bloom-shader.ts +1 -1
- package/templates/rain/src/render/clouds-shader.ts +2 -2
- package/templates/rain/src/render/clouds.ts +2 -1
- package/templates/rain/src/render/exposure.ts +11 -109
- package/templates/rain/src/render/post-shader.ts +7 -11
- package/templates/rain/src/render/postprocessing.ts +8 -24
- package/templates/rain/src/render/quality.ts +44 -98
- package/templates/rain/src/render/world-shader.ts +281 -97
- package/templates/rain/src/render/world.ts +82 -2
- package/templates/rain/src/style.css +1 -1
- package/templates/rain/src/ui/GameUi.tsx +6 -2
- package/templates/rain/src/ui/Hud.tsx +1 -1
- package/templates/rain/tools/generate-shaders.mjs +2 -2
- package/templates/rain/tools/tempest-post.frag +4 -6
- package/templates/rain/tools/tempest-world.frag +80 -12
- package/templates/rts/.codex/config.toml +6 -2
- package/templates/rts/.cursor/mcp.json +8 -2
- package/templates/rts/.gemini/settings.json +8 -2
- package/templates/rts/.mcp.json +8 -2
- package/templates/rts/.vscode/mcp.json +9 -2
- package/templates/rts/.zed/settings.json +9 -2
- package/templates/rts/AGENTS.md +15 -16
- package/templates/rts/CLAUDE.md +15 -16
- package/templates/rts/opencode.json +10 -2
- package/templates/rts/package.json +14 -9
- package/templates/rts/playtests/performance.playtest.json +1 -1
- package/templates/rts/playtests/rts-attack.playtest.json +5 -0
- package/templates/rts/playtests/rts-build.playtest.json +20 -1
- package/templates/rts/playtests/rts-orders.playtest.json +1 -1
- package/templates/rts/playtests/rts-pause.playtest.json +112 -0
- package/templates/rts/playtests/rts-train.playtest.json +1 -1
- package/templates/rts/playtests/rts-zoom.playtest.json +81 -0
- package/templates/rts/src/game.ts +29 -7
- package/templates/rts/src/render/army.ts +181 -49
- package/templates/rts/src/render/backlightMaterial.ts +49 -18
- package/templates/rts/src/render/environment.ts +276 -0
- package/templates/rts/src/render/exposure.ts +3 -65
- package/templates/rts/src/render/ground.ts +478 -0
- package/templates/rts/src/render/lighting.ts +62 -11
- package/templates/rts/src/render/materialLighting.ts +2 -11
- package/templates/rts/src/render/materials.ts +47 -118
- package/templates/rts/src/render/palette.ts +30 -13
- package/templates/rts/src/render/picking.ts +18 -0
- package/templates/rts/src/render/postprocessing.ts +4 -4
- package/templates/rts/src/render/quality.ts +64 -85
- package/templates/rts/src/render/resources.ts +21 -22
- package/templates/rts/src/render/sky.ts +9 -12
- package/templates/rts/src/render/terrain.ts +36 -11
- package/templates/rts/src/scenes/Play.ts +373 -38
- package/templates/rts/src/sim/ai.ts +0 -11
- package/templates/rts/src/state.ts +46 -0
- package/templates/rts/src/style.css +1543 -0
- package/templates/rts/src/ui/Commands.tsx +204 -107
- package/templates/rts/src/ui/GameUi.tsx +12 -5
- package/templates/rts/src/ui/Hud.tsx +611 -116
- package/templates/rts/src/ui/Minimap.tsx +103 -37
- package/templates/rts/src/ui/icons.tsx +116 -0
- package/templates/rts/src/ui/labels.ts +73 -0
- package/templates/rts/src/ui/minimapPoint.ts +30 -0
- package/templates/rts/threenative.config.ts +1 -1
- package/templates/runner/.codex/config.toml +6 -2
- package/templates/runner/.cursor/mcp.json +8 -2
- package/templates/runner/.gemini/settings.json +8 -2
- package/templates/runner/.mcp.json +8 -2
- package/templates/runner/.vscode/mcp.json +9 -2
- package/templates/runner/.zed/settings.json +9 -2
- package/templates/runner/AGENTS.md +12 -12
- package/templates/runner/CLAUDE.md +12 -12
- package/templates/runner/opencode.json +10 -2
- package/templates/runner/package.json +15 -10
- package/templates/runner/playtests/near-miss.playtest.json +48 -0
- package/templates/runner/playtests/performance.playtest.json +2 -2
- package/templates/runner/playtests/stride.playtest.json +27 -0
- package/templates/runner/playtests/survives.playtest.json +2 -2
- package/templates/runner/src/conventions.ts +3 -1
- package/templates/runner/src/entities/Runner.ts +11 -5
- package/templates/runner/src/render/atmosphere.ts +444 -0
- package/templates/runner/src/render/backlightMaterial.ts +49 -18
- package/templates/runner/src/render/clouds.ts +605 -0
- package/templates/runner/src/render/exposure.ts +6 -111
- package/templates/runner/src/render/gpuSky.ts +752 -0
- package/templates/runner/src/render/kitExposure.ts +20 -0
- package/templates/runner/src/render/lighting.ts +26 -4
- package/templates/runner/src/render/materialLighting.ts +2 -11
- package/templates/runner/src/render/postprocessing.ts +4 -4
- package/templates/runner/src/render/quality.ts +26 -114
- package/templates/runner/src/render/sky.ts +73 -1
- package/templates/runner/src/scenes/Run.ts +19 -15
- package/templates/runner/src/track.ts +12 -3
- package/templates/sailing/.codex/config.toml +6 -2
- package/templates/sailing/.cursor/mcp.json +8 -2
- package/templates/sailing/.gemini/settings.json +8 -2
- package/templates/sailing/.mcp.json +8 -2
- package/templates/sailing/.vscode/mcp.json +9 -2
- package/templates/sailing/.zed/settings.json +9 -2
- package/templates/sailing/AGENTS.md +10 -11
- package/templates/sailing/CLAUDE.md +10 -11
- package/templates/sailing/opencode.json +10 -2
- package/templates/sailing/package.json +15 -10
- package/templates/sailing/playtests/fail.playtest.json +46 -5
- package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +7 -0
- package/templates/sailing/playtests/performance.playtest.json +1 -1
- package/templates/sailing/src/game.ts +1 -0
- package/templates/sailing/src/render/backlightMaterial.ts +49 -18
- package/templates/sailing/src/render/exposure.ts +6 -111
- package/templates/sailing/src/render/kitExposure.ts +20 -0
- package/templates/sailing/src/render/materialLighting.ts +2 -11
- package/templates/sailing/src/render/ocean.ts +0 -1
- package/templates/sailing/src/render/postprocessing.ts +4 -4
- package/templates/sailing/src/render/quality.ts +31 -138
- package/templates/sailing/src/scenes/Sailing.ts +12 -4
- package/templates/sailing/src/ui/Hud.tsx +6 -2
- package/templates/sailing/src/ui/Menu.tsx +1 -1
- package/templates/shooter/.codex/config.toml +6 -2
- package/templates/shooter/.cursor/mcp.json +8 -2
- package/templates/shooter/.gemini/settings.json +8 -2
- package/templates/shooter/.mcp.json +8 -2
- package/templates/shooter/.vscode/mcp.json +9 -2
- package/templates/shooter/.zed/settings.json +9 -2
- package/templates/shooter/AGENTS.md +13 -12
- package/templates/shooter/CLAUDE.md +13 -12
- package/templates/shooter/index.html +1 -1
- package/templates/shooter/main.html +13 -0
- package/templates/shooter/opencode.json +10 -2
- package/templates/shooter/package.json +15 -10
- package/templates/shooter/playtests/breakable-shatters.playtest.json +6 -0
- package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +6 -0
- package/templates/shooter/playtests/hands-authored-rate.playtest.json +54 -0
- package/templates/shooter/playtests/movement-eases.playtest.json +53 -0
- package/templates/shooter/playtests/performance.playtest.json +3 -3
- package/templates/shooter/playtests/stairs-smooth-the-eye.playtest.json +56 -0
- package/templates/shooter/playtests/weapon-sharp-while-turning.playtest.json +206 -0
- package/templates/shooter/src/entities/Breakables.ts +34 -10
- package/templates/shooter/src/entities/Enemy.ts +176 -54
- package/templates/shooter/src/entities/FpsPlayer.ts +55 -16
- package/templates/shooter/src/entities/Rifle.ts +83 -9
- package/templates/shooter/src/entities/movement.ts +96 -0
- package/templates/shooter/src/render/atmosphere.ts +444 -0
- package/templates/shooter/src/render/backlightMaterial.ts +49 -18
- package/templates/shooter/src/render/camera.ts +3 -1
- package/templates/shooter/src/render/clouds.ts +605 -0
- package/templates/shooter/src/render/exposure.ts +10 -109
- package/templates/shooter/src/render/facade.ts +26 -68
- package/templates/shooter/src/render/gpuSky.ts +752 -0
- package/templates/shooter/src/render/lighting.ts +27 -4
- package/templates/shooter/src/render/materialAssignments.ts +9 -1
- package/templates/shooter/src/render/materialLighting.ts +2 -11
- package/templates/shooter/src/render/occlusion.ts +13 -4
- package/templates/shooter/src/render/palette.ts +1 -0
- package/templates/shooter/src/render/postprocessing.ts +4 -4
- package/templates/shooter/src/render/quality.ts +50 -108
- package/templates/shooter/src/render/scale.ts +0 -11
- package/templates/shooter/src/render/sky.ts +103 -2
- package/templates/shooter/src/render/surface.ts +140 -0
- package/templates/shooter/src/render/town.ts +3 -6
- package/templates/shooter/src/render/townMaterials.ts +95 -42
- package/templates/shooter/src/render/vehicles.ts +2 -0
- package/templates/shooter/src/scenes/Play.ts +83 -23
- package/templates/shooter/src/ui/Hud.tsx +268 -193
- package/templates/shooter/src/worker-page.ts +29 -0
- package/templates/shooter/src/worker.ts +5 -0
- package/templates/shooter/threenative.config.ts +3 -0
- package/templates/shooter/vite.config.ts +2 -0
- package/templates/snow/.codex/config.toml +6 -2
- package/templates/snow/.cursor/mcp.json +8 -2
- package/templates/snow/.gemini/settings.json +8 -2
- package/templates/snow/.mcp.json +8 -2
- package/templates/snow/.vscode/mcp.json +9 -2
- package/templates/snow/.zed/settings.json +9 -2
- package/templates/snow/AGENTS.md +12 -10
- package/templates/snow/CLAUDE.md +12 -10
- package/templates/snow/opencode.json +10 -2
- package/templates/snow/package.json +15 -10
- package/templates/snow/playtests/performance.playtest.json +1 -1
- package/templates/snow/src/render/backlightMaterial.ts +49 -18
- package/templates/snow/src/render/exposure.ts +17 -106
- package/templates/snow/src/render/materialLighting.ts +2 -11
- package/templates/snow/src/render/postprocessing.ts +11 -5
- package/templates/snow/src/render/quality.ts +46 -126
- package/templates/snow/src/render/snowSurface.ts +32 -15
- package/templates/snow/src/scenes/Snow.ts +2 -1
- package/templates/starter/.codex/config.toml +6 -2
- package/templates/starter/.cursor/mcp.json +8 -2
- package/templates/starter/.gemini/settings.json +8 -2
- package/templates/starter/.mcp.json +8 -2
- package/templates/starter/.vscode/mcp.json +9 -2
- package/templates/starter/.zed/settings.json +9 -2
- package/templates/starter/AGENTS.md +18 -14
- package/templates/starter/CLAUDE.md +18 -14
- package/templates/starter/index.html +1 -1
- package/templates/starter/main.html +12 -0
- package/templates/starter/native-playtests/react-hud.playtest.json +1 -0
- package/templates/starter/native-playtests/render-chain.playtest.json +34 -21
- package/templates/starter/opencode.json +10 -2
- package/templates/starter/package.json +15 -10
- package/templates/starter/playtests/play.playtest.json +22 -2
- package/templates/starter/playtests/production-readiness.playtest.json +14 -0
- package/templates/starter/src/entities/Crate.ts +19 -1
- package/templates/starter/src/render/arena.ts +2 -2
- package/templates/starter/src/render/atmosphere.ts +444 -0
- package/templates/starter/src/render/backlightMaterial.ts +49 -18
- package/templates/starter/src/render/camera.ts +28 -0
- package/templates/starter/src/render/clouds.ts +605 -0
- package/templates/starter/src/render/contactShadow.ts +50 -0
- package/templates/starter/src/render/exposure.ts +9 -111
- package/templates/starter/src/render/gpuSky.ts +752 -0
- package/templates/starter/src/render/grade.ts +1 -1
- package/templates/starter/src/render/lighting.ts +34 -6
- package/templates/starter/src/render/materialLighting.ts +2 -11
- package/templates/starter/src/render/postprocessing.ts +27 -14
- package/templates/starter/src/render/quality.ts +18 -147
- package/templates/starter/src/render/sky.ts +90 -40
- package/templates/starter/src/render/temporalAA.ts +1 -1
- package/templates/starter/src/render/temporalAAStage.ts +1 -1
- package/templates/starter/src/render/temporalCurrentFootprint.ts +0 -1
- package/templates/starter/src/render/temporalDetailStage.ts +106 -0
- package/templates/starter/src/render/temporalRejectionCounter.ts +2 -2
- package/templates/starter/src/render/volumetricFogCamera.ts +32 -0
- package/templates/starter/src/render/volumetricFogOptions.ts +7 -0
- package/templates/starter/src/render/volumetricFogTransport.ts +27 -19
- package/templates/starter/src/render/volumetricFogVolume.ts +31 -7
- package/templates/starter/src/scenes/Play.ts +11 -8
- package/templates/starter/src/ui/Hud.tsx +1 -1
- package/templates/starter/src/worker-page.ts +29 -0
- package/templates/starter/src/worker.ts +5 -0
- package/templates/starter/vite.config.ts +2 -0
- package/templates/tower-defense/.codex/config.toml +6 -2
- package/templates/tower-defense/.cursor/mcp.json +8 -2
- package/templates/tower-defense/.gemini/settings.json +8 -2
- package/templates/tower-defense/.mcp.json +8 -2
- package/templates/tower-defense/.vscode/mcp.json +9 -2
- package/templates/tower-defense/.zed/settings.json +9 -2
- package/templates/tower-defense/AGENTS.md +10 -12
- package/templates/tower-defense/CLAUDE.md +10 -12
- package/templates/tower-defense/opencode.json +10 -2
- package/templates/tower-defense/package.json +15 -10
- package/templates/tower-defense/playtests/chill-tint.playtest.json +387 -0
- package/templates/tower-defense/playtests/performance.playtest.json +1 -1
- package/templates/tower-defense/src/enemies/Enemy.ts +9 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +49 -18
- package/templates/tower-defense/src/render/exposure.ts +11 -109
- package/templates/tower-defense/src/render/lighting.ts +4 -2
- package/templates/tower-defense/src/render/materialLighting.ts +2 -11
- package/templates/tower-defense/src/render/postprocessing.ts +4 -4
- package/templates/tower-defense/src/render/quality.ts +10 -116
- package/templates/tower-defense/src/render/sky.ts +2 -2
- package/templates/tower-defense/src/scenes/Battle.ts +4 -0
- package/template-assets/autoExposure.ts +0 -225
- package/template-assets/exposureGraph.ts +0 -178
- package/template-assets/exposureReadback.ts +0 -79
- package/template-assets/worldEnvironment.ts +0 -1212
- package/templates/action-rpg/src/render/autoExposure.ts +0 -225
- package/templates/action-rpg/src/render/exposureGraph.ts +0 -178
- package/templates/action-rpg/src/render/exposureReadback.ts +0 -79
- package/templates/action-rpg/src/render/worldEnvironment.ts +0 -1212
- package/templates/minimal/src/render/autoExposure.ts +0 -225
- package/templates/minimal/src/render/exposureGraph.ts +0 -178
- package/templates/minimal/src/render/exposureReadback.ts +0 -79
- package/templates/minimal/src/render/worldEnvironment.ts +0 -1212
- package/templates/platformer/src/render/autoExposure.ts +0 -225
- package/templates/platformer/src/render/exposureGraph.ts +0 -178
- package/templates/platformer/src/render/exposureReadback.ts +0 -79
- package/templates/platformer/src/render/worldEnvironment.ts +0 -1212
- package/templates/puzzle/src/render/autoExposure.ts +0 -225
- package/templates/puzzle/src/render/exposureGraph.ts +0 -178
- package/templates/puzzle/src/render/exposureReadback.ts +0 -79
- package/templates/puzzle/src/render/worldEnvironment.ts +0 -1212
- package/templates/racing/src/render/autoExposure.ts +0 -225
- package/templates/racing/src/render/exposureGraph.ts +0 -178
- package/templates/racing/src/render/exposureReadback.ts +0 -79
- package/templates/racing/src/render/worldEnvironment.ts +0 -1212
- package/templates/rain/src/render/autoExposure.ts +0 -225
- package/templates/rain/src/render/exposureGraph.ts +0 -178
- package/templates/rain/src/render/exposureReadback.ts +0 -79
- package/templates/rain/src/render/worldEnvironment.ts +0 -1212
- package/templates/rts/src/render/autoExposure.ts +0 -225
- package/templates/rts/src/render/exposureGraph.ts +0 -178
- package/templates/rts/src/render/exposureReadback.ts +0 -79
- package/templates/rts/src/render/worldEnvironment.ts +0 -1212
- package/templates/runner/src/render/autoExposure.ts +0 -225
- package/templates/runner/src/render/exposureGraph.ts +0 -178
- package/templates/runner/src/render/exposureReadback.ts +0 -79
- package/templates/runner/src/render/worldEnvironment.ts +0 -1212
- package/templates/sailing/src/render/autoExposure.ts +0 -225
- package/templates/sailing/src/render/exposureGraph.ts +0 -178
- package/templates/sailing/src/render/exposureReadback.ts +0 -79
- package/templates/sailing/src/render/worldEnvironment.ts +0 -1212
- package/templates/shooter/src/render/autoExposure.ts +0 -225
- package/templates/shooter/src/render/exposureGraph.ts +0 -178
- package/templates/shooter/src/render/exposureReadback.ts +0 -79
- package/templates/shooter/src/render/worldEnvironment.ts +0 -1212
- package/templates/snow/src/render/autoExposure.ts +0 -225
- package/templates/snow/src/render/exposureGraph.ts +0 -178
- package/templates/snow/src/render/exposureReadback.ts +0 -79
- package/templates/snow/src/render/worldEnvironment.ts +0 -1212
- package/templates/starter/src/render/autoExposure.ts +0 -225
- package/templates/starter/src/render/exposureGraph.ts +0 -178
- package/templates/starter/src/render/exposureReadback.ts +0 -79
- package/templates/starter/src/render/worldEnvironment.ts +0 -1212
- package/templates/tower-defense/src/render/autoExposure.ts +0 -225
- package/templates/tower-defense/src/render/exposureGraph.ts +0 -178
- package/templates/tower-defense/src/render/exposureReadback.ts +0 -79
- package/templates/tower-defense/src/render/worldEnvironment.ts +0 -1212
|
@@ -5,6 +5,67 @@ day, each re-finding the shapes through TypeErrors. This page lists every global
|
|
|
5
5
|
game exposes, what it returns, and how to read it from the browser console. All of them are
|
|
6
6
|
read-only observation surfaces; none exists to drive gameplay.
|
|
7
7
|
|
|
8
|
+
## One debug switch and one report window
|
|
9
|
+
|
|
10
|
+
Set `TN_DEBUG=1` in the host environment, add `?tnDebug=1` to the browser URL, or assign
|
|
11
|
+
`globalThis.__THREENATIVE_DEBUG__ = true` before the game boots. A console assignment after boot
|
|
12
|
+
does not install instrumentation retroactively. Worker boot must receive the flag before its game
|
|
13
|
+
module evaluates. The switch enables incumbent spans/counters and debug producers for bridge,
|
|
14
|
+
callbacks, scene/renderer/GPU, memory, loading, host and UI activity.
|
|
15
|
+
|
|
16
|
+
`TN_FRAME_BUDGET.counters.engine` contains numeric per-frame summaries by name (`samples`, `mean`,
|
|
17
|
+
percentiles and `max`). One `TN_DEBUG_REPORT` for that same window ranks observed costs with
|
|
18
|
+
`basis`, caller and a matching lever where available. Read the units before comparing:
|
|
19
|
+
|
|
20
|
+
| Basis | Meaning |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| Measured CPU milliseconds/share | Timed synchronous work divided by the observed frame interval. Parent phases and nested callbacks overlap; adding them double-counts work. |
|
|
23
|
+
| Getter-equivalent estimate | Crossing count times a measured getter calibration. This estimates boundary overhead; it does not time every invoke, set or write. |
|
|
24
|
+
| Counts and bytes | Work or traffic observed, with unavailable cost unless separately timed. A large total alone is no measured CPU share. |
|
|
25
|
+
| Asynchronous wall time | Time until a decode, GPU sample or completion arrives; it can overlap other work and is not synchronous CPU/GPU duration. |
|
|
26
|
+
|
|
27
|
+
Debug windows expose `durationMs` between completed report boundaries, including host gaps.
|
|
28
|
+
Count/byte observations include `perSecond` derived from that duration. The first window,
|
|
29
|
+
zero/unavailable duration, missing frame samples or a truncated summary ring leave the rate null.
|
|
30
|
+
Worker traffic reports shallow UTF-16/primitive byte estimates and explicit unmeasured nested
|
|
31
|
+
fields, rather than claiming structured-clone wire sizes. HUD serialized bytes are exact UTF-8.
|
|
32
|
+
Asset dispatch costs name each URL; asynchronous load/decode wall time stays out of CPU rankings.
|
|
33
|
+
`textureMainThreadDecodeFallbacks` identifies the image-element path, whose later decode CPU cost
|
|
34
|
+
is unavailable. Shared TRS writes include unchanged writes; pure math values stay outside the
|
|
35
|
+
scene-transform census. GPU created/freed bytes begin at diagnostic activation, without claiming
|
|
36
|
+
an inventory of earlier allocations.
|
|
37
|
+
Native V8 installs GC prologue/epilogue callbacks only after debug activation and reports
|
|
38
|
+
`gcPauses`/`gcPauseMs`; shutdown removes them. Browser/Wasm GC entries are optional platform
|
|
39
|
+
observations, so an unavailable GC observer leaves those counters absent.
|
|
40
|
+
|
|
41
|
+
GPU query results can arrive in a later frame. Join requested/resolved/delivered sample identity
|
|
42
|
+
before comparing cadence or attributing a duration to a world draw. Queue completion delivery
|
|
43
|
+
delay, host gaps and measured GPU execution are separate observations. An unsupported observer or
|
|
44
|
+
counter remains absent; treat it as unmeasured rather than a zero. Shared Wasm/native counter names
|
|
45
|
+
do not establish that desktop or Android has executed; those claims require their actual lanes.
|
|
46
|
+
The owned renderer's current CMake adapters reject Android/iOS; forwarding a debug flag to the
|
|
47
|
+
legacy host supplies no shared-renderer parity on those platforms.
|
|
48
|
+
`findings.share: null` means the finding has no corresponding measured cost; it is not zero cost.
|
|
49
|
+
|
|
50
|
+
`TN_HOT_CALL`, `TN_BRIDGE_WARNING` and `TN_SCENE_WARNING` are actionable performance warnings;
|
|
51
|
+
playtest fails them even when console-error checks are opted out. `TN_DEBUG_REPORT` is diagnostic
|
|
52
|
+
and does not itself fail a run. Bound its numeric source through `assert.engineCost`, using the
|
|
53
|
+
exact names from `TN_FRAME_BUDGET.counters.engine`; a missing or unmeasured bounded counter fails.
|
|
54
|
+
|
|
55
|
+
The engine-only smoke scenario reuses the native-smoke game without changing its gameplay:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
node packages/playtest/dist/runner/cli.js examples/native-smoke/playtests/debug-telemetry.playtest.json \
|
|
59
|
+
--url 'http://127.0.0.1:5173/?tnDebug=1' \
|
|
60
|
+
--server-command 'pnpm --filter threenative-native-smoke dev --host 127.0.0.1 --port 5173' \
|
|
61
|
+
--browser-recipe webgpu --headed
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
It requires a debug-only callback counter in an actual budget window and bounds it by the loop's
|
|
65
|
+
five-step cap. This proves the observation path when run; it does not qualify every producer or
|
|
66
|
+
claim a device lane. Debug-off retains the existing census without installing debug observers,
|
|
67
|
+
timers or call stacks.
|
|
68
|
+
|
|
8
69
|
## `window.__THREENATIVE__` — entity snapshot (dev builds only)
|
|
9
70
|
|
|
10
71
|
Installed by `defineGame` when the dev-server flag is on (`installDevTools`); absent in
|
|
@@ -54,6 +115,9 @@ On web this global does not exist — do not probe for it in portable code.
|
|
|
54
115
|
`TN_OPACITY_TRANSPARENT`: scene-entry console warning; the engine turned `transparent` on for visible materials with `opacity < 1` so the authored opacity takes effect. Override on the material: `alphaHash: true`, or `opacity: 1` for an opaque surface.
|
|
55
116
|
`TN_OPACITY_IGNORED`: printed by a direct `renderTrapAudit(scene)` call for a material that still ignores its opacity.
|
|
56
117
|
|
|
118
|
+
Markers print at the Verbose (`console.debug`) level in the browser console, so DevTools hides them
|
|
119
|
+
by default; harnesses still receive them. Open the page with `?tnLog=1` to print them normally.
|
|
120
|
+
|
|
57
121
|
## Runner-side markers
|
|
58
122
|
|
|
59
123
|
Two further globals are set by tooling, not the game, and are named here so a stray
|
|
@@ -232,18 +232,17 @@ directory anyway and the build converts it:
|
|
|
232
232
|
build fails and names the install command for your platform — it does not copy the unusable file
|
|
233
233
|
through and report success. Ask the user before installing anything; it is roughly 350 MB.
|
|
234
234
|
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
be; it gives you a resolved Blender and the same fail-closed handling, not extra privilege.
|
|
235
|
+
To see what a file contains before you commit it, ask Blender through the same converter the build
|
|
236
|
+
uses — `packages/blender-bridge/gpl/convert.py` reports mesh, triangle, vertex and bone counts,
|
|
237
|
+
material names, clip names and image names:
|
|
238
|
+
|
|
239
|
+
```sh
|
|
240
|
+
blender --background --factory-startup --python packages/blender-bridge/gpl/convert.py -- \
|
|
241
|
+
'{"source": "assets/hero.fbx", "out": "/tmp/hero.glb"}'
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
For bpy work of your own — decimating a scan, unwrapping, baking AO, retargeting — write the script
|
|
245
|
+
and run it with `blender --background --python`. Nothing here is a sandbox or claims to be.
|
|
247
246
|
|
|
248
247
|
## The narrower tools
|
|
249
248
|
|
|
@@ -30,6 +30,14 @@ revisit later is the engine's job, not yours.
|
|
|
30
30
|
`matrixWorldAutoUpdate = false` is allowed and the engine will skip it, but its parents must stay
|
|
31
31
|
still. For one node that never moves, `node.updateMatrix(); node.matrixAutoUpdate = false` is the
|
|
32
32
|
cheaper pair: it skips the per-object compose and leaves the walk intact.
|
|
33
|
+
- **Web threads.** The dev and preview servers send `Cross-Origin-Opener-Policy: same-origin` and
|
|
34
|
+
`Cross-Origin-Embedder-Policy: require-corp`, and the build writes both into `dist/_headers`, so the
|
|
35
|
+
page is cross-origin isolated and loads the threaded engine: the world-matrix walk splits over up
|
|
36
|
+
to 8 workers. `TN_FRAME_BUDGET` reports `threads: "on (N)"`. The page always loads the threaded
|
|
37
|
+
engine and fails closed with `TN_WEB_THREADS_OFF` when it is not cross-origin isolated or the pool
|
|
38
|
+
starts no worker, so a host must send the two headers; `TN_WASM_THREADS_MISSING` names a missing
|
|
39
|
+
threaded build. A cross-origin asset without a `Cross-Origin-Resource-Policy` header needs
|
|
40
|
+
`credentialless` in place of `require-corp`. `?tnIsolation=0` serves a page without the headers.
|
|
33
41
|
- **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
|
|
34
42
|
and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
|
|
35
43
|
batch bounds that span the map.
|
|
@@ -116,3 +124,14 @@ exactly when someone is measuring. `npx @threenative/playtest perf` turns a log
|
|
|
116
124
|
report. When the percentile is
|
|
117
125
|
bad but the cause is not obvious, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md` names the function before you
|
|
118
126
|
change a line.
|
|
127
|
+
|
|
128
|
+
## Static checks, and what they cannot tell you
|
|
129
|
+
|
|
130
|
+
`pnpm check` runs the strict typecheck, ESLint and a Biome format check, and `pnpm test` runs it
|
|
131
|
+
first. ESLint fails on a floating Promise and on an async callback given to a synchronous slot, and
|
|
132
|
+
it warns when a `new Vector3()`-style math constructor runs directly inside `Scene.update`,
|
|
133
|
+
`Scene.render` or a `ctx.beforeRender` callback. That warning is a prompt to measure, not a
|
|
134
|
+
finding: reuse an instance the scene owns only if `TN_FRAME_BUDGET` shows allocation pressure.
|
|
135
|
+
It does not follow helper calls, so a quiet result is not proof a frame allocates nothing. A
|
|
136
|
+
suppression needs a reason: `// eslint-disable-next-line <rule> -- <why>`. Lint does not prove a
|
|
137
|
+
frame rate, a resource leak or native portability; the playtest and the meters do.
|
|
@@ -66,6 +66,27 @@ Read it in this order, because each line rules out a whole class of fix:
|
|
|
66
66
|
|
|
67
67
|
Only then open the raw trace file, and only if the summary points somewhere specific.
|
|
68
68
|
|
|
69
|
+
## Go deeper with the `threenative-devtools` MCP server
|
|
70
|
+
|
|
71
|
+
Every project wires Chrome DevTools as the `threenative-devtools` MCP server. Use it after
|
|
72
|
+
`playtest trace`, when the summary points at one place and you need to look inside it. It launches
|
|
73
|
+
Chrome with the same WebGPU recipe as a playtest, in a temporary profile. Chrome starts only on the
|
|
74
|
+
first tool call.
|
|
75
|
+
|
|
76
|
+
1. `navigate_page` to `http://127.0.0.1:<port>/?tnFrameSpans=1`, then hold the movement keys with
|
|
77
|
+
`press_key`, because a parked camera hides the cost of a moving one.
|
|
78
|
+
2. `performance_start_trace`, play for at least 10 s, then `performance_stop_trace`.
|
|
79
|
+
3. `performance_analyze_insight` on the insight the trace names.
|
|
80
|
+
4. `list_console_messages` for `TN_FRAME_BUDGET`, `TN_FRAME_SPANS` and `TN_SCENE_WARNING`.
|
|
81
|
+
|
|
82
|
+
Use it for GPU timing, A/B deltas inside one page, the network and asset waterfall, heap snapshots
|
|
83
|
+
(`take_heapsnapshot`) and console output. **Do not quote its CPU times as absolute numbers.** Its
|
|
84
|
+
browser keeps async call stacks on, and the engine wraps every GPU callback in a promise. On one
|
|
85
|
+
game that read main render as 8.3 ms per frame against 1.3 ms in a clean browser, and a trace added
|
|
86
|
+
3.9 ms per frame. An absolute CPU number comes from `playtest trace`. A ratio between two arms in
|
|
87
|
+
the same DevTools page is fine. The server sees only the browser: a native or Android frame goes
|
|
88
|
+
through `npx @threenative/playtest perf --target <platform>`.
|
|
89
|
+
|
|
69
90
|
## The trap that produces a confident wrong number
|
|
70
91
|
|
|
71
92
|
**A frame rate measured on a virtual display is wrong, not missing.** Under a private Xvfb there
|
|
@@ -9,8 +9,8 @@ Three.js source in this project, yours to rewrite or delete.
|
|
|
9
9
|
not raw `BoxGeometry`.** A sharp box reads as Minecraft; the same box with a 0.14 corner
|
|
10
10
|
radius reads as a toy, and that is most of the difference between a scene that looks
|
|
11
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
|
|
13
|
-
`src/render/`
|
|
12
|
+
run of meshes, the scene builds `createRandom(seed)` and passes it down.
|
|
13
|
+
`src/render/` imports shared Unreal look plumbing from `@threenative/core`; its lighting and materials stay game-owned.
|
|
14
14
|
- `lighting.ts` — key, sky/ground bounce, **rim**, ambient, with soft shadows and a
|
|
15
15
|
`normalBias` tuned for rounded geometry. The rim is what stops silhouettes reading as
|
|
16
16
|
flat cut-outs; do not delete it while "simplifying".
|
|
@@ -18,8 +18,7 @@ Three.js source in this project, yours to rewrite or delete.
|
|
|
18
18
|
**lead** are the framing: the default aims ahead of the character rather than centring it,
|
|
19
19
|
because a level that runs one way puts half the picture behind the player otherwise.
|
|
20
20
|
- `postprocessing.ts` — the editable presets and `setupPost` delegation.
|
|
21
|
-
- `
|
|
22
|
-
optional TSL stages, with `createRenderChain` reporting applied or refused stages.
|
|
21
|
+
- `WorldEnvironment` from `@threenative/core` — the shared Unreal render chain, with filmic tone mapping and metered exposure. Override options in `quality.ts`; `TN_RENDER_CHAIN` reports applied or refused stages.
|
|
23
22
|
- `materials.ts` — `floorMaterial`, `structureMaterial` and `propMaterial`, over a `DataTexture`
|
|
24
23
|
metre grid and a grain normal map. **Two greys and one saturated colour is the whole rule:**
|
|
25
24
|
light grid where the player walks, dark grid on sides and structure, and a single saturated
|
|
@@ -136,6 +135,26 @@ stage you turned on that is not in that line as `applied: true` did not run, and
|
|
|
136
135
|
why. An unknown `ssgiQuality` or `tonemapMode` throws at construction rather than quietly
|
|
137
136
|
becoming the default.
|
|
138
137
|
|
|
138
|
+
## Unreal's film curve and colour grade
|
|
139
|
+
|
|
140
|
+
`tonemapMode: "filmic"` runs the curve and the defaults of a fresh Unreal Engine 5.8.3 project
|
|
141
|
+
(`render/tonemap.ts`, your source). `tonemapMode: "aces"` is the named override. The curve takes
|
|
142
|
+
`filmicCurve: { slope: 0.88, toe: 0.55, shoulder: 0.26, blackClip: 0, whiteClip: 0.04, ... }`, and
|
|
143
|
+
the grade takes Unreal's controls under `colorGrade`:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
colorGrade: {
|
|
147
|
+
whiteTemp: 5500, whiteTint: 0, // Kelvin; "colorTemperature" in temperatureMode warms instead
|
|
148
|
+
global: { saturation: [1, 1, 1, 1.1] }, // [red, green, blue, master], like Unreal's panel
|
|
149
|
+
shadows: { gain: [1, 1, 1.05, 1] }, // also midtones and highlights; limits shadowsMax, highlightsMin/Max
|
|
150
|
+
toneCurveAmount: 1, // 0 = graded colour with no curve
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
A control left out keeps Unreal's default and adds no shader code. Both options throw under any
|
|
155
|
+
other `tonemapMode`. Unreal's colour LUT also clips each channel at 43.7 after exposure.
|
|
156
|
+
That clip is off by default because it moves hot-emitter pixels; `filmicCurve: { lutClip: LUT_CLIP }` turns it on.
|
|
157
|
+
|
|
139
158
|
## Shafts of light — the one recipe that is easy to get wrong
|
|
140
159
|
|
|
141
160
|
You want the beam a cathedral window or a hole in a cave roof throws. **Do not build cone
|
|
@@ -26,7 +26,7 @@ problem, not instead of it: read the code the change touches and trace the real
|
|
|
26
26
|
flow end to end, then climb. Two rungs work → take the higher one and move on.
|
|
27
27
|
|
|
28
28
|
1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
|
|
29
|
-
2. **Already installed in the engine?**
|
|
29
|
+
2. **Already installed in the engine?** For a new game, search `engine_search_capabilities` for the full request and each concrete mechanic and inspect hits with `engine_capability_detail`; for an existing game, reuse its discovery and binding constraints through the steps 5-7 route in `threenative-capabilities`, without restarting whole-game discovery or planning. Reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; reuse its recorded result for an existing game rather than treating each edit as a new game. Keep installed systems instead of hand-writing replacements.
|
|
30
30
|
3. **Already in this game?** Reuse a helper, type, or pattern that already lives in `src/`. Re-implementing what sits a few files over is the most common slop.
|
|
31
31
|
4. **Stdlib or engine convention does it?** `loadAll`, `addInSlices`, `GroundSnap`, an input vector, a physics query — reach for those before writing your own loop.
|
|
32
32
|
5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
|
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: prd-creator
|
|
3
|
-
description:
|
|
3
|
+
description: Plan new ThreeNative games only, after kit selection plus mechanics-reference and built-in capability discovery; hand approved plans to texture selection, execution and verification.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# ThreeNative game PRD
|
|
7
7
|
|
|
8
|
-
Use this
|
|
9
|
-
and
|
|
10
|
-
|
|
8
|
+
Use this for new games only, at step 4 of `threenative-capabilities`, after kit selection and both
|
|
9
|
+
mechanics-reference and built-in capability discovery. Existing-game changes follow steps 5-7
|
|
10
|
+
using their existing context; do not invoke this skill to restart whole-game planning.
|
|
11
|
+
The outcome is a small, distinctive, playable plan grounded in both discovery passes.
|
|
11
12
|
|
|
12
13
|
## Plan
|
|
13
14
|
|
|
@@ -22,11 +23,21 @@ engine surface and explicitly approved by the user, not a generic genre template
|
|
|
22
23
|
5. Record prerequisites: required tools/MCPs, service access, test users, and environment variable
|
|
23
24
|
names. Use placeholders only; never read or write real secrets into planning artifacts.
|
|
24
25
|
|
|
26
|
+
Copy the three completed discovery sections into `.agent/prd/PRD.md`: **Kit**, **Mechanics**
|
|
27
|
+
and **References**. Each needs a value or explicit `none` with a reason; a blank or missing
|
|
28
|
+
section blocks approval. Required texture search/download is step 5, after plan approval;
|
|
29
|
+
record planned asset needs here without claiming assets have already been selected or downloaded.
|
|
30
|
+
|
|
25
31
|
Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
|
|
26
32
|
`.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
|
|
27
33
|
bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
|
|
28
|
-
The first task verifies prerequisites
|
|
29
|
-
|
|
34
|
+
The first task verifies prerequisites and selects/downloads required textures from the mechanics
|
|
35
|
+
matches and supplied reference. Step 6 delegates to subagents focused on specific areas: every
|
|
36
|
+
bounded task names its area, file ownership and acceptance check. The coordinator reviews and
|
|
37
|
+
integrates all returned changes before step 7 mechanics playtests; do not use a catch-all worker.
|
|
38
|
+
Later tasks playtest mechanics with real actions and assertions, then require the reference-image
|
|
39
|
+
visual judge gate from `threenative-capabilities`. Preserve the pre-planning capability decisions
|
|
40
|
+
in the relevant task checks.
|
|
30
41
|
|
|
31
42
|
## Approval gate
|
|
32
43
|
|
|
@@ -1,27 +1,91 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: threenative-capabilities
|
|
3
|
-
description:
|
|
3
|
+
description: Route ThreeNative authoring: new games follow prompt, kit, mechanics discovery, plan, textures, execution, mechanics playtest and reference-image judge; existing games use steps 5-7 only.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# ThreeNative
|
|
7
|
-
|
|
8
|
-
This is
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
6
|
+
# ThreeNative authoring route
|
|
7
|
+
|
|
8
|
+
This is the critical planning prerequisite for a new game and the routing entry for an existing
|
|
9
|
+
game. Classify the user's intent using the current project and plan: starter code alone does not
|
|
10
|
+
make a new-game request an existing-game change. Ask if intent is ambiguous.
|
|
11
|
+
Preserve the request's distinctive fantasy and infer concrete mechanics, not just a genre label.
|
|
12
|
+
|
|
13
|
+
**Tools.** Every server named below is in this game's `.mcp.json`, and a host loads it only for a
|
|
14
|
+
session started in this folder. A session started elsewhere (one that ran `create-threenative`)
|
|
15
|
+
has none of them in its tool list: run `node node_modules/@threenative/core/mcp/call.mjs <server>
|
|
16
|
+
<tool> '<json>'` from this folder, and `call.mjs <server>` lists that server's tools. A tool that
|
|
17
|
+
is missing from your list never skips its step.
|
|
18
|
+
|
|
19
|
+
## New game
|
|
20
|
+
|
|
21
|
+
Follow steps 1-8 in order; finish both discovery passes before planning. Record actual results,
|
|
22
|
+
including explicit `none` with a reason; a blank discovery result blocks plan approval.
|
|
23
|
+
|
|
24
|
+
1. **Prompt** — read the user's complete request and any supplied reference image.
|
|
25
|
+
2. **Starter kit** — inspect installed `create-threenative` template `kit.json` fields and exact
|
|
26
|
+
`--genre` routing. Choose a matching kit; if no kit matches, use `minimal` (`--template minimal`).
|
|
27
|
+
Record the kit and why it fits. Keep the chosen kit's source as the starting point.
|
|
28
|
+
3. **Mechanics discovery** — threenative-reverse-engineer is the mechanics-reference role:
|
|
29
|
+
the current `threenative-engine` MCP serves it through `engine_search_references` and
|
|
30
|
+
`engine_reference_detail`. Search named games and the implied mechanics, inspect relevant
|
|
31
|
+
matches, and record pinned sources and feel rules. For Tier-2 matches, read the pinned repo
|
|
32
|
+
and use `engine_save_reference` for the nodes/cards actually walked; unavailable references
|
|
33
|
+
remain `none: references unavailable`, not fabricated matches.
|
|
34
|
+
PLUS engine_capabilities built-in discovery, served by that same MCP: call
|
|
35
|
+
`engine_search_capabilities` with `scope: "request"` for the complete mechanically explicit
|
|
36
|
+
request, then `scope: "mechanic"` per mechanic; inspect hits with `engine_capability_detail`.
|
|
37
|
+
Record installed capabilities and binding constraints. A `verdict: "none"` means game-owned
|
|
38
|
+
behavior in `src/`; do not rephrase until something matches. These role names add no servers.
|
|
39
|
+
4. **Core-mechanics plan** — hand **Kit**, **Mechanics** and **References** to `prd-creator`.
|
|
40
|
+
Plan the core loop from both discovery passes, with controls, camera, state, acceptance checks,
|
|
41
|
+
target platforms and appearance/asset needs. Get explicit approval and an instruction to
|
|
42
|
+
implement before downloads or game-source edits. Required texture selection follows the plan.
|
|
43
|
+
5. **Required textures** — use threenative-asset-mcp (configured as `threenative-assets`). From
|
|
44
|
+
the mechanics matches and reference image, if provided, identify only the textures needed by
|
|
45
|
+
the plan. Call `asset_search_sources`, the returned source's search/list-files tools, then
|
|
46
|
+
`asset_download_file`; verify the returned licence and record downloaded paths/source/licence
|
|
47
|
+
in `CREDITS.md`. Follow `.agents/skills/threenative-assets/SKILL.md`; no unrelated downloads or
|
|
48
|
+
invented tool results. If no textures are required, record `none` and why. Reuse existing files.
|
|
49
|
+
6. **Execute** — execute plan, delegate to subagents focused on specific areas. Give each a
|
|
50
|
+
bounded task, explicit file ownership, relevant context and an acceptance check; preserve other
|
|
51
|
+
writers and avoid a single catch-all worker. The coordinator reviews and integrates the areas
|
|
52
|
+
before step 7, resolving interfaces and failures rather than trusting worker reports. Use the
|
|
53
|
+
chosen kit, discovered capabilities and downloaded textures. Keep appearance in game-owned `src/render/`; use stock
|
|
54
|
+
`WorldEnvironment` defaults or explicitly report named overrides. Borrow mechanics only:
|
|
55
|
+
no code, level layouts, character names or art; cite pinned `file:line` sources.
|
|
56
|
+
7. **Mechanics playtest** — follow `.agents/skills/threenative-playtest/SKILL.md`. Execute a
|
|
57
|
+
fail-closed scenario for each core mechanic with observable state, real input actions and
|
|
58
|
+
assertions. An empty assertion set or missing observation fails; a screenshot is not mechanics
|
|
59
|
+
proof. Repair failures and rerun the affected scenario. Report only platforms actually run.
|
|
60
|
+
8. **Reference-image visual judge** — after mechanics pass, use
|
|
61
|
+
`.agents/skills/threenative-visuals/SKILL.md` and the installed
|
|
62
|
+
`node_modules/create-threenative/agent-docs/references/dream-loop.md`: compare a fresh, nonblank
|
|
63
|
+
gameplay capture against the supplied reference image with a fresh read-only judge. If no
|
|
64
|
+
image was supplied, ask for a supplied target or an explicitly authorized image-tool route,
|
|
65
|
+
as that existing contract requires; do not invent a target or choose a provider/model.
|
|
66
|
+
A missing target, capture or judgment is unverified, not a pass. Require `PASS`;
|
|
67
|
+
`REQUEST_CHANGES` and `NOT_OBSERVED` block completion. Fix and rejudge against the same target.
|
|
68
|
+
|
|
69
|
+
## Existing game
|
|
70
|
+
|
|
71
|
+
Use steps 5-7 only, with the existing game, plan, mechanics matches and reference context.
|
|
72
|
+
Do not repeat kit selection, mechanics discovery or whole-game planning; do not invoke
|
|
73
|
+
`prd-creator` just to restart the game plan. Do not add step 8 to this route. If another binding
|
|
74
|
+
project gate conflicts, ask the user rather than silently waiving or appending it.
|
|
75
|
+
|
|
76
|
+
5. **Required textures** — apply new-game step 5 to the requested change using existing context;
|
|
77
|
+
reuse current assets and download only missing required textures. Ask a targeted question if
|
|
78
|
+
essential context is missing instead of restarting discovery.
|
|
79
|
+
6. **Execute** — delegate to subagents focused on specific areas with bounded tasks and file ownership,
|
|
80
|
+
using the existing game and plan. The coordinator reviews and integrates their changes before step 7;
|
|
81
|
+
preserve established mechanics, assets, appearance choices and binding capability constraints.
|
|
82
|
+
Apply the same step-6 ownership and acceptance checks above; do not restart planning or use a catch-all worker.
|
|
83
|
+
7. **Mechanics playtest** — execute step 7 for affected mechanics and their related regressions.
|
|
84
|
+
Keep real captures where needed to observe the change; do not substitute them for assertions.
|
|
85
|
+
|
|
86
|
+
Returned capability constraints are binding, including `@threenative/physics/navigation` subpaths
|
|
87
|
+
and platform support. Use `attachToBone` for held weapons (add a portable `Bone` named `RightHand`
|
|
88
|
+
when needed) rather than rebuilding installed systems. If MCP
|
|
89
|
+
is unavailable, run `npx threenative doctor`; for a new game's capability pass, use the installed
|
|
90
|
+
`node_modules/create-threenative/agent-docs/references/capability-reference.md` and report missing
|
|
91
|
+
services honestly. Existing games keep their existing context and requested 5-7 route.
|
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: threenative-performance
|
|
3
|
-
description: Measure ThreeNative frame budgets and report platform evidence without guessing. Use when a frame budget, FPS floor, or platform performance claim is in question, when reading `TN_FRAME_BUDGET`, or when writing a bounded performance assertion.
|
|
3
|
+
description: Measure ThreeNative frame budgets and report platform evidence without guessing. Use when the game is slow, when a frame budget, FPS floor, or platform performance claim is in question, when reading `TN_FRAME_BUDGET`, or when writing a bounded performance assertion.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# ThreeNative performance evidence
|
|
7
7
|
|
|
8
|
-
Pool objects; load static GLBs
|
|
9
|
-
desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
|
|
8
|
+
Pool objects; load static GLBs via `ctx.assets.model()`; Unexecuted platforms stay unverified. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
|
|
10
9
|
`residual` and per-pass draws and triangles. `defineGame({ frameBudget: false })` silences
|
|
11
10
|
output, never measurement.
|
|
12
11
|
|
|
@@ -15,16 +14,21 @@ output, never measurement.
|
|
|
15
14
|
`TN_SCENE_WARNING` fires when the GPU used under a third of a frame whose render phase overran
|
|
16
15
|
the display period: move draws and objects, not settings. `npx threenative doctor` and
|
|
17
16
|
`DEV_MODE=true` repeat it; `TN_FRAME_SPANS=1` splits that phase.
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
Largest static win: three skips binding updates when nothing changed; not writing a transform saved 7.35 ms on 1,561 objects, `markStatic(root)` 0.009 ms.
|
|
18
|
+
An uncaught per-frame walk or poll? Fix it, then `file-engine-bug`.
|
|
19
|
+
|
|
20
|
+
## Slow or stuttering game
|
|
21
|
+
|
|
22
|
+
`npx @threenative/playtest trace --url <url> --text` names the hot function (`--cpu-prof <file>`
|
|
23
|
+
writes a `.cpuprofile`). Then use the `threenative-devtools` MCP: quote its GPU, heap and network, not its
|
|
24
|
+
inflated CPU times.
|
|
20
25
|
|
|
21
26
|
## Use the shipped defaults
|
|
22
27
|
|
|
23
28
|
The engine prepares transforms, batches, culls, scales resolution and cooks assets;
|
|
24
29
|
read `node_modules/create-threenative/agent-docs/references/performance-basics.md` before hand-rolling any.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
`{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`,
|
|
30
|
+
Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Proof:
|
|
31
|
+
`{"performance":{"minFps":60,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`; frame time defaults to 16.7 ms p95 (looser needs `maxFrameMsReason`);
|
|
28
32
|
defined in `node_modules/create-threenative/agent-docs/references/assertion-reference.md#performance`; pass bounds fail closed without a
|
|
29
33
|
per-pass split.
|
|
30
34
|
|
|
@@ -53,6 +57,3 @@ per-pass split.
|
|
|
53
57
|
|
|
54
58
|
Android: budget a ~500 MiB driver floor before textures; a dual-use equirectangular
|
|
55
59
|
environment adds ~48 MiB: `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`.
|
|
56
|
-
|
|
57
|
-
Name the hot function: `--cpu-prof <file>` (native, or a browser/desktop playtest) writes a
|
|
58
|
-
DevTools `.cpuprofile`.
|
|
@@ -13,7 +13,7 @@ const RULESET = [
|
|
|
13
13
|
"",
|
|
14
14
|
"Before writing code, stop at the first rung that holds (read the code the change touches first):",
|
|
15
15
|
"1. Does this need to exist? No -> skip it (YAGNI).",
|
|
16
|
-
"2.
|
|
16
|
+
"2. Follow `threenative-capabilities`: New games: steps 1-8 (discovery before `prd-creator`). Existing games: steps 5-7 only, reusing existing context without whole-game replanning. Step 6 delegates bounded areas with file ownership to subagents; the coordinator integrates before step 7. References borrow mechanics only: no code, level layouts, character names or art.",
|
|
17
17
|
"3. Already in this game? Reuse what is in `src/`.",
|
|
18
18
|
"4. Stdlib or engine convention (loadAll, addInSlices, GroundSnap, an input vector, a physics query)? Use it.",
|
|
19
19
|
"5. Already-installed dependency? Use it; add none for a few lines.",
|
|
@@ -373,8 +373,9 @@ function hasImageModality(architecture, key) {
|
|
|
373
373
|
}
|
|
374
374
|
|
|
375
375
|
function capabilitySupportsImages(value, needsInput) {
|
|
376
|
-
|
|
377
|
-
|
|
376
|
+
// OpenRouter answers `/models/<id>/endpoints` with the model object; a list is accepted too.
|
|
377
|
+
const entries = Array.isArray(value?.data) ? value.data : value?.data ? [value.data] : [];
|
|
378
|
+
return entries.some((endpoint) => {
|
|
378
379
|
const architecture = endpoint?.architecture;
|
|
379
380
|
return (
|
|
380
381
|
hasImageModality(architecture, "output_modalities") &&
|
|
@@ -387,7 +388,8 @@ function capabilityEndpoint(apiEndpoint, model) {
|
|
|
387
388
|
if (process.env.NODE_ENV === "test" && process.env.TN_REFERENCE_CAPABILITIES_ENDPOINT)
|
|
388
389
|
return process.env.TN_REFERENCE_CAPABILITIES_ENDPOINT;
|
|
389
390
|
const endpoint = new URL(apiEndpoint);
|
|
390
|
-
|
|
391
|
+
// OpenRouter routes `<author>/<slug>` as two path segments; an encoded slash is a 404.
|
|
392
|
+
endpoint.pathname = `/api/v1/models/${model.split("/").map(encodeURIComponent).join("/")}/endpoints`;
|
|
391
393
|
endpoint.search = "";
|
|
392
394
|
return endpoint.toString();
|
|
393
395
|
}
|
|
@@ -645,7 +647,10 @@ async function generate(options, recordFile, record, roots) {
|
|
|
645
647
|
const safeError =
|
|
646
648
|
error instanceof ProviderError
|
|
647
649
|
? error
|
|
648
|
-
:
|
|
650
|
+
: // A check of the returned image (its type, its extension) names what failed; it holds no secret.
|
|
651
|
+
error instanceof InputError
|
|
652
|
+
? new ProviderError(error.message, { category: "invalid-image" })
|
|
653
|
+
: new ProviderError("provider operation failed", { category: "provider" });
|
|
649
654
|
const receipt = removeRequest(record, requestId, "pending");
|
|
650
655
|
if (receipt !== undefined) {
|
|
651
656
|
const destination =
|