create-threenative 0.2.5 → 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 +25 -3
- package/agent-docs/references/assertion-reference.md +40 -1
- package/agent-docs/references/build-profiles.md +126 -0
- package/agent-docs/references/capability-reference.md +1382 -65
- package/agent-docs/references/finding-assets.md +8 -1
- package/agent-docs/references/performance-basics.md +117 -0
- package/agent-docs/references/rigging-characters.md +51 -0
- 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-docs/references/webview-ui.md +3 -2
- package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
- package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
- package/agent-files/.agents/skills/threenative-assets/SKILL.md +12 -4
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
- package/agent-files/.agents/skills/threenative-context/SKILL.md +9 -1
- package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
- 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/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
- package/agent-files/.claude/settings.json +38 -0
- package/agent-files/.codex/hooks.json +40 -0
- package/capabilities.json +1891 -101
- package/dist/index.d.ts +39 -1
- package/dist/index.js +480 -56
- package/dist/threenative.js +1247 -177
- 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 +2228 -105
- package/template-assets/worldEnvironment.ts +52 -1
- package/templates/action-rpg/AGENTS.md +43 -43
- package/templates/action-rpg/CLAUDE.md +43 -43
- package/templates/action-rpg/kit.json +1 -1
- package/templates/action-rpg/package.json +14 -8
- 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 +12 -12
- package/templates/minimal/CLAUDE.md +12 -12
- package/templates/minimal/package.json +13 -7
- 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 +15 -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 +14 -10
- 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 +21 -22
- package/templates/puzzle/CLAUDE.md +21 -22
- 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 +14 -8
- 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 +20 -21
- package/templates/racing/CLAUDE.md +20 -21
- package/templates/racing/package.json +14 -8
- 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 +14 -8
- 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 +8 -12
- package/templates/runner/CLAUDE.md +8 -12
- package/templates/runner/README.md +3 -3
- package/templates/runner/package.json +14 -8
- 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 +14 -14
- package/templates/sailing/CLAUDE.md +14 -14
- package/templates/sailing/assets/ship.glb +0 -0
- package/templates/sailing/package.json +14 -8
- 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 +29 -44
- package/templates/shooter/CLAUDE.md +29 -44
- package/templates/shooter/index.html +1 -0
- package/templates/shooter/package.json +14 -8
- 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 +20 -20
- package/templates/starter/CLAUDE.md +20 -20
- package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
- package/templates/starter/package.json +15 -9
- package/templates/starter/playtests/play.playtest.json +2 -1
- package/templates/starter/playtests/{restart.playtest.json → production-readiness.playtest.json} +17 -12
- 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/src/ui/Hud.tsx +2 -2
- package/templates/starter/src/ui/Menu.tsx +5 -1
- 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 +16 -14
- package/templates/{defense → tower-defense}/CLAUDE.md +16 -14
- 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/prd-creator/SKILL.md +0 -40
- package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -45
- package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
- package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -57
- package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -42
- 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/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
|
@@ -6,9 +6,16 @@ asset tools when the asset is conventional; build anything specific to this game
|
|
|
6
6
|
|
|
7
7
|
Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
|
|
8
8
|
your host lists its tools alongside your own. Your host reads that file from the directory it was
|
|
9
|
-
launched in: start the session in this project, not in a parent of it. It advertises
|
|
9
|
+
launched in: start the session in this project, not in a parent of it. It advertises 44; these 8
|
|
10
10
|
are the loop you will use for nearly everything:
|
|
11
11
|
|
|
12
|
+
For a humanoid that needs a skeleton or more motion, use the complete
|
|
13
|
+
[`rigging-characters.md`](rigging-characters.md) recipe. Inspect with `asset_inspect_rig`,
|
|
14
|
+
preserve or fit a rig with `asset_auto_rig`, select and bake donor clips with
|
|
15
|
+
`asset_retarget_animations`, and confirm the result with `asset_preview_animation` on a nonblank
|
|
16
|
+
contact sheet. AETHER / 02 is the pinned sample; its 18-bone rig has no fingers or toes, and the
|
|
17
|
+
tools report those absent roles instead of inventing them.
|
|
18
|
+
|
|
12
19
|
For a bespoke animated creature, use the complete [`creating-creatures.md`](creating-creatures.md)
|
|
13
20
|
recipe. It keeps the editable spec and claims under `.threenative/creatures/`, compiles the GLB
|
|
14
21
|
into the configured `assets/` source, and requires independent preview review before game
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Performance basics — what the engine already does, and what you choose
|
|
2
|
+
|
|
3
|
+
Every frame this framework runs the same measured loop. Some performance work is done for you;
|
|
4
|
+
the rest is a content choice only the game can make. This page is the short list of both, so you
|
|
5
|
+
reach for the right abstraction before you profile anything.
|
|
6
|
+
|
|
7
|
+
## The split
|
|
8
|
+
|
|
9
|
+
- **The engine decides what it can measure where it is used**: world-transform preparation, scene
|
|
10
|
+
batching and projection, per-pass culling, resolution, load scheduling, asset cooking, first-use
|
|
11
|
+
warmup, and the frame meter. Do not hand-roll these — a hand-rolled version usually costs you the
|
|
12
|
+
engine's version.
|
|
13
|
+
- **You decide what cannot be read from the code**: how much detail is on screen, how many objects,
|
|
14
|
+
what never moves, how far shadows reach, how many particles. Those are content decisions, and the
|
|
15
|
+
frame meter reports what they cost.
|
|
16
|
+
|
|
17
|
+
If you can measure the value where it is used, let the engine decide; a constant you are told to
|
|
18
|
+
revisit later is the engine's job, not yours.
|
|
19
|
+
|
|
20
|
+
## Automatic — leave it alone
|
|
21
|
+
|
|
22
|
+
- **Scene batching and projection.** The engine merges equal geometry and material into fewer draws
|
|
23
|
+
and projects the authored scene automatically. A per-mesh `onBeforeRender` / `onAfterRender` hook
|
|
24
|
+
that packs buffers or mutates geometry makes the whole scene decline projection. Put once-per-draw
|
|
25
|
+
work in `ctx.beforeRender(fn)` instead: it runs after the frame's last fixed update and before
|
|
26
|
+
projection packs, on the batched and unbatched paths alike.
|
|
27
|
+
- **Transform preparation.** Exactly one world-matrix preparation runs per actual world draw. Never
|
|
28
|
+
call `updateMatrixWorld(true)` yourself, and do not set `scene.matrixWorldAutoUpdate = false`
|
|
29
|
+
unless you then update the scene yourself. Marking a measured-static subtree
|
|
30
|
+
`matrixWorldAutoUpdate = false` is allowed and the engine will skip it, but its parents must stay
|
|
31
|
+
still. For one node that never moves, `node.updateMatrix(); node.matrixAutoUpdate = false` is the
|
|
32
|
+
cheaper pair: it skips the per-object compose and leaves the walk intact.
|
|
33
|
+
- **Per-pass culling.** The main camera, each shadow and each reflection pass cull their own way,
|
|
34
|
+
and the engine owns that. Do not set `frustumCulled = false` on a batch, and do not give one
|
|
35
|
+
batch bounds that span the map.
|
|
36
|
+
- **The projected-size cut is yours to tune**, not the engine's: `renderer.minimumProjectedPixels`
|
|
37
|
+
(default `0.5`; a shipped title raised it to `2`) drops what the render camera cannot resolve
|
|
38
|
+
before it is submitted. Raise it before you write LOD machinery, and read `TN_PROJECTION` to see
|
|
39
|
+
how many objects it actually drops. Shadow casters are never dropped on the main view alone, so a
|
|
40
|
+
scene of small casters stays expensive — `castShadow = false` on props the cut would otherwise
|
|
41
|
+
drop is the game's call.
|
|
42
|
+
- **Resolution.** `render.resolutionScale: "auto"` holds GPU headroom and never lowers resolution
|
|
43
|
+
on a CPU overrun; `TN_FRAME_BUDGET` reports the scale actually used. A number is the named pin
|
|
44
|
+
override.
|
|
45
|
+
- **Quality.** Each template ships `src/render/quality.ts` (three tiers, platform default,
|
|
46
|
+
`TN_QUALITY_TIER`) and `adaptiveQuality.ts` (measured frame windows). Use the tiers; do not invent
|
|
47
|
+
a fourth switch.
|
|
48
|
+
- **Loading.** `loadAll(items, load)` loads with bounded concurrency and returns results in the
|
|
49
|
+
input's order. `addInSlices(objects, add)` attaches hundreds of objects across frames. A pool that
|
|
50
|
+
pushes results lands a different asset every load.
|
|
51
|
+
- **Assets.** The build cooks textures to KTX2/Basis, deduplicates model images and reports bytes;
|
|
52
|
+
`assets.budget` fails the build over a ceiling. Do not ship unpacked 4K textures and plan to
|
|
53
|
+
optimize later.
|
|
54
|
+
- **First use.** `warmUpScene(scene, camera)` compiles what a scene needs in slices, presenting a
|
|
55
|
+
frame between each. Warm up the real scene before interactive play; do not pre-touch every
|
|
56
|
+
possible variant.
|
|
57
|
+
|
|
58
|
+
## Where the frame actually goes, in that order
|
|
59
|
+
|
|
60
|
+
Ask these three questions before you profile anything, because they decide who owns the fix:
|
|
61
|
+
|
|
62
|
+
1. **Is the GPU busy?** `TN_FRAME_BUDGET` carries `gpuMs`. A frame with a 16 ms `render` phase and a
|
|
63
|
+
2 ms GPU is not a rendering problem — the GPU is idle and waiting for JavaScript.
|
|
64
|
+
`gpuMs` is sampled one frame in eight (`renderer.gpuTimestampFrameInterval`, default `8`): reading
|
|
65
|
+
every pass of every frame cost native Midway 161 ms/s of main-thread JavaScript.
|
|
66
|
+
2. **How many objects does the scene walk?** `TN_PROJECTION` reports `considered`, `culled`,
|
|
67
|
+
`exemptShadowCasters` and `exemptFrustumCulled` for the frame. Three.js visits every object once
|
|
68
|
+
per pass (main, each shadow, each reflection) and that visit is roughly 2 µs each on a desktop
|
|
69
|
+
core: 1,600 objects is ~3.5 ms of a 16 ms render before a single draw is issued. This is the
|
|
70
|
+
number to move, and the only lever is fewer objects.
|
|
71
|
+
3. **Is it the engine's own work?** It usually is not: measured on a 1,561-mesh game, the engine's
|
|
72
|
+
whole share — camera cull, frame-op recorder, frame meter — was under 1.5 ms of a 20 ms frame,
|
|
73
|
+
with the rest being three.js's walk over the game's scene plus the game's own `update`.
|
|
74
|
+
|
|
75
|
+
A GPU that is idle with a slow `render` phase is an object-count problem, not a graphics problem.
|
|
76
|
+
|
|
77
|
+
## Reach for these before you write your own
|
|
78
|
+
|
|
79
|
+
| You have | Use | What it gives you |
|
|
80
|
+
| --- | --- | --- |
|
|
81
|
+
| Many copies of one shape | `InstancedBatch` | One draw, no per-copy mesh |
|
|
82
|
+
| Many *different* shapes that never move relative to each other — a ship, a rig, a building, the static parts of an imported model | `mergeParts` | One mesh per material, so the walk visits one object instead of dozens; pass `preserve: ["uv", "normal"]` when the pieces carry authored normals or texture UVs |
|
|
83
|
+
| One over-detailed body seen at many distances | `ClusteredBatch` / `ClusteredMesh` | Each copy submits the detail its distance earns |
|
|
84
|
+
| A particle surface | `GPUParticles3D` | Pooled dispatch, game-owned appearance |
|
|
85
|
+
| Bullet streaks | `TracerPool3D` | Pooled travelling meshes |
|
|
86
|
+
| A sprite that faces the camera | `Billboard3D` | No hand-written per-frame orientation |
|
|
87
|
+
| One directional shadow over an open world | `VirtualShadowNode` | Camera-centred, texel-snapped clip levels; `trackCaster` for movers |
|
|
88
|
+
| Distance detail swaps | three's `LOD` | Standard, and the engine can still batch it |
|
|
89
|
+
| Raycasts over a large static scene | `GPUSceneBVH` / `ScenePicker` | Built once, queried many times |
|
|
90
|
+
|
|
91
|
+
## The shortcuts that cost a frame
|
|
92
|
+
|
|
93
|
+
- One mesh per bullet or particle. Pool them (`TracerPool3D`, `GPUParticles3D`) or instance them.
|
|
94
|
+
- A fresh `Vector3`, array or object per entity inside `update`. Hoist it out of the loop and reuse
|
|
95
|
+
it; allocation shows up as GC in the trace, not in the average.
|
|
96
|
+
- A per-mesh render hook that packs buffers. That is `ctx.beforeRender` once per draw.
|
|
97
|
+
- Many shadow-casting lights, or one 4K shadow map for a whole valley. One directional light plus
|
|
98
|
+
`VirtualShadowNode`.
|
|
99
|
+
- The same large equirect on `scene.background` and `scene.environment`. The environment light is
|
|
100
|
+
charged again and moves in power-of-two steps — see `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`.
|
|
101
|
+
- A unique material or texture per copy. Share materials and images; the batcher merges equal
|
|
102
|
+
material and geometry.
|
|
103
|
+
|
|
104
|
+
## Measure, then change one thing
|
|
105
|
+
|
|
106
|
+
`TN_FRAME_BUDGET` reports `fps`, `gpuMs` and the five phases (`update`, `render`, `overlay`,
|
|
107
|
+
`residual`, `hostGap`) plus per-pass draws and triangles; `TN_PROJECTION` reports the object census
|
|
108
|
+
(`considered`, `culled`, `exemptShadowCasters`) and the cut's threshold; `TN_RENDER_PROJECTION`
|
|
109
|
+
reports whether the scene batched and, when it did not, the reason. Launching with `DEV_MODE=true`
|
|
110
|
+
turns on the engine's dev surfaces (backtick opens the object and geometry inspector) and puts the
|
|
111
|
+
scene-shape verdict in a corner chip, so the engine's own finding is on screen while you play instead
|
|
112
|
+
of after you grep. It draws the verdict alone: the loop's rAF rate is throttled under a compositor or
|
|
113
|
+
a virtual display, so a frame rate read off that chip — or off a screenshot — is a number that lies
|
|
114
|
+
exactly when someone is measuring. `npx @threenative/playtest perf` turns a log into a windowed
|
|
115
|
+
report. When the percentile is
|
|
116
|
+
bad but the cause is not obvious, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md` names the function before you
|
|
117
|
+
change a line.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Rigging characters — the full MCP tool loop
|
|
2
|
+
|
|
3
|
+
Companion to the humanoid paragraph in `finding-assets.md`. Reach for these tools when a game
|
|
4
|
+
needs a rigged character or extra motion on an existing one. The model choice, clip selection,
|
|
5
|
+
material changes and intentional motion adjustments stay authored game data; the tools only
|
|
6
|
+
produce the GLB.
|
|
7
|
+
|
|
8
|
+
AETHER / 02 is the pinned default sample: an 18-bone humanoid with 11 clips, five materials, both
|
|
9
|
+
UV sets, tangents and two material extensions. `SkeletalMesh3D` loads it and its `hand.R` is the
|
|
10
|
+
weapon attachment bone. It is CC0, and was built from a 14-unit source robot, so its source size
|
|
11
|
+
is preserved unless a game explicitly authors a `SkeletalMesh3D.size` override.
|
|
12
|
+
|
|
13
|
+
## 1. Inspect before deciding
|
|
14
|
+
|
|
15
|
+
`asset_inspect_rig` takes a local GLB path, or `{ "sourceId": "aether-02" }` to acquire the pinned
|
|
16
|
+
sample into the development cache, plus optional local UAL ZIP/GLB libraries. It reports meshes,
|
|
17
|
+
joints, suggested bone-role mappings with ambiguity, attribute and extension support, measured
|
|
18
|
+
bounds, clips, and the actual attachment candidates. It never downloads the animation libraries;
|
|
19
|
+
supply local archives or select release donors by clip id.
|
|
20
|
+
|
|
21
|
+
## 2. Preserve or fit a rig
|
|
22
|
+
|
|
23
|
+
`asset_auto_rig` preserves an existing valid rig by default. For an unrigged upright biped it fits
|
|
24
|
+
an 18-joint skeleton from measured geometry, then binds smooth (up to four normalized influences)
|
|
25
|
+
or rigid (one bone per connected mechanical region) weights and publishes the skinned GLB under the
|
|
26
|
+
project root. When the anatomy is ambiguous — arms joined to the torso, legs not separated — it
|
|
27
|
+
returns a correction request with the measured landmarks instead of a bad rig; pass corrected
|
|
28
|
+
`overrides` and call it again. Replacing a real rig requires `replaceRig: true`.
|
|
29
|
+
|
|
30
|
+
## 3. Select and retarget motion
|
|
31
|
+
|
|
32
|
+
`asset_retarget_animations` fetches only the donor clips you select from the pinned release and
|
|
33
|
+
bakes them onto the target: `{ "id": "ual1/Walk_Loop", "variant": "in_place" }`. In-place is the
|
|
34
|
+
normal game-controlled locomotion output; root motion explicitly uses the matching `root_motion`
|
|
35
|
+
variant. New clips keep their namespace (`ual1/Walk_Loop`) so an existing `Walk` is never
|
|
36
|
+
overwritten. Existing target clips survive unless you pass `keepExistingClips: false` for a
|
|
37
|
+
game-minimal export. Target materials, UVs, tangents and extensions are preserved.
|
|
38
|
+
|
|
39
|
+
## 4. Confirm with a contact sheet
|
|
40
|
+
|
|
41
|
+
`asset_preview_animation` renders a prepared GLB from two to six angles with an optional clip time
|
|
42
|
+
or an explicit bone pose, and publishes a nonblank contact sheet under the project root. A missing
|
|
43
|
+
rendering backend returns an explicit `unavailable` result; a blank frame fails. Inspect the sheet
|
|
44
|
+
before delivery — a valid animation container alone is not approval.
|
|
45
|
+
|
|
46
|
+
## 5. Cook and play
|
|
47
|
+
|
|
48
|
+
Load the prepared GLB the ordinary way and play clips with `SkeletalMesh3D` and its update loop.
|
|
49
|
+
Attach a game-authored weapon with `attachToBone(character.root, "hand.R", weapon)`. Credit the
|
|
50
|
+
source and keep its license notice with the asset; the donor libraries are CC0, and the pinned
|
|
51
|
+
clips are fetched once into the development cache on first use, then reused offline.
|
|
@@ -12,7 +12,7 @@ Companion to the short `Building what you cannot download` section in this proje
|
|
|
12
12
|
- **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
|
|
13
13
|
landmark, scenery composition, or environment set piece whose silhouette must match. Use
|
|
14
14
|
the sculpt tools to turn that reference into editable `src/render/` source.
|
|
15
|
-
- **Bespoke, without a reference image** — read `agent-docs/dream-loop.md` and acquire one from
|
|
15
|
+
- **Bespoke, without a reference image** — read `node_modules/create-threenative/agent-docs/references/dream-loop.md` and acquire one from
|
|
16
16
|
the user or an explicitly selected host/provider tool. Do not invent a reference: comparison
|
|
17
17
|
without evidence is unguided iteration.
|
|
18
18
|
|
|
@@ -90,7 +90,7 @@ suppressed either way — acknowledging the trap does not give the display a vsy
|
|
|
90
90
|
|
|
91
91
|
The same command also refuses when WebGPU came from SwiftShader, Chromium's CPU rasteriser
|
|
92
92
|
(`TN_TRACE_SOFTWARE_ADAPTER`): a trace of software rendering names software rendering's functions.
|
|
93
|
-
`agent-docs/capture-the-frame.md` covers that adapter trap in full.
|
|
93
|
+
`node_modules/create-threenative/agent-docs/references/capture-the-frame.md` covers that adapter trap in full.
|
|
94
94
|
|
|
95
95
|
## After the trace
|
|
96
96
|
|
|
@@ -20,10 +20,14 @@ Three.js source in this project, yours to rewrite or delete.
|
|
|
20
20
|
- `postprocessing.ts` — the editable presets and `setupPost` delegation.
|
|
21
21
|
- `worldEnvironment.ts` — the editable Godot-named render chain: tone mapping/exposure and
|
|
22
22
|
optional TSL stages, with `createRenderChain` reporting applied or refused stages.
|
|
23
|
-
- `
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
23
|
+
- `materials.ts` — `floorMaterial`, `structureMaterial` and `propMaterial`, over a `DataTexture`
|
|
24
|
+
metre grid and a grain normal map. **Two greys and one saturated colour is the whole rule:**
|
|
25
|
+
light grid where the player walks, dark grid on sides and structure, and a single saturated
|
|
26
|
+
hue reserved for what they can touch. A lit floor alone in black reads as a test fixture no
|
|
27
|
+
matter how good the floor is, and the darkest band is the cheapest thing to fix in a first
|
|
28
|
+
screenshot.
|
|
29
|
+
- `arena.ts` — the ground, the walls and one platform builder. **Keep something in all three
|
|
30
|
+
depth bands:** the ground the player stands on, the dark mass behind it, and the sky above.
|
|
27
31
|
|
|
28
32
|
## Traps
|
|
29
33
|
|
|
@@ -10,10 +10,11 @@ ships, and never the game itself. The scene stays in the native runtime; only th
|
|
|
10
10
|
| web | the page itself, beside `GameCanvas` | shipped |
|
|
11
11
|
| Android | a transparent `WebView` over the SDL surface | shipped, proven on a Pixel 8 |
|
|
12
12
|
| desktop (Linux) | a transparent WebKitGTK window over the game window | shipped |
|
|
13
|
-
| desktop (Windows
|
|
13
|
+
| desktop (Windows) | a transparent WebView2 surface over the game | implemented; final distribution verification is platform-specific |
|
|
14
|
+
| desktop (macOS) | a transparent `WKWebView` over the game | implemented; final distribution verification is platform-specific |
|
|
14
15
|
| iOS | a transparent `WKWebView` over the Metal layer | written, **unproven on hardware** |
|
|
15
16
|
|
|
16
|
-
Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
|
|
17
|
+
`ui.renderer` defaults to `"web"`. Turn it off with `ui: { renderer: "native" }` in `threenative.config.ts`. That ships no web view
|
|
17
18
|
and no extra process, and draws `View`/`Text` quads inside the rendered frame instead.
|
|
18
19
|
|
|
19
20
|
## Two things cross the boundary, and nothing else
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: file-engine-bug
|
|
3
|
-
description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session. Use when doctor and a minimal repro separate an engine bug from a game or machine problem,
|
|
3
|
+
description: File a confirmed @threenative/* engine bug on ThreeNativeHQ/threenative using the user's own gh CLI session, and move a game-side patch for it upstream. Use when doctor and a minimal repro separate an engine bug from a game or machine problem, when you have pasted output proving it, or when a patch in patches/ fixes one.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Filing an engine bug
|
|
@@ -20,7 +20,18 @@ fix that lives in this game's source, and not a machine problem doctor names.
|
|
|
20
20
|
Implement the workaround first and continue the game (`AGENTS.md`: never stall on a framework
|
|
21
21
|
bug). Filing does not wait for the workaround to be clean.
|
|
22
22
|
|
|
23
|
-
## 2.
|
|
23
|
+
## 2. A patch is temporary — ship the fix through one PR
|
|
24
|
+
|
|
25
|
+
A fix inside `@threenative/*` may **start** as a game-side patch
|
|
26
|
+
(`patches/@threenative+<package>@<version>.patch`, wired through pnpm `patchedDependencies`, every
|
|
27
|
+
hunk commented with the game it came from) so you can iterate and measure it against the game. The
|
|
28
|
+
patch is temporary: **once the fixes are settled** — measured, reviewed, regression checks green —
|
|
29
|
+
move them into the engine **through one pull request** on the ThreeNative repository, batching every
|
|
30
|
+
settled hunk with the checks that prove it rather than opening one PR per fix. Delete the game
|
|
31
|
+
patch when a release carrying the merged fixes is pinned. A mechanism that stays in a game patch is
|
|
32
|
+
a bug in the process: the next game hits the same wall.
|
|
33
|
+
|
|
34
|
+
## 3. Search before filing
|
|
24
35
|
|
|
25
36
|
```sh
|
|
26
37
|
gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or three keywords>"
|
|
@@ -29,7 +40,7 @@ gh issue list --repo ThreeNativeHQ/threenative --state open --search "<two or th
|
|
|
29
40
|
An open issue already covering it: add your repro and output as a comment
|
|
30
41
|
(`gh issue comment <number> --body-file <file>`) instead of a new report.
|
|
31
42
|
|
|
32
|
-
##
|
|
43
|
+
## 4. File it
|
|
33
44
|
|
|
34
45
|
Write the body to a file first; quoting goes through `--body-file`, never inline:
|
|
35
46
|
|
|
@@ -49,7 +60,7 @@ The body carries, in this order:
|
|
|
49
60
|
from the project's `package.json`.
|
|
50
61
|
- **Workaround** — what the game shipped with to keep moving.
|
|
51
62
|
|
|
52
|
-
##
|
|
63
|
+
## 5. When not to file
|
|
53
64
|
|
|
54
65
|
- `gh auth status` fails or `gh` is missing: do not authenticate for the user and do not stall —
|
|
55
66
|
hand them the drafted title and body file and name the one command that files it.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ponytail
|
|
3
|
+
description: >
|
|
4
|
+
Force the laziest solution that actually works: smallest, shortest, most minimal.
|
|
5
|
+
Use on any coding task in this game — writing, adding, refactoring, fixing,
|
|
6
|
+
reviewing, or picking a dependency — and whenever a request smells over-built
|
|
7
|
+
("simplest", "minimal", "yagni", "do less", "shortest path", "too much code",
|
|
8
|
+
"bloat", "boilerplate"). Adds YAGNI and reuse to the engine's capability-first
|
|
9
|
+
rule: never hand-write what an installed @threenative system already does.
|
|
10
|
+
Source: github.com/DietrichGebert/ponytail (MIT). Do NOT use for non-coding
|
|
11
|
+
requests (general knowledge, prose, translation, summaries, recipes).
|
|
12
|
+
argument-hint: "[off]"
|
|
13
|
+
license: MIT
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Ponytail — lazy senior dev
|
|
17
|
+
|
|
18
|
+
You are a lazy senior developer. Lazy means efficient, not careless. The best code
|
|
19
|
+
is the code never written. Active every response; this project's hook re-injects the
|
|
20
|
+
ruleset every session and prompt, and `PONYTAIL=off` or "stop ponytail" turns it off.
|
|
21
|
+
|
|
22
|
+
## The ladder
|
|
23
|
+
|
|
24
|
+
Stop at the first rung that holds. The ladder runs *after* you understand the
|
|
25
|
+
problem, not instead of it: read the code the change touches and trace the real
|
|
26
|
+
flow end to end, then climb. Two rungs work → take the higher one and move on.
|
|
27
|
+
|
|
28
|
+
1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
|
|
29
|
+
2. **Already installed in the engine?** Search `engine_search_capabilities` for the full request and each concrete mechanic, inspect hits with `engine_capability_detail`, and reuse the returned system — a node, convention, helper or subpath that already ships is the answer, not a thing to re-implement. This rung *is* the critical capability gate; never skip it because the task looks small, and never jump to hand-written code while it is unsearched.
|
|
30
|
+
3. **Already in this game?** Reuse a helper, type, or pattern that already lives in `src/`. Re-implementing what sits a few files over is the most common slop.
|
|
31
|
+
4. **Stdlib or engine convention does it?** `loadAll`, `addInSlices`, `GroundSnap`, an input vector, a physics query — reach for those before writing your own loop.
|
|
32
|
+
5. **Already-installed dependency solves it?** Use it; never add a new one for what a few lines can do.
|
|
33
|
+
6. **Can it be one line?** One line.
|
|
34
|
+
7. **Only then:** the minimum code that works, in this game's `src/`.
|
|
35
|
+
|
|
36
|
+
## Rules
|
|
37
|
+
|
|
38
|
+
- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
|
|
39
|
+
- No boilerplate, no scaffolding "for later"; later can scaffold for itself. Deletion over addition. Boring over clever.
|
|
40
|
+
- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place is a second bug.
|
|
41
|
+
- Complex request? Ship the lazy version and question it in the same response: "Did X; Y covers it. Need full X? Say so." Never stall on a question you can default.
|
|
42
|
+
- Two same-size options? Take the one correct on edge cases — lazy means less code, not the flimsier algorithm.
|
|
43
|
+
- Bug fix = root cause, not symptom: grep every caller of the function you touch and fix the shared one. One guard where all callers route through is smaller than a guard per caller, and patching only the path the ticket names leaves a sibling caller broken.
|
|
44
|
+
- Mark a deliberate corner cut with a `ponytail:` comment naming the ceiling and the upgrade path.
|
|
45
|
+
|
|
46
|
+
## Output
|
|
47
|
+
|
|
48
|
+
Code first. Then at most three short lines: what was skipped, when to add it.
|
|
49
|
+
Pattern: `[code] → skipped: [X], add when [Y].` No essays, no feature tours, no
|
|
50
|
+
design notes. Explanation the user explicitly asked for (a plan, a report, per-phase
|
|
51
|
+
notes) is not debt — give it in full.
|
|
52
|
+
|
|
53
|
+
## When NOT to be lazy
|
|
54
|
+
|
|
55
|
+
Never simplify away: understanding the problem (a small diff you do not understand is
|
|
56
|
+
just laziness dressed up as efficiency), input validation at trust boundaries, error
|
|
57
|
+
handling that prevents data loss, security, accessibility, anything explicitly
|
|
58
|
+
requested, and the calibration real hardware needs. Lazy code without its check is
|
|
59
|
+
unfinished: non-trivial logic leaves ONE runnable check behind — the smallest thing
|
|
60
|
+
that fails if the logic breaks. In this game the proof is a playtest scenario, never a
|
|
61
|
+
new test framework; trivial one-liners need no test.
|
|
62
|
+
|
|
63
|
+
## Boundaries
|
|
64
|
+
|
|
65
|
+
Ponytail governs what you build, not how you talk. "stop ponytail" / "normal mode" /
|
|
66
|
+
`PONYTAIL=off`: revert. Level persists until changed or session end.
|
|
67
|
+
|
|
68
|
+
The shortest path to done is the right path.
|
|
@@ -26,20 +26,28 @@ If FabCLI needs a session, proactively run `fabcli auth login`. Use Claude brows
|
|
|
26
26
|
`chrome:control-chrome`, to complete the login with the user's active browser session, then retry
|
|
27
27
|
the MCP call. Never read, copy, print, or persist browser cookies or tokens. The MCP checks
|
|
28
28
|
entitlement and accepts only Fab Standard or CC-BY; it never claims or buys. Full arguments:
|
|
29
|
-
`agent-docs/finding-assets.md`.
|
|
29
|
+
`node_modules/create-threenative/agent-docs/references/finding-assets.md`.
|
|
30
30
|
|
|
31
|
-
For a bespoke animated creature, follow `agent-docs/creating-creatures.md`. Call the five
|
|
31
|
+
For a bespoke animated creature, follow `node_modules/create-threenative/agent-docs/references/creating-creatures.md`. Call the five
|
|
32
32
|
`creature_*` tools through the project asset server, keep the editable spec and claims in
|
|
33
33
|
`.threenative/creatures/`, compile into the configured `assets/` source, and get independent
|
|
34
34
|
visual review before delivery. `creature_status` distinguishes compile-only availability from
|
|
35
35
|
optional preview/check dependencies; an unavailable renderer is not approval.
|
|
36
36
|
|
|
37
|
+
For a humanoid that needs a skeleton or more motion, follow `node_modules/create-threenative/agent-docs/references/rigging-characters.md`.
|
|
38
|
+
Inspect first with `asset_inspect_rig` (a local GLB or the pinned `aether-02` sample), auto-rig an
|
|
39
|
+
unrigged biped with `asset_auto_rig` (or pass explicit landmarks when it returns a correction
|
|
40
|
+
request), select donors with `asset_retarget_animations` (in-place by default; `root_motion` only
|
|
41
|
+
from the matching `_RM` donor), and confirm the result with `asset_preview_animation` on a
|
|
42
|
+
nonblank contact sheet before cooking. The 18-bone AETHER sample has no fingers or toes; the
|
|
43
|
+
tools report those absent roles instead of inventing them.
|
|
44
|
+
|
|
37
45
|
Choose the sculpt branch before coding: conventional → asset tools; trivial → portable geometry;
|
|
38
46
|
bespoke with a reference → `sculpt_plan`, `sculpt_spec_gate` until every region passes, one
|
|
39
47
|
factory per pass in `src/render/`, then `sculpt_compare` and `sculpt_pass_gate` against a real
|
|
40
|
-
capture; bespoke without a reference → read `agent-docs/dream-loop.md` and acquire a
|
|
48
|
+
capture; bespoke without a reference → read `node_modules/create-threenative/agent-docs/references/dream-loop.md` and acquire a
|
|
41
49
|
user-supplied or explicitly authorized target before sculpting. Use `node scripts/reference.mjs`
|
|
42
50
|
only when the user selected its provider/model; never invent a reference or hide a missing key.
|
|
43
51
|
`sculpt_grimoire` supplies techniques. `threenative-sculpt-mcp` guides source and never launches
|
|
44
52
|
a browser. A missing/blank capture fails; credit the reference before the turn ends. See
|
|
45
|
-
`agent-docs/sculpt-from-a-reference.md`.
|
|
53
|
+
`node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`.
|
|
@@ -21,7 +21,7 @@ movement, navigation, attachment, particle, terrain, or measurement system.
|
|
|
21
21
|
|
|
22
22
|
The manifest is the complete public surface; grep misses subpath exports such as
|
|
23
23
|
`@threenative/physics/navigation`. If MCP is unavailable after `npx threenative doctor`, use
|
|
24
|
-
`agent-docs/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
|
|
24
|
+
`node_modules/create-threenative/agent-docs/references/capability-reference.md` and repeat the full-request plus per-mechanic pass manually.
|
|
25
25
|
Returned constraints are binding: import navigation from its returned subpath, use `attachToBone`
|
|
26
26
|
for held weapons (add a portable `Bone` named `RightHand` when needed), and never invent platform
|
|
27
27
|
support. One game rewrote 446 installed lines and ran at 9 FPS; discovery prevents that.
|
|
@@ -6,7 +6,7 @@ description: Use the portable ThreeNative ctx lifecycle, scheduling, randomness,
|
|
|
6
6
|
# ThreeNative context surface
|
|
7
7
|
|
|
8
8
|
These are properties on `ctx`, never imports; use them before writing equivalent game plumbing.
|
|
9
|
-
The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
|
|
9
|
+
The recipes are in `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md` and imports still require
|
|
10
10
|
`engine_search_capabilities`.
|
|
11
11
|
|
|
12
12
|
| Use | Instead of | Contract |
|
|
@@ -14,6 +14,7 @@ The recipes are in `agent-docs/ctx-cookbook.md` and imports still require
|
|
|
14
14
|
| `ctx.goto("<scene-name>")` | hand reset | async scene rebuild |
|
|
15
15
|
| `ctx.tween(...)` | `Math.sin`/`lerp` accumulator | timed interpolation with optional `ease` |
|
|
16
16
|
| `ctx.after(...)` / `ctx.every(...)` | timer branches in `update` | disposable schedules |
|
|
17
|
+
| `ctx.beforeRender(fn)` | per-frame packing in `update` or an object `onBeforeRender` hook | one dispatch per actual world draw, after the last fixed step and before the projection; cleared like `ctx.afterPhysics` |
|
|
17
18
|
| `ctx.random.range(-1, 1)` | `Math.random()` | reproducible when `seed` is configured |
|
|
18
19
|
| `ctx.pointer.on(...)` / `ctx.pointer.drag(...)` | hover/press/drag bookkeeping | web/native pointer-id stream |
|
|
19
20
|
| `ctx.raycast()` / `ctx.raycastAll()` | `new Raycaster()` | backend-neutral intersections |
|
|
@@ -29,6 +30,13 @@ restart, `game.goto("<scene-name>")` from React resets declared initial state fi
|
|
|
29
30
|
uses `ctx.state.set({ /* copy this game's initial-state shape */ })` before the goto. `ctx.random` is
|
|
30
31
|
deterministic only when `defineGame({ seed })` is configured.
|
|
31
32
|
|
|
33
|
+
`ctx.beforeRender(fn)` runs once per actual world draw, after the frame's last fixed update and
|
|
34
|
+
before the projection reconciles, so `fn` reads the frame's final state; a held, loader-only frame
|
|
35
|
+
draws no world and dispatches nothing. It is cleared on scene change and stop, like
|
|
36
|
+
`ctx.afterPhysics`. Reach for it when the draw itself consumes per-frame CPU work — packing an
|
|
37
|
+
instanced batch, rebuilding a buffer — instead of an object `onBeforeRender` hook, which makes the
|
|
38
|
+
render projection decline the whole frame.
|
|
39
|
+
|
|
32
40
|
`pnpm budgets` rejects superseded raw constructs such as `new Audio(`, `Math.random(`,
|
|
33
41
|
`new Raycaster(`, `.visible = false`, and `new Box3().setFromObject(`; use the named capability or
|
|
34
42
|
annotate a genuinely necessary line with a non-empty `// engine-override: reason`.
|
|
@@ -5,14 +5,28 @@ description: Measure ThreeNative frame budgets and report platform evidence with
|
|
|
5
5
|
|
|
6
6
|
# ThreeNative performance evidence
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Pool objects; load static GLBs through `ctx.assets.model()`; never claim Android/iOS from a
|
|
9
|
+
desktop proof. `TN_FRAME_BUDGET` reports `fps`, `hostGap`, `update`, `render`, `overlay`,
|
|
10
|
+
`residual` and per-pass draws and triangles. `defineGame({ frameBudget: false })` silences
|
|
11
|
+
output, never measurement.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
## When the scene is the problem
|
|
14
|
+
|
|
15
|
+
`TN_SCENE_WARNING` fires when the GPU used under a third of a frame whose render phase overran
|
|
16
|
+
the display period: move draws and objects, not settings. `npx threenative doctor` and
|
|
17
|
+
`DEV_MODE=true` repeat it; `TN_FRAME_SPANS=1` splits that phase.
|
|
18
|
+
The largest static win is free — three skips per-object binding updates when nothing changed, so
|
|
19
|
+
not writing a transform saved 7.35 ms on 1,561 objects where `markStatic(root)` saved 0.009 ms.
|
|
20
|
+
|
|
21
|
+
## Use the shipped defaults
|
|
22
|
+
|
|
23
|
+
The engine prepares transforms, batches, culls, scales resolution and cooks assets;
|
|
24
|
+
read `node_modules/create-threenative/agent-docs/references/performance-basics.md` before hand-rolling any.
|
|
25
|
+
Unexecuted platforms stay unverified; never invent numbers.
|
|
26
|
+
Withdraw thermally-confounded Tiers 1–3 comparisons; always report Tier 4. Bounded proof:
|
|
27
|
+
`{"performance":{"maxFrameMsP95":33,"minFps":30,"maxPhaseMsP95":{"render":12},"maxPassDrawCalls":{"shadow":400}}}`,
|
|
28
|
+
defined in `node_modules/create-threenative/agent-docs/references/assertion-reference.md#performance`; pass bounds fail closed without a
|
|
29
|
+
per-pass split.
|
|
16
30
|
|
|
17
31
|
|Tier|Measure|Floor|Target|
|
|
18
32
|
|---|---|---:|---:|
|
|
@@ -37,6 +51,8 @@ fields are defined in `agent-docs/assertion-reference.md#performance`.
|
|
|
37
51
|
|4|Thermal-status|≤2|≤1|
|
|
38
52
|
|4|Whole-device-current|—|report;not-gated|
|
|
39
53
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
54
|
+
Android: budget a ~500 MiB driver floor before textures; a dual-use equirectangular
|
|
55
|
+
environment adds ~48 MiB: `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`.
|
|
56
|
+
|
|
57
|
+
Name the hot function: `--cpu-prof <file>` (native, or a browser/desktop playtest) writes a
|
|
58
|
+
DevTools `.cpuprofile`.
|
|
@@ -40,5 +40,5 @@ Playtests fail closed: a missing entity, absent observation, or empty assertion
|
|
|
40
40
|
`allowTrivial` waiver needs a 20-character reason; `true` alone is invalid, and all-waived
|
|
41
41
|
triviality fails `TN_PLAYTEST_SCENARIO_ASSERTS_NOTHING`. Use `holdTicks`/`waitTicks` for fixed-step
|
|
42
42
|
time (`holdFrames`/`waitFrames` are compatibility aliases); `warmupFrames` means RAF warmup.
|
|
43
|
-
Read `agent-docs/assertion-reference.md` for assertion fields and `agent-docs/debug-surface.md`
|
|
43
|
+
Read `node_modules/create-threenative/agent-docs/references/assertion-reference.md` for assertion fields and `node_modules/create-threenative/agent-docs/references/debug-surface.md`
|
|
44
44
|
for bridge globals. The JSON-safe bridge resource is `state`; `GameState` is a deprecated alias.
|
|
@@ -17,4 +17,4 @@ intents; `src/game.ts` decides their meaning. `useUiState<GameState>()` is undef
|
|
|
17
17
|
snapshot, and `useUiIntent()` sends commands. Mark every touch target `data-tn-interactive`; the
|
|
18
18
|
host routes marked pointer-down events to UI and unmarked touches to the game. Share state and
|
|
19
19
|
components, but keep appearance in `src/ui/`. The full state, hit-region, and renderer contract is
|
|
20
|
-
`agent-docs/webview-ui.md`.
|
|
20
|
+
`node_modules/create-threenative/agent-docs/references/webview-ui.md`.
|
|
@@ -17,10 +17,10 @@ Use browser automation on the user's real Chrome when available; otherwise run
|
|
|
17
17
|
status. A black headless capture is a capture failure until proven otherwise.
|
|
18
18
|
|
|
19
19
|
For reference matching, solve lighting first: search `engine_search_capabilities` before adding
|
|
20
|
-
effects, read `TN_RENDER_CHAIN`, and use `agent-docs/visual-baseline.md` and
|
|
21
|
-
`agent-docs/capture-the-frame.md` for the per-file baseline and capture recipe.
|
|
20
|
+
effects, read `TN_RENDER_CHAIN`, and use `node_modules/create-threenative/agent-docs/references/visual-baseline.md` and
|
|
21
|
+
`node_modules/create-threenative/agent-docs/references/capture-the-frame.md` for the per-file baseline and capture recipe.
|
|
22
22
|
|
|
23
|
-
For a supplied or explicitly generated target, read `agent-docs/dream-loop.md`. It is the shared
|
|
23
|
+
For a supplied or explicitly generated target, read `node_modules/create-threenative/agent-docs/references/dream-loop.md`. It is the shared
|
|
24
24
|
workflow for locking the target, preserving its hash, obtaining a fresh gameplay capture, and
|
|
25
25
|
asking the read-only verifier for an independent `PASS`, `REQUEST_CHANGES`, or `NOT_OBSERVED`.
|
|
26
26
|
Run `node scripts/visual-loop.mjs --record <run>/run.json` before and after each round; read its
|
|
@@ -38,4 +38,4 @@ visible while tuning bounds, density, and `bakeBudgetMs`.
|
|
|
38
38
|
never hand-author a device constant. A `(0, 1]` value pins it; invalid values fail at config load.
|
|
39
39
|
Both modes report `TN_FRAME_BUDGET.surface` (`resolutionScale`, `scaleSource`, sample count, and
|
|
40
40
|
buffer size), and `display: config.display` must reach `defineGame`. See the pixel-budget details
|
|
41
|
-
in `agent-docs/visual-baseline.md` and the engine's measurement skill.
|
|
41
|
+
in `node_modules/create-threenative/agent-docs/references/visual-baseline.md` and the engine's measurement skill.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Project-scoped ponytail activation. Runs only where this file is installed: the engine repo
|
|
3
|
+
// and every project `create-threenative` generates. It injects the same ruleset on session,
|
|
4
|
+
// prompt and subagent start so the AGENTS.md rule cannot drift out of the model's context.
|
|
5
|
+
//
|
|
6
|
+
// It is deliberately small: no mode file, no statusline, no state written outside the project.
|
|
7
|
+
// `PONYTAIL=off` (or removing this hook) turns it off.
|
|
8
|
+
|
|
9
|
+
if (process.env.PONYTAIL === "off") process.exit(0);
|
|
10
|
+
|
|
11
|
+
const RULESET = [
|
|
12
|
+
"PONYTAIL MODE ACTIVE — laziest solution that actually works.",
|
|
13
|
+
"",
|
|
14
|
+
"Before writing code, stop at the first rung that holds (read the code the change touches first):",
|
|
15
|
+
"1. Does this need to exist? No -> skip it (YAGNI).",
|
|
16
|
+
"2. Already installed in the engine? Search `engine_search_capabilities` and inspect with `engine_capability_detail` — reuse the returned system. This rung IS the critical capability gate; a shipped node, convention, helper or subpath is the answer, never hand-write what it already does.",
|
|
17
|
+
"3. Already in this game? Reuse what is in `src/`.",
|
|
18
|
+
"4. Stdlib or engine convention (loadAll, addInSlices, GroundSnap, an input vector, a physics query)? Use it.",
|
|
19
|
+
"5. Already-installed dependency? Use it; add none for a few lines.",
|
|
20
|
+
"6. One line? One line.",
|
|
21
|
+
"7. Only then: the minimum code that works.",
|
|
22
|
+
"",
|
|
23
|
+
"No unrequested abstractions, no boilerplate, no scaffolding for later; deletion over addition; fewest files; shortest diff once you understand the problem. Bug fix = grep every caller and fix the shared function once. Code first, then at most three short lines (`[code] -> skipped: [X], add when [Y].`).",
|
|
24
|
+
"Never simplify away: understanding the problem, trust-boundary validation, error handling that prevents data loss, security, accessibility, anything explicitly requested, hardware calibration. Non-trivial logic leaves ONE runnable check behind — here that is a playtest scenario.",
|
|
25
|
+
'Off: "stop ponytail" / `PONYTAIL=off`. Full rules: `.claude/skills/ponytail/SKILL.md` or `.agents/skills/ponytail/SKILL.md`.',
|
|
26
|
+
].join("\n");
|
|
27
|
+
|
|
28
|
+
let stdin = "";
|
|
29
|
+
process.stdin.setEncoding("utf8");
|
|
30
|
+
process.stdin.on("data", (chunk) => {
|
|
31
|
+
stdin += chunk;
|
|
32
|
+
});
|
|
33
|
+
process.stdin.on("end", emit);
|
|
34
|
+
process.stdin.on("error", () => process.exit(0));
|
|
35
|
+
// Never hang a session, and never fail one: an unreadable skill or closed stdin exits quietly.
|
|
36
|
+
setTimeout(() => process.exit(0), 3000).unref();
|
|
37
|
+
|
|
38
|
+
function emit() {
|
|
39
|
+
let event = "SessionStart";
|
|
40
|
+
try {
|
|
41
|
+
event = JSON.parse(stdin || "{}").hook_event_name || event;
|
|
42
|
+
} catch {
|
|
43
|
+
// Malformed stdin still gets the ruleset; the event name only shapes the envelope.
|
|
44
|
+
}
|
|
45
|
+
process.stdout.write(
|
|
46
|
+
JSON.stringify({
|
|
47
|
+
hookSpecificOutput: { hookEventName: event, additionalContext: RULESET },
|
|
48
|
+
}),
|
|
49
|
+
);
|
|
50
|
+
process.exit(0);
|
|
51
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hooks": {
|
|
3
|
+
"SessionStart": [
|
|
4
|
+
{
|
|
5
|
+
"hooks": [
|
|
6
|
+
{
|
|
7
|
+
"type": "command",
|
|
8
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
|
|
9
|
+
"timeout": 5,
|
|
10
|
+
"statusMessage": "Loading ponytail..."
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
}
|
|
14
|
+
],
|
|
15
|
+
"UserPromptSubmit": [
|
|
16
|
+
{
|
|
17
|
+
"hooks": [
|
|
18
|
+
{
|
|
19
|
+
"type": "command",
|
|
20
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
|
|
21
|
+
"timeout": 5
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
}
|
|
25
|
+
],
|
|
26
|
+
"SubagentStart": [
|
|
27
|
+
{
|
|
28
|
+
"hooks": [
|
|
29
|
+
{
|
|
30
|
+
"type": "command",
|
|
31
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ponytail-context.mjs\"",
|
|
32
|
+
"timeout": 5
|
|
33
|
+
}
|
|
34
|
+
]
|
|
35
|
+
}
|
|
36
|
+
]
|
|
37
|
+
}
|
|
38
|
+
}
|