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
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Scaffold a ThreeNative game:
|
|
|
6
6
|
pnpm create threenative my-game
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
The default template is `starter`. Choose `minimal`, `platformer`, `action-rpg`, `defense`,
|
|
9
|
+
The default template is `starter`. Choose `minimal`, `platformer`, `action-rpg`, `tower-defense`,
|
|
10
10
|
`racing`, `sailing`, or `shooter` for a different starting point:
|
|
11
11
|
|
|
12
12
|
```sh
|
|
@@ -14,7 +14,7 @@ pnpm create threenative my-game --template minimal
|
|
|
14
14
|
pnpm create threenative my-game --template starter
|
|
15
15
|
pnpm create threenative my-game --template platformer
|
|
16
16
|
pnpm create threenative my-game --template action-rpg
|
|
17
|
-
pnpm create threenative my-game --template defense
|
|
17
|
+
pnpm create threenative my-game --template tower-defense
|
|
18
18
|
pnpm create threenative my-game --template racing
|
|
19
19
|
pnpm create threenative my-game --template sailing
|
|
20
20
|
pnpm create threenative my-game --template shooter
|
|
@@ -29,6 +29,28 @@ cd my-game
|
|
|
29
29
|
npm install
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
+
## Branding your game
|
|
33
|
+
|
|
34
|
+
The identity a player sees is yours, and it lives only in generated game files — never in a
|
|
35
|
+
package. Three surfaces carry it:
|
|
36
|
+
|
|
37
|
+
- `threenative.config.ts` — `app.name`, `app.icon` (and `app.icons` per platform), the desktop
|
|
38
|
+
`window.title`, and `bootSplash` for the launch background. `app.id` is the reverse-DNS identity
|
|
39
|
+
the installer and file manager show.
|
|
40
|
+
- `public/` — the images those fields point at. Replacing the scaffold's `public/icon.png` is what
|
|
41
|
+
stops a packaged app shipping the engine's default icon.
|
|
42
|
+
- `src/render/` — `loading.ts` owns the in-game loading appearance; every file there is generated
|
|
43
|
+
game source you can rewrite.
|
|
44
|
+
|
|
45
|
+
`threenative doctor --target desktop` reports which of those a desktop build actually resolves.
|
|
46
|
+
|
|
47
|
+
Once a desktop release container exists, inspect the brand it actually carries rather than the
|
|
48
|
+
config you meant to ship:
|
|
49
|
+
`node node_modules/@threenative/runtime-native/scripts/verify-starter-desktop.mjs --container <unpacked-directory> --config .threenative/build/config.json`.
|
|
50
|
+
It compares the launcher/file-manager name, the embedded icon bytes and the declared loading
|
|
51
|
+
sequence against that config, and refuses a container that still carries the engine's default icon
|
|
52
|
+
— which the scaffold's own `public/icon.png` is until you replace it.
|
|
53
|
+
|
|
32
54
|
The published package declares those Node and pnpm minimums. Its asset pipeline reaches `sharp`
|
|
33
55
|
through `@gltf-transform/functions` → `ndarray-pixels` → `sharp`; `@threenative/core` also brings
|
|
34
56
|
the asset MCP's `sharp` copy. On a machine whose system has an incompatible global libvips, let
|
|
@@ -48,7 +70,7 @@ hidden by the install recipe.
|
|
|
48
70
|
Inside a generated project, `npx threenative doctor --text` reports what would break a build:
|
|
49
71
|
missing or version-mismatched `@threenative` packages, a portable entry with no default game
|
|
50
72
|
export, no web entry, no scenario, no capability search for your agent. Naming the build you
|
|
51
|
-
intend — `--target web|desktop|android|ios
|
|
73
|
+
intend — `--target web|desktop|android|ios` (iOS is not a supported target yet), optionally with `--mode debug|release` — makes that
|
|
52
74
|
build's prerequisites decide the verdict instead of warning beside "available".
|
|
53
75
|
|
|
54
76
|
Tool discovery reports four separate facts, because three of them are routinely mistaken for the
|
|
@@ -452,7 +452,7 @@ Proves console, network, runtime, and readiness diagnostics stayed clean. **Use
|
|
|
452
452
|
|
|
453
453
|
### `performance`
|
|
454
454
|
|
|
455
|
-
Proves a live render sample exists and optionally bounds frame time, an fps floor, per-phase frame budget, draw calls
|
|
455
|
+
Proves a live render sample exists and optionally bounds frame time, an fps floor, per-phase frame budget, whole-frame or per-pass draw calls and triangles. **Use when** that is the thing the scenario must prove.
|
|
456
456
|
|
|
457
457
|
- **Supported on:** web, desktop, bevy · **Requires:** runtime.performance
|
|
458
458
|
|
|
@@ -462,12 +462,17 @@ Proves a live render sample exists and optionally bounds frame time, an fps floo
|
|
|
462
462
|
| `minFps` | number | no |
|
|
463
463
|
| `maxPhaseMsP95` | { [phase]: number } | no |
|
|
464
464
|
| `maxDrawCalls` | number | no |
|
|
465
|
+
| `maxPassDrawCalls` | { [pass: 'main' | 'shadow' | 'reflection' | 'nested']: number } | no |
|
|
466
|
+
| `maxPassTriangles` | { [pass: 'main' | 'shadow' | 'reflection' | 'nested']: number } | no |
|
|
465
467
|
| `maxTriangles` | number | no |
|
|
466
468
|
|
|
467
469
|
|
|
468
470
|
```json
|
|
469
471
|
{
|
|
470
472
|
"performance": {
|
|
473
|
+
"maxPassDrawCalls": {
|
|
474
|
+
"shadow": 400
|
|
475
|
+
},
|
|
471
476
|
"maxPhaseMsP95": {
|
|
472
477
|
"render": 12
|
|
473
478
|
},
|
|
@@ -662,6 +667,40 @@ Proves animation evidence appeared in the effect log or runtime observation. **U
|
|
|
662
667
|
}
|
|
663
668
|
```
|
|
664
669
|
|
|
670
|
+
### `audio`
|
|
671
|
+
|
|
672
|
+
Proves which labelled audio cues the game actually played, and how often. Every other audio check
|
|
673
|
+
is about the *file* — it exists, it decodes, it is inside its budget — and all of them stay green
|
|
674
|
+
while a one-shot line sounds a second time mid-match. **Use when** that is the thing the scenario
|
|
675
|
+
must prove.
|
|
676
|
+
|
|
677
|
+
Label a cue by passing a cue name to the audio bus when the game plays it; unlabelled sounds are never counted.
|
|
678
|
+
When it fails, `observations.json/runtimeObservations/gameplay/audio/recentCues` says when each
|
|
679
|
+
play happened.
|
|
680
|
+
|
|
681
|
+
- **Supported on:** web, desktop · **Requires:** runtime.audio
|
|
682
|
+
|
|
683
|
+
| Field | Type | Required |
|
|
684
|
+
| --- | --- | --- |
|
|
685
|
+
| `cue` | string | yes |
|
|
686
|
+
| `minPlays` | non-negative integer (defaults to 1) | no |
|
|
687
|
+
| `maxPlays` | non-negative integer; 0 proves silence | no |
|
|
688
|
+
| `minGapMs` | non-negative integer; fewest ms since the line before it | no |
|
|
689
|
+
|
|
690
|
+
|
|
691
|
+
```json
|
|
692
|
+
{
|
|
693
|
+
"audio": [
|
|
694
|
+
{
|
|
695
|
+
"cue": "speech:p01",
|
|
696
|
+
"minPlays": 1,
|
|
697
|
+
"maxPlays": 1,
|
|
698
|
+
"minGapMs": 500
|
|
699
|
+
}
|
|
700
|
+
]
|
|
701
|
+
}
|
|
702
|
+
```
|
|
703
|
+
|
|
665
704
|
### `scene`
|
|
666
705
|
|
|
667
706
|
Bounds the room the game is played in — the lights, materials, fog and camera framing the renderer was handed. Fails closed on a bridge that does not report the scene. **Use when** that is the thing the scenario must prove.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Cook profiles — one asset tree, a different representation per artifact
|
|
2
|
+
|
|
3
|
+
Companion to the commented `buildProfiles` example in this project's `threenative.config.ts`. A
|
|
4
|
+
profile is **not** a second asset pipeline: it is one compiler, run with different
|
|
5
|
+
resource-processing options, so the phone build can ship smaller bytes out of the same sources you
|
|
6
|
+
already committed. With no `buildProfiles` block every build behaves exactly as it always has —
|
|
7
|
+
this is opt-in and the ordinary `assets` block still means what it means.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
buildProfiles: {
|
|
11
|
+
defaults: { android: "compact" }, // a target's default profile
|
|
12
|
+
profiles: {
|
|
13
|
+
compact: {
|
|
14
|
+
assets: { textures: { maxSize: 1024 }, models: { textures: { maxSize: 1024 } } },
|
|
15
|
+
artifactBudget: { packagedAssetBytes: { limit: 18_000_000, severity: "error" } },
|
|
16
|
+
performanceBudget: { maxDrawCalls: 300, maxFrameMsP95: 22 },
|
|
17
|
+
},
|
|
18
|
+
},
|
|
19
|
+
},
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Which profile a build cooks
|
|
23
|
+
|
|
24
|
+
1. `threenative build --target android --profile compact` — **the flag wins.**
|
|
25
|
+
2. `buildProfiles.defaults.android` — the target's own default.
|
|
26
|
+
3. Neither — the `assets` block is used exactly as declared.
|
|
27
|
+
|
|
28
|
+
Every build that selects a profile announces it before it cooks, so a log never leaves you guessing
|
|
29
|
+
which representation produced the bytes:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
threenative build: profile compact (flag) for web
|
|
33
|
+
threenative build: profile compact (default) for android
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
An unknown name fails the build by name (`TN_CONFIG_PROFILE_UNKNOWN`, listing the profiles this
|
|
37
|
+
project declares) **before any asset is encoded**, rather than shipping the wrong representation.
|
|
38
|
+
Every declared profile is validated, not only the selected one, so a broken budget cannot lie in
|
|
39
|
+
wait for the day someone names that profile.
|
|
40
|
+
|
|
41
|
+
## What an overlay may change
|
|
42
|
+
|
|
43
|
+
`profiles.<name>.assets` may change `audio`, `budget`, `lod`, `models`, `targets` and `textures`
|
|
44
|
+
— the *processing* options. It may **not** restate `source`, `output` or `exclude`: the directory
|
|
45
|
+
tree being compiled, where it is written, and what is left out are one answer for the whole
|
|
46
|
+
project, because two profiles disagreeing about the source tree is a build that cooks half a game.
|
|
47
|
+
Those keys are refused.
|
|
48
|
+
|
|
49
|
+
The cap is `maxSize` on the longest edge, preserving aspect and 4x4 alignment, and never
|
|
50
|
+
upscaling — a 512² source under `maxSize: 1024` ships byte-identical. `assets.models.textures.maxSize`
|
|
51
|
+
caps the images carried *inside* a `.glb`, and the two caps key apart: capping one never renames or
|
|
52
|
+
re-encodes the other.
|
|
53
|
+
|
|
54
|
+
**A cap and a `codec: "none"` override cannot both be true**, and the build says so
|
|
55
|
+
(`TN_CONFIG_PROFILE_CONFLICT`): that override returns the authored bytes before resizing, so the
|
|
56
|
+
cap would silently do nothing. Drop the override or take the cap out of the profile.
|
|
57
|
+
|
|
58
|
+
## Native is decoder-free, and the cap still holds
|
|
59
|
+
|
|
60
|
+
Android and iOS ship no WASM, so no KTX2 transcoder and no Meshopt/Draco decoder exists in the
|
|
61
|
+
bundle — a phone cannot decode them, so the cook never produces them. A cap on such a target is
|
|
62
|
+
applied by **resizing the image during the compile** and shipping a PNG, not by writing a KTX2
|
|
63
|
+
nobody could read. The dimension you asked for is the dimension the file decodes to, alpha kept, and
|
|
64
|
+
the source on disk is never modified. Meshopt output is omitted for the same reason.
|
|
65
|
+
|
|
66
|
+
That is also why `assets.budget`'s `uncooked` ceiling is exempt on a mobile target without
|
|
67
|
+
decoders: those bytes are deliberately left raw, not accidentally uncooked. Read the two numbers
|
|
68
|
+
separately — see `agent-docs/mobile-memory-budget.md` for what a decoded image actually costs a
|
|
69
|
+
phone.
|
|
70
|
+
|
|
71
|
+
## Byte budgets, and what the two numbers are
|
|
72
|
+
|
|
73
|
+
`artifactBudget` is a ceiling on **what the build produced**, measured on the staged artifact
|
|
74
|
+
before it is published:
|
|
75
|
+
|
|
76
|
+
- `artifactBytes` — the produced artifact: a file, or the recursive sum of a directory, `.app`
|
|
77
|
+
bundle or outDir. It is everything the player downloads or installs, code included.
|
|
78
|
+
- `packagedAssetBytes` — the sum of the **asset files that survived the packaging selector**: the
|
|
79
|
+
manifest-declared closure that was actually staged. This is the number to write when the question
|
|
80
|
+
is "did the cook do its job".
|
|
81
|
+
|
|
82
|
+
Each is `{ limit, severity }`. `"error"` refuses the build and leaves the previous artifact exactly
|
|
83
|
+
where it was — the new one is published only when every gate has passed; `"warn"` prints and
|
|
84
|
+
publishes. Neither is a judgement about the look: a profile can ship a smaller image, and what that
|
|
85
|
+
image looks like is still yours.
|
|
86
|
+
|
|
87
|
+
## Frame budgets are not measured by the build
|
|
88
|
+
|
|
89
|
+
`performanceBudget` takes the harness's own `assert.performance` fields — `minFps`, `maxFrameMsP95`,
|
|
90
|
+
`maxDrawCalls`, `maxTriangles`, `maxPassDrawCalls`, `maxPassTriangles`, `maxPhaseMsP95` (phases
|
|
91
|
+
`hostGap`, `update`, `render`, `overlay`, `residual`; passes `main`, `shadow`, `reflection`,
|
|
92
|
+
`nested`). The build cannot measure any of it — those numbers only exist once a runtime drew frames
|
|
93
|
+
— so a performance budget never refuses a build and never passes one. It is published into the
|
|
94
|
+
build report and enforced by the next run.
|
|
95
|
+
|
|
96
|
+
## `--build-report` carries the budget with the bytes
|
|
97
|
+
|
|
98
|
+
Every build publishes `<artifact>.build-report.json` **atomically beside the artifact it wrote**:
|
|
99
|
+
`schemaVersion`, `target`, `profile`, the artifact's `sha256`, the manifest's `sha256`, the two
|
|
100
|
+
measured byte counts, and the `performanceBudget` (or `null`). A report that exists is a build that
|
|
101
|
+
finished.
|
|
102
|
+
|
|
103
|
+
```sh
|
|
104
|
+
npx threenative-playtest playtests/survives.playtest.json --url http://127.0.0.1:5173 \
|
|
105
|
+
--build-report dist.build-report.json --artifact dist --browser-recipe webgpu
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The runner re-hashes the artifact under test and refuses the run when it is not the one the report
|
|
109
|
+
describes (`TN_PLAYTEST_BUILD_REPORT_STALE`, naming both digests) — a budget measured on other bytes
|
|
110
|
+
bounds nothing. It also refuses a report for a different target, a malformed report, and a budget
|
|
111
|
+
the target cannot observe. Otherwise the budget merges **per key** into the scenario's
|
|
112
|
+
`assert.performance`, and the scenario's own value wins where it declares one. `--artifact` is
|
|
113
|
+
required on browser and Android because nothing else says which build the run exercises; `--target
|
|
114
|
+
desktop` and `--target ios` already name it.
|
|
115
|
+
|
|
116
|
+
## Appearance is still yours
|
|
117
|
+
|
|
118
|
+
A profile changes representation, not look: which bytes reach the disk, and the ceilings that hold
|
|
119
|
+
the build to them. Materials, shaders, lighting, tone mapping, post and framing are your
|
|
120
|
+
`src/render/` code and stay there — the same `1024²` texture under a different sampler, a different
|
|
121
|
+
mip bias and a different exposure is three different looks from one profile. If a profile makes the
|
|
122
|
+
game look wrong, fix the appearance in your own source; do not reach for a byte ceiling to hide it.
|
|
123
|
+
|
|
124
|
+
To see what a cook actually chose, read the manifest's `via` for the assets your scenario loads, or
|
|
125
|
+
`ctx.assets.resolved` in the running game, which reports each logical path's URL and the `via` that
|
|
126
|
+
resolved it (`manifest` or the no-manifest `source` fallback).
|