create-threenative 0.2.8 → 0.2.10
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 +87 -35
- package/agent-docs/references/auto-exposure.md +57 -0
- package/agent-docs/references/capability-reference.md +1097 -23
- package/agent-docs/references/debug-surface.md +6 -0
- package/agent-docs/references/finding-assets.md +46 -10
- package/agent-docs/references/performance-basics.md +5 -4
- package/agent-docs/references/terrain-authoring.md +140 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
- package/capabilities.json +1210 -27
- package/dist/index.d.ts +28 -3
- package/dist/index.js +396 -166
- package/dist/threenative.js +986 -235
- package/dist/web-engine-buffer-geometry-utils.js +281 -0
- package/dist/web-engine-decal-geometry.js +184 -0
- package/dist/web-engine-gltf-loader.js +196 -0
- package/dist/web-engine-hdr-loader.js +190 -0
- package/dist/web-engine-lut-cube-loader.js +122 -0
- package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
- package/dist/web-engine-mesh-bvh.js +32 -0
- package/dist/web-engine-post-effects.js +168 -0
- package/dist/web-engine-runtime.js +42506 -0
- package/package.json +11 -8
- package/template-assets/autoExposure.ts +225 -0
- package/template-assets/exposure.ts +111 -0
- package/template-assets/exposureGraph.ts +178 -0
- package/template-assets/exposureReadback.ts +79 -0
- package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
- package/template-assets/patches/three@0.185.1.patch +6594 -700
- package/template-assets/patches/vite@8.2.0.patch +422 -0
- package/template-assets/worldEnvironment.ts +433 -30
- package/templates/action-rpg/AGENTS.md +11 -10
- package/templates/action-rpg/CLAUDE.md +11 -10
- package/templates/action-rpg/package.json +13 -10
- package/templates/action-rpg/playtests/performance.playtest.json +7 -1
- package/templates/action-rpg/src/progress.ts +0 -4
- package/templates/action-rpg/src/render/autoExposure.ts +225 -0
- package/templates/action-rpg/src/render/backlightControls.ts +66 -0
- package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
- package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
- package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
- package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
- package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
- package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
- package/templates/action-rpg/src/render/exposure.ts +111 -0
- package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
- package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
- package/templates/action-rpg/src/render/heightFog.ts +118 -0
- package/templates/action-rpg/src/render/lighting.ts +26 -1
- package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
- package/templates/action-rpg/src/render/materialLighting.ts +155 -0
- package/templates/action-rpg/src/render/postprocessing.ts +17 -2
- package/templates/action-rpg/src/render/quality.ts +61 -2
- package/templates/action-rpg/src/render/sky.ts +21 -1
- package/templates/action-rpg/src/render/vfx.ts +133 -58
- package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
- package/templates/action-rpg/src/scenes/Play.ts +81 -16
- package/templates/action-rpg/threenative.config.ts +3 -0
- package/templates/action-rpg/vite.config.ts +10 -2
- package/templates/minimal/AGENTS.md +9 -10
- package/templates/minimal/CLAUDE.md +9 -10
- package/templates/minimal/package.json +11 -9
- package/templates/minimal/playtests/play.playtest.json +7 -1
- package/templates/minimal/playtests/sky.playtest.json +10 -1
- package/templates/minimal/src/render/autoExposure.ts +225 -0
- package/templates/minimal/src/render/backlightControls.ts +66 -0
- package/templates/minimal/src/render/backlightMaterial.ts +147 -0
- package/templates/minimal/src/render/environmentContribution.ts +188 -0
- package/templates/minimal/src/render/environmentRadiance.ts +36 -0
- package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
- package/templates/minimal/src/render/environmentSampling.ts +193 -0
- package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
- package/templates/minimal/src/render/exposure.ts +111 -0
- package/templates/minimal/src/render/exposureGraph.ts +178 -0
- package/templates/minimal/src/render/exposureReadback.ts +79 -0
- package/templates/minimal/src/render/heightFog.ts +118 -0
- package/templates/minimal/src/render/lighting.ts +25 -1
- package/templates/minimal/src/render/materialAssignments.ts +102 -0
- package/templates/minimal/src/render/materialLighting.ts +146 -0
- package/templates/minimal/src/render/postprocessing.ts +16 -2
- package/templates/minimal/src/render/quality.ts +60 -2
- package/templates/minimal/src/render/sky.ts +21 -1
- package/templates/minimal/src/render/worldEnvironment.ts +433 -30
- package/templates/minimal/src/scenes/Play.ts +50 -1
- package/templates/minimal/vite.config.ts +10 -2
- package/templates/platformer/AGENTS.md +7 -5
- package/templates/platformer/CLAUDE.md +7 -5
- package/templates/platformer/package.json +13 -10
- package/templates/platformer/playtests/performance.playtest.json +7 -1
- package/templates/platformer/src/render/autoExposure.ts +225 -0
- package/templates/platformer/src/render/backlightControls.ts +66 -0
- package/templates/platformer/src/render/backlightMaterial.ts +147 -0
- package/templates/platformer/src/render/environmentContribution.ts +188 -0
- package/templates/platformer/src/render/environmentRadiance.ts +36 -0
- package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
- package/templates/platformer/src/render/environmentSampling.ts +193 -0
- package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
- package/templates/platformer/src/render/exposure.ts +111 -0
- package/templates/platformer/src/render/exposureGraph.ts +178 -0
- package/templates/platformer/src/render/exposureReadback.ts +79 -0
- package/templates/platformer/src/render/heightFog.ts +118 -0
- package/templates/platformer/src/render/lighting.ts +26 -1
- package/templates/platformer/src/render/materialAssignments.ts +160 -0
- package/templates/platformer/src/render/materialLighting.ts +155 -0
- package/templates/platformer/src/render/materials.ts +7 -2
- package/templates/platformer/src/render/palette.ts +3 -3
- package/templates/platformer/src/render/postprocessing.ts +17 -2
- package/templates/platformer/src/render/quality.ts +61 -2
- package/templates/platformer/src/render/sky.ts +72 -23
- package/templates/platformer/src/render/skyEnvironment.ts +50 -0
- package/templates/platformer/src/render/worldEnvironment.ts +433 -30
- package/templates/platformer/src/scenes/Play.ts +70 -6
- package/templates/platformer/vite.config.ts +10 -2
- package/templates/puzzle/AGENTS.md +10 -9
- package/templates/puzzle/CLAUDE.md +10 -9
- package/templates/puzzle/package.json +13 -10
- package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
- package/templates/puzzle/playtests/lit.playtest.json +7 -1
- package/templates/puzzle/playtests/performance.playtest.json +7 -1
- package/templates/puzzle/src/render/autoExposure.ts +225 -0
- package/templates/puzzle/src/render/backlightControls.ts +66 -0
- package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
- package/templates/puzzle/src/render/environmentContribution.ts +188 -0
- package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
- package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
- package/templates/puzzle/src/render/environmentSampling.ts +193 -0
- package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
- package/templates/puzzle/src/render/exposure.ts +111 -0
- package/templates/puzzle/src/render/exposureGraph.ts +178 -0
- package/templates/puzzle/src/render/exposureReadback.ts +79 -0
- package/templates/puzzle/src/render/heightFog.ts +118 -0
- package/templates/puzzle/src/render/lighting.ts +33 -1
- package/templates/puzzle/src/render/materialAssignments.ts +160 -0
- package/templates/puzzle/src/render/materialLighting.ts +155 -0
- package/templates/puzzle/src/render/materials.ts +1 -1
- package/templates/puzzle/src/render/postprocessing.ts +8 -2
- package/templates/puzzle/src/render/quality.ts +62 -1
- package/templates/puzzle/src/render/sky.ts +20 -1
- package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
- package/templates/puzzle/src/scenes/Play.ts +51 -2
- package/templates/puzzle/vite.config.ts +10 -2
- package/templates/racing/AGENTS.md +8 -7
- package/templates/racing/CLAUDE.md +8 -7
- package/templates/racing/package.json +13 -10
- package/templates/racing/playtests/performance.playtest.json +7 -1
- package/templates/racing/playtests/survives.playtest.json +6 -0
- package/templates/racing/src/render/autoExposure.ts +225 -0
- package/templates/racing/src/render/backlightControls.ts +66 -0
- package/templates/racing/src/render/backlightMaterial.ts +147 -0
- package/templates/racing/src/render/environmentContribution.ts +188 -0
- package/templates/racing/src/render/environmentRadiance.ts +36 -0
- package/templates/racing/src/render/environmentSampleCache.ts +43 -0
- package/templates/racing/src/render/environmentSampling.ts +193 -0
- package/templates/racing/src/render/environmentSnapshot.ts +53 -0
- package/templates/racing/src/render/exposure.ts +111 -0
- package/templates/racing/src/render/exposureGraph.ts +178 -0
- package/templates/racing/src/render/exposureReadback.ts +79 -0
- package/templates/racing/src/render/heightFog.ts +118 -0
- package/templates/racing/src/render/lighting.ts +29 -1
- package/templates/racing/src/render/materialAssignments.ts +160 -0
- package/templates/racing/src/render/materialLighting.ts +155 -0
- package/templates/racing/src/render/palette.ts +1 -10
- package/templates/racing/src/render/postprocessing.ts +17 -2
- package/templates/racing/src/render/quality.ts +61 -2
- package/templates/racing/src/render/shapes.ts +0 -25
- package/templates/racing/src/render/sky.ts +25 -5
- package/templates/racing/src/render/worldEnvironment.ts +433 -30
- package/templates/racing/src/scenes/Race.ts +110 -13
- package/templates/racing/src/track/circuit.ts +0 -9
- package/templates/racing/vite.config.ts +10 -2
- package/templates/rain/AGENTS.md +8 -9
- package/templates/rain/CLAUDE.md +8 -9
- package/templates/rain/native-playtests/boot.playtest.json +11 -1
- package/templates/rain/package.json +14 -10
- package/templates/rain/playtests/automation.playtest.json +1 -1
- package/templates/rain/playtests/performance.playtest.json +11 -1
- package/templates/rain/playtests/tiers.playtest.json +15 -0
- package/templates/rain/playtests/weather.playtest.json +1 -1
- package/templates/rain/src/game.ts +1 -34
- package/templates/rain/src/render/autoExposure.ts +225 -0
- package/templates/rain/src/render/exposure.ts +111 -0
- package/templates/rain/src/render/exposureGraph.ts +178 -0
- package/templates/rain/src/render/exposureReadback.ts +79 -0
- package/templates/rain/src/render/postprocessing.ts +3 -0
- package/templates/rain/src/render/quality.ts +27 -1
- package/templates/rain/src/render/worldEnvironment.ts +433 -30
- package/templates/rain/src/scenes/Boot.ts +14 -0
- package/templates/rain/src/state.ts +5 -1
- package/templates/rain/src/ui/GameUi.tsx +6 -6
- package/templates/rain/tools/generate-shaders.mjs +1 -1
- package/templates/rain/vite.config.ts +10 -2
- package/templates/rts/AGENTS.md +10 -11
- package/templates/rts/CLAUDE.md +10 -11
- package/templates/rts/package.json +12 -9
- package/templates/rts/playtests/performance.playtest.json +7 -1
- package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-attack.playtest.json +10 -1
- package/templates/rts/playtests/rts-build.playtest.json +10 -1
- package/templates/rts/playtests/rts-orders.playtest.json +7 -1
- package/templates/rts/playtests/rts-train.playtest.json +10 -1
- package/templates/rts/src/render/army.ts +10 -2
- package/templates/rts/src/render/autoExposure.ts +225 -0
- package/templates/rts/src/render/backlightControls.ts +66 -0
- package/templates/rts/src/render/backlightMaterial.ts +147 -0
- package/templates/rts/src/render/environmentContribution.ts +188 -0
- package/templates/rts/src/render/environmentRadiance.ts +36 -0
- package/templates/rts/src/render/environmentSampleCache.ts +43 -0
- package/templates/rts/src/render/environmentSampling.ts +193 -0
- package/templates/rts/src/render/environmentSnapshot.ts +53 -0
- package/templates/rts/src/render/exposure.ts +111 -0
- package/templates/rts/src/render/exposureGraph.ts +178 -0
- package/templates/rts/src/render/exposureReadback.ts +79 -0
- package/templates/rts/src/render/heightFog.ts +118 -0
- package/templates/rts/src/render/lighting.ts +26 -1
- package/templates/rts/src/render/materialAssignments.ts +160 -0
- package/templates/rts/src/render/materialLighting.ts +155 -0
- package/templates/rts/src/render/postprocessing.ts +8 -2
- package/templates/rts/src/render/quality.ts +61 -2
- package/templates/rts/src/render/sky.ts +21 -1
- package/templates/rts/src/render/worldEnvironment.ts +433 -30
- package/templates/rts/src/scenes/Play.ts +54 -3
- package/templates/rts/src/sim/ai.ts +0 -1
- package/templates/rts/src/sim/terrain.ts +0 -4
- package/templates/rts/vite.config.ts +10 -2
- package/templates/runner/AGENTS.md +10 -8
- package/templates/runner/CLAUDE.md +10 -8
- package/templates/runner/package.json +13 -10
- package/templates/runner/playtests/performance.playtest.json +10 -1
- package/templates/runner/src/physics.ts +0 -1
- package/templates/runner/src/render/autoExposure.ts +225 -0
- package/templates/runner/src/render/backlightControls.ts +66 -0
- package/templates/runner/src/render/backlightMaterial.ts +147 -0
- package/templates/runner/src/render/environmentContribution.ts +188 -0
- package/templates/runner/src/render/environmentRadiance.ts +36 -0
- package/templates/runner/src/render/environmentSampleCache.ts +43 -0
- package/templates/runner/src/render/environmentSampling.ts +193 -0
- package/templates/runner/src/render/environmentSnapshot.ts +53 -0
- package/templates/runner/src/render/exposure.ts +111 -0
- package/templates/runner/src/render/exposureGraph.ts +178 -0
- package/templates/runner/src/render/exposureReadback.ts +79 -0
- package/templates/runner/src/render/heightFog.ts +118 -0
- package/templates/runner/src/render/lighting.ts +26 -1
- package/templates/runner/src/render/materialAssignments.ts +160 -0
- package/templates/runner/src/render/materialLighting.ts +155 -0
- package/templates/runner/src/render/postprocessing.ts +17 -2
- package/templates/runner/src/render/quality.ts +61 -2
- package/templates/runner/src/render/sky.ts +21 -1
- package/templates/runner/src/render/worldEnvironment.ts +433 -30
- package/templates/runner/src/scenes/Run.ts +67 -2
- package/templates/runner/threenative.config.ts +3 -0
- package/templates/runner/vite.config.ts +10 -2
- package/templates/sailing/AGENTS.md +14 -13
- package/templates/sailing/CLAUDE.md +14 -13
- package/templates/sailing/native-playtests/survives.playtest.json +7 -0
- package/templates/sailing/package.json +13 -10
- package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
- package/templates/sailing/src/entities/Ship.ts +38 -18
- package/templates/sailing/src/render/autoExposure.ts +225 -0
- package/templates/sailing/src/render/backlightControls.ts +66 -0
- package/templates/sailing/src/render/backlightMaterial.ts +147 -0
- package/templates/sailing/src/render/camera.ts +12 -4
- package/templates/sailing/src/render/environmentContribution.ts +188 -0
- package/templates/sailing/src/render/environmentRadiance.ts +36 -0
- package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
- package/templates/sailing/src/render/environmentSampling.ts +193 -0
- package/templates/sailing/src/render/environmentSetup.ts +24 -0
- package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
- package/templates/sailing/src/render/exposure.ts +111 -0
- package/templates/sailing/src/render/exposureGraph.ts +178 -0
- package/templates/sailing/src/render/exposureReadback.ts +79 -0
- package/templates/sailing/src/render/heightFog.ts +118 -0
- package/templates/sailing/src/render/lighting.ts +26 -1
- package/templates/sailing/src/render/materialAssignments.ts +160 -0
- package/templates/sailing/src/render/materialLighting.ts +155 -0
- package/templates/sailing/src/render/ocean.ts +71 -53
- package/templates/sailing/src/render/postprocessing.ts +16 -2
- package/templates/sailing/src/render/props.ts +0 -45
- package/templates/sailing/src/render/quality.ts +61 -1
- package/templates/sailing/src/render/sky.ts +21 -1
- package/templates/sailing/src/render/worldEnvironment.ts +433 -30
- package/templates/sailing/src/scenes/Boot.ts +12 -1
- package/templates/sailing/src/scenes/Sailing.ts +87 -2
- package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
- package/templates/sailing/threenative.config.ts +3 -0
- package/templates/sailing/vite.config.ts +10 -2
- package/templates/shooter/AGENTS.md +8 -6
- package/templates/shooter/CLAUDE.md +8 -6
- package/templates/shooter/package.json +13 -10
- package/templates/shooter/playtests/performance.playtest.json +7 -1
- package/templates/shooter/src/entities/Enemy.ts +0 -15
- package/templates/shooter/src/entities/Rifle.ts +38 -1
- package/templates/shooter/src/render/autoExposure.ts +225 -0
- package/templates/shooter/src/render/backlightControls.ts +66 -0
- package/templates/shooter/src/render/backlightMaterial.ts +147 -0
- package/templates/shooter/src/render/camera.ts +1 -12
- package/templates/shooter/src/render/decals.ts +299 -5
- package/templates/shooter/src/render/environmentContribution.ts +188 -0
- package/templates/shooter/src/render/environmentRadiance.ts +36 -0
- package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
- package/templates/shooter/src/render/environmentSampling.ts +193 -0
- package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
- package/templates/shooter/src/render/exposure.ts +111 -0
- package/templates/shooter/src/render/exposureGraph.ts +178 -0
- package/templates/shooter/src/render/exposureReadback.ts +79 -0
- package/templates/shooter/src/render/gunfx.ts +0 -1
- package/templates/shooter/src/render/heightFog.ts +118 -0
- package/templates/shooter/src/render/lighting.ts +26 -1
- package/templates/shooter/src/render/materialAssignments.ts +160 -0
- package/templates/shooter/src/render/materialLighting.ts +155 -0
- package/templates/shooter/src/render/postprocessing.ts +17 -2
- package/templates/shooter/src/render/quality.ts +61 -2
- package/templates/shooter/src/render/scale.ts +2 -93
- package/templates/shooter/src/render/sky.ts +21 -1
- package/templates/shooter/src/render/vehicles.ts +0 -17
- package/templates/shooter/src/render/worldEnvironment.ts +433 -30
- package/templates/shooter/src/scenes/Play.ts +64 -2
- package/templates/shooter/vite.config.ts +10 -2
- package/templates/snow/AGENTS.md +8 -6
- package/templates/snow/CLAUDE.md +8 -6
- package/templates/snow/package.json +13 -10
- package/templates/snow/src/render/autoExposure.ts +225 -0
- package/templates/snow/src/render/backlightControls.ts +66 -0
- package/templates/snow/src/render/backlightMaterial.ts +147 -0
- package/templates/snow/src/render/environmentContribution.ts +188 -0
- package/templates/snow/src/render/environmentRadiance.ts +36 -0
- package/templates/snow/src/render/environmentSampleCache.ts +43 -0
- package/templates/snow/src/render/environmentSampling.ts +193 -0
- package/templates/snow/src/render/environmentSnapshot.ts +53 -0
- package/templates/snow/src/render/exposure.ts +111 -0
- package/templates/snow/src/render/exposureGraph.ts +178 -0
- package/templates/snow/src/render/exposureReadback.ts +79 -0
- package/templates/snow/src/render/heightFog.ts +118 -0
- package/templates/snow/src/render/lighting.ts +33 -1
- package/templates/snow/src/render/materialAssignments.ts +160 -0
- package/templates/snow/src/render/materialLighting.ts +155 -0
- package/templates/snow/src/render/postprocessing.ts +16 -2
- package/templates/snow/src/render/quality.ts +59 -1
- package/templates/snow/src/render/sky.ts +21 -2
- package/templates/snow/src/render/worldEnvironment.ts +433 -30
- package/templates/snow/src/scenes/Snow.ts +29 -1
- package/templates/snow/threenative.config.ts +3 -0
- package/templates/snow/vite.config.ts +10 -2
- package/templates/starter/AGENTS.md +11 -16
- package/templates/starter/CLAUDE.md +11 -16
- package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
- package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
- package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
- package/templates/starter/package.json +13 -10
- package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
- package/templates/starter/playtests/movement.playtest.json +192 -0
- package/templates/starter/playtests/play.playtest.json +18 -2
- package/templates/starter/playtests/production-readiness.playtest.json +43 -1
- package/templates/starter/public/grade.cube +735 -0
- package/templates/starter/src/entities/Crate.ts +4 -0
- package/templates/starter/src/entities/Player.ts +79 -18
- package/templates/starter/src/game.ts +1 -0
- package/templates/starter/src/render/adaptiveQuality.ts +28 -41
- package/templates/starter/src/render/autoExposure.ts +225 -0
- package/templates/starter/src/render/backlightControls.ts +66 -0
- package/templates/starter/src/render/backlightMaterial.ts +147 -0
- package/templates/starter/src/render/environmentContribution.ts +188 -0
- package/templates/starter/src/render/environmentRadiance.ts +36 -0
- package/templates/starter/src/render/environmentSampleCache.ts +43 -0
- package/templates/starter/src/render/environmentSampling.ts +193 -0
- package/templates/starter/src/render/environmentSnapshot.ts +53 -0
- package/templates/starter/src/render/exposure.ts +111 -0
- package/templates/starter/src/render/exposureGraph.ts +178 -0
- package/templates/starter/src/render/exposureReadback.ts +79 -0
- package/templates/starter/src/render/grade.ts +157 -0
- package/templates/starter/src/render/heightFog.ts +118 -0
- package/templates/starter/src/render/lighting.ts +26 -1
- package/templates/starter/src/render/materialAssignments.ts +160 -0
- package/templates/starter/src/render/materialLighting.ts +155 -0
- package/templates/starter/src/render/postprocessing.ts +90 -4
- package/templates/starter/src/render/quality.ts +80 -8
- package/templates/starter/src/render/qualityPolicy.ts +54 -0
- package/templates/starter/src/render/rendererGate.ts +36 -0
- package/templates/starter/src/render/sky.ts +23 -1
- package/templates/starter/src/render/temporalAA.ts +197 -0
- package/templates/starter/src/render/temporalAAFrame.ts +179 -0
- package/templates/starter/src/render/temporalAAHooks.ts +101 -0
- package/templates/starter/src/render/temporalAAInput.ts +56 -0
- package/templates/starter/src/render/temporalAAResolve.ts +65 -0
- package/templates/starter/src/render/temporalAAStage.ts +76 -0
- package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
- package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
- package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
- package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
- package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
- package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
- package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
- package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
- package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
- package/templates/starter/src/render/temporalResolve.ts +139 -0
- package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
- package/templates/starter/src/render/temporalResolveMath.ts +196 -0
- package/templates/starter/src/render/volumetricFog.ts +124 -0
- package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
- package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
- package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
- package/templates/starter/src/render/worldEnvironment.ts +433 -30
- package/templates/starter/src/scenes/Play.ts +110 -1
- package/templates/starter/src/state.ts +1 -0
- package/templates/starter/src/ui/Hud.tsx +1 -1
- package/templates/starter/src/ui/Menu.tsx +1 -1
- package/templates/starter/tools/make-grade-lut.mjs +101 -0
- package/templates/starter/vite.config.ts +10 -2
- package/templates/tower-defense/AGENTS.md +10 -9
- package/templates/tower-defense/CLAUDE.md +10 -9
- package/templates/tower-defense/package.json +13 -10
- package/templates/tower-defense/playtests/performance.playtest.json +7 -1
- package/templates/tower-defense/src/render/autoExposure.ts +225 -0
- package/templates/tower-defense/src/render/backlightControls.ts +66 -0
- package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
- package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
- package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
- package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
- package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
- package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
- package/templates/tower-defense/src/render/exposure.ts +111 -0
- package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
- package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
- package/templates/tower-defense/src/render/lighting.ts +33 -1
- package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
- package/templates/tower-defense/src/render/materialLighting.ts +155 -0
- package/templates/tower-defense/src/render/postprocessing.ts +8 -2
- package/templates/tower-defense/src/render/quality.ts +61 -2
- package/templates/tower-defense/src/render/shapes.ts +0 -3
- package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
- package/templates/tower-defense/src/scenes/Battle.ts +65 -2
- package/templates/tower-defense/vite.config.ts +10 -2
- package/templates/minimal/src/scenes/Boot.ts +0 -5
|
@@ -3,6 +3,7 @@ import {
|
|
|
3
3
|
type ICtx,
|
|
4
4
|
Scene,
|
|
5
5
|
type SceneFrame,
|
|
6
|
+
getPlatform,
|
|
6
7
|
isMobile,
|
|
7
8
|
isTouchscreenAvailable,
|
|
8
9
|
} from "@threenative/core";
|
|
@@ -21,9 +22,11 @@ import { BOOT_AREA, bootPrint } from "../render/bootPrint.js";
|
|
|
21
22
|
import { OrbitFollow, setupCamera } from "../render/camera.js";
|
|
22
23
|
import { setupLighting } from "../render/lighting.js";
|
|
23
24
|
import { createLoadingScreen } from "../render/loading.js";
|
|
25
|
+
import { createMaterialLighting } from "../render/materialLighting.js";
|
|
24
26
|
import { createMaterials } from "../render/materials.js";
|
|
25
27
|
import { setupPost } from "../render/postprocessing.js";
|
|
26
28
|
import { createBall, createCrate, createLog } from "../render/props.js";
|
|
29
|
+
import { isWebGLFallbackRenderer, materialLightingEnabled } from "../render/quality.js";
|
|
27
30
|
import { createScenery } from "../render/scenery.js";
|
|
28
31
|
import { setupSky } from "../render/sky.js";
|
|
29
32
|
import { createSnowSurface } from "../render/snowSurface.js";
|
|
@@ -78,6 +81,8 @@ function placeBody(
|
|
|
78
81
|
}
|
|
79
82
|
|
|
80
83
|
export class Snow extends Scene<GameState, IPhysicsContext> {
|
|
84
|
+
#materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
|
|
85
|
+
#post: ReturnType<typeof setupPost> | undefined;
|
|
81
86
|
static override readonly initialState: GameState = {
|
|
82
87
|
autoExplore: true,
|
|
83
88
|
ballGap: 0,
|
|
@@ -113,9 +118,19 @@ export class Snow extends Scene<GameState, IPhysicsContext> {
|
|
|
113
118
|
ctx.scene,
|
|
114
119
|
ctx.renderer.raw as Parameters<typeof setupLighting>[1],
|
|
115
120
|
);
|
|
116
|
-
|
|
121
|
+
const materialEnvironment = {
|
|
122
|
+
web: getPlatform().runtime === "web",
|
|
123
|
+
rendererKind: ctx.renderer.kind,
|
|
124
|
+
webglFallback: isWebGLFallbackRenderer(ctx.renderer.raw),
|
|
125
|
+
mobile: isMobile(),
|
|
126
|
+
software: ctx.renderer.softwareAdapter !== undefined,
|
|
127
|
+
};
|
|
128
|
+
this.#post = setupPost(ctx.renderer, ctx.scene, ctx.camera, {
|
|
129
|
+
onTierChanged: (tier) =>
|
|
130
|
+
this.#materialLighting?.setEnabled(materialLightingEnabled(tier, materialEnvironment)),
|
|
117
131
|
mobile,
|
|
118
132
|
software: ctx.renderer.softwareAdapter !== undefined,
|
|
133
|
+
gpuClass: ctx.renderer.gpuClass?.class,
|
|
119
134
|
});
|
|
120
135
|
const loading = createLoadingScreen(ctx);
|
|
121
136
|
const camera = ctx.camera as PerspectiveCamera;
|
|
@@ -513,6 +528,13 @@ export class Snow extends Scene<GameState, IPhysicsContext> {
|
|
|
513
528
|
|
|
514
529
|
let waypoint = 0;
|
|
515
530
|
let pointer: { x: number; y: number } | undefined;
|
|
531
|
+
this.#materialLighting = ctx.entities.add(
|
|
532
|
+
"material-lighting",
|
|
533
|
+
createMaterialLighting(ctx.scene, ctx.camera, lights.sun, {
|
|
534
|
+
...materialEnvironment,
|
|
535
|
+
enabled: materialLightingEnabled(this.#post.tier, materialEnvironment),
|
|
536
|
+
}),
|
|
537
|
+
);
|
|
516
538
|
return (frameCtx, dt) => {
|
|
517
539
|
loading.update();
|
|
518
540
|
const input = frameCtx.input;
|
|
@@ -611,6 +633,12 @@ export class Snow extends Scene<GameState, IPhysicsContext> {
|
|
|
611
633
|
});
|
|
612
634
|
};
|
|
613
635
|
}
|
|
636
|
+
override exit(): void {
|
|
637
|
+
this.#materialLighting?.dispose();
|
|
638
|
+
this.#materialLighting = undefined;
|
|
639
|
+
this.#post?.dispose();
|
|
640
|
+
this.#post = undefined;
|
|
641
|
+
}
|
|
614
642
|
}
|
|
615
643
|
|
|
616
644
|
function clampToField(value: number): number {
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import type { IThreeNativeConfig } from "@threenative/core";
|
|
2
2
|
|
|
3
3
|
const config: IThreeNativeConfig = {
|
|
4
|
+
// Pinned to the legacy engine: the native engine does not bind three BufferGeometryUtils.mergeGeometries, three/tsl Return, atomicAdd, atomicLoad, deltaTime and log yet (PRD-573 slice 8).
|
|
5
|
+
// Delete this line when `pnpm build --target desktop` passes without it, and the game runs on the native engine.
|
|
6
|
+
engine: "threejs",
|
|
4
7
|
app: {
|
|
5
8
|
id: "com.threenative.__PROJECT_ID__",
|
|
6
9
|
name: "__PROJECT_NAME__",
|
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import tailwindcss from "@tailwindcss/vite";
|
|
2
2
|
import { watchAssets } from "@threenative/assets";
|
|
3
3
|
import react from "@vitejs/plugin-react";
|
|
4
|
-
import {
|
|
4
|
+
import {
|
|
5
|
+
createEngineFreshnessPlugin,
|
|
6
|
+
createWebBrandPlugin,
|
|
7
|
+
webRuntimeDecoders,
|
|
8
|
+
} from "create-threenative";
|
|
5
9
|
import { defineConfig } from "vite";
|
|
6
10
|
import type { Plugin } from "vite";
|
|
7
11
|
import config from "./threenative.config.js";
|
|
@@ -11,7 +15,11 @@ function assetsWatchPlugin(): Plugin {
|
|
|
11
15
|
name: "threenative-assets-watch",
|
|
12
16
|
apply: "serve",
|
|
13
17
|
async configureServer(server) {
|
|
14
|
-
const handle = watchAssets({
|
|
18
|
+
const handle = watchAssets({
|
|
19
|
+
config: config.assets,
|
|
20
|
+
cwd: server.config.root,
|
|
21
|
+
runtimeDecoders: webRuntimeDecoders(config),
|
|
22
|
+
});
|
|
15
23
|
server.httpServer?.once("close", () => handle.close());
|
|
16
24
|
// Nothing is served before the first cook settles: until it does, `public/` has no
|
|
17
25
|
// `assets.manifest.json` and every asset answers from its source fallback.
|
|
@@ -1,14 +1,10 @@
|
|
|
1
1
|
# AGENTS.md — __PROJECT_NAME__ starter
|
|
2
|
-
|
|
3
2
|
Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
|
|
4
|
-
|
|
5
3
|
## Ownership
|
|
6
|
-
|
|
7
4
|
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
|
|
8
|
-
`src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as a photographed sky and a rigged figure: `src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) the background, the environment light and the fog colour, `lighting.ts` adds the one sun it names in `SUN_DIRECTION`, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Swap the sky for any equirectangular image and re-aim `SUN_DIRECTION` at its sun; swap the rig and edit `CLIPS`.
|
|
5
|
+
`src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as a photographed sky and a rigged figure: `src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) the background, the environment light and the fog colour, `lighting.ts` adds the one sun it names in `SUN_DIRECTION`, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Swap the sky for any equirectangular image and re-aim `SUN_DIRECTION` at its sun; swap the rig and edit `CLIPS`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `src/render/sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
|
|
9
6
|
|
|
10
7
|
## Start every change
|
|
11
|
-
|
|
12
8
|
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
|
|
13
9
|
`engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
|
|
14
10
|
matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
|
|
@@ -17,14 +13,12 @@ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics b
|
|
|
17
13
|
3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
|
|
18
14
|
use returned subpaths and `attachToBone` rather than rebuilding installed systems.
|
|
19
15
|
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` enables continuous collision by default; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
|
|
20
|
-
|
|
21
16
|
## When the framework blocks you, write plain Three.js
|
|
22
17
|
|
|
23
18
|
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
24
19
|
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
25
20
|
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
26
21
|
(API, expectation, result, replacement); never stall the game.
|
|
27
|
-
|
|
28
22
|
## Workflow skills
|
|
29
23
|
|
|
30
24
|
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
@@ -35,7 +29,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
|
|
|
35
29
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
36
30
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
37
31
|
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
38
|
-
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
|
|
32
|
+
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
|
|
39
33
|
|
|
40
34
|
## Commands and map
|
|
41
35
|
|
|
@@ -56,7 +50,6 @@ own UI, and `state.ts` publishes JSON-safe values. Keep `playtests/survives.play
|
|
|
56
50
|
proof and update outcome tests.
|
|
57
51
|
|
|
58
52
|
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src/render/touch-controls.ts` adds a left movement stick and right jump button; the scene passes its input to `Player`, with keyboard mapping as the desktop fallback.
|
|
59
|
-
|
|
60
53
|
## Portable authoring contracts
|
|
61
54
|
|
|
62
55
|
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
|
|
@@ -72,25 +65,27 @@ randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
|
72
65
|
When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each
|
|
73
66
|
rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names
|
|
74
67
|
tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which
|
|
75
|
-
therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches
|
|
68
|
+
therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
|
|
76
69
|
|
|
77
70
|
## The arena is a test arena, and its look is a grid
|
|
78
71
|
`src/render/arena.ts` owns the ground, the four walls, one pillar, and `platform()`, the single builder both ends of the course are cut from. A platform is a light metre-grid plate over a dark-grid body down to the ground: two meshes, so the player collides with exactly the triangles they can see, and the sides read as structure while the walking surface reads as floor. The ground has no collider — that is the pit under the gap, and why falling costs a life instead of landing on scenery. Move a platform and move its support surface in `Play.ts` and `Goal.ts` with it, or grounding will answer for a surface that is no longer there.
|
|
79
72
|
`materials.ts` is the whole look: two greys and one saturated colour. Light grid where the player walks, dark grid on sides and structure, and the single `accent` hue reserved for the crate, the pickup and the flagpole — what you can touch. `worldGridUVs` makes one grid tile one metre on every face of every prop, so call it after a geometry is placed and before it is given to a mesh.
|
|
80
|
-
|
|
81
73
|
## Quality and proof
|
|
82
74
|
|
|
83
|
-
`src/render/quality.ts` owns `low`, `medium`, `high`;
|
|
84
|
-
`setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit.
|
|
75
|
+
WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` selects the boot tier (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`; `unknown` falls back to `isMobile()`), and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
|
|
76
|
+
`setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit. A bounded participating medium is generated source you own: `src/render/volumetricFog.ts` and its three companions build depth-correct mist, and `STARTER_MIST` there owns this game's density, colour, bounds and its single `enabled` flag — off costs no target and no pixel. `Play` passes it the live `ctx.renderer.kind`, so the WebGL fallback allocates nothing, and it owns `scene.fog` while it lives, so aerial perspective and god rays must stay off: they render the same air. `setupPost`'s `fog` factory rebuilds it whenever the tier replaces the chain. It is lit by `ambient` until you pass `points` (unshadowed, finite-range `PointLight`s) or a `sun` whose shadow map already exists — nothing wires one for you.
|
|
85
77
|
The shipped chain is ambient occlusion on `high` and `medium`, bloom, vignette, the tone curve and the shared SMAA. There are no authored paint stages: a real sun and a real sky carry the shading, and a Kuwahara smear or an ink outline over a photograph only cost frames. `quality.ts` owns tier and strength, and every `xxxEnabled: true` carries the measurement that justified it; `TN_RENDER_CHAIN` names each stage independently, and a missing stage observation is a failure.
|
|
86
78
|
`input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
|
|
87
79
|
|
|
80
|
+
`src/render/temporalAA.ts` is an experimental, opt-in TRAANode provider for scene input reconstruction. Shipped quality tiers do not enable it. Supply colour/depth/velocity from the same scene pass through a `traa` RenderChain stage, reset history on camera cuts, and dispose with the stage. The optional exact scene-pass argument enables a bounded raw4 current-footprint candidate for supported reduced rasters; it owns four-sample beauty and matching visibility replays and restores ordinary pass policy on unsupported inputs. Opaque RGB remains a pixel-frequency approximation; alpha-tested visibility uses sample interpolation. The ordinary path uses scene-pass MSAA disabled. `temporalResolve.ts` retains optional linear/Catmull–Rom and ordinary-blend comparisons, both depth-history vetoes, and mandatory RGB clipping. Original quality/recovery, GPU cost, automatic scaling and native gates remain unqualified.
|
|
88
81
|
## One shadow for a big outdoor level
|
|
89
|
-
When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options.
|
|
90
|
-
|
|
82
|
+
When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. Movers sort themselves: a caster whose matrix changes draws through a per-level mover map and returns to the cached levels after `staticAfterFrames` quiet frames, each change redrawing only its own region. `trackCaster(object)` pins a mover for good, `pinStatic(object)` opts an object out; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
|
|
91
83
|
## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
|
|
92
84
|
|
|
93
85
|
The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
94
|
-
Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
86
|
+
For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
95
87
|
## Optional multiplayer transport
|
|
96
88
|
For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
|
|
89
|
+
|
|
90
|
+
High-tier desktop browser WebGPU adds game-owned grazing backlight (`lighting.ts`: `rimGain: 0`) and measured-dark directional fill (`fillGain: 0` or black `fillColor`). `materialLighting.ts` preserves borrowed material maps and restores originals on lower quality/exit; mobile, software, WebGL and native retain originals. `TN_ENVIRONMENT_CONTRIBUTION` reports even with overrides zero; `environmentSampling.ts` estimates actual IBL once during load; unavailable/stale samples stay unknown and disable analytic fill. Native material terms remain unqualified.
|
|
91
|
+
`src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds. One fog owner at a time: an enabled `STARTER_MIST` clears both `scene.fog` and `scene.fogNode`.
|
|
@@ -1,16 +1,12 @@
|
|
|
1
1
|
<!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
|
|
2
2
|
|
|
3
3
|
# AGENTS.md — __PROJECT_NAME__ starter
|
|
4
|
-
|
|
5
4
|
Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
|
|
6
|
-
|
|
7
5
|
## Ownership
|
|
8
|
-
|
|
9
6
|
ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns gameplay and every visible choice in `src/render/`, `src/entities/`,
|
|
10
|
-
`src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as a photographed sky and a rigged figure: `src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) the background, the environment light and the fog colour, `lighting.ts` adds the one sun it names in `SUN_DIRECTION`, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Swap the sky for any equirectangular image and re-aim `SUN_DIRECTION` at its sun; swap the rig and edit `CLIPS`.
|
|
7
|
+
`src/scenes/`, and `src/ui/`; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. The look ships as a photographed sky and a rigged figure: `src/render/sky.ts` makes `assets/sky.jpg` (Poly Haven, CC0) the background, the environment light and the fog colour, `lighting.ts` adds the one sun it names in `SUN_DIRECTION`, and `Player.ts` drives `assets/mannequin.glb` (Quaternius, CC0) through `SkeletalMesh3D`. Swap the sky for any equirectangular image and re-aim `SUN_DIRECTION` at its sun; swap the rig and edit `CLIPS`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `src/render/sky.ts` makes — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
|
|
11
8
|
|
|
12
9
|
## Start every change
|
|
13
|
-
|
|
14
10
|
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
|
|
15
11
|
`engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
|
|
16
12
|
matches with `engine_capability_detail`, and record a capability or no-match for the plan. Apply the `ponytail` ladder before writing code; never hand-write what the capability search already installs.
|
|
@@ -19,14 +15,12 @@ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics b
|
|
|
19
15
|
3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
|
|
20
16
|
use returned subpaths and `attachToBone` rather than rebuilding installed systems.
|
|
21
17
|
4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and `npx @threenative/playtest doctor`; missing observations are not zero. For *"a bullet passes through a wall"*, `RigidBody3D` enables continuous collision by default; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web and native.
|
|
22
|
-
|
|
23
18
|
## When the framework blocks you, write plain Three.js
|
|
24
19
|
|
|
25
20
|
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
26
21
|
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
27
22
|
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
28
23
|
(API, expectation, result, replacement); never stall the game.
|
|
29
|
-
|
|
30
24
|
## Workflow skills
|
|
31
25
|
|
|
32
26
|
- `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
|
|
@@ -37,7 +31,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
|
|
|
37
31
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
38
32
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
39
33
|
- `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
|
|
40
|
-
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
|
|
34
|
+
- Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
|
|
41
35
|
|
|
42
36
|
## Commands and map
|
|
43
37
|
|
|
@@ -58,7 +52,6 @@ own UI, and `state.ts` publishes JSON-safe values. Keep `playtests/survives.play
|
|
|
58
52
|
proof and update outcome tests.
|
|
59
53
|
|
|
60
54
|
On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), local `src/render/touch-controls.ts` adds a left movement stick and right jump button; the scene passes its input to `Player`, with keyboard mapping as the desktop fallback.
|
|
61
|
-
|
|
62
55
|
## Portable authoring contracts
|
|
63
56
|
|
|
64
57
|
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
|
|
@@ -74,25 +67,27 @@ randomness is deterministic only when `defineGame({ seed })` is configured.
|
|
|
74
67
|
When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a retargeted clip against its source per bone in degrees — whole quaternions relative to each
|
|
75
68
|
rig's own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is caught where a bone-direction check reads zero. `clipTrackBindings` names
|
|
76
69
|
tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose instead of the animation), `clipBoneCoverage` names bones the clip does not drive and which
|
|
77
|
-
therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches
|
|
70
|
+
therefore keep the previous clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
|
|
78
71
|
|
|
79
72
|
## The arena is a test arena, and its look is a grid
|
|
80
73
|
`src/render/arena.ts` owns the ground, the four walls, one pillar, and `platform()`, the single builder both ends of the course are cut from. A platform is a light metre-grid plate over a dark-grid body down to the ground: two meshes, so the player collides with exactly the triangles they can see, and the sides read as structure while the walking surface reads as floor. The ground has no collider — that is the pit under the gap, and why falling costs a life instead of landing on scenery. Move a platform and move its support surface in `Play.ts` and `Goal.ts` with it, or grounding will answer for a surface that is no longer there.
|
|
81
74
|
`materials.ts` is the whole look: two greys and one saturated colour. Light grid where the player walks, dark grid on sides and structure, and the single `accent` hue reserved for the crate, the pickup and the flagpole — what you can touch. `worldGridUVs` makes one grid tile one metre on every face of every prop, so call it after a geometry is placed and before it is given to a mesh.
|
|
82
|
-
|
|
83
75
|
## Quality and proof
|
|
84
76
|
|
|
85
|
-
`src/render/quality.ts` owns `low`, `medium`, `high`;
|
|
86
|
-
`setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit.
|
|
77
|
+
WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high`; the GPU family from `ctx.renderer.gpuClass` selects the boot tier (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`; `unknown` falls back to `isMobile()`), and `adaptiveQuality.ts` reads `game.ts` frame windows. Fresh GPU time wins, with a named presentation fallback. After startup, two overloaded windows lower quality; five with 20% headroom raise it; cooldown is five seconds. Presentation fallback allows 5% timing jitter (`presentationTolerance`); `overloadBudgetMs` reports its threshold. Vsync-bound presentation alone cannot prove recovery headroom.
|
|
78
|
+
`setupPost` exposes policy options and `targetFps`; `Play` supplies `display.maxFps` and readiness. Pin `{ tier: "low" }`; invalid tiers throw and pinned costs report. The `quality` entity and `TN_QUALITY_TIER` expose decisions; dispose on scene exit. A bounded participating medium is generated source you own: `src/render/volumetricFog.ts` and its three companions build depth-correct mist, and `STARTER_MIST` there owns this game's density, colour, bounds and its single `enabled` flag — off costs no target and no pixel. `Play` passes it the live `ctx.renderer.kind`, so the WebGL fallback allocates nothing, and it owns `scene.fog` while it lives, so aerial perspective and god rays must stay off: they render the same air. `setupPost`'s `fog` factory rebuilds it whenever the tier replaces the chain. It is lit by `ambient` until you pass `points` (unshadowed, finite-range `PointLight`s) or a `sun` whose shadow map already exists — nothing wires one for you.
|
|
87
79
|
The shipped chain is ambient occlusion on `high` and `medium`, bloom, vignette, the tone curve and the shared SMAA. There are no authored paint stages: a real sun and a real sky carry the shading, and a Kuwahara smear or an ink outline over a photograph only cost frames. `quality.ts` owns tier and strength, and every `xxxEnabled: true` carries the measurement that justified it; `TN_RENDER_CHAIN` names each stage independently, and a missing stage observation is a failure.
|
|
88
80
|
`input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. A scenario with no assertions or missing observations fails; open a real capture after visual changes. When a frame costs more than it should, find the object first: backtick opens the overlay, whose **Geometry** tab captures one frame on **Capture** and ranks the objects that submitted its triangles beside their projected size on screen; an agent gets the same report from `"assert": { "geometry": { "limit": 25 } }` in a scenario, which needs `runtime.geometry`. Those numbers are measured submissions reconciled against the frame's own pass totals, so the remainder the rows do not account for is reported, and what cannot be measured — a packed batch's per-member draws, unknown bounds — says so with a reason instead of reading as zero.
|
|
89
81
|
|
|
82
|
+
`src/render/temporalAA.ts` is an experimental, opt-in TRAANode provider for scene input reconstruction. Shipped quality tiers do not enable it. Supply colour/depth/velocity from the same scene pass through a `traa` RenderChain stage, reset history on camera cuts, and dispose with the stage. The optional exact scene-pass argument enables a bounded raw4 current-footprint candidate for supported reduced rasters; it owns four-sample beauty and matching visibility replays and restores ordinary pass policy on unsupported inputs. Opaque RGB remains a pixel-frequency approximation; alpha-tested visibility uses sample interpolation. The ordinary path uses scene-pass MSAA disabled. `temporalResolve.ts` retains optional linear/Catmull–Rom and ordinary-blend comparisons, both depth-history vetoes, and mandatory RGB clipping. Original quality/recovery, GPU cost, automatic scaling and native gates remain unqualified.
|
|
90
83
|
## One shadow for a big outdoor level
|
|
91
|
-
When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options.
|
|
92
|
-
|
|
84
|
+
When one directional light must shadow a whole valley and a 2048² map smudges, set `sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] })` from `@threenative/core`: camera-centred, texel-snapped clip levels, cached until the window moves and shared through Three's shadow slot. Bias, normal bias, intensity, radius, blur samples, map type and filter stay on `sun.shadow`; map sizes come from the options. Movers sort themselves: a caster whose matrix changes draws through a per-level mover map and returns to the cached levels after `staticAfterFrames` quiet frames, each change redrawing only its own region. `trackCaster(object)` pins a mover for good, `pinStatic(object)` opts an object out; call `invalidateAll()` when static geometry changes. `TN_VIRTUAL_SHADOW` reports rendered, mover-map and cached-level work.
|
|
93
85
|
## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
|
|
94
86
|
|
|
95
87
|
The performance skill carries `TN_FRAME_BUDGET`, platform targets, and the `display.maxFps` rule. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it on screen (it draws the verdict alone — no frame rate, which reads throttled under a compositor or a virtual display; see `agent-docs/references/performance-basics.md`); `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
|
|
96
|
-
Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
88
|
+
For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
97
89
|
## Optional multiplayer transport
|
|
98
90
|
For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
|
|
91
|
+
|
|
92
|
+
High-tier desktop browser WebGPU adds game-owned grazing backlight (`lighting.ts`: `rimGain: 0`) and measured-dark directional fill (`fillGain: 0` or black `fillColor`). `materialLighting.ts` preserves borrowed material maps and restores originals on lower quality/exit; mobile, software, WebGL and native retain originals. `TN_ENVIRONMENT_CONTRIBUTION` reports even with overrides zero; `environmentSampling.ts` estimates actual IBL once during load; unavailable/stale samples stay unknown and disable analytic fill. Native material terms remain unqualified.
|
|
93
|
+
`src/render/exposure.ts` owns optional adaptation (`enabled: false`); `autoExposure.ts` meters even when disabled. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds. One fog owner at a time: an enabled `STARTER_MIST` clears both `scene.fog` and `scene.fogNode`.
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
"height": 720
|
|
8
8
|
},
|
|
9
9
|
"warmupFrames": 2,
|
|
10
|
+
"startTick": 600,
|
|
10
11
|
"steps": [
|
|
11
12
|
{
|
|
12
13
|
"kind": "input",
|
|
@@ -26,8 +27,57 @@
|
|
|
26
27
|
"assert": {
|
|
27
28
|
"renderChain": {
|
|
28
29
|
"tier": "high",
|
|
30
|
+
"perAdapter": {
|
|
31
|
+
"integrated": {
|
|
32
|
+
"contributions": { "graphOutputChanged": ["grade", "grain"] },
|
|
33
|
+
"stages": {
|
|
34
|
+
"includes": ["ambientOcclusion", "bloom", "vignette", "grade", "grain"],
|
|
35
|
+
"order": ["ambientOcclusion", "bloom", "vignette", "grade", "grain"]
|
|
36
|
+
},
|
|
37
|
+
"tier": "medium"
|
|
38
|
+
},
|
|
39
|
+
"mobile-high": {
|
|
40
|
+
"contributions": { "graphOutputChanged": ["grade", "grain"] },
|
|
41
|
+
"stages": {
|
|
42
|
+
"includes": ["ambientOcclusion", "bloom", "vignette", "grade", "grain"],
|
|
43
|
+
"order": ["ambientOcclusion", "bloom", "vignette", "grade", "grain"]
|
|
44
|
+
},
|
|
45
|
+
"tier": "medium"
|
|
46
|
+
},
|
|
47
|
+
"mobile-low": {
|
|
48
|
+
"contributions": { "graphOutputChanged": ["grade"] },
|
|
49
|
+
"stages": {
|
|
50
|
+
"includes": ["bloom", "vignette", "grade"],
|
|
51
|
+
"excludes": ["ambientOcclusion", "grain"],
|
|
52
|
+
"order": ["bloom", "vignette", "grade"]
|
|
53
|
+
},
|
|
54
|
+
"tier": "low"
|
|
55
|
+
},
|
|
56
|
+
"mobile-mid": {
|
|
57
|
+
"contributions": { "graphOutputChanged": ["grade"] },
|
|
58
|
+
"stages": {
|
|
59
|
+
"includes": ["bloom", "vignette", "grade"],
|
|
60
|
+
"excludes": ["ambientOcclusion", "grain"],
|
|
61
|
+
"order": ["bloom", "vignette", "grade"]
|
|
62
|
+
},
|
|
63
|
+
"tier": "low"
|
|
64
|
+
},
|
|
65
|
+
"software": {
|
|
66
|
+
"contributions": { "graphOutputChanged": ["grade"] },
|
|
67
|
+
"stages": {
|
|
68
|
+
"includes": ["bloom", "vignette", "grade"],
|
|
69
|
+
"excludes": ["ambientOcclusion", "grain"],
|
|
70
|
+
"order": ["bloom", "vignette", "grade"]
|
|
71
|
+
},
|
|
72
|
+
"tier": "low"
|
|
73
|
+
}
|
|
74
|
+
},
|
|
29
75
|
"stages": {
|
|
30
|
-
"includes": ["ambientOcclusion", "bloom", "vignette"]
|
|
76
|
+
"includes": ["ambientOcclusion", "bloom", "vignette", "grade", "grain"],
|
|
77
|
+
"order": ["ambientOcclusion", "bloom", "vignette", "grade", "grain"]
|
|
78
|
+
},
|
|
79
|
+
"contributions": {
|
|
80
|
+
"graphOutputChanged": ["grade", "grain"]
|
|
31
81
|
}
|
|
32
82
|
},
|
|
33
83
|
"resources": [
|
|
@@ -37,13 +87,6 @@
|
|
|
37
87
|
"gte": 1,
|
|
38
88
|
"changed": true
|
|
39
89
|
}
|
|
40
|
-
],
|
|
41
|
-
"visibility": [
|
|
42
|
-
{
|
|
43
|
-
"entity": "player",
|
|
44
|
-
"minProjectedPixels": 20,
|
|
45
|
-
"allowTrivial": "The player is visible from the first tick; the state rows carry the native render proof."
|
|
46
|
-
}
|
|
47
90
|
]
|
|
48
91
|
}
|
|
49
92
|
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "smooth-motion",
|
|
4
|
+
"target": "desktop",
|
|
5
|
+
"subject": "player",
|
|
6
|
+
"viewport": {
|
|
7
|
+
"width": 320,
|
|
8
|
+
"height": 180
|
|
9
|
+
},
|
|
10
|
+
"warmupFrames": 60,
|
|
11
|
+
"steps": [
|
|
12
|
+
{
|
|
13
|
+
"kind": "wait",
|
|
14
|
+
"label": "ready",
|
|
15
|
+
"waitTicks": 240,
|
|
16
|
+
"release": true
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"kind": "input",
|
|
20
|
+
"label": "clear-crate",
|
|
21
|
+
"press": ["KeyS"],
|
|
22
|
+
"holdTicks": 35,
|
|
23
|
+
"release": true
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"kind": "input",
|
|
27
|
+
"label": "steady-walk",
|
|
28
|
+
"press": ["KeyD"],
|
|
29
|
+
"holdTicks": 180,
|
|
30
|
+
"release": true
|
|
31
|
+
}
|
|
32
|
+
],
|
|
33
|
+
"assert": {
|
|
34
|
+
"movement": {
|
|
35
|
+
"entity": "player",
|
|
36
|
+
"minDistance": 3
|
|
37
|
+
},
|
|
38
|
+
"components": [
|
|
39
|
+
{
|
|
40
|
+
"entity": "smooth-motion",
|
|
41
|
+
"component": "samples",
|
|
42
|
+
"gte": 21
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"entity": "smooth-motion",
|
|
46
|
+
"component": "playerCv",
|
|
47
|
+
"gte": 0,
|
|
48
|
+
"lte": 0.1
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
"entity": "smooth-motion",
|
|
52
|
+
"component": "cameraCv",
|
|
53
|
+
"gte": 0,
|
|
54
|
+
"lte": 0.1
|
|
55
|
+
}
|
|
56
|
+
],
|
|
57
|
+
"diagnostics": {
|
|
58
|
+
"noConsoleErrors": true,
|
|
59
|
+
"noNetworkErrors": false,
|
|
60
|
+
"runtimeReady": true,
|
|
61
|
+
"networkErrorsOptOutReason": "The starter loads no network resources, and the native host exposes no runtime.network observation."
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
@@ -17,9 +17,9 @@
|
|
|
17
17
|
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
18
18
|
},
|
|
19
19
|
"dependencies": {
|
|
20
|
-
"@threenative/core": "0.3.
|
|
21
|
-
"@threenative/physics": "0.3.
|
|
22
|
-
"@threenative/ui": "0.3.
|
|
20
|
+
"@threenative/core": "0.3.6",
|
|
21
|
+
"@threenative/physics": "0.3.6",
|
|
22
|
+
"@threenative/ui": "0.3.6",
|
|
23
23
|
"react": "19.2.0",
|
|
24
24
|
"react-dom": "19.2.0",
|
|
25
25
|
"react-reconciler": "0.33.0",
|
|
@@ -27,25 +27,26 @@
|
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@tailwindcss/vite": "4.3.3",
|
|
30
|
-
"@threenative/assets": "0.3.
|
|
31
|
-
"@threenative/playtest": "0.3.
|
|
30
|
+
"@threenative/assets": "0.3.7",
|
|
31
|
+
"@threenative/playtest": "0.3.6",
|
|
32
32
|
"@types/react": "19.2.0",
|
|
33
33
|
"@types/react-dom": "19.2.0",
|
|
34
34
|
"@types/three": "0.185.3",
|
|
35
35
|
"@vitejs/plugin-react": "6.0.5",
|
|
36
|
-
"create-threenative": "0.2.
|
|
36
|
+
"create-threenative": "0.2.10",
|
|
37
37
|
"esbuild": "0.27.0",
|
|
38
38
|
"playwright": "1.62.1",
|
|
39
39
|
"tailwindcss": "4.3.3",
|
|
40
|
-
"typescript": "
|
|
40
|
+
"typescript": "7.0.2",
|
|
41
41
|
"vite": "8.2.0",
|
|
42
42
|
"@gltf-transform/cli": "4.4.2"
|
|
43
43
|
},
|
|
44
44
|
"optionalDependencies": {
|
|
45
|
-
"@threenative/runtime-native": "0.3.
|
|
45
|
+
"@threenative/runtime-native": "0.3.6"
|
|
46
46
|
},
|
|
47
47
|
"overrides": {
|
|
48
|
-
"sharp": ">=0.35.4"
|
|
48
|
+
"sharp": ">=0.35.4",
|
|
49
|
+
"@vitejs/devtools": "0.4.1"
|
|
49
50
|
},
|
|
50
51
|
"pnpm": {
|
|
51
52
|
"overrides": {
|
|
@@ -53,7 +54,9 @@
|
|
|
53
54
|
},
|
|
54
55
|
"onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
|
|
55
56
|
"patchedDependencies": {
|
|
56
|
-
"three@0.185.1": "patches/three@0.185.1.patch"
|
|
57
|
+
"three@0.185.1": "patches/three@0.185.1.patch",
|
|
58
|
+
"vite@8.2.0": "patches/vite@8.2.0.patch",
|
|
59
|
+
"@tailwindcss/node@4.3.3": "patches/@tailwindcss__node@4.3.3.patch"
|
|
57
60
|
}
|
|
58
61
|
}
|
|
59
62
|
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "smooth-motion",
|
|
4
|
+
"target": "web",
|
|
5
|
+
"subject": "player",
|
|
6
|
+
"viewport": {
|
|
7
|
+
"width": 1280,
|
|
8
|
+
"height": 720
|
|
9
|
+
},
|
|
10
|
+
"warmupFrames": 60,
|
|
11
|
+
"steps": [
|
|
12
|
+
{
|
|
13
|
+
"kind": "wait",
|
|
14
|
+
"label": "ready",
|
|
15
|
+
"waitTicks": 240,
|
|
16
|
+
"release": true
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"kind": "input",
|
|
20
|
+
"label": "clear-crate",
|
|
21
|
+
"press": ["KeyS"],
|
|
22
|
+
"holdTicks": 35,
|
|
23
|
+
"release": true
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"kind": "input",
|
|
27
|
+
"label": "steady-walk",
|
|
28
|
+
"press": ["KeyD"],
|
|
29
|
+
"holdTicks": 180,
|
|
30
|
+
"release": true
|
|
31
|
+
}
|
|
32
|
+
],
|
|
33
|
+
"assert": {
|
|
34
|
+
"diagnostics": {
|
|
35
|
+
"noConsoleErrors": true,
|
|
36
|
+
"noNetworkErrors": true,
|
|
37
|
+
"runtimeReady": true
|
|
38
|
+
},
|
|
39
|
+
"movement": {
|
|
40
|
+
"entity": "player",
|
|
41
|
+
"minDistance": 3
|
|
42
|
+
},
|
|
43
|
+
"components": [
|
|
44
|
+
{
|
|
45
|
+
"entity": "smooth-motion",
|
|
46
|
+
"component": "samples",
|
|
47
|
+
"gte": 21
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"entity": "smooth-motion",
|
|
51
|
+
"component": "playerCv",
|
|
52
|
+
"gte": 0,
|
|
53
|
+
"lte": 0.1
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
"entity": "smooth-motion",
|
|
57
|
+
"component": "cameraCv",
|
|
58
|
+
"gte": 0,
|
|
59
|
+
"lte": 0.1
|
|
60
|
+
}
|
|
61
|
+
]
|
|
62
|
+
}
|
|
63
|
+
}
|