create-threenative 0.2.6 → 0.2.7
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/README.md +2 -2
- package/agent-docs/references/build-profiles.md +126 -0
- package/agent-docs/references/capability-reference.md +431 -20
- package/agent-docs/references/performance-basics.md +8 -5
- package/agent-docs/references/sculpt-from-a-reference.md +1 -1
- package/agent-docs/references/trace-a-slow-frame.md +1 -1
- package/agent-docs/references/visual-baseline.md +8 -4
- package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +5 -5
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-context/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +3 -3
- package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
- package/capabilities.json +555 -21
- package/dist/index.d.ts +30 -1
- package/dist/index.js +294 -55
- package/dist/threenative.js +714 -154
- package/package.json +6 -6
- package/template-assets/assets/mannequin-combat.glb +0 -0
- package/template-assets/assets/mannequin.glb +0 -0
- package/template-assets/assets/player-viewmodel.glb +0 -0
- package/template-assets/assets/sky.jpg +0 -0
- package/template-assets/clearwater/README.md +141 -0
- package/template-assets/clearwater/install.mjs +50 -0
- package/template-assets/clearwater/src/clearwater.ts +180 -0
- package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
- package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
- package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
- package/template-assets/clearwater/src/render/clearwater.ts +278 -0
- package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
- package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
- package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
- package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
- package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
- package/template-assets/patches/three@0.185.1.patch +2101 -138
- package/template-assets/worldEnvironment.ts +52 -1
- package/templates/action-rpg/AGENTS.md +42 -42
- package/templates/action-rpg/CLAUDE.md +42 -42
- package/templates/action-rpg/kit.json +1 -1
- package/templates/action-rpg/package.json +13 -7
- package/templates/action-rpg/playtests/combat.playtest.json +162 -23
- package/templates/action-rpg/playtests/performance.playtest.json +4 -3
- package/templates/action-rpg/playtests/survives.playtest.json +25 -8
- package/templates/action-rpg/src/conventions.ts +24 -18
- package/templates/action-rpg/src/entities/Enemy.ts +74 -24
- package/templates/action-rpg/src/entities/Fighter.ts +127 -0
- package/templates/action-rpg/src/entities/Player.ts +102 -32
- package/templates/action-rpg/src/game.ts +3 -3
- package/templates/action-rpg/src/render/camera.ts +18 -16
- package/templates/action-rpg/src/render/dungeon.ts +192 -0
- package/templates/action-rpg/src/render/lighting.ts +45 -28
- package/templates/action-rpg/src/render/loading.ts +4 -4
- package/templates/action-rpg/src/render/materials.ts +191 -47
- package/templates/action-rpg/src/render/palette.ts +14 -13
- package/templates/action-rpg/src/render/postprocessing.ts +12 -2
- package/templates/action-rpg/src/render/props.ts +117 -0
- package/templates/action-rpg/src/render/quality.ts +40 -82
- package/templates/action-rpg/src/render/sky.ts +36 -13
- package/templates/action-rpg/src/render/touch-controls.ts +1 -1
- package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
- package/templates/action-rpg/src/scenes/Play.ts +61 -39
- package/templates/action-rpg/src/style.css +9 -7
- package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
- package/templates/action-rpg/src/ui/Hud.tsx +3 -3
- package/templates/action-rpg/threenative.config.ts +14 -1
- package/templates/action-rpg/vite.config.ts +4 -1
- package/templates/minimal/AGENTS.md +10 -10
- package/templates/minimal/CLAUDE.md +10 -10
- package/templates/minimal/package.json +12 -6
- package/templates/minimal/playtests/play.playtest.json +6 -5
- package/templates/minimal/playtests/sky.playtest.json +27 -0
- package/templates/minimal/src/conventions.ts +6 -3
- package/templates/minimal/src/entities/Player.ts +73 -27
- package/templates/minimal/src/main.ts +2 -3
- package/templates/minimal/src/render/camera.ts +22 -4
- package/templates/minimal/src/render/lighting.ts +24 -48
- package/templates/minimal/src/render/materials.ts +158 -13
- package/templates/minimal/src/render/palette.ts +10 -7
- package/templates/minimal/src/render/postprocessing.ts +12 -25
- package/templates/minimal/src/render/quality.ts +35 -69
- package/templates/minimal/src/render/sky.ts +35 -54
- package/templates/minimal/src/render/touch-controls.ts +1 -1
- package/templates/minimal/src/render/worldEnvironment.ts +52 -1
- package/templates/minimal/src/scenes/Play.ts +121 -111
- package/templates/minimal/src/state.ts +0 -4
- package/templates/minimal/src/style.css +0 -10
- package/templates/minimal/threenative.config.ts +14 -1
- package/templates/minimal/vite.config.ts +4 -1
- package/templates/platformer/AGENTS.md +18 -56
- package/templates/platformer/CLAUDE.md +18 -56
- package/templates/platformer/kit.json +2 -2
- package/templates/platformer/package.json +13 -9
- package/templates/platformer/playtests/buffer.playtest.json +15 -5
- package/templates/platformer/playtests/collect.playtest.json +8 -34
- package/templates/platformer/playtests/coyote.playtest.json +12 -34
- package/templates/platformer/playtests/damage.playtest.json +40 -15
- package/templates/platformer/playtests/hud.playtest.json +34 -0
- package/templates/platformer/playtests/move.playtest.json +24 -0
- package/templates/platformer/playtests/performance.playtest.json +24 -7
- package/templates/platformer/playtests/respawn.playtest.json +46 -11
- package/templates/platformer/playtests/stomp.playtest.json +49 -12
- package/templates/platformer/playtests/survives.playtest.json +3 -19
- package/templates/platformer/playtests/world.playtest.json +26 -0
- package/templates/platformer/src/entities/Fox.ts +273 -0
- package/templates/platformer/src/entities/Pickup.ts +43 -60
- package/templates/platformer/src/entities/Walker.ts +88 -0
- package/templates/platformer/src/game.ts +11 -8
- package/templates/platformer/src/level/Checkpoints.ts +29 -16
- package/templates/platformer/src/level/Stage.ts +469 -0
- package/templates/platformer/src/render/blocks.ts +94 -0
- package/templates/platformer/src/render/camera.ts +28 -3
- package/templates/platformer/src/render/fox.ts +196 -0
- package/templates/platformer/src/render/lighting.ts +42 -33
- package/templates/platformer/src/render/materials.ts +115 -5
- package/templates/platformer/src/render/palette.ts +68 -53
- package/templates/platformer/src/render/pickups.ts +142 -0
- package/templates/platformer/src/render/postprocessing.ts +12 -2
- package/templates/platformer/src/render/props.ts +147 -0
- package/templates/platformer/src/render/quality.ts +47 -99
- package/templates/platformer/src/render/scenery.ts +172 -0
- package/templates/platformer/src/render/sky.ts +120 -31
- package/templates/platformer/src/render/touch-controls.ts +5 -2
- package/templates/platformer/src/render/walkers.ts +96 -0
- package/templates/platformer/src/render/waterfall.ts +85 -0
- package/templates/platformer/src/render/worldEnvironment.ts +52 -1
- package/templates/platformer/src/scenes/Boot.ts +3 -4
- package/templates/platformer/src/scenes/Play.ts +362 -0
- package/templates/platformer/src/state.ts +16 -14
- package/templates/platformer/src/style.css +9 -8
- package/templates/platformer/src/ui/Hud.tsx +62 -29
- package/templates/platformer/src/ui/Menu.tsx +2 -2
- package/templates/platformer/threenative.config.ts +14 -1
- package/templates/platformer/vite.config.ts +4 -1
- package/templates/puzzle/AGENTS.md +19 -20
- package/templates/puzzle/CLAUDE.md +19 -20
- package/templates/puzzle/assets/native-proof.glb +0 -0
- package/templates/puzzle/assets/native-proof.png +0 -0
- package/templates/puzzle/kit.json +1 -1
- package/templates/puzzle/package.json +13 -7
- package/templates/puzzle/playtests/axis.playtest.json +20 -0
- package/templates/puzzle/playtests/blocked.playtest.json +73 -0
- package/templates/puzzle/playtests/caused.playtest.json +65 -0
- package/templates/puzzle/playtests/lit.playtest.json +74 -0
- package/templates/puzzle/playtests/performance.playtest.json +24 -7
- package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
- package/templates/puzzle/playtests/replay.playtest.json +81 -0
- package/templates/puzzle/playtests/restart.playtest.json +108 -0
- package/templates/puzzle/playtests/seal.playtest.json +98 -0
- package/templates/puzzle/playtests/settle.playtest.json +100 -0
- package/templates/puzzle/playtests/survives.playtest.json +6 -29
- package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
- package/templates/puzzle/src/entities/Crate.ts +99 -42
- package/templates/puzzle/src/entities/Seal.ts +69 -0
- package/templates/puzzle/src/entities/Warden.ts +135 -0
- package/templates/puzzle/src/game.ts +15 -11
- package/templates/puzzle/src/render/camera.ts +66 -31
- package/templates/puzzle/src/render/crateShape.ts +70 -0
- package/templates/puzzle/src/render/lighting.ts +41 -41
- package/templates/puzzle/src/render/loading.ts +4 -4
- package/templates/puzzle/src/render/materials.ts +131 -27
- package/templates/puzzle/src/render/palette.ts +19 -29
- package/templates/puzzle/src/render/postprocessing.ts +15 -3
- package/templates/puzzle/src/render/quality.ts +71 -80
- package/templates/puzzle/src/render/shapes.ts +109 -108
- package/templates/puzzle/src/render/sky.ts +18 -10
- package/templates/puzzle/src/render/touch-controls.ts +8 -51
- package/templates/puzzle/src/render/vault.ts +315 -0
- package/templates/puzzle/src/render/warden.ts +46 -0
- package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
- package/templates/puzzle/src/scenes/Play.ts +793 -0
- package/templates/puzzle/src/state.ts +55 -24
- package/templates/puzzle/src/style.css +7 -8
- package/templates/puzzle/src/ui/App.tsx +2 -2
- package/templates/puzzle/src/ui/Hud.tsx +92 -40
- package/templates/puzzle/src/ui/Menu.tsx +40 -2
- package/templates/puzzle/threenative.config.ts +14 -1
- package/templates/puzzle/vite.config.ts +4 -1
- package/templates/racing/AGENTS.md +19 -20
- package/templates/racing/CLAUDE.md +19 -20
- package/templates/racing/package.json +13 -7
- package/templates/racing/playtests/boost.playtest.json +33 -12
- package/templates/racing/playtests/outcome.playtest.json +32 -50
- package/templates/racing/playtests/performance.playtest.json +2 -1
- package/templates/racing/playtests/ranking.playtest.json +5 -14
- package/templates/racing/playtests/rescue.playtest.json +2 -2
- package/templates/racing/playtests/reverse.playtest.json +30 -8
- package/templates/racing/playtests/shortcut.playtest.json +54 -9
- package/templates/racing/playtests/touch-controls.playtest.json +32 -5
- package/templates/racing/src/entities/CarBody.ts +327 -0
- package/templates/racing/src/entities/LineDriver.ts +220 -0
- package/templates/racing/src/entities/RacingCar.ts +150 -89
- package/templates/racing/src/entities/Rival.ts +61 -24
- package/templates/racing/src/game.ts +5 -0
- package/templates/racing/src/render/camera.ts +49 -7
- package/templates/racing/src/render/lighting.ts +36 -37
- package/templates/racing/src/render/materials.ts +239 -19
- package/templates/racing/src/render/palette.ts +19 -21
- package/templates/racing/src/render/postprocessing.ts +12 -2
- package/templates/racing/src/render/quality.ts +43 -82
- package/templates/racing/src/render/shapes.ts +20 -6
- package/templates/racing/src/render/sky.ts +47 -39
- package/templates/racing/src/render/touch-controls.ts +1 -1
- package/templates/racing/src/render/worldEnvironment.ts +52 -1
- package/templates/racing/src/scenes/Race.ts +107 -54
- package/templates/racing/src/state.ts +2 -0
- package/templates/racing/src/track/Checkline.ts +22 -7
- package/templates/racing/src/track/Lap.ts +64 -36
- package/templates/racing/src/track/Ranking.ts +20 -11
- package/templates/racing/src/track/Track.ts +809 -361
- package/templates/racing/src/track/TrackSector.ts +40 -11
- package/templates/racing/src/track/circuit.ts +477 -0
- package/templates/racing/src/track/rescue.ts +16 -4
- package/templates/racing/threenative.config.ts +14 -1
- package/templates/racing/vite.config.ts +4 -1
- package/templates/rts/AGENTS.md +96 -0
- package/templates/rts/CLAUDE.md +98 -0
- package/templates/rts/kit.json +7 -0
- package/templates/{defense → rts}/package.json +13 -7
- package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
- package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
- package/templates/rts/playtests/rts-attack.playtest.json +75 -0
- package/templates/rts/playtests/rts-build.playtest.json +68 -0
- package/templates/rts/playtests/rts-orders.playtest.json +150 -0
- package/templates/rts/playtests/rts-train.playtest.json +62 -0
- package/templates/rts/playtests/survives.playtest.json +58 -0
- package/templates/rts/public/favicon.svg +4 -0
- package/templates/rts/src/game.ts +64 -0
- package/templates/rts/src/orders.ts +22 -0
- package/templates/rts/src/render/army.ts +346 -0
- package/templates/rts/src/render/camera.ts +123 -0
- package/templates/rts/src/render/lighting.ts +61 -0
- package/templates/rts/src/render/loading.ts +33 -0
- package/templates/rts/src/render/materials.ts +152 -0
- package/templates/rts/src/render/models.ts +705 -0
- package/templates/rts/src/render/palette.ts +17 -0
- package/templates/rts/src/render/picking.ts +93 -0
- package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
- package/templates/rts/src/render/quality.ts +128 -0
- package/templates/rts/src/render/resources.ts +141 -0
- package/templates/rts/src/render/sky.ts +44 -0
- package/templates/rts/src/render/terrain.ts +116 -0
- package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
- package/templates/rts/src/scenes/Play.ts +650 -0
- package/templates/rts/src/sim/ai.ts +1140 -0
- package/templates/rts/src/sim/combat.ts +416 -0
- package/templates/rts/src/sim/construction.ts +374 -0
- package/templates/rts/src/sim/economy.ts +167 -0
- package/templates/rts/src/sim/game.ts +1082 -0
- package/templates/rts/src/sim/movement.ts +371 -0
- package/templates/rts/src/sim/nav.ts +276 -0
- package/templates/rts/src/sim/production.ts +180 -0
- package/templates/rts/src/sim/terrain.ts +170 -0
- package/templates/rts/src/sim/types.ts +647 -0
- package/templates/rts/src/sim/vision.ts +46 -0
- package/templates/rts/src/state.ts +100 -0
- package/templates/{defense → rts}/src/style.css +21 -8
- package/templates/rts/src/ui/App.tsx +21 -0
- package/templates/rts/src/ui/Commands.tsx +129 -0
- package/templates/rts/src/ui/GameUi.tsx +22 -0
- package/templates/rts/src/ui/Hud.tsx +165 -0
- package/templates/rts/src/ui/Minimap.tsx +84 -0
- package/templates/rts/tailwind.config.ts +2 -0
- package/templates/rts/threenative.config.ts +56 -0
- package/templates/rts/tsconfig.json +17 -0
- package/templates/{defense → rts}/vite.config.ts +4 -1
- package/templates/runner/AGENTS.md +6 -10
- package/templates/runner/CLAUDE.md +6 -10
- package/templates/runner/README.md +3 -3
- package/templates/runner/package.json +13 -7
- package/templates/runner/playtests/performance.playtest.json +2 -2
- package/templates/runner/src/conventions.ts +4 -3
- package/templates/runner/src/entities/Runner.ts +54 -7
- package/templates/runner/src/game.ts +2 -0
- package/templates/runner/src/render/camera.ts +4 -2
- package/templates/runner/src/render/dust.ts +5 -2
- package/templates/runner/src/render/lighting.ts +41 -45
- package/templates/runner/src/render/loading.ts +2 -2
- package/templates/runner/src/render/materials.ts +165 -25
- package/templates/runner/src/render/palette.ts +17 -28
- package/templates/runner/src/render/postprocessing.ts +12 -2
- package/templates/runner/src/render/quality.ts +42 -96
- package/templates/runner/src/render/shapes.ts +59 -37
- package/templates/runner/src/render/sky.ts +32 -41
- package/templates/runner/src/render/touch-controls.ts +1 -1
- package/templates/runner/src/render/worldEnvironment.ts +52 -1
- package/templates/runner/src/scenes/Run.ts +26 -6
- package/templates/runner/src/track.ts +6 -1
- package/templates/runner/threenative.config.ts +14 -1
- package/templates/runner/vite.config.ts +4 -1
- package/templates/sailing/AGENTS.md +12 -12
- package/templates/sailing/CLAUDE.md +12 -12
- package/templates/sailing/assets/ship.glb +0 -0
- package/templates/sailing/package.json +13 -7
- package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
- package/templates/sailing/playtests/sails.playtest.json +33 -0
- package/templates/sailing/playtests/win.playtest.json +156 -8
- package/templates/sailing/src/conventions.ts +29 -2
- package/templates/sailing/src/entities/Ship.ts +381 -57
- package/templates/sailing/src/game.ts +14 -0
- package/templates/sailing/src/render/camera.ts +63 -9
- package/templates/sailing/src/render/lighting.ts +49 -27
- package/templates/sailing/src/render/materials.ts +50 -15
- package/templates/sailing/src/render/ocean.ts +647 -60
- package/templates/sailing/src/render/palette.ts +16 -12
- package/templates/sailing/src/render/postprocessing.ts +12 -2
- package/templates/sailing/src/render/props.ts +316 -442
- package/templates/sailing/src/render/quality.ts +14 -4
- package/templates/sailing/src/render/sky.ts +116 -23
- package/templates/sailing/src/render/worldEnvironment.ts +52 -1
- package/templates/sailing/src/scenes/Boot.ts +21 -0
- package/templates/sailing/src/scenes/Sailing.ts +173 -39
- package/templates/sailing/src/state.ts +6 -0
- package/templates/sailing/src/ui/Hud.tsx +41 -9
- package/templates/sailing/threenative.config.ts +14 -1
- package/templates/sailing/vite.config.ts +4 -1
- package/templates/shooter/AGENTS.md +27 -42
- package/templates/shooter/CLAUDE.md +27 -42
- package/templates/shooter/index.html +1 -0
- package/templates/shooter/package.json +13 -7
- package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
- package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
- package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
- package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
- package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
- package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
- package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
- package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
- package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
- package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
- package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
- package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
- package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
- package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
- package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
- package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
- package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
- package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
- package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
- package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
- package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
- package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
- package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
- package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
- package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
- package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
- package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
- package/templates/shooter/playtests/input-control.playtest.json +43 -98
- package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
- package/templates/shooter/playtests/performance.playtest.json +62 -26
- package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
- package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
- package/templates/shooter/playtests/survives.playtest.json +36 -30
- package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
- package/templates/shooter/src/entities/Breakables.ts +412 -0
- package/templates/shooter/src/entities/Enemy.ts +2095 -0
- package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
- package/templates/shooter/src/entities/Rifle.ts +442 -0
- package/templates/shooter/src/entities/Target.ts +199 -83
- package/templates/shooter/src/entities/TouchControls.ts +276 -0
- package/templates/shooter/src/game.ts +75 -41
- package/templates/shooter/src/main.ts +0 -1
- package/templates/shooter/src/postPhysics.ts +36 -0
- package/templates/shooter/src/render/camera.ts +78 -74
- package/templates/shooter/src/render/decals.ts +142 -82
- package/templates/shooter/src/render/facade.ts +1373 -0
- package/templates/shooter/src/render/gunfx.ts +704 -0
- package/templates/shooter/src/render/lighting.ts +52 -38
- package/templates/shooter/src/render/loading.ts +2 -2
- package/templates/shooter/src/render/materials.ts +100 -88
- package/templates/shooter/src/render/occlusion.ts +108 -0
- package/templates/shooter/src/render/palette.ts +10 -10
- package/templates/shooter/src/render/palm.ts +455 -0
- package/templates/shooter/src/render/pooled-billboards.ts +144 -0
- package/templates/shooter/src/render/postprocessing.ts +15 -3
- package/templates/shooter/src/render/quality.ts +40 -82
- package/templates/shooter/src/render/scale.ts +148 -15
- package/templates/shooter/src/render/shapes.ts +138 -613
- package/templates/shooter/src/render/sky.ts +35 -35
- package/templates/shooter/src/render/town-schematic.ts +120 -0
- package/templates/shooter/src/render/town.ts +986 -0
- package/templates/shooter/src/render/townMaterials.ts +160 -0
- package/templates/shooter/src/render/vehicles.ts +741 -0
- package/templates/shooter/src/render/worldEnvironment.ts +52 -1
- package/templates/shooter/src/scenes/Play.ts +727 -650
- package/templates/shooter/src/state.ts +26 -41
- package/templates/shooter/src/style.css +207 -11
- package/templates/shooter/src/surfaces.ts +131 -0
- package/templates/shooter/src/ui/App.tsx +9 -10
- package/templates/shooter/src/ui/Crosshair.tsx +25 -18
- package/templates/shooter/src/ui/GameUi.tsx +6 -9
- package/templates/shooter/src/ui/Hud.tsx +428 -39
- package/templates/shooter/src/ui/Minimap.tsx +164 -0
- package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
- package/templates/shooter/src/ui/main.tsx +2 -3
- package/templates/shooter/threenative.config.ts +14 -1
- package/templates/shooter/vite.config.ts +4 -1
- package/templates/starter/AGENTS.md +17 -17
- package/templates/starter/CLAUDE.md +17 -17
- package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
- package/templates/starter/package.json +13 -7
- package/templates/starter/playtests/play.playtest.json +2 -1
- package/templates/starter/playtests/survives.playtest.json +1 -1
- package/templates/starter/src/conventions.ts +6 -3
- package/templates/starter/src/entities/Goal.ts +35 -42
- package/templates/starter/src/entities/Player.ts +99 -16
- package/templates/starter/src/render/arena.ts +131 -0
- package/templates/starter/src/render/lighting.ts +27 -44
- package/templates/starter/src/render/materials.ts +164 -35
- package/templates/starter/src/render/palette.ts +16 -16
- package/templates/starter/src/render/postprocessing.ts +6 -7
- package/templates/starter/src/render/quality.ts +43 -101
- package/templates/starter/src/render/shapes.ts +1 -1
- package/templates/starter/src/render/sky.ts +39 -45
- package/templates/starter/src/render/touch-controls.ts +3 -1
- package/templates/starter/src/render/worldEnvironment.ts +52 -1
- package/templates/starter/src/scenes/Play.ts +82 -81
- package/templates/starter/threenative.config.ts +14 -1
- package/templates/starter/vite.config.ts +4 -1
- package/templates/tower-defense/.codex/config.toml +19 -0
- package/templates/tower-defense/.cursor/mcp.json +32 -0
- package/templates/tower-defense/.gemini/settings.json +32 -0
- package/templates/tower-defense/.mcp.json +32 -0
- package/templates/tower-defense/.vscode/mcp.json +36 -0
- package/templates/tower-defense/.zed/settings.json +36 -0
- package/templates/{defense → tower-defense}/AGENTS.md +14 -12
- package/templates/{defense → tower-defense}/CLAUDE.md +14 -12
- package/templates/tower-defense/README.md +16 -0
- package/templates/tower-defense/index.html +12 -0
- package/templates/tower-defense/kit.json +7 -0
- package/templates/tower-defense/opencode.json +41 -0
- package/templates/tower-defense/package.json +56 -0
- package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
- package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
- package/templates/tower-defense/playtests/look.playtest.json +130 -0
- package/templates/tower-defense/playtests/performance.playtest.json +77 -0
- package/templates/tower-defense/playtests/placement.playtest.json +115 -0
- package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
- package/templates/tower-defense/playtests/strike.playtest.json +98 -0
- package/templates/tower-defense/playtests/survives.playtest.json +85 -0
- package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
- package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
- package/templates/tower-defense/playtests/victory.playtest.json +810 -0
- package/templates/tower-defense/src/balance.ts +187 -0
- package/templates/tower-defense/src/board/Board.ts +100 -0
- package/templates/tower-defense/src/board/Route.ts +84 -0
- package/templates/tower-defense/src/camera-rig.ts +62 -0
- package/templates/tower-defense/src/economy.ts +64 -0
- package/templates/tower-defense/src/effects/Effects.ts +284 -0
- package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
- package/templates/tower-defense/src/game.ts +72 -0
- package/templates/tower-defense/src/intents.ts +21 -0
- package/templates/tower-defense/src/main.ts +15 -0
- package/templates/tower-defense/src/physics.ts +6 -0
- package/templates/tower-defense/src/render/camera.ts +38 -0
- package/templates/tower-defense/src/render/lighting.ts +42 -0
- package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
- package/templates/tower-defense/src/render/materials.ts +103 -0
- package/templates/tower-defense/src/render/palette.ts +58 -0
- package/templates/tower-defense/src/render/postprocessing.ts +46 -0
- package/templates/tower-defense/src/render/quality.ts +128 -0
- package/templates/tower-defense/src/render/shapes.ts +550 -0
- package/templates/tower-defense/src/render/sky.ts +27 -0
- package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
- package/templates/tower-defense/src/scenes/Battle.ts +539 -0
- package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
- package/templates/tower-defense/src/state.ts +88 -0
- package/templates/tower-defense/src/style.css +137 -0
- package/templates/tower-defense/src/towers/Tower.ts +230 -0
- package/templates/tower-defense/src/towers/targeting.ts +97 -0
- package/templates/tower-defense/src/ui/Hud.tsx +270 -0
- package/templates/tower-defense/src/ui/Menu.tsx +134 -0
- package/templates/tower-defense/src/ui/icons.tsx +54 -0
- package/templates/tower-defense/src/ui/main.tsx +14 -0
- package/templates/tower-defense/src/waves.ts +90 -0
- package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
- package/templates/tower-defense/vite.config.ts +41 -0
- package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
- package/agent-files/.claude/skills/ponytail/SKILL.md +0 -68
- package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
- package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -53
- package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
- package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -65
- package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -58
- package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
- package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
- package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
- package/agent-files/AGENT-ROLES.md +0 -26
- package/templates/action-rpg/src/render/shapes.ts +0 -269
- package/templates/action-rpg/src/render/types.ts +0 -3
- package/templates/action-rpg/src/scenes/Boot.ts +0 -12
- package/templates/defense/README.md +0 -10
- package/templates/defense/kit.json +0 -7
- package/templates/defense/playtests/leak.playtest.json +0 -23
- package/templates/defense/playtests/placement.playtest.json +0 -40
- package/templates/defense/playtests/scan.playtest.json +0 -20
- package/templates/defense/playtests/survive.playtest.json +0 -45
- package/templates/defense/playtests/survives.playtest.json +0 -36
- package/templates/defense/src/attackers/Attacker.ts +0 -120
- package/templates/defense/src/board/Route.ts +0 -94
- package/templates/defense/src/conventions.ts +0 -18
- package/templates/defense/src/economy.ts +0 -36
- package/templates/defense/src/entities/Player.ts +0 -52
- package/templates/defense/src/game.ts +0 -51
- package/templates/defense/src/physics.ts +0 -13
- package/templates/defense/src/placement/Buildable.ts +0 -49
- package/templates/defense/src/render/camera.ts +0 -16
- package/templates/defense/src/render/lighting.ts +0 -37
- package/templates/defense/src/render/materials.ts +0 -22
- package/templates/defense/src/render/palette.ts +0 -28
- package/templates/defense/src/render/quality.ts +0 -170
- package/templates/defense/src/render/shapes.ts +0 -246
- package/templates/defense/src/render/sky.ts +0 -45
- package/templates/defense/src/scenes/Boot.ts +0 -12
- package/templates/defense/src/scenes/Defense.ts +0 -231
- package/templates/defense/src/state.ts +0 -56
- package/templates/defense/src/towers/Tower.ts +0 -95
- package/templates/defense/src/towers/targeting.ts +0 -53
- package/templates/defense/src/ui/Hud.tsx +0 -62
- package/templates/defense/src/ui/Menu.tsx +0 -7
- package/templates/defense/src/waves.ts +0 -40
- package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
- package/templates/minimal/src/render/hud.ts +0 -69
- package/templates/platformer/playtests/avoidance.playtest.json +0 -28
- package/templates/platformer/playtests/chase.playtest.json +0 -21
- package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
- package/templates/platformer/playtests/oneway.playtest.json +0 -44
- package/templates/platformer/playtests/patrol.playtest.json +0 -13
- package/templates/platformer/playtests/physics.playtest.json +0 -14
- package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
- package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
- package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
- package/templates/platformer/src/conventions.ts +0 -18
- package/templates/platformer/src/entities/Character.ts +0 -286
- package/templates/platformer/src/entities/Chaser.ts +0 -118
- package/templates/platformer/src/entities/Patrol.ts +0 -93
- package/templates/platformer/src/level/Platform.ts +0 -46
- package/templates/platformer/src/render/rig.ts +0 -60
- package/templates/platformer/src/render/terrain.ts +0 -31
- package/templates/platformer/src/scenes/Level.ts +0 -241
- package/templates/puzzle/README.md +0 -43
- package/templates/puzzle/playtests/carry.playtest.json +0 -71
- package/templates/puzzle/playtests/swing.playtest.json +0 -38
- package/templates/puzzle/src/conventions.ts +0 -25
- package/templates/puzzle/src/entities/Ball.ts +0 -70
- package/templates/puzzle/src/entities/Gripper.ts +0 -69
- package/templates/puzzle/src/entities/Pendulum.ts +0 -89
- package/templates/puzzle/src/physics.ts +0 -19
- package/templates/puzzle/src/room.ts +0 -83
- package/templates/puzzle/src/scenes/Boot.ts +0 -12
- package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
- package/templates/shooter/playtests/combat.playtest.json +0 -48
- package/templates/shooter/playtests/fail.playtest.json +0 -31
- package/templates/shooter/playtests/per-item.playtest.json +0 -59
- package/templates/shooter/playtests/shooter.playtest.json +0 -99
- package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
- package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
- package/templates/shooter/src/combat/damage.ts +0 -40
- package/templates/shooter/src/conventions.ts +0 -51
- package/templates/shooter/src/entities/Pickup.ts +0 -70
- package/templates/shooter/src/entities/Player.ts +0 -310
- package/templates/shooter/src/level/SpawnPoints.ts +0 -28
- package/templates/shooter/src/playtest-events.ts +0 -15
- package/templates/shooter/src/render/touch-controls.ts +0 -305
- package/templates/shooter/src/render/types.ts +0 -3
- package/templates/shooter/src/render/ui.css +0 -330
- package/templates/shooter/src/render/ui.ts +0 -75
- package/templates/shooter/src/render/vfx.ts +0 -215
- package/templates/shooter/src/ui/Menu.tsx +0 -41
- package/templates/shooter/src/waves.ts +0 -50
- package/templates/shooter/src/weapons/Hitscan.ts +0 -42
- package/templates/shooter/src/weapons/Projectile.ts +0 -92
- package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
- package/templates/starter/playtests/assets.playtest.json +0 -65
- package/templates/starter/playtests/buffer.playtest.json +0 -79
- package/templates/starter/playtests/cloth.playtest.json +0 -113
- package/templates/starter/playtests/coyote.playtest.json +0 -87
- package/templates/starter/playtests/gameover.playtest.json +0 -66
- package/templates/starter/playtests/goal.playtest.json +0 -67
- package/templates/starter/playtests/look.playtest.json +0 -175
- package/templates/starter/playtests/models-baseline.png +0 -0
- package/templates/starter/playtests/models.playtest.json +0 -74
- package/templates/starter/playtests/monitoring.playtest.json +0 -72
- package/templates/starter/playtests/odometer.playtest.json +0 -54
- package/templates/starter/playtests/restart.playtest.json +0 -91
- package/templates/starter/playtests/seed.playtest.json +0 -54
- package/templates/starter/playtests/textures-baseline.png +0 -0
- package/templates/starter/playtests/textures.playtest.json +0 -74
- package/templates/starter/playtests/touch-controls.playtest.json +0 -42
- package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
- package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
- package/templates/starter/src/render/coast.ts +0 -199
- package/templates/starter/src/render/hero.ts +0 -88
- package/templates/starter/src/render/implicitSurface.ts +0 -199
- package/templates/starter/src/render/kuwahara.ts +0 -174
- package/templates/starter/src/render/outline.ts +0 -141
- package/templates/starter/src/render/painterly.ts +0 -86
- package/templates/starter/src/render/rockRidge.ts +0 -198
- package/templates/starter/src/render/rockRidge.worker.ts +0 -77
- package/templates/starter/src/render/scenery.ts +0 -40
- package/templates/starter/src/render/textureLifetime.ts +0 -53
- package/templates/starter/src/render/water.ts +0 -38
- package/templates/starter/src/render/watercolor.ts +0 -85
- /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
- /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
- /package/templates/{defense → rts}/.codex/config.toml +0 -0
- /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
- /package/templates/{defense → rts}/.gemini/settings.json +0 -0
- /package/templates/{defense → rts}/.mcp.json +0 -0
- /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
- /package/templates/{defense → rts}/.zed/settings.json +0 -0
- /package/templates/{defense → rts}/index.html +0 -0
- /package/templates/{defense → rts}/opencode.json +0 -0
- /package/templates/{defense → rts}/src/main.ts +0 -0
- /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
- /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
- /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
- /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
- /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
- /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
- /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
|
@@ -24,8 +24,10 @@ import {
|
|
|
24
24
|
} from "three";
|
|
25
25
|
import { bloom } from "three/addons/tsl/display/BloomNode.js";
|
|
26
26
|
import { denoise } from "three/addons/tsl/display/DenoiseNode.js";
|
|
27
|
+
import { fxaa } from "three/addons/tsl/display/FXAANode.js";
|
|
27
28
|
import { ao } from "three/addons/tsl/display/GTAONode.js";
|
|
28
29
|
import { godrays } from "three/addons/tsl/display/GodraysNode.js";
|
|
30
|
+
import { smaa } from "three/addons/tsl/display/SMAANode.js";
|
|
29
31
|
import { ssgi } from "three/addons/tsl/display/SSGINode.js";
|
|
30
32
|
import { ssr } from "three/addons/tsl/display/SSRNode.js";
|
|
31
33
|
import { sharpen } from "three/addons/tsl/display/SharpenNode.js";
|
|
@@ -33,6 +35,7 @@ import {
|
|
|
33
35
|
color,
|
|
34
36
|
convertToTexture,
|
|
35
37
|
float,
|
|
38
|
+
max,
|
|
36
39
|
metalness,
|
|
37
40
|
mrt,
|
|
38
41
|
normalView,
|
|
@@ -45,6 +48,9 @@ import {
|
|
|
45
48
|
} from "three/tsl";
|
|
46
49
|
import type { Node } from "three/webgpu";
|
|
47
50
|
|
|
51
|
+
/** Godot's `Viewport.screen_space_aa`: which post-process antialiasing smooths the frame's edges. */
|
|
52
|
+
export type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
|
|
53
|
+
|
|
48
54
|
/** Godot's `Environment.tonemap_mode`, with the modes Three.js actually ships. */
|
|
49
55
|
export type TonemapMode = "aces" | "agx" | "neutral";
|
|
50
56
|
|
|
@@ -184,6 +190,16 @@ export interface IWorldEnvironmentOptions {
|
|
|
184
190
|
readonly sharpenStrength?: number;
|
|
185
191
|
/** Corner darkening, as a fraction removed at the extreme corner. Zero disables it. */
|
|
186
192
|
readonly vignetteAmount?: number;
|
|
193
|
+
/**
|
|
194
|
+
* Post-process antialiasing, run last. Godot's `Viewport.screen_space_aa`. Default `"smaa"`.
|
|
195
|
+
*
|
|
196
|
+
* Not optional in practice: the chain renders `pass(scene, camera)` single-sampled, so the moment
|
|
197
|
+
* any stage runs, the renderer's own multisampling no longer reaches the frame and every edge
|
|
198
|
+
* stairsteps — the single loudest "this is a prototype" signal in a frame. It is requested only
|
|
199
|
+
* when some other stage (or a `baseColour`) installs a chain; with nothing installed the renderer
|
|
200
|
+
* draws straight to the canvas with its own MSAA and this would be paying twice.
|
|
201
|
+
*/
|
|
202
|
+
readonly screenSpaceAA?: ScreenSpaceAA;
|
|
187
203
|
/** Godot's `glow_enabled`. */
|
|
188
204
|
readonly bloomEnabled?: boolean;
|
|
189
205
|
readonly bloomStrength?: number;
|
|
@@ -391,6 +407,7 @@ export class WorldEnvironment {
|
|
|
391
407
|
sharpenEnabled: options.sharpenEnabled ?? false,
|
|
392
408
|
sharpenStrength: options.sharpenStrength ?? 0.2,
|
|
393
409
|
vignetteAmount: options.vignetteAmount ?? 0,
|
|
410
|
+
screenSpaceAA: options.screenSpaceAA ?? "smaa",
|
|
394
411
|
bloomEnabled: options.bloomEnabled ?? true,
|
|
395
412
|
bloomStrength: options.bloomStrength ?? 0.7,
|
|
396
413
|
bloomRadius: options.bloomRadius ?? 0.5,
|
|
@@ -432,6 +449,11 @@ export class WorldEnvironment {
|
|
|
432
449
|
(name === "vignette" && options.vignetteAmount > 0),
|
|
433
450
|
);
|
|
434
451
|
requested.push(...options.authoredStageNames);
|
|
452
|
+
if (
|
|
453
|
+
options.screenSpaceAA !== "disabled" &&
|
|
454
|
+
(requested.length > 0 || target.baseColour !== undefined)
|
|
455
|
+
)
|
|
456
|
+
requested.push("antialias");
|
|
435
457
|
|
|
436
458
|
// With no stage running there is no node graph to install — the renderer's own
|
|
437
459
|
// tone-mapping path renders the frame, and the exposure scalar is live there (measured:
|
|
@@ -542,7 +564,14 @@ export class WorldEnvironment {
|
|
|
542
564
|
// Applied before SSGI by the chain's canonical order; composing it after the GI
|
|
543
565
|
// combine instead darkens crevices the gather re-lit — that is a look choice, and
|
|
544
566
|
// this file is where you make it.
|
|
545
|
-
|
|
567
|
+
//
|
|
568
|
+
// Denoised with the same depth-aware filter as the GI gather: GTAO's interleaved
|
|
569
|
+
// sampling otherwise reads as a speckled halo around every contact — around feet on a
|
|
570
|
+
// plain floor most of all — which is exactly the "not smooth" a player notices first.
|
|
571
|
+
const occlusion = options.denoiseEnabled
|
|
572
|
+
? denoised(denoise(contact.getTextureNode(), depth(), normal(), view))
|
|
573
|
+
: contact;
|
|
574
|
+
return input.mul(occlusion.r);
|
|
546
575
|
},
|
|
547
576
|
}),
|
|
548
577
|
stage({
|
|
@@ -668,6 +697,26 @@ export class WorldEnvironment {
|
|
|
668
697
|
return input.mul(fall.oneMinus());
|
|
669
698
|
},
|
|
670
699
|
}),
|
|
700
|
+
{
|
|
701
|
+
// Last, after every built-in: antialiasing is defined on the finished picture, and any
|
|
702
|
+
// stage after it would put the stairsteps back.
|
|
703
|
+
name: "antialias",
|
|
704
|
+
after: "gradualBackground",
|
|
705
|
+
build: (input) => {
|
|
706
|
+
const colour = input as ChainNode;
|
|
707
|
+
// SMAA and FXAA find edges by local contrast and expect display-range colour, but this is
|
|
708
|
+
// the linear HDR frame before the tone curve — a sun-lit edge at 20 against sky at 3
|
|
709
|
+
// would blend into a bright halo. The reversible Karis weighting squeezes it into [0, 1)
|
|
710
|
+
// for the filter and expands it back afterwards, so edges resolve without the halo.
|
|
711
|
+
const peak = max(colour.r, max(colour.g, colour.b));
|
|
712
|
+
const squeezed = colour.div(peak.add(1));
|
|
713
|
+
const filtered = (options.screenSpaceAA === "fxaa"
|
|
714
|
+
? fxaa(squeezed)
|
|
715
|
+
: smaa(squeezed)) as unknown as ChainNode;
|
|
716
|
+
const back = max(filtered.r, max(filtered.g, filtered.b));
|
|
717
|
+
return filtered.div(float(1).sub(back).max(1e-4));
|
|
718
|
+
},
|
|
719
|
+
},
|
|
671
720
|
];
|
|
672
721
|
|
|
673
722
|
// The kit's own stages, composed after the built-ins. The factory is called with the two
|
|
@@ -723,6 +772,7 @@ export class WorldEnvironment {
|
|
|
723
772
|
const options = this.#options;
|
|
724
773
|
const off: Record<string, string> = {
|
|
725
774
|
ambientOcclusion: "gtaoEnabled is false",
|
|
775
|
+
antialias: 'screenSpaceAA is "disabled", or no other stage installed a chain',
|
|
726
776
|
bloom: "bloomEnabled is false",
|
|
727
777
|
godRays: "godraysEnabled is false",
|
|
728
778
|
sharpen: "sharpenEnabled is false",
|
|
@@ -745,6 +795,7 @@ export class WorldEnvironment {
|
|
|
745
795
|
denoise: options.denoiseEnabled,
|
|
746
796
|
exposure: options.exposure,
|
|
747
797
|
marker: "TN_WORLD_ENVIRONMENT",
|
|
798
|
+
screenSpaceAA: options.screenSpaceAA,
|
|
748
799
|
ssgiQuality: options.ssgiQuality,
|
|
749
800
|
stages,
|
|
750
801
|
tonemapMode: options.tonemapMode,
|
|
@@ -9,21 +9,14 @@ visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only
|
|
|
9
9
|
|
|
10
10
|
## Start every change
|
|
11
11
|
|
|
12
|
-
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
|
|
16
|
-
direct the user to review it, and wait for explicit approval plus an instruction to implement it.
|
|
17
|
-
3. Treat returned constraints as binding. `@threenative/physics/navigation` is a browser-only
|
|
18
|
-
WASM boundary here; use returned subpaths and `attachToBone` for held weapons.
|
|
12
|
+
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant 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.
|
|
13
|
+
2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints, direct the user to review it, and wait for explicit approval plus an instruction to implement it.
|
|
14
|
+
3. Treat returned constraints as binding. `@threenative/physics/navigation` is a browser-only WASM boundary here; use returned subpaths, and `attachToBone` for the blade in `hand_r`.
|
|
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` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
|
|
20
16
|
|
|
21
17
|
## When the framework blocks you, write plain Three.js
|
|
22
18
|
|
|
23
|
-
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
24
|
-
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
25
|
-
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
26
|
-
(API, expectation, result, replacement); never stall the game.
|
|
19
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); never stall the game.
|
|
27
20
|
|
|
28
21
|
## Workflow skills
|
|
29
22
|
|
|
@@ -35,7 +28,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
|
|
|
35
28
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
36
29
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
37
30
|
- `.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. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
|
|
31
|
+
- 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.
|
|
39
32
|
|
|
40
33
|
## Commands and map
|
|
41
34
|
|
|
@@ -46,50 +39,57 @@ pnpm build --target desktop
|
|
|
46
39
|
pnpm test
|
|
47
40
|
```
|
|
48
41
|
|
|
49
|
-
Controls: WASD/arrows move; Space/F attacks; E casts Arcane Surge; Q/U equips or
|
|
50
|
-
tests inventory; T defeats the visible enemy; C/R checkpoints; H/X damage or defeat.
|
|
51
|
-
lead to a boss win or zero-health loss. `StatBlock.ts` and
|
|
52
|
-
`intersectShape` for range
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
`
|
|
57
|
-
|
|
42
|
+
Controls: WASD/arrows move; Space/F attacks; E casts Arcane Surge; Shift rolls; Q/U equips or
|
|
43
|
+
unequips; P/L tests inventory; T defeats the visible enemy; C/R checkpoints; H/X damage or defeat.
|
|
44
|
+
Three rooms lead through two doorways to a boss win or zero-health loss. `StatBlock.ts` and
|
|
45
|
+
`Inventory.ts` are game-owned; use `intersectShape` for range, `intersectRay` for line of sight.
|
|
46
|
+
|
|
47
|
+
Every figure is `assets/mannequin-combat.glb` — hero, raiders and boss alike — instanced through
|
|
48
|
+
`SkeletalMesh3D` in `src/entities/Fighter.ts`: `requiredClips` fails the load by name,
|
|
49
|
+
`normaliseToMetres(model, { axis: "height", metres: 1.545 })` puts the `Head` joint where a 1.8 m
|
|
50
|
+
capsule expects it, hostiles are the same rig in a red-orange material, and the boss the same rig at
|
|
51
|
+
1.3x. Actions play the file's own clips — `Sword_Attack`, `Spell_Simple_Shoot`, `Punch_Jab`,
|
|
52
|
+
`Hit_Chest`, `Death01`, `PickUp_Table`, `Roll` — and a corpse keeps its entity registered so its death
|
|
53
|
+
clip finishes. `src/scenes/Play.ts` wires the loop and hands each room `Group` from
|
|
54
|
+
`src/render/dungeon.ts` to `buildStaticColliders`; `src/entities/` owns gameplay, `src/render/` the
|
|
55
|
+
look, `src/ui/` React, and `state.ts` publishes JSON-safe health, room and inventory. Keep
|
|
58
56
|
`playtests/survives.playtest.json` as the smoke proof and update the other scenarios with gameplay.
|
|
59
57
|
The state bridge flushes about 100 ms, so per-frame feedback stays in scene-owned Three.js.
|
|
60
58
|
|
|
59
|
+
On a touch-primary device, `src/render/touch-controls.ts` adds a left movement stick, attack and
|
|
60
|
+
Arcane Surge buttons; keyboard controls remain available on desktop.
|
|
61
|
+
|
|
61
62
|
## Portable authoring contracts
|
|
62
63
|
|
|
63
|
-
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `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.
|
|
64
|
+
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.
|
|
64
65
|
|
|
65
|
-
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
|
|
66
|
-
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact, `normaliseToMetres` for authored model scale, and `attachToBone` for held props.
|
|
67
|
-
Register testable entities with `ctx.entities`; `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, instance with `SkeletalMesh3D` to clone safely and validate clips, then call `character.update(dt)` from the owning scene's `update(dt)`.
|
|
66
|
+
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact, `normaliseToMetres` for authored model scale, and `attachToBone` for held props. Register testable entities with `ctx.entities`; `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, instance with `SkeletalMesh3D` to clone safely and validate clips, then call `character.update(dt)` from the owning scene's `update(dt)`. `attachToBone` re-parents a game-owned mesh to a named joint, so the hand moves the sword in every clip for free; the model faces +Z, so `facingVector` is `(sin, 0, cos)` of `figure.rotation.y`.
|
|
68
67
|
`ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then
|
|
69
68
|
`return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch.
|
|
70
|
-
`game.goto("<scene-name>")` also rebuilds the scene, but
|
|
71
|
-
|
|
69
|
+
`game.goto("<scene-name>")` also rebuilds the scene, but resets the game's state. Seeded randomness
|
|
70
|
+
is deterministic only when `defineGame({ seed })` is configured.
|
|
72
71
|
|
|
73
|
-
`AnimationPlayer` re-times a looping clip to the ground the body covers so feet do not skate —
|
|
74
|
-
in-place clips too, off a planted foot; a speed past what the clip carries is **clamped at 3x**, so
|
|
75
|
-
set it near `player.stride.clipGroundSpeed`. `strideSync: false` opts out, `maxFootSlide` bounds it. `clipPoseError` scores a retarget against its source
|
|
72
|
+
`AnimationPlayer` re-times a looping clip to the ground the body covers so feet do not skate — in-place clips too, off a planted foot; a speed past what the clip carries is **clamped at 3x**, so set it near `player.stride.clipGroundSpeed`. `strideSync: false` opts out, `maxFootSlide` bounds it. `clipPoseError` scores a retarget against its source
|
|
76
73
|
per bone in degrees — whole quaternions relative to each rig's bind pose, so bind conventions
|
|
77
74
|
cancel and an axis-rolled limb is caught where a bone-direction check reads zero.
|
|
78
|
-
`clipTrackBindings` names tracks that bind nothing (`<bone>.undefined`, which plays the bind
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
## Look and evidence
|
|
75
|
+
`clipTrackBindings` names tracks that bind nothing (`<bone>.undefined`, which plays the bind pose),
|
|
76
|
+
`clipBoneCoverage` names bones the clip does not drive, which keep the previous clip's pose, and
|
|
77
|
+
`boneContact` reports in metres whether a bone reaches its prop. 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 256 per presented frame 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.
|
|
83
78
|
|
|
84
|
-
|
|
79
|
+
## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
|
|
85
80
|
|
|
86
|
-
|
|
81
|
+
`src/render/` is yours to edit and is where the base look lives: the prototype test scene, a metre
|
|
82
|
+
grid in world UVs over a light floor and a dark structure, `palette.ts`'s five roles with exactly one
|
|
83
|
+
saturated `accent` for anything you can touch, `sky.ts`'s photograph behind everything, and bevelled
|
|
84
|
+
`RoundedBoxGeometry` sunk by its bevel radius. Torch point lights are the only warm light.
|
|
85
|
+
`quality.ts` defines `low`, `medium`, and `high`; `isMobile()` selects `low`, otherwise `high`, and
|
|
86
|
+
`setupPost(..., { tier: "low" })` is the named override — unknown tiers throw and `TN_QUALITY_TIER`
|
|
87
|
+
reports the source. VFX appearance belongs in `src/render/vfx.ts`: keep its TSL material, geometry,
|
|
88
|
+
colour, blend, curves, timing and capacity there; gameplay creates `GPUParticles3D` once, adds it with
|
|
89
|
+
`ctx.add`, and calls `restart()` from the real attack or Arcane Surge path.
|
|
87
90
|
|
|
88
|
-
|
|
89
|
-
`high`; `isMobile()` selects `low`, otherwise `high`, and `setupPost(..., { tier: "low" })` is the
|
|
90
|
-
named override. Unknown tiers throw and `TN_QUALITY_TIER` reports the chosen source. A scenario
|
|
91
|
-
with no assertions or missing observations fails; keep the durable smoke proof and open a capture. 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 beside the frame rate; `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.
|
|
91
|
+
A scenario with no assertions or missing observations fails; keep the durable smoke proof and open a capture. 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.
|
|
92
92
|
|
|
93
|
-
Recipes
|
|
93
|
+
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`.
|
|
94
94
|
## Optional multiplayer transport
|
|
95
95
|
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`.
|
|
@@ -11,21 +11,14 @@ visual decision; `src/game.ts` stays portable and `src/main.ts` is the web-only
|
|
|
11
11
|
|
|
12
12
|
## Start every change
|
|
13
13
|
|
|
14
|
-
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
|
|
18
|
-
direct the user to review it, and wait for explicit approval plus an instruction to implement it.
|
|
19
|
-
3. Treat returned constraints as binding. `@threenative/physics/navigation` is a browser-only
|
|
20
|
-
WASM boundary here; use returned subpaths and `attachToBone` for held weapons.
|
|
14
|
+
1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant 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.
|
|
15
|
+
2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints, direct the user to review it, and wait for explicit approval plus an instruction to implement it.
|
|
16
|
+
3. Treat returned constraints as binding. `@threenative/physics/navigation` is a browser-only WASM boundary here; use returned subpaths, and `attachToBone` for the blade in `hand_r`.
|
|
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` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
|
|
22
18
|
|
|
23
19
|
## When the framework blocks you, write plain Three.js
|
|
24
20
|
|
|
25
|
-
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
|
|
26
|
-
piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
|
|
27
|
-
bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
|
|
28
|
-
(API, expectation, result, replacement); never stall the game.
|
|
21
|
+
When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); never stall the game.
|
|
29
22
|
|
|
30
23
|
## Workflow skills
|
|
31
24
|
|
|
@@ -37,7 +30,7 @@ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report
|
|
|
37
30
|
- `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
|
|
38
31
|
- `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
|
|
39
32
|
- `.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. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above.
|
|
33
|
+
- 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.
|
|
41
34
|
|
|
42
35
|
## Commands and map
|
|
43
36
|
|
|
@@ -48,50 +41,57 @@ pnpm build --target desktop
|
|
|
48
41
|
pnpm test
|
|
49
42
|
```
|
|
50
43
|
|
|
51
|
-
Controls: WASD/arrows move; Space/F attacks; E casts Arcane Surge; Q/U equips or
|
|
52
|
-
tests inventory; T defeats the visible enemy; C/R checkpoints; H/X damage or defeat.
|
|
53
|
-
lead to a boss win or zero-health loss. `StatBlock.ts` and
|
|
54
|
-
`intersectShape` for range
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
`
|
|
59
|
-
|
|
44
|
+
Controls: WASD/arrows move; Space/F attacks; E casts Arcane Surge; Shift rolls; Q/U equips or
|
|
45
|
+
unequips; P/L tests inventory; T defeats the visible enemy; C/R checkpoints; H/X damage or defeat.
|
|
46
|
+
Three rooms lead through two doorways to a boss win or zero-health loss. `StatBlock.ts` and
|
|
47
|
+
`Inventory.ts` are game-owned; use `intersectShape` for range, `intersectRay` for line of sight.
|
|
48
|
+
|
|
49
|
+
Every figure is `assets/mannequin-combat.glb` — hero, raiders and boss alike — instanced through
|
|
50
|
+
`SkeletalMesh3D` in `src/entities/Fighter.ts`: `requiredClips` fails the load by name,
|
|
51
|
+
`normaliseToMetres(model, { axis: "height", metres: 1.545 })` puts the `Head` joint where a 1.8 m
|
|
52
|
+
capsule expects it, hostiles are the same rig in a red-orange material, and the boss the same rig at
|
|
53
|
+
1.3x. Actions play the file's own clips — `Sword_Attack`, `Spell_Simple_Shoot`, `Punch_Jab`,
|
|
54
|
+
`Hit_Chest`, `Death01`, `PickUp_Table`, `Roll` — and a corpse keeps its entity registered so its death
|
|
55
|
+
clip finishes. `src/scenes/Play.ts` wires the loop and hands each room `Group` from
|
|
56
|
+
`src/render/dungeon.ts` to `buildStaticColliders`; `src/entities/` owns gameplay, `src/render/` the
|
|
57
|
+
look, `src/ui/` React, and `state.ts` publishes JSON-safe health, room and inventory. Keep
|
|
60
58
|
`playtests/survives.playtest.json` as the smoke proof and update the other scenarios with gameplay.
|
|
61
59
|
The state bridge flushes about 100 ms, so per-frame feedback stays in scene-owned Three.js.
|
|
62
60
|
|
|
61
|
+
On a touch-primary device, `src/render/touch-controls.ts` adds a left movement stick, attack and
|
|
62
|
+
Arcane Surge buttons; keyboard controls remain available on desktop.
|
|
63
|
+
|
|
63
64
|
## Portable authoring contracts
|
|
64
65
|
|
|
65
|
-
Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `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.
|
|
66
|
+
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.
|
|
66
67
|
|
|
67
|
-
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
|
|
68
|
-
Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact, `normaliseToMetres` for authored model scale, and `attachToBone` for held props.
|
|
69
|
-
Register testable entities with `ctx.entities`; `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, instance with `SkeletalMesh3D` to clone safely and validate clips, then call `character.update(dt)` from the owning scene's `update(dt)`.
|
|
68
|
+
Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable; generated conventions call `GroundSnap` for floor contact, `normaliseToMetres` for authored model scale, and `attachToBone` for held props. Register testable entities with `ctx.entities`; `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, instance with `SkeletalMesh3D` to clone safely and validate clips, then call `character.update(dt)` from the owning scene's `update(dt)`. `attachToBone` re-parents a game-owned mesh to a named joint, so the hand moves the sword in every clip for free; the model faces +Z, so `facingVector` is `(sin, 0, cos)` of `figure.rotation.y`.
|
|
70
69
|
`ctx.goto(name)` rebuilds without resetting game state; from a frame function `goto` and then
|
|
71
70
|
`return`; `ctx.state.set({ /* copy this game's initial-state shape */ })` is a partial patch.
|
|
72
|
-
`game.goto("<scene-name>")` also rebuilds the scene, but
|
|
73
|
-
|
|
71
|
+
`game.goto("<scene-name>")` also rebuilds the scene, but resets the game's state. Seeded randomness
|
|
72
|
+
is deterministic only when `defineGame({ seed })` is configured.
|
|
74
73
|
|
|
75
|
-
`AnimationPlayer` re-times a looping clip to the ground the body covers so feet do not skate —
|
|
76
|
-
in-place clips too, off a planted foot; a speed past what the clip carries is **clamped at 3x**, so
|
|
77
|
-
set it near `player.stride.clipGroundSpeed`. `strideSync: false` opts out, `maxFootSlide` bounds it. `clipPoseError` scores a retarget against its source
|
|
74
|
+
`AnimationPlayer` re-times a looping clip to the ground the body covers so feet do not skate — in-place clips too, off a planted foot; a speed past what the clip carries is **clamped at 3x**, so set it near `player.stride.clipGroundSpeed`. `strideSync: false` opts out, `maxFootSlide` bounds it. `clipPoseError` scores a retarget against its source
|
|
78
75
|
per bone in degrees — whole quaternions relative to each rig's bind pose, so bind conventions
|
|
79
76
|
cancel and an axis-rolled limb is caught where a bone-direction check reads zero.
|
|
80
|
-
`clipTrackBindings` names tracks that bind nothing (`<bone>.undefined`, which plays the bind
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
## Look and evidence
|
|
77
|
+
`clipTrackBindings` names tracks that bind nothing (`<bone>.undefined`, which plays the bind pose),
|
|
78
|
+
`clipBoneCoverage` names bones the clip does not drive, which keep the previous clip's pose, and
|
|
79
|
+
`boneContact` reports in metres whether a bone reaches its prop. 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 256 per presented frame 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.
|
|
85
80
|
|
|
86
|
-
|
|
81
|
+
## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
|
|
87
82
|
|
|
88
|
-
|
|
83
|
+
`src/render/` is yours to edit and is where the base look lives: the prototype test scene, a metre
|
|
84
|
+
grid in world UVs over a light floor and a dark structure, `palette.ts`'s five roles with exactly one
|
|
85
|
+
saturated `accent` for anything you can touch, `sky.ts`'s photograph behind everything, and bevelled
|
|
86
|
+
`RoundedBoxGeometry` sunk by its bevel radius. Torch point lights are the only warm light.
|
|
87
|
+
`quality.ts` defines `low`, `medium`, and `high`; `isMobile()` selects `low`, otherwise `high`, and
|
|
88
|
+
`setupPost(..., { tier: "low" })` is the named override — unknown tiers throw and `TN_QUALITY_TIER`
|
|
89
|
+
reports the source. VFX appearance belongs in `src/render/vfx.ts`: keep its TSL material, geometry,
|
|
90
|
+
colour, blend, curves, timing and capacity there; gameplay creates `GPUParticles3D` once, adds it with
|
|
91
|
+
`ctx.add`, and calls `restart()` from the real attack or Arcane Surge path.
|
|
89
92
|
|
|
90
|
-
|
|
91
|
-
`high`; `isMobile()` selects `low`, otherwise `high`, and `setupPost(..., { tier: "low" })` is the
|
|
92
|
-
named override. Unknown tiers throw and `TN_QUALITY_TIER` reports the chosen source. A scenario
|
|
93
|
-
with no assertions or missing observations fails; keep the durable smoke proof and open a capture. 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 beside the frame rate; `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.
|
|
93
|
+
A scenario with no assertions or missing observations fails; keep the durable smoke proof and open a capture. 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
94
|
|
|
95
|
-
Recipes
|
|
95
|
+
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`.
|
|
96
96
|
## Optional multiplayer transport
|
|
97
97
|
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`.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "action-rpg",
|
|
3
3
|
"title": "Action RPG",
|
|
4
|
-
"blurb": "A three-room dungeon
|
|
4
|
+
"blurb": "A three-room grid dungeon of mannequin fighters: melee, the Arcane Surge, loot, equipment, persistence, and a real character sheet.",
|
|
5
5
|
"genre": "action-rpg",
|
|
6
6
|
"kit": true
|
|
7
7
|
}
|
|
@@ -16,9 +16,9 @@
|
|
|
16
16
|
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
17
17
|
},
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"@threenative/core": "0.3.
|
|
20
|
-
"@threenative/physics": "0.3.
|
|
21
|
-
"@threenative/ui": "0.3.
|
|
19
|
+
"@threenative/core": "0.3.4",
|
|
20
|
+
"@threenative/physics": "0.3.4",
|
|
21
|
+
"@threenative/ui": "0.3.4",
|
|
22
22
|
"react": "19.2.0",
|
|
23
23
|
"react-dom": "19.2.0",
|
|
24
24
|
"three": "0.185.1"
|
|
@@ -26,13 +26,13 @@
|
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@gltf-transform/cli": "4.4.2",
|
|
28
28
|
"@tailwindcss/vite": "4.3.3",
|
|
29
|
-
"@threenative/assets": "0.3.
|
|
30
|
-
"@threenative/playtest": "0.3.
|
|
29
|
+
"@threenative/assets": "0.3.5",
|
|
30
|
+
"@threenative/playtest": "0.3.4",
|
|
31
31
|
"@types/react": "19.2.0",
|
|
32
32
|
"@types/react-dom": "19.2.0",
|
|
33
33
|
"@types/three": "0.185.3",
|
|
34
34
|
"@vitejs/plugin-react": "6.0.5",
|
|
35
|
-
"create-threenative": "0.2.
|
|
35
|
+
"create-threenative": "0.2.7",
|
|
36
36
|
"esbuild": "0.27.0",
|
|
37
37
|
"playwright": "1.62.1",
|
|
38
38
|
"tailwindcss": "4.3.3",
|
|
@@ -40,9 +40,15 @@
|
|
|
40
40
|
"vite": "8.2.0"
|
|
41
41
|
},
|
|
42
42
|
"optionalDependencies": {
|
|
43
|
-
"@threenative/runtime-native": "0.3.
|
|
43
|
+
"@threenative/runtime-native": "0.3.4"
|
|
44
|
+
},
|
|
45
|
+
"overrides": {
|
|
46
|
+
"sharp": ">=0.35.4"
|
|
44
47
|
},
|
|
45
48
|
"pnpm": {
|
|
49
|
+
"overrides": {
|
|
50
|
+
"sharp": ">=0.35.4"
|
|
51
|
+
},
|
|
46
52
|
"onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
|
|
47
53
|
"patchedDependencies": {
|
|
48
54
|
"three@0.185.1": "patches/three@0.185.1.patch"
|