@opengamehq/skills 1.3.0 → 1.5.0
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/CHANGELOG.md +44 -0
- package/README.md +12 -4
- package/dist/.claude-plugin/marketplace.json +26 -0
- package/dist/skills/manifest.json +1409 -145
- package/dist/skills/opengame-accessibility/CHANGELOG.md +4 -0
- package/dist/skills/opengame-accessibility/SKILL.md +48 -32
- package/dist/skills/opengame-all-in-one/CHANGELOG.md +21 -0
- package/dist/skills/opengame-all-in-one/SKILL.md +195 -0
- package/dist/skills/opengame-all-in-one/references/opengame-accessibility/README.md +102 -0
- package/dist/skills/opengame-all-in-one/references/opengame-api/README.md +107 -0
- package/dist/skills/opengame-all-in-one/references/opengame-assets/README.md +168 -0
- package/dist/skills/opengame-all-in-one/references/opengame-assets/references/pipeline.md +164 -0
- package/dist/skills/opengame-all-in-one/references/opengame-audio/README.md +238 -0
- package/dist/skills/opengame-all-in-one/references/opengame-audio/helpers/audio-chain.js +325 -0
- package/dist/skills/opengame-all-in-one/references/opengame-audio/references/mix-notes.md +125 -0
- package/dist/skills/opengame-all-in-one/references/opengame-audio/references/qa-without-ears.md +177 -0
- package/dist/skills/opengame-all-in-one/references/opengame-capture/README.md +128 -0
- package/dist/skills/opengame-all-in-one/references/opengame-capture/references/pipeline.md +114 -0
- package/dist/skills/opengame-all-in-one/references/opengame-capture/references/threejs.md +161 -0
- package/dist/skills/opengame-all-in-one/references/opengame-characters/README.md +180 -0
- package/dist/skills/opengame-all-in-one/references/opengame-characters/references/first-person-body.md +108 -0
- package/dist/skills/opengame-all-in-one/references/opengame-characters/references/integration.md +144 -0
- package/dist/skills/opengame-all-in-one/references/opengame-characters/references/player-og.md +160 -0
- package/dist/skills/opengame-all-in-one/references/opengame-cli/README.md +189 -0
- package/dist/skills/opengame-all-in-one/references/opengame-deploy/README.md +223 -0
- package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/json-events.md +63 -0
- package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/manifest.md +89 -0
- package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/packaging.md +119 -0
- package/dist/skills/opengame-all-in-one/references/opengame-depth/README.md +154 -0
- package/dist/skills/opengame-all-in-one/references/opengame-enemies/README.md +155 -0
- package/dist/skills/opengame-all-in-one/references/opengame-enemies/references/pacing-and-bots.md +108 -0
- package/dist/skills/opengame-all-in-one/references/opengame-enemies/references/threejs.md +193 -0
- package/dist/skills/opengame-all-in-one/references/opengame-front-end/README.md +185 -0
- package/dist/skills/opengame-all-in-one/references/opengame-front-end/references/launch.md +50 -0
- package/dist/skills/opengame-all-in-one/references/opengame-front-end/references/menus.md +81 -0
- package/dist/skills/opengame-all-in-one/references/opengame-game-feel/README.md +181 -0
- package/dist/skills/opengame-all-in-one/references/opengame-game-feel/helpers/spring.js +146 -0
- package/dist/skills/opengame-all-in-one/references/opengame-game-feel/references/feel-numbers.md +142 -0
- package/dist/skills/opengame-all-in-one/references/opengame-game-feel/references/killcam.md +88 -0
- package/dist/skills/opengame-all-in-one/references/opengame-jam/README.md +114 -0
- package/dist/skills/opengame-all-in-one/references/opengame-lighting/README.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-lighting/helpers/light-pool.js +185 -0
- package/dist/skills/opengame-all-in-one/references/opengame-loading/README.md +135 -0
- package/dist/skills/opengame-all-in-one/references/opengame-loading/helpers/loading-count.mjs +115 -0
- package/dist/skills/opengame-all-in-one/references/opengame-loading/references/threejs.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-look/README.md +181 -0
- package/dist/skills/opengame-all-in-one/references/opengame-look/references/matching-a-reference.md +73 -0
- package/dist/skills/opengame-all-in-one/references/opengame-look/references/painterly.md +69 -0
- package/dist/skills/opengame-all-in-one/references/opengame-look/references/post-and-lens.md +73 -0
- package/dist/skills/opengame-all-in-one/references/opengame-maps/README.md +74 -0
- package/dist/skills/opengame-all-in-one/references/opengame-maps/references/map-spec.md +77 -0
- package/dist/skills/opengame-all-in-one/references/opengame-mobile/README.md +86 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/README.md +183 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/briefs.md +293 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/day-one-questions.md +46 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/edge-cases.md +27 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/filmable.md +244 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/finishing.md +126 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/measure.md +282 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-capture.md +151 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-gates.md +84 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-genres.md +198 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-grammar.md +320 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-ops.md +127 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/og-snipers-record.md +110 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/owner-eye.md +214 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/reference-study.md +293 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/song.md +64 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/README.md +193 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/briefs.md +293 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/day-one-questions.md +46 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/filmable.md +244 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/measure.md +282 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-capture.md +151 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-gates.md +84 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-genres.md +198 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-grammar.md +320 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-ops.md +127 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/og-snipers-record.md +110 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/owner-eye.md +214 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/reference-study.md +293 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/song.md +64 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/README.md +174 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/briefs.md +293 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/day-one-questions.md +46 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/filmable.md +244 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/finishing.md +126 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/measure.md +282 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-capture.md +151 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-gates.md +84 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-genres.md +198 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-grammar.md +320 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-ops.md +127 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/og-snipers-record.md +110 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/owner-eye.md +214 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/reference-study.md +293 -0
- package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/song.md +64 -0
- package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/README.md +139 -0
- package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/references/bot-lobbies.md +71 -0
- package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/references/netcode.md +165 -0
- package/dist/skills/opengame-all-in-one/references/opengame-performance/README.md +177 -0
- package/dist/skills/opengame-all-in-one/references/opengame-performance/helpers/landing-pacer.mjs +86 -0
- package/dist/skills/opengame-all-in-one/references/opengame-performance/references/measuring.md +123 -0
- package/dist/skills/opengame-all-in-one/references/opengame-performance/references/webgpu.md +86 -0
- package/dist/skills/opengame-all-in-one/references/opengame-production/README.md +192 -0
- package/dist/skills/opengame-all-in-one/references/opengame-production/references/team.md +107 -0
- package/dist/skills/opengame-all-in-one/references/opengame-production/references/templates.md +153 -0
- package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/README.md +170 -0
- package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/cheap-tells.md +43 -0
- package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/judges.md +95 -0
- package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/review-prompt.md +32 -0
- package/dist/skills/opengame-all-in-one/references/opengame-rhythm/README.md +134 -0
- package/dist/skills/opengame-all-in-one/references/opengame-rhythm/references/charting.md +109 -0
- package/dist/skills/opengame-all-in-one/references/opengame-rhythm/references/timing.md +92 -0
- package/dist/skills/opengame-all-in-one/references/opengame-router/README.md +54 -0
- package/dist/skills/opengame-all-in-one/references/opengame-router/references/process.md +38 -0
- package/dist/skills/opengame-all-in-one/references/opengame-scene-audit/README.md +136 -0
- package/dist/skills/opengame-all-in-one/references/opengame-scene-audit/helpers/scene-audit.js +677 -0
- package/dist/skills/opengame-all-in-one/references/opengame-sdk/README.md +283 -0
- package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/engines.md +93 -0
- package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/frame.md +107 -0
- package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/identity.md +111 -0
- package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/leaderboards.md +115 -0
- package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/radio.md +71 -0
- package/dist/skills/opengame-all-in-one/references/opengame-stability/README.md +112 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/README.md +160 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/archetypes.md +113 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/briefs.md +273 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/core.md +129 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/craft.md +299 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/edge-cases.md +27 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/filmable.md +244 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/finishing.md +126 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/gates.md +184 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/measure.md +282 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/music.md +148 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/og-clash-record.md +133 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/ops.md +154 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/owner-eye.md +214 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/review.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/title.md +92 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/README.md +172 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/archetypes.md +113 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/briefs.md +273 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/core.md +129 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/craft.md +299 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/edge-cases.md +27 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/filmable.md +244 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/finishing.md +126 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/gates.md +184 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/measure.md +282 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/music.md +148 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/og-clash-record.md +133 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/ops.md +154 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/owner-eye.md +214 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/reference-set.md +92 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/review.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/title.md +92 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/README.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/archetypes.md +113 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/briefs.md +273 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/core.md +129 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/craft.md +299 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/edge-cases.md +27 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/filmable.md +244 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/finishing.md +126 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/gates.md +184 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/measure.md +282 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/music.md +148 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/og-clash-record.md +133 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/ops.md +154 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/owner-eye.md +214 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/review.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/title.md +92 -0
- package/dist/skills/opengame-all-in-one/references/opengame-verification/README.md +197 -0
- package/dist/skills/opengame-all-in-one/references/opengame-verification/helpers/browser-evidence.mjs +74 -0
- package/dist/skills/opengame-all-in-one/references/opengame-weapons/README.md +179 -0
- package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/handling-numbers.md +114 -0
- package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/reloads-and-hands.md +96 -0
- package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/sights-and-scopes.md +98 -0
- package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/threejs.md +240 -0
- package/dist/skills/opengame-all-in-one/references/opengame-world-physics/README.md +141 -0
- package/dist/skills/opengame-all-in-one/references/opengame-world-physics/references/measured-failures.md +79 -0
- package/dist/skills/opengame-api/CHANGELOG.md +12 -0
- package/dist/skills/opengame-api/SKILL.md +39 -13
- package/dist/skills/opengame-assets/CHANGELOG.md +11 -0
- package/dist/skills/opengame-assets/SKILL.md +79 -31
- package/dist/skills/opengame-assets/references/pipeline.md +67 -0
- package/dist/skills/opengame-audio/CHANGELOG.md +11 -0
- package/dist/skills/opengame-audio/SKILL.md +129 -41
- package/dist/skills/opengame-audio/references/mix-notes.md +44 -1
- package/dist/skills/opengame-audio/references/qa-without-ears.md +177 -0
- package/dist/skills/opengame-capture/CHANGELOG.md +10 -0
- package/dist/skills/opengame-capture/SKILL.md +44 -20
- package/dist/skills/opengame-capture/references/pipeline.md +33 -1
- package/dist/skills/opengame-capture/references/threejs.md +17 -1
- package/dist/skills/opengame-characters/CHANGELOG.md +15 -0
- package/dist/skills/opengame-characters/SKILL.md +94 -39
- package/dist/skills/opengame-characters/references/first-person-body.md +108 -0
- package/dist/skills/opengame-characters/references/player-og.md +1 -1
- package/dist/skills/opengame-cli/CHANGELOG.md +20 -0
- package/dist/skills/opengame-cli/SKILL.md +12 -11
- package/dist/skills/opengame-deploy/CHANGELOG.md +30 -0
- package/dist/skills/opengame-deploy/SKILL.md +43 -23
- package/dist/skills/opengame-deploy/references/json-events.md +6 -5
- package/dist/skills/opengame-deploy/references/manifest.md +9 -3
- package/dist/skills/opengame-deploy/references/packaging.md +32 -30
- package/dist/skills/opengame-depth/CHANGELOG.md +8 -0
- package/dist/skills/opengame-depth/SKILL.md +61 -33
- package/dist/skills/opengame-enemies/CHANGELOG.md +10 -0
- package/dist/skills/opengame-enemies/SKILL.md +96 -40
- package/dist/skills/opengame-enemies/references/pacing-and-bots.md +108 -0
- package/dist/skills/opengame-enemies/references/threejs.md +59 -0
- package/dist/skills/opengame-front-end/CHANGELOG.md +4 -0
- package/dist/skills/opengame-front-end/SKILL.md +85 -39
- package/dist/skills/opengame-front-end/references/menus.md +42 -8
- package/dist/skills/opengame-game-feel/CHANGELOG.md +11 -0
- package/dist/skills/opengame-game-feel/SKILL.md +95 -47
- package/dist/skills/opengame-game-feel/references/feel-numbers.md +59 -0
- package/dist/skills/opengame-game-feel/references/killcam.md +88 -0
- package/dist/skills/opengame-jam/CHANGELOG.md +12 -0
- package/dist/skills/opengame-jam/SKILL.md +48 -33
- package/dist/skills/opengame-lighting/CHANGELOG.md +9 -0
- package/dist/skills/opengame-lighting/SKILL.md +85 -34
- package/dist/skills/opengame-loading/CHANGELOG.md +4 -0
- package/dist/skills/opengame-loading/SKILL.md +78 -38
- package/dist/skills/opengame-loading/helpers/loading-count.mjs +115 -0
- package/dist/skills/opengame-loading/references/threejs.md +32 -7
- package/dist/skills/opengame-look/CHANGELOG.md +9 -0
- package/dist/skills/opengame-look/SKILL.md +122 -51
- package/dist/skills/opengame-look/references/matching-a-reference.md +73 -0
- package/dist/skills/opengame-look/references/painterly.md +69 -0
- package/dist/skills/opengame-look/references/post-and-lens.md +10 -3
- package/dist/skills/opengame-maps/CHANGELOG.md +9 -0
- package/dist/skills/opengame-maps/SKILL.md +78 -0
- package/dist/skills/opengame-maps/references/map-spec.md +77 -0
- package/dist/skills/opengame-mobile/CHANGELOG.md +4 -0
- package/dist/skills/opengame-mobile/SKILL.md +18 -18
- package/dist/skills/opengame-montage-make/CHANGELOG.md +5 -0
- package/dist/skills/opengame-montage-make/SKILL.md +187 -0
- package/dist/skills/opengame-montage-make/references/briefs.md +293 -0
- package/dist/skills/opengame-montage-make/references/day-one-questions.md +46 -0
- package/dist/skills/opengame-montage-make/references/edge-cases.md +27 -0
- package/dist/skills/opengame-montage-make/references/filmable.md +244 -0
- package/dist/skills/opengame-montage-make/references/finishing.md +126 -0
- package/dist/skills/opengame-montage-make/references/measure.md +282 -0
- package/dist/skills/opengame-montage-make/references/montage-capture.md +151 -0
- package/dist/skills/opengame-montage-make/references/montage-gates.md +84 -0
- package/dist/skills/opengame-montage-make/references/montage-genres.md +198 -0
- package/dist/skills/opengame-montage-make/references/montage-grammar.md +320 -0
- package/dist/skills/opengame-montage-make/references/montage-ops.md +127 -0
- package/dist/skills/opengame-montage-make/references/og-snipers-record.md +110 -0
- package/dist/skills/opengame-montage-make/references/owner-eye.md +214 -0
- package/dist/skills/opengame-montage-make/references/reference-study.md +293 -0
- package/dist/skills/opengame-montage-make/references/song.md +64 -0
- package/dist/skills/opengame-montage-plan/CHANGELOG.md +5 -0
- package/dist/skills/opengame-montage-plan/SKILL.md +197 -0
- package/dist/skills/opengame-montage-plan/references/briefs.md +293 -0
- package/dist/skills/opengame-montage-plan/references/day-one-questions.md +46 -0
- package/dist/skills/opengame-montage-plan/references/filmable.md +244 -0
- package/dist/skills/opengame-montage-plan/references/measure.md +282 -0
- package/dist/skills/opengame-montage-plan/references/montage-capture.md +151 -0
- package/dist/skills/opengame-montage-plan/references/montage-gates.md +84 -0
- package/dist/skills/opengame-montage-plan/references/montage-genres.md +198 -0
- package/dist/skills/opengame-montage-plan/references/montage-grammar.md +320 -0
- package/dist/skills/opengame-montage-plan/references/montage-ops.md +127 -0
- package/dist/skills/opengame-montage-plan/references/og-snipers-record.md +110 -0
- package/dist/skills/opengame-montage-plan/references/owner-eye.md +214 -0
- package/dist/skills/opengame-montage-plan/references/reference-study.md +293 -0
- package/dist/skills/opengame-montage-plan/references/song.md +64 -0
- package/dist/skills/opengame-montage-review-and-improve/CHANGELOG.md +5 -0
- package/dist/skills/opengame-montage-review-and-improve/SKILL.md +178 -0
- package/dist/skills/opengame-montage-review-and-improve/references/briefs.md +293 -0
- package/dist/skills/opengame-montage-review-and-improve/references/day-one-questions.md +46 -0
- package/dist/skills/opengame-montage-review-and-improve/references/filmable.md +244 -0
- package/dist/skills/opengame-montage-review-and-improve/references/finishing.md +126 -0
- package/dist/skills/opengame-montage-review-and-improve/references/measure.md +282 -0
- package/dist/skills/opengame-montage-review-and-improve/references/montage-capture.md +151 -0
- package/dist/skills/opengame-montage-review-and-improve/references/montage-gates.md +84 -0
- package/dist/skills/opengame-montage-review-and-improve/references/montage-genres.md +198 -0
- package/dist/skills/opengame-montage-review-and-improve/references/montage-grammar.md +320 -0
- package/dist/skills/opengame-montage-review-and-improve/references/montage-ops.md +127 -0
- package/dist/skills/opengame-montage-review-and-improve/references/og-snipers-record.md +110 -0
- package/dist/skills/opengame-montage-review-and-improve/references/owner-eye.md +214 -0
- package/dist/skills/opengame-montage-review-and-improve/references/reference-study.md +293 -0
- package/dist/skills/opengame-montage-review-and-improve/references/song.md +64 -0
- package/dist/skills/opengame-multiplayer/CHANGELOG.md +15 -0
- package/dist/skills/opengame-multiplayer/SKILL.md +143 -0
- package/dist/skills/opengame-multiplayer/references/bot-lobbies.md +71 -0
- package/dist/skills/opengame-multiplayer/references/netcode.md +165 -0
- package/dist/skills/opengame-performance/CHANGELOG.md +8 -0
- package/dist/skills/opengame-performance/SKILL.md +106 -65
- package/dist/skills/opengame-performance/helpers/landing-pacer.mjs +86 -0
- package/dist/skills/opengame-performance/references/measuring.md +51 -0
- package/dist/skills/opengame-performance/references/webgpu.md +86 -0
- package/dist/skills/opengame-production/CHANGELOG.md +13 -0
- package/dist/skills/opengame-production/SKILL.md +119 -54
- package/dist/skills/opengame-production/references/team.md +107 -0
- package/dist/skills/opengame-production/references/templates.md +106 -16
- package/dist/skills/opengame-quality-bar/CHANGELOG.md +10 -0
- package/dist/skills/opengame-quality-bar/SKILL.md +94 -42
- package/dist/skills/opengame-quality-bar/references/cheap-tells.md +14 -7
- package/dist/skills/opengame-quality-bar/references/judges.md +95 -0
- package/dist/skills/opengame-quality-bar/references/review-prompt.md +10 -5
- package/dist/skills/opengame-rhythm/CHANGELOG.md +5 -0
- package/dist/skills/opengame-rhythm/SKILL.md +138 -0
- package/dist/skills/opengame-rhythm/references/charting.md +109 -0
- package/dist/skills/opengame-rhythm/references/timing.md +92 -0
- package/dist/skills/opengame-router/CHANGELOG.md +12 -0
- package/dist/skills/opengame-router/SKILL.md +14 -7
- package/dist/skills/opengame-scene-audit/CHANGELOG.md +15 -0
- package/dist/skills/opengame-scene-audit/SKILL.md +64 -47
- package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +97 -19
- package/dist/skills/opengame-sdk/CHANGELOG.md +16 -0
- package/dist/skills/opengame-sdk/SKILL.md +27 -10
- package/dist/skills/opengame-sdk/references/engines.md +2 -2
- package/dist/skills/opengame-sdk/references/identity.md +10 -11
- package/dist/skills/opengame-sdk/references/leaderboards.md +11 -1
- package/dist/skills/opengame-sdk/references/radio.md +1 -1
- package/dist/skills/opengame-stability/CHANGELOG.md +4 -0
- package/dist/skills/opengame-stability/SKILL.md +59 -27
- package/dist/skills/opengame-trailer-make/CHANGELOG.md +5 -0
- package/dist/skills/opengame-trailer-make/SKILL.md +164 -0
- package/dist/skills/opengame-trailer-make/references/archetypes.md +113 -0
- package/dist/skills/opengame-trailer-make/references/briefs.md +273 -0
- package/dist/skills/opengame-trailer-make/references/core.md +129 -0
- package/dist/skills/opengame-trailer-make/references/craft.md +299 -0
- package/dist/skills/opengame-trailer-make/references/edge-cases.md +27 -0
- package/dist/skills/opengame-trailer-make/references/filmable.md +244 -0
- package/dist/skills/opengame-trailer-make/references/finishing.md +126 -0
- package/dist/skills/opengame-trailer-make/references/gates.md +184 -0
- package/dist/skills/opengame-trailer-make/references/measure.md +282 -0
- package/dist/skills/opengame-trailer-make/references/music.md +148 -0
- package/dist/skills/opengame-trailer-make/references/og-clash-record.md +133 -0
- package/dist/skills/opengame-trailer-make/references/ops.md +154 -0
- package/dist/skills/opengame-trailer-make/references/owner-eye.md +214 -0
- package/dist/skills/opengame-trailer-make/references/review.md +141 -0
- package/dist/skills/opengame-trailer-make/references/title.md +92 -0
- package/dist/skills/opengame-trailer-plan/CHANGELOG.md +5 -0
- package/dist/skills/opengame-trailer-plan/SKILL.md +176 -0
- package/dist/skills/opengame-trailer-plan/references/archetypes.md +113 -0
- package/dist/skills/opengame-trailer-plan/references/briefs.md +273 -0
- package/dist/skills/opengame-trailer-plan/references/core.md +129 -0
- package/dist/skills/opengame-trailer-plan/references/craft.md +299 -0
- package/dist/skills/opengame-trailer-plan/references/edge-cases.md +27 -0
- package/dist/skills/opengame-trailer-plan/references/filmable.md +244 -0
- package/dist/skills/opengame-trailer-plan/references/finishing.md +126 -0
- package/dist/skills/opengame-trailer-plan/references/gates.md +184 -0
- package/dist/skills/opengame-trailer-plan/references/measure.md +282 -0
- package/dist/skills/opengame-trailer-plan/references/music.md +148 -0
- package/dist/skills/opengame-trailer-plan/references/og-clash-record.md +133 -0
- package/dist/skills/opengame-trailer-plan/references/ops.md +154 -0
- package/dist/skills/opengame-trailer-plan/references/owner-eye.md +214 -0
- package/dist/skills/opengame-trailer-plan/references/reference-set.md +92 -0
- package/dist/skills/opengame-trailer-plan/references/review.md +141 -0
- package/dist/skills/opengame-trailer-plan/references/title.md +92 -0
- package/dist/skills/opengame-trailer-review-and-improve/CHANGELOG.md +5 -0
- package/dist/skills/opengame-trailer-review-and-improve/SKILL.md +145 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/archetypes.md +113 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/briefs.md +273 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/core.md +129 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/craft.md +299 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/edge-cases.md +27 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/filmable.md +244 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/finishing.md +126 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/gates.md +184 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/measure.md +282 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/music.md +148 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/og-clash-record.md +133 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/ops.md +154 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/owner-eye.md +214 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/review.md +141 -0
- package/dist/skills/opengame-trailer-review-and-improve/references/title.md +92 -0
- package/dist/skills/opengame-verification/CHANGELOG.md +11 -0
- package/dist/skills/opengame-verification/SKILL.md +113 -48
- package/dist/skills/opengame-weapons/CHANGELOG.md +11 -0
- package/dist/skills/opengame-weapons/SKILL.md +129 -55
- package/dist/skills/opengame-weapons/references/handling-numbers.md +42 -0
- package/dist/skills/opengame-weapons/references/reloads-and-hands.md +96 -0
- package/dist/skills/opengame-weapons/references/sights-and-scopes.md +98 -0
- package/dist/skills/opengame-weapons/references/threejs.md +71 -0
- package/dist/skills/opengame-world-physics/CHANGELOG.md +9 -0
- package/dist/skills/opengame-world-physics/SKILL.md +55 -24
- package/dist/skills/opengame-world-physics/references/measured-failures.md +28 -1
- package/package.json +1 -1
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: opengame-lighting
|
|
3
|
-
description: Light a three.js browser game so it reads as a place. Covers characters that
|
|
3
|
+
description: Light a three.js browser game so it reads as a place. Covers characters that are not silhouettes, wide lenses, the light limit, a shadow key that does not crawl, exposure from a meter, auto-exposure and measured darkness, a fixed pool of real lights, a carried torch, the player's hands, real indirect light and lit effects. Use when the person says the lighting is flat, characters look black, shadows flicker, it is too dark or too bright, the flashlight or hands look wrong, or add lamps.
|
|
4
4
|
metadata:
|
|
5
|
-
version: "1.
|
|
5
|
+
version: "1.1.0"
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Lighting
|
|
@@ -10,7 +10,9 @@ metadata:
|
|
|
10
10
|
Most flat-looking games have one problem: everything is lit by an ambient term, so
|
|
11
11
|
nothing is darker than anything else. The fix is a costed rig: one real shadow-casting
|
|
12
12
|
key, a weak fill, real indirect light, and a fixed number of point lights however many
|
|
13
|
-
lamps the level has.
|
|
13
|
+
lamps the level has. Dark games add a second problem: the exposure. In a game lit by a
|
|
14
|
+
torch and a muzzle flash, how the sensor meters is the look, and it is set by numbers
|
|
15
|
+
measured from the reference, not by eye on a bright monitor.
|
|
14
16
|
|
|
15
17
|
Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
16
18
|
|
|
@@ -19,76 +21,125 @@ Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
|
19
21
|
### No character is a silhouette
|
|
20
22
|
- **Invariant:** Every character, creature and held item shows form and colour against every background it appears on, and none reads as a black silhouette.
|
|
21
23
|
- **Technique:** Light characters on purpose: an ambient or hemisphere term that reaches skinned materials, a rim from the side away from the key, and a fill so hands and faces keep detail in backlight. Confirm the character shader receives each term, because a fill that reads an empty input has no effect. Give the view model its own environment. In three.js add a `HemisphereLight`, a Fresnel rim through `onBeforeCompile` on the character's `MeshStandardMaterial`, and a PMREM environment on the view-model scene.
|
|
22
|
-
- **Reference configuration:** OC's first review found "black silhouettes with glowing balls stuck on them". The renderer gave skinned meshes no rim, fill or ambient, and the ambient term it did have read zero without a sky probe; fixing it took shader edits in 3 streams. The view model's studio environment gave 41% of the gun's brightness. OC keeps zombie flesh lighter than the floor (its albedo L was 17 against a target of 50 or more) and the boss at 2:1 contrast or better against its background (pit fog had cut it to 1.12:1).
|
|
24
|
+
- **Reference configuration:** OC's first review found "black silhouettes with glowing balls stuck on them". The renderer gave skinned meshes no rim, fill or ambient, and the ambient term it did have read zero without a sky probe; fixing it took shader edits in 3 streams. The view model's studio environment gave 41% of the gun's brightness. OC keeps zombie flesh lighter than the floor (its albedo L was 17 against a target of 50 or more) and the boss at 2:1 contrast or better against its background (pit fog had cut it to 1.12:1). LC tints near-camera zombie hands to 0.6 of the face with roughness at least 0.86, because a hand 0.4 m from a lamp gets about 7 times what a face at 1.1 m does.
|
|
23
25
|
- **Applies when:** Every 3D game with characters, dark scenes above all.
|
|
24
26
|
- **Verify:** Capture each character type in the darkest spot and the most backlit spot of each level, then sample face, hands and torso against the floor behind them.
|
|
25
27
|
|
|
28
|
+
### Light figures about the line to the eye under a wide lens
|
|
29
|
+
- **Invariant:** Under a wide lens every figure shows a lit side and a shade side wherever it stands in the frame, so a figure at the edge reads as shaped as one at the centre.
|
|
30
|
+
- **Technique:** Build each figure's light direction per fragment from the line between the figure and the eye (`cross(up, toEye)`), not from one camera-space direction, which lights every surface off axis from the front. In a banded style use two flat values with one drawn edge, and keep halftone to the core shadow. When shading will not show, colour the shader's own decision (lit, shade, edge) in a debug view before changing any value.
|
|
31
|
+
- **Reference configuration:** OH: with the light in camera space, every crowd surface 40 degrees off axis under a 104 degree lens came out lit. Five passes changed values and failed; the light about the line to the eye fixed it in one, found by colouring the branch the shader took. It matters above roughly 70 degrees of field of view.
|
|
32
|
+
- **Applies when:** Wide lenses, stylised or banded lighting, and crowds spread across the frame.
|
|
33
|
+
- **Verify:** A debug snapshot coloured by branch, and 1:1 crops of figures at the centre and the edges of the frame.
|
|
34
|
+
|
|
26
35
|
### Count the light sources against the light limit on day one
|
|
27
36
|
- **Invariant:** Before anyone tunes the look, the team has counted the things that look like they emit light and measured the light limit the renderer applies, adaptive quality included.
|
|
28
|
-
- **Technique:** List every fire, lamp, screen and glow the concept implies and compare that count with the limit the renderer uses at runtime. Where sources outnumber lights, plan for it: bake static fire into lightmaps or probes, show the nearest sources through the pool below, and let emissive plus bloom carry the rest. Pin quality in captures so adaptive quality cannot drop lights unseen. In three.js `WebGLRenderer` shades every light for every lit fragment and recompiles when the light count changes, so
|
|
29
|
-
- **Reference configuration:** OC's arena had 218 to 224 fire sites against a 32-light cap, and adaptive quality dropped captures to "8 of 224". The cap surfaced only after about 6 rejections on day one
|
|
37
|
+
- **Technique:** List every fire, lamp, screen and glow the concept implies and compare that count with the limit the renderer uses at runtime. Where sources outnumber lights, plan for it: bake static fire into lightmaps or probes, show the nearest sources through the pool below, and let emissive plus bloom carry the rest. Pin quality in captures so adaptive quality cannot drop lights unseen. In three.js `WebGLRenderer` shades every light for every lit fragment and recompiles when the light count changes; in `WebGPURenderer` the light set is part of every lit shader's key, so adding a light or toggling its `visible` or `castShadow` rebuilds every lit material in view. Create every light at boot at intensity zero.
|
|
38
|
+
- **Reference configuration:** OC's arena had 218 to 224 fire sites against a 32-light cap, and adaptive quality dropped captures to "8 of 224". The cap surfaced only after about 6 rejections on day one; 224 clustered lights measured about 0.2 ms, so raising the cap was cheap. LC fixes its set at boot: a hemisphere, a near fill, lightning, the weapon light (the one shadow caster in play), two alternating muzzle-flash points and three lamp points.
|
|
30
39
|
- **Applies when:** Any level lit by many practicals: fires, torches, neon, screens.
|
|
31
40
|
- **Verify:** Log the active light count each frame with quality pinned and unpinned. It matches the plan, and a walk past every fire shows no source going dark.
|
|
32
41
|
|
|
33
42
|
### One shadow-casting key that does not crawl
|
|
34
|
-
- **Invariant:** One directional light casts the world's shadows, its shadow box covers the play area around the player only, and shadow edges do not shimmer as the player walks.
|
|
35
|
-
- **Technique:** Follow the player with the shadow camera and snap its centre to the shadow map's texel grid.
|
|
36
|
-
- **Reference configuration:** DK: a 34 m box biased forward of the player, texel-snapped, bias about -0.0003 to -0.00035, normal bias 0.05 to 0.10,
|
|
43
|
+
- **Invariant:** One directional light casts the world's shadows, it clears the terrain that frames the play space, its shadow box covers the play area around the player only, and shadow edges do not shimmer as the player walks.
|
|
44
|
+
- **Technique:** Follow the player with the shadow camera and snap its centre to the shadow map's texel grid. Check which unit the engine's bias is counted in (texels or world units) before setting it, then tune depth bias and normal bias against acne and peter-panning on moving casters. Fade the shadow to nothing over the outer edge of the box rather than cutting it. Lower a sun only along its existing bearing, and dump the direction the shader receives.
|
|
45
|
+
- **Reference configuration:** DK: a 34 m box biased forward of the player, texel-snapped, bias about -0.0003 to -0.00035, normal bias 0.05 to 0.10, ramped out over the outer 14% of the box, on a 2048 map. SR uses a 120 m box for its island. OS: a bias of 0.02 set as metres came out at 0.4 mm against 8.8 mm texels and drew the owner's "hard-edged rectangle" on the near cascade, fixed at depth 1.0 and normal 0.5 texels, found by turning caster groups off one at a time; cascades 6, 18, 54 and 150 m. OS suns sat 2 to 10 degrees under their ridges, and a "12deg" title sun "actually lit from 51deg".
|
|
37
46
|
- **Applies when:** Outdoor and large-interior 3D scenes with a sun or moon. A small interior lit only by practicals may use a local shadow instead.
|
|
38
47
|
- **Verify:** Record a slow walk along a wall edge: the shadow's stair-step outline stays still. Shrink the box on purpose and check the edge fades instead of cliff-cutting.
|
|
39
48
|
|
|
40
49
|
### Shadow is darker than light
|
|
41
50
|
- **Invariant:** Shadowed surfaces are clearly darker than lit ones of the same material, and the difference is warm against cool.
|
|
42
51
|
- **Technique:** Lower the fill before raising the key. Measure a lit surface and its shadowed neighbour in a linear capture, not by eye on a bright monitor.
|
|
43
|
-
- **Reference configuration:** Shadowed at 15 to 40% of lit across our games; the ST look pass targets 15 to 20%. MC: sun 3.5 at about 17 degrees elevation, hemisphere 0.18, ambient 0.34, environment 0.30. DK contrasts a cold moon (0xa8c0f0, 2.6) with warm sodium practicals (0xffb765, 5 cd, 22 m, decay 2).
|
|
44
|
-
- **Applies when:** Lit 3D looks. Stylised looks state their band count and ratio in the look
|
|
52
|
+
- **Reference configuration:** Shadowed at 15 to 40% of lit across our earlier games; the ST look pass targets 15 to 20%. MC: sun 3.5 at about 17 degrees elevation, hemisphere 0.18, ambient 0.34, environment 0.30. DK contrasts a cold moon (0xa8c0f0, 2.6) with warm sodium practicals (0xffb765, 5 cd, 22 m, decay 2). OS sets fill at 0.2 to 0.3 of the sun. LC pushes warm lights toward rose (1, 0.74, 0.8), because "amber on pale cloth is yellow".
|
|
53
|
+
- **Applies when:** Lit 3D looks. Stylised looks state their band count and ratio in the look page instead.
|
|
45
54
|
- **Verify:** Sample the luminance of matched lit and shadowed pixels in a capture with the grade off and report the ratio.
|
|
46
55
|
|
|
47
|
-
###
|
|
48
|
-
- **Invariant:**
|
|
49
|
-
- **Technique:**
|
|
50
|
-
- **Reference configuration:**
|
|
56
|
+
### Expose each map from a meter, and gate its frames on numbers
|
|
57
|
+
- **Invariant:** Each map's exposure comes from a meter, its frames meet written targets for highlights, crushed shadow and visible sky, and its own light preset is what reaches the shader, with nothing leaking from a title, menu or parent game.
|
|
58
|
+
- **Technique:** Expose so a mid-grey card in full sun reads one fixed scene value, and treat any per-map exposure setting as an offset from it. Set fill as a fraction of the sun and the sky as a multiple of a sunlit white wall, choosing the ratios by A/B in one page load. Set the gates (median luma, a bright percentile, the share of crushed pixels) before capturing, and capture from fixed cameras beside the concept. Indoors, widen eye adaptation only under a detected roof. Read each map's effective light values from the renderer after a trip through the menus, and check the pre-match and countdown views in every weather, not only play.
|
|
59
|
+
- **Reference configuration:** OS: a horizontal 18% card in sun reads 0.21 scene (sRGB about 135); sky 1.25 to 1.6 times a sunlit white wall, where a 4 times horizon clipped and its probes filled every shadow ("flat overcast white sky"); fill 0.2 to 0.3 of the sun. Gates: p50 95 to 130, p95 205 or more, crushed (all channels under 20) 3% or less, against first captures at p95 100 to 160 and crushed 14 to 34% ("Highlights are missing, not shadows"). One map's card read 0.0735 against 0.195, so its exposure rose 2.65 times: the only art change judges preferred across 20 rounds. Eye adaptation capped at plus 0.3 EV outdoors and plus 2.2 EV under a roof; the pre-match screen gets plus 0.35 EV and a toe lift ("Moody, not black").
|
|
60
|
+
- **Applies when:** Lit 3D games with several maps or screens, forks of another game, or roofed spaces in an outdoor game. A dark game whose exposure adapts also follows the next two rules.
|
|
61
|
+
- **Verify:** Luma statistics on fixed cameras beside the concept for every map, screen and weather. A light-strength sweep that changes no pixel means the light's falloff ends before the surface, not that the intensity is right.
|
|
62
|
+
|
|
63
|
+
### Auto-exposure leans on what is lit and never strobes
|
|
64
|
+
- **Invariant:** In a game whose exposure adapts, a lit subject never burns white, unlit space falls to black, a darker scene stays darker instead of being undone by the sensor, and firing never strobes the frame.
|
|
65
|
+
- **Technique:** Meter on the GPU and never read the result back: build the HDR target's mip chain once, read a small level into a one-pixel target, and weight the mean toward the brightest parts (clamped) blended with the plain average. Close fast and open slowly. Cap how far the sensor may open by the light that falls on the subject: raycast the main light's centre, compute its illuminance there, and never open past where a mid-grey card at that point sits at the key, opening less when an enemy is in the cone. Cap the dip after a muzzle flash against the level before the burst, and recover a black frame to visible at once. Take every reading with the game's population present, and never let warm-up frames feed the meter.
|
|
66
|
+
- **Reference configuration:** LC: key 0.36 to 0.42 of white (0.3 at the darkest night), range minus 9 to plus 0.7 stops ("more than that and the night reads as dusk"), close in 0.04 s, open in 0.21 s, at most 4 stops down a frame, weighted 3:1 brightest to mean with anything over 4 whites counted as 4, a black frame visible within 0.04 s, otherwise at most 3 stops a second. Ceiling card = log2(key·π/(0.18·E)) with plus one stop on the world and none with an enemy in the cone: a 3% wreck went to minus 2.8 stops, and a figure at 10 m reads "a man in a tunic". A flash dip capped at 1.25 stops cured an unreported white and black strobe at 10 rounds a second. A zombie in the unlit beam moved the meter 0.8 of a stop, so every night still taken without one read 0.8 stop bright. Warm-up frames fed the meter and blacked the title. The meter equalising albedo once whited out a near board while three hours went into restyling materials (`opengame-look`).
|
|
67
|
+
- **Applies when:** Night, interior, horror or flashlight games with HDR and adaptive exposure.
|
|
68
|
+
- **Verify:** Figure-against-background luminance per frame with figures at several distances in the beam (LC used 2.8, 5, 10 and 15 m), consecutive frames during full-auto fire, and a lamp-off empty field.
|
|
69
|
+
|
|
70
|
+
### Darkness is a measured target, reached with light rather than exposure
|
|
71
|
+
- **Invariant:** The darkness of every key state is written as numbers from the reference and the owner's word, reached by changing the scene's light rather than the sensor, and checked with the game's population present.
|
|
72
|
+
- **Technique:** Measure box luminance in reference stills of the same state, and write a target per state (lamp off, lamp on, flash, lightning) in the look page. To match, raise the night's own light and cut sensor gain by the same number of stops, and give the dark a hue from the reference. Take readings at a fixed weather time. When the owner's word and the reference differ, follow the owner and write down where. After darkening, recheck indoors with the carried light on: a darker night can make a space unplayable, which is answered with the carried light, not by lifting the dark.
|
|
73
|
+
- **Reference configuration:** LC's film: forest 0.009 to 0.020 of white, sky 57 to 80 of 255, pool tops 111 to 124; night light up and sensor gain down by 4.2 to 4.8 stops. Then the owner: "when u have ur flashlight off its a bit too bright/still tooe asy to see around needs to be much horro more scary where muzzle flash is really how u can see clearly ... make it scarier...". Targets became 6 to 9 of 255 in the middle of the frame with the lamp off, and 90 to 110 at the centre at 3 m with it on, under 12 outside the cone; the first zone went from 49.8 to 10.1 lamp off. That made indoors unplayable and led to the torch rebuild in the next rules. Night levels moved with the weather minute (11.7 against 15.6 of 255 at one stand).
|
|
74
|
+
- **Applies when:** Every dark or horror game, and every game matched to a reference.
|
|
75
|
+
- **Verify:** Four stills per change at fixed stands (lamp off, lamp on, flash, lightning) with enemies present, box means compared with the targets.
|
|
76
|
+
|
|
77
|
+
### A fixed pool of real lights, given to what counts at the camera
|
|
78
|
+
- **Invariant:** The number of real point and spot lights never changes during play, so no shader recompiles mid-game, each slot goes to the lamps that matter most at the camera, and a lit light never jumps or flickers by being swapped.
|
|
79
|
+
- **Technique:** Create the pool once and leave it in the scene. Each frame, rank the authored sources by what they put on the view (distance, intensity, fog transmission), swap a source in only when it clearly outranks the weakest shown one, and hand a slot over on the frame its intensity is exactly zero. Never toggle `visible` on a light; set intensity to zero. Draw glows beyond the pool as unlit colour above white. [helpers/light-pool.js](helpers/light-pool.js) does this, and its `selfTest()` plants a shrinking pool, a ranked pool and a pool without fades to prove its checks.
|
|
80
|
+
- **Reference configuration:** DK shows about 68 authored lamps through 4, 6 or 8 real lights by quality tier, with 1.7 times hysteresis and 0.25 s fades; DK defines a lit-light teleport as a pooled light moving more than 0.25 m in a frame with non-zero intensity, excluding sources that really moved. LC runs three pooled points with a quarter hysteresis: before it ranked by what counts at the lens, a 1,600 cd yard lamp 87.5 m away took the light of a post 27 m away, and a 225 cd strobe "takes one of the engine's three lamps from across the map". Up to 8 nearer lamps glow in the air without being lights.
|
|
51
81
|
- **Applies when:** More authored lights than the budget allows real ones, which is almost every level with lamps.
|
|
52
|
-
- **Verify:** `renderer.info.programs.length` is unchanged after walking the whole level past every lamp,
|
|
82
|
+
- **Verify:** The renderer's program count (`renderer.info.programs.length` in `WebGLRenderer`) is unchanged after walking the whole level past every lamp, the helper's `measurePool` reports zero count changes and zero lit teleports, and a per-frame log shows which lamp holds each slot.
|
|
83
|
+
|
|
84
|
+
### Lights on the camera are deliberate
|
|
85
|
+
- **Invariant:** The only camera-held lights that reach the world are designed ones (a carried torch or weapon light, a muzzle flash) costed and measured as part of the rig; view-model fills and the light that makes hands and weapons read never reach the world pass, and the view model never casts into it.
|
|
86
|
+
- **Technique:** Put view-model lights on the view model's own layer and pass, or make them a term in the view model's material that adds no engine light. A camera-parented light that lights the world by accident moves at player speed and defeats shadows, pools and every measurement of the rig; a carried torch is costed, shadowed and measured like any other key (next rule).
|
|
87
|
+
- **Reference configuration:** DK's weapon rig carries a fill parented to the camera on its own layer, a key 1.34 and a cool rim 0.44 for the weapon only, excluded from pool measurements as a source that really moves. OC moved its fills near the hands away and lower and halved them instead of dimming the scene; its third-person muzzle light is about 0.12 of the first-person one, 30 cm ahead of the gun. LC's whole night is lit by a carried torch, which the old wording of this rule forbade; the lamp on the operator's own hands is a material "return" term that adds no engine light, and the hands cast no shadow.
|
|
88
|
+
- **Applies when:** First-person games and any game with a view model.
|
|
89
|
+
- **Verify:** List lights at runtime with their parent chain and layers: the only camera-held lights on the world layer are the declared carried light and muzzle flashes.
|
|
90
|
+
|
|
91
|
+
### A carried light throws from its real bore
|
|
92
|
+
- **Invariant:** A torch or weapon light leaves from where it is mounted, lights distant targets the way a real torch does, with a hot spot and soft spill rather than a disc, and is never shadowed by the player's own body or weapon.
|
|
93
|
+
- **Technique:** Share one beam-profile function between the light's cookie, any marched beam in the air and the atmosphere. Give it real intensity on axis, a tight hot spot, a corona and a little spill, a long near field so it falls off with distance the way a real torch does, and a retro term so a surface lit from where it is seen is not darkened by the cosine. Turn shadow casting off on every view-model mesh before warm-up, so nothing near the lens can shadow the beam, and then bring the shadow's near plane close: a far near plane paints slabs on near faces. Ease the output right at the lens.
|
|
94
|
+
- **Reference configuration:** LC's first light: 1800 cd (7000 blacked out everything outside the pool), hot spot 6.5 degrees, corona 15 degrees, 3% spill to 37 degrees, leaving the muzzle 17 cm under the lens and crossing the centre at 7 m. Rebuilt for the darker night: 12,000 cd on axis, end 30 m, near field 22.4 m, hot spot 0.13 rad, corona 0.2 rad, spill 1/20, retro term (1 + 0.4(1 - c²)/c); a grey card on axis at 3, 5, 10, 15 and 25 m read 109/76/43/36/38 before and 108/104/93/80/42 after. Shadow near plane 0.12 m (0.45 painted slabs), normal bias 3 cm, redrawn every frame at Ultra and every second or third frame below.
|
|
95
|
+
- **Applies when:** Flashlight, headlamp and weapon-light games.
|
|
96
|
+
- **Verify:** A grey card on axis at five distances, and a capture with figures at three distances showing a round pool with heads lit.
|
|
97
|
+
|
|
98
|
+
### Light the player's hands from the lens, on their draws only
|
|
99
|
+
- **Invariant:** In a dark first-person game the player's gloves, sleeves and weapon read (each finger, the seams, the top of the weapon), stay darker than the brightest lit world surface, and never pump with exposure.
|
|
100
|
+
- **Technique:** Add a fill after exposure on the view model's draws only (emissive plus albedo times fill), peaking at the hands and falling toward elbow and muzzle, lower with the carried light off, with no rim term and cloth albedo at or below the glove's. Hold carried things inside a luminance band pinned to a reference the owner accepted, and test the fill in the real build rather than patched in at capture time.
|
|
101
|
+
- **Reference configuration:** LC: fill 0.35 to 0.7 in output units where the key is 0.36 (1.3 drew white), a third of that with the light off, cloth albedo 0.08 to 0.18: "The limit is the light on the hands, not the maps." Carried things sit about 25/255 at rest, 30 at most on the sights, never above the snow, with the darkest twentieth at 4 to 11. Raising the gloves' fill for one reload drew a glove "paper-white"; pinned at 0.2 of the accepted pistol's fill, the glove reads 44 to 51 where the pistol reads 55 to 57. A fill tested by patching at capture time drew the hands white in the real build.
|
|
102
|
+
- **Applies when:** Dark first-person games, and any game whose view model is lit apart from the world.
|
|
103
|
+
- **Verify:** Stills at rest, aiming and reloading, light on and off: count the fingers, and the gloves are never the brightest thing in the frame.
|
|
104
|
+
|
|
105
|
+
### Part the light terms on a near-camera object before editing its maps
|
|
106
|
+
- **Invariant:** Before any map of a near-camera object (a held weapon, hands, gloves) is edited, the team knows which light term carries its brightness.
|
|
107
|
+
- **Technique:** Hold each light term at its uniform in turn (lens fill off, carried light off, environment off, then a pure red map) and read the object's masked luminance each time. Never re-grade a shared map to answer one weapon's light. With a light at the camera, put form into the colour: pale tops, dark channels.
|
|
108
|
+
- **Reference configuration:** LC's held weapon: 39.6/255 as it was, 6.7 with the lens fill off, 36.3 with the torch's return off, 4.3 with all three off; the fill carried 32 of 39 levels and the torch 4. Every "pale magazine, cream brass, salmon stock" was the light, and a metalness pass on twenty guns changed nothing. A lamp at the camera shades no relief, so glove pad tops were rubbed pale and channels darkened in the albedo.
|
|
109
|
+
- **Applies when:** First-person games, and anything lit by a light on or near the camera.
|
|
110
|
+
- **Verify:** A parting table for one object per class, and a grey-percentile count beside the accepted reference.
|
|
53
111
|
|
|
54
112
|
### Real indirect light
|
|
55
|
-
- **Invariant:** Light bounces: a sunlit floor warms the wall beside it and a dark
|
|
56
|
-
- **Technique:** Bake it. Per-vertex or lightmapped irradiance for static geometry, plus a grid of spherical-harmonic probes sampled by moving actors. three's `LightProbeGrid` (examples, WebGL only) bakes probe grids on the GPU; lightmaps can be baked offline. Hemisphere fill, environment maps and ambient occlusion are not global illumination, and calling them that is a false claim.
|
|
57
|
-
- **Reference configuration:** SR bakes single-bounce irradiance into a per-vertex atlas for static geometry and nine-coefficient SH probes for actors, validated against a signature of the world so a stale bake refuses to load.
|
|
58
|
-
- **Applies when:** Any game that wants depth from light, most of all interiors and mixed indoor and outdoor spaces. A flat style chosen in the look
|
|
113
|
+
- **Invariant:** Light bounces: a sunlit floor warms the wall beside it and a dark hallway is darker than an open courtyard, from an actual bounce or occlusion solution rather than a brighter ambient.
|
|
114
|
+
- **Technique:** Bake it. Per-vertex or lightmapped irradiance for static geometry, plus a grid of spherical-harmonic probes sampled by moving actors. three's `LightProbeGrid` (examples, WebGL only) bakes probe grids on the GPU; lightmaps can be baked offline. The cheap version bakes sky visibility per vertex at load. Decode packed values per vertex, never after interpolation. Hemisphere fill, environment maps and ambient occlusion alone are not global illumination, and calling them that is a false claim.
|
|
115
|
+
- **Reference configuration:** SR bakes single-bounce irradiance into a per-vertex atlas for static geometry and nine-coefficient SH probes for actors, validated against a signature of the world so a stale bake refuses to load. OS bakes sky visibility at load (7 rays per vertex, in a spare vertex channel) plus bounce through doorways: 40 to 125 ms once and nothing per frame, and it answered "interiors lit like the yard" on 15 of 17 maps; decoding after interpolation banded every wall. OS desaturates occluded indirect light, not albedo.
|
|
116
|
+
- **Applies when:** Any game that wants depth from light, most of all interiors and mixed indoor and outdoor spaces. A flat style chosen in the look page may skip it.
|
|
59
117
|
- **Verify:** Isolate the indirect term in a debug view: it varies across the level and is darker in enclosed spaces. Keep the bake source and confirm the shipped data matches the shipped geometry.
|
|
60
118
|
|
|
61
119
|
### Emissive is not a light
|
|
62
|
-
- **Invariant:** Anything that looks like it lights its surroundings does light them, through a real light in the pool or a baked contribution.
|
|
63
|
-
- **Technique:** Pair each practical (lamp, screen, fire, sign) with a pooled source or a baked contribution. Flicker a practical on three detuned sines and drive its emissive from the same value so the bulb and the light agree.
|
|
64
|
-
- **Reference configuration:** DK's practicals (hanging lamps, wall lamps, fluorescents, emergency domes, fires) are driven per frame with their emissive following the light.
|
|
120
|
+
- **Invariant:** Anything that looks like it lights its surroundings does light them, through a real light in the pool or a baked contribution, and its light reaches the surfaces it should.
|
|
121
|
+
- **Technique:** Pair each practical (lamp, screen, fire, sign) with a pooled source or a baked contribution. Flicker a practical on three detuned sines and drive its emissive from the same value so the bulb and the light agree. Size each lamp's range from its hang height, because a light whose range ends before the floor looks the same at any intensity.
|
|
122
|
+
- **Reference configuration:** DK's practicals (hanging lamps, wall lamps, fluorescents, emergency domes, fires) are driven per frame with their emissive following the light. OS: 64 lamps looked identical from intensity 3 to 52,000 because "The engine's light fades to exactly zero at its radius"; a range of 1.8 times the hang height keeps about 82% at the floor. LC's lamps are inverse-square at 400 cd, a pool about 8 m across.
|
|
65
123
|
- **Applies when:** Any scene with visible light sources.
|
|
66
124
|
- **Verify:** Turn a practical's light off in a debug build: the surfaces near it change, not just the bulb.
|
|
67
125
|
|
|
68
|
-
### Nothing on the camera lights the world
|
|
69
|
-
- **Invariant:** No light attached to the camera or the player's view model reaches the world pass.
|
|
70
|
-
- **Technique:** Put view-model lights on the view model's own layer and pass. A camera-parented light moving at player speed defeats shadows, pools and every measurement of the rig.
|
|
71
|
-
- **Reference configuration:** DK's weapon rig carries a fill light parented to the camera on its own layer, a key 1.34 and a cool rim 0.44 for the weapon only; its pool measurements exclude that fill as a source that really moves. OC moved its fill lights near the hands away and lower and halved them, instead of dimming the scene. OC's third-person muzzle light is about 0.12 of the first-person one, 30 cm ahead of the gun.
|
|
72
|
-
- **Applies when:** First-person games and any game with a view model.
|
|
73
|
-
- **Verify:** List lights at runtime with their parent chain and layers; none under the camera is on the world layer.
|
|
74
|
-
|
|
75
126
|
### Environment for reflections
|
|
76
127
|
- **Invariant:** Reflective materials reflect something real: the sky, or a probe of the place.
|
|
77
128
|
- **Technique:** A PMREM of the sky in `scene.environment`, or a captured cube of the level, regenerated after a lost WebGL context. Where areas differ, give each its own environment, and set reflection strength per material class (`envMapIntensity` in three.js).
|
|
78
|
-
- **Reference configuration:** DK bakes its procedural sky into a 256 PMREM; SR captures a 128 cube. OC's titan chain links at metallic 0.7 mirrored the night sky and went black, and iron without a metal flag read as grey cloth.
|
|
129
|
+
- **Reference configuration:** DK bakes its procedural sky into a 256 PMREM; SR captures a 128 cube. OC's titan chain links at metallic 0.7 mirrored the night sky and went black, and iron without a metal flag read as grey cloth. LC's open mud was "a black mirror of a dark sky" over three quarters of it.
|
|
79
130
|
- **Applies when:** PBR looks with any metal or gloss.
|
|
80
131
|
- **Verify:** Capture a metal surface while turning: its highlight and reflection move with the view and match the sky.
|
|
81
132
|
|
|
82
133
|
### Effects take the scene's light
|
|
83
134
|
- **Invariant:** Particles, smoke, blood, rain and other effects are lit by the place they are in, unless they emit light themselves.
|
|
84
135
|
- **Technique:** Turn effect lighting on explicitly, since many particle systems ship unlit, or feed the scene's ambient and nearest light colour into the effect shader. In three.js `SpriteMaterial` and `PointsMaterial` ignore lights: draw lit effects as instanced quads with `MeshLambertMaterial` or `MeshStandardMaterial`, or pass a light colour uniform sampled from a `LightProbe` or the light pool.
|
|
85
|
-
- **Reference configuration:** OC's particles were unlit by default, so its blood read "salmon pink" in 3 reports and was never fixed.
|
|
136
|
+
- **Reference configuration:** OC's particles were unlit by default, so its blood read "salmon pink" in 3 reports and was never fixed. LC lights each rain streak's ends by the torch's profile, the flashes, the lamps, the lightning and one shadow-map texel, for 0.15 ms of GPU.
|
|
86
137
|
- **Applies when:** Any lit 3D look with particles. Emissive effects (sparks, muzzle flash, magic) stay unlit on purpose.
|
|
87
138
|
- **Verify:** Fire the same effect in a fire-lit spot and in shadow: its brightness and tint follow the location.
|
|
88
139
|
|
|
89
140
|
### One owner for exposure, one rig per screen
|
|
90
141
|
- **Invariant:** One person or agent owns exposure and light intensity, every change is made against the merged build, and each screen (arena, menu, results) has its own rig.
|
|
91
|
-
- **Technique:** Keep light rigs in a table per screen in the look
|
|
92
|
-
- **Reference configuration:** OC's arena boosts leaked onto menu figures and gave them a foil look. Two streams' brightening would have stacked to 2.55 times. A 300,000 rifle light caused the defect agents were chasing, and light powers were "a guess". Lightning is clamped and runs at 25% in cinematics.
|
|
142
|
+
- **Technique:** Keep light rigs in a table per screen in the look page. Make brightness changes relative to the current merged values, not on top of another stream's unmerged boost, and attach a capture to each change. A change that lowers, darkens or brightens anything gets a check from the player's view before it ships, since each one tends to cause the next note.
|
|
143
|
+
- **Reference configuration:** OC's arena boosts leaked onto menu figures and gave them a foil look. Two streams' brightening would have stacked to 2.55 times. A 300,000 rifle light caused the defect agents were chasing, and light powers were "a guess". Lightning is clamped and runs at 25% in cinematics. LC's darker night made indoors unplayable, and its brighter gloves turned one "paper-white"; OS's maps without presets inherited another screen's light.
|
|
93
144
|
- **Applies when:** Any game where several people or agents touch the look.
|
|
94
145
|
- **Verify:** Diff light values between merged main and each pending change; each screen's capture matches its rig table.
|
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# opengame-loading changelog
|
|
2
2
|
|
|
3
|
+
## 1.1.0
|
|
4
|
+
|
|
5
|
+
New rules for a first frame that needs no fetch (OH), cold visits measured with an empty driver shader cache and fewer request waves (OS), a menu that answers the moment it shows (LC), the lobby as the loading screen (OS) and textures decoded off the main thread and shipped by role (LC). The count now reads 100 only when play can start, budgets only fall, and a new helper, `loading-count.mjs`, does the counting.
|
|
6
|
+
|
|
3
7
|
## 1.0.0
|
|
4
8
|
|
|
5
9
|
First public release, in the opengamehq/opengame repository and the OpenGame CLI.
|
|
@@ -1,46 +1,65 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: opengame-loading
|
|
3
|
-
description: Get a browser game from link to playable fast,
|
|
3
|
+
description: Get a browser game from link to playable fast, with a near-instant second visit. Covers a first frame that needs no fetch, one loading screen before a menu that means ready, cold visits measured with empty caches, request waves before bytes, budgets that only fall, hashed caching, retries and stall deadlines, a count that reads 100 only at play, the lobby as the loading screen, and textures decoded off the main thread. Use when loading is slow, the bar sticks, or a menu or return visit is slow.
|
|
4
4
|
metadata:
|
|
5
|
-
version: "1.
|
|
5
|
+
version: "1.1.0"
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Loading
|
|
9
9
|
|
|
10
10
|
A player decides whether to stay before the game has finished downloading. They need a
|
|
11
|
-
working title screen with sound in a second or two, an honest
|
|
12
|
-
streams behind it,
|
|
13
|
-
returning player should download nothing. OC (OG
|
|
14
|
-
times and reached its 15 s target only for returning
|
|
15
|
-
|
|
11
|
+
working title screen with sound in a second or two, an honest count while the world
|
|
12
|
+
streams behind it, a menu that answers the moment it shows, and nothing on screen that
|
|
13
|
+
is a stand-in for the real thing. A returning player should download nothing. OC (OG
|
|
14
|
+
Clash) asked for load speed about 12 times and reached its 15 s target only for returning
|
|
15
|
+
players. OS measured a fast boot that turned out to be warm, LC tested first visits on a
|
|
16
|
+
fast line while its owner played over a real one, and LC found that the wait was the
|
|
17
|
+
main thread more than the megabytes, so the first rules here are the ones that move a
|
|
18
|
+
first visit most.
|
|
16
19
|
|
|
17
20
|
Rules carry five tags; `opengame-quality-bar` explains them and the game codes. Three.js
|
|
18
21
|
loaders, compression, Vite and service-worker detail is in
|
|
19
|
-
[references/threejs.md](references/threejs.md).
|
|
20
|
-
|
|
22
|
+
[references/threejs.md](references/threejs.md). An honest count, weighted by the last
|
|
23
|
+
visit's timings, is in [helpers/loading-count.mjs](helpers/loading-count.mjs). Frame-time
|
|
24
|
+
cost of loading belongs to `opengame-performance`; phone memory and texture caps to
|
|
25
|
+
`opengame-mobile`; the visible bar and the press that starts play to `opengame-front-end`.
|
|
21
26
|
|
|
22
27
|
## Rules
|
|
23
28
|
|
|
24
|
-
### The title comes first and the
|
|
25
|
-
- **Invariant:** The first screen a player sees is interactive over key art before the world has downloaded, and
|
|
26
|
-
- **Technique:** Split the download into tiers. The boot tier holds the shell, the key art, the title UI, its music and the input that unlocks audio. The next tier holds what the player will use first (their character, the equipped loadout, the spawn area). The rest loads by need. Draw the title from a still or a light scene, and swap in the live scene only once it is fully ready. Compile shaders behind the menus, not after Play.
|
|
27
|
-
- **Reference configuration:** OC's targets: key art on frame one, press-start under 1 s, title under 2 s on a first visit and under 1 s after. OC's 3D title needed the arena (135 MB) and the boss (15 MB) before it could show, and a key-art title estimated at "15x faster first load" was deferred as a 1-2 day build. Loading the arena behind the menus made Play take 0.12-0.15 s.
|
|
29
|
+
### The title comes first, one boot loading screen comes before the menu, and the menu means ready
|
|
30
|
+
- **Invariant:** The first screen a player sees is interactive over key art before the world has downloaded, boot has one loading screen and it comes before the menu, and once the menu shows, starting play answers at once with no second wait.
|
|
31
|
+
- **Technique:** Split the download into tiers. The boot tier holds the shell, the key art, the title UI, its music and the input that unlocks audio. The next tier holds what the player will use first (their character, the equipped loadout, the spawn area). The rest loads by need, behind the menu and behind play. The menu waits for each system's first-ready set (what the title and a run's first minute draw), not for everything. Draw the title from a still or a light scene, and swap in the live scene only once it is fully ready. Compile shaders behind the loading screen and menus, not after Play. In a match-based game with many maps, the lobby and countdown are the chosen map's loading screen (the lobby rule below).
|
|
32
|
+
- **Reference configuration:** OC's targets: key art on frame one, press-start under 1 s, title under 2 s on a first visit and under 1 s after. OC's 3D title needed the arena (135 MB) and the boss (15 MB) before it could show, and a key-art title estimated at "15x faster first load" was deferred as a 1-2 day build. Loading the arena behind the menus made Play take 0.12-0.15 s. LC's owner: "we jshould just have the lading screen before the main menu... and then main menua nd hitting new run automatically starts game.. no more loading... and optimzie the fuck out of load time so its super fucking fast". LC's title now shows in about 1.0 s with 4.4 MB fetched (it had been 6-7 s and 82.7 MB), the menu waits for each stream's first-ready set, and New run reaches the first frame in 12-23 ms; its 8 s menu at 50 Mbit was never met (15-24 s). OS's owner: "everything nedes to load in under 3s p95 ... (1-2s ideally)" and "how do we get boot to title to a mere seconds? 14s is very high"; it was never met, with boot at 10-14 s and a 22.8 s median from map pick to control.
|
|
28
33
|
- **Applies when:** Every game whose world is larger than a few megabytes.
|
|
29
|
-
- **Verify:** On a cold cache at the stated bandwidth, record time and bytes to an interactive title, then press Play as soon as
|
|
34
|
+
- **Verify:** On a cold cache at the stated bandwidth, record time and bytes to an interactive title, then press Play as soon as the menu shows and record the wait to the first frame of play.
|
|
35
|
+
|
|
36
|
+
### The first frame is the game's own picture and needs no fetch
|
|
37
|
+
- **Invariant:** The first frame the browser paints shows the game's own picture and type, without waiting on any request, and the scene arrives after it at an even pace.
|
|
38
|
+
- **Technique:** Inline a tiny blurred still (or a CSS rendering of the first frame) and the title font into the entry document, so first paint needs nothing from the network; swap the full key art and the live content in as they arrive. Publish a first-play budget: requests and bytes to the title, and to the first moment of play. Keep hashed assets immutable and lists revalidated (see the caching rule).
|
|
39
|
+
- **Reference configuration:** OH's bare paper showed for 2.9 s before its first picture, 7.3 s at 400 KB/s; a CSS still made the first painted frame instant (0.0 s, 0.1 s at 400 KB/s). Its place paints in 2.2-6 s; the title takes 11 requests and 2.00 MB, and the first note of a linked song 19 requests and 6.86 MB. LC inlines a 19 KB font and a 594 B blurred still.
|
|
40
|
+
- **Applies when:** Any game whose scene needs seconds to build.
|
|
41
|
+
- **Verify:** Film the page from navigation at 10 fps on a throttled link and measure saturation per frame: no blank frame after the first paint. Count bytes and requests to the title at the server, not only in the browser.
|
|
42
|
+
|
|
43
|
+
### Cold first visits are fast: few request waves and parallel compiles, measured with empty caches
|
|
44
|
+
- **Invariant:** A first-time player reaches the title in seconds, every cold number is measured with an empty browser cache and an empty GPU driver shader cache, and no frame the player sees waits on a compile.
|
|
45
|
+
- **Technique:** For each cold run, use a fresh browser profile and point the driver's shader disk cache at a new empty directory, because that cache lives outside the browser profile. Compile boot pipelines in parallel (asynchronous pipeline creation for all of them at once, never one after another), and prewarm heavy variants behind the title, keyed per device and renderer profile. Cut requests before bytes: keep a ledger of which code asks for each file, pack small files into boot packs fetched as the engine starts, and rebuild the boot list from a measured cold boot on every release. When the engine fetches from workers, shape the link at a proxy or the server, because browser network throttling may not reach worker fetches. Time the main thread too: shader graph builds and CPU work can be the whole wait.
|
|
46
|
+
- **Reference configuration:** OS's "fresh profile" boot of 5-9 s was warm; truly cold it took 45.6 s, with weapon shaders compiling one after another at 15-18 s each, and compiling them in parallel took it from 42 to 23 s. A prewarm keyed per device and renderer profile cut OS's cold title from 53.2 to 19.9 s. A who-asks ledger took OS's pre-title set from 152 MB in 1,842 requests to 5.40 MB in 180; packs took boot network time from 12-14 s to 8.7 s, and a stale boot list cost 27.2 s against 3.2 s for one rebuilt from a measured cold boot. On OS's link, 22.5 MB arrived in 8-10 s while 80 MB in more files took 12.5-18.7 s: requests, not bytes. OS found that browser throttling skipped its engine's worker fetches. LC: "The wait is the main thread, not the megabytes"; a cached return visit was as slow as a first (11-17 s), and cutting 59 to 39 MB barely moved it.
|
|
47
|
+
- **Applies when:** WebGPU or WebGL games with compiled pipelines, and any game that streams many files.
|
|
48
|
+
- **Verify:** Back-to-back cold and warm boots, each cold one with a fresh profile and an empty driver cache, print seconds to title for both. A request replay on each release prints requests, bytes and seconds.
|
|
30
49
|
|
|
31
50
|
### Ship what the runtime requests, listed in a manifest
|
|
32
51
|
- **Invariant:** The deployed build contains only files the game requests, and a manifest generated from real runs lists each one with its size and the tier that needs it.
|
|
33
|
-
- **Technique:** Log every request during scripted runs through every screen, mode, weapon and device class. Diff the log against the build folder, move unrequested files out, and fail the build when a large file has no entry. Keep a tier and a device class on each manifest entry, and gate the size of each tier.
|
|
34
|
-
- **Reference configuration:** OC's build folder grew to about 6.3 GB in 25,600 files, "mostly files the game never loads"; its deploy worker logged real requests to prune it, and the CDN set came to 3.07 GB. Boot loads grew from 225 MB in 590 files to 833 MB in 6,124 files over a few days, and models from 222 to 490 MB over R74-R77, with no gate to stop them.
|
|
52
|
+
- **Technique:** Log every request during scripted runs through every screen, mode, weapon and device class. Diff the log against the build folder, move unrequested files out, and fail the build when a large file has no entry. Keep a tier and a device class on each manifest entry, and gate the size of each tier. Generate the preload list from a boot with preloading off, so the build writes it rather than a person, and have every capture check it.
|
|
53
|
+
- **Reference configuration:** OC's build folder grew to about 6.3 GB in 25,600 files, "mostly files the game never loads"; its deploy worker logged real requests to prune it, and the CDN set came to 3.07 GB. Boot loads grew from 225 MB in 590 files to 833 MB in 6,124 files over a few days, and models from 222 to 490 MB over R74-R77, with no gate to stop them. LC's hand-kept preload list went stale three times in a day and cost about 12 MB, until it was generated from a boot with preloading off.
|
|
35
54
|
- **Applies when:** Every game with a build step or an asset pipeline. It matters most when an exporter writes every asset in the project.
|
|
36
55
|
- **Verify:** A full scripted run requests every manifest entry, and the build folder holds nothing outside the manifest.
|
|
37
56
|
|
|
38
|
-
### Bytes before the
|
|
39
|
-
- **Invariant:** The bytes needed before the title and the time they take on a named connection are written budgets
|
|
40
|
-
- **Technique:** State the target as time at a bandwidth, convert it to bytes, and gate each build on the bytes
|
|
41
|
-
- **Reference configuration:** OC's target was 15 s or less at 25 Mbps, which is about 47 MB at roughly 3.1 MB/s. Before the title it sent 309 MB in 1,788 files; 291-304 MB took 119.6-123.2 s at 25 Mbps. Compression took that to 181 MB (R164), still about 58 s.
|
|
57
|
+
### Bytes before the menu have a budget at a stated bandwidth, and the budget only moves down
|
|
58
|
+
- **Invariant:** The bytes needed before the title and the menu, and the time they take on a named connection, are written budgets measured on every build with a cold cache and a throttled network, and no system's share grows without a named decision.
|
|
59
|
+
- **Technique:** State the target as time at a bandwidth, convert it to bytes, and gate each build on the bytes each tier actually transfers. Measure with network throttling in a real browser rather than on localhost at full speed, and record the transfer size the browser reports. Keep a record per system that only moves down: each boot records its megabytes before the menu, fails on growth past a small margin, lowers the figure automatically, and raises it only by name from an unflagged boot. Hold each menu code chunk to a fixed compressed byte count, measured on the old and new trees in the same minute, and pay for new bytes by deleting retired flags or moving code into chunks loaded later. Find bytes by source with the source map before trimming by hand.
|
|
60
|
+
- **Reference configuration:** OC's target was 15 s or less at 25 Mbps, which is about 47 MB at roughly 3.1 MB/s. Before the title it sent 309 MB in 1,788 files; 291-304 MB took 119.6-123.2 s at 25 Mbps. Compression took that to 181 MB (R164), still about 58 s. LC fails a boot at 3% plus 0.15 MB over a system's record; before the menu LC went from 121.5 MB to 29.66 MB, then to 35.7 MB after multiplayer and new finishes, against a 25 MB target. LC's weapons menu chunk is fixed at 137,501 gzip bytes; raw bytes can fall while compressed bytes rise; rounding 17-digit floats in one JSON register saved 7,711 bytes, and a source map found one misplaced 16,737-byte file after 40 minutes of trims had found 306 bytes.
|
|
42
61
|
- **Applies when:** Every web game. Pick the bandwidth with the owner; a phone on mobile data is slower than a desk.
|
|
43
|
-
- **Verify:** A cold-cache run under the stated throttle prints bytes transferred and seconds to an interactive title, and fails above budget.
|
|
62
|
+
- **Verify:** A cold-cache run under the stated throttle prints bytes transferred and seconds to an interactive title and menu, and fails above budget. A boot that adds a megabyte to one system fails, and the commit message carries the before and after figures.
|
|
44
63
|
|
|
45
64
|
### Every file is precompressed and typed
|
|
46
65
|
- **Invariant:** Every compressible file is served precompressed with the right `Content-Type` and `Content-Encoding`, the server picks the encoding from `Accept-Encoding`, and nothing is compressed twice.
|
|
@@ -50,32 +69,53 @@ loaders, compression, Vite and service-worker detail is in
|
|
|
50
69
|
- **Verify:** For one file of each type, request it with `Accept-Encoding: br, gzip` and read the response headers; in the network log, the transfer size of each text, wasm and model file is well under its resource size.
|
|
51
70
|
|
|
52
71
|
### Hashed names and long-lived caching
|
|
53
|
-
- **Invariant:** A returning player on an unchanged build downloads only the small entry document,
|
|
54
|
-
- **Technique:** Put a content hash in every asset's file name. Serve hashed files as `Cache-Control: public, max-age=31536000, immutable`, and the entry document as `no-cache` with an ETag. Avoid per-build path prefixes, which change every URL on every deploy. A service worker that keeps hashed files in Cache Storage helps where the HTTP cache is evicted.
|
|
55
|
-
- **Reference configuration:** OC's content-hash cache (R193) took a returning player from 150 s to 14.7 s. Before it, per-build paths made every deploy a full download. An earlier server rewrite took repeat visits from 714 MB to 5.1 MB.
|
|
72
|
+
- **Invariant:** A returning player on an unchanged build downloads only the small entry document, after a deploy downloads only the files that changed, and a page that booted on one build never mixes in files from the next.
|
|
73
|
+
- **Technique:** Put a content hash in every asset's file name. Serve hashed files as `Cache-Control: public, max-age=31536000, immutable`, and the entry document as `no-cache` with an ETag. Avoid per-build path prefixes, which change every URL on every deploy. Keep the previous build's hashed files on the host for some hours after a deploy and switch the entry document atomically, so a page booting across a swap still finds its files. A service worker that keeps hashed files in Cache Storage helps where the HTTP cache is evicted.
|
|
74
|
+
- **Reference configuration:** OC's content-hash cache (R193) took a returning player from 150 s to 14.7 s. Before it, per-build paths made every deploy a full download. An earlier server rewrite took repeat visits from 714 MB to 5.1 MB. LC's return visit went from 825 requests to 9; pages that booted across a preview swap had 404'd and drew an old model all session, so LC keeps the previous build's files for 3 hours. OS once served 79 newer-build files to an old page; with each publish under its own stamped path, 3,568 of 3,568 requests matched the page's build.
|
|
56
75
|
- **Applies when:** Every game that is played more than once or deployed more than once.
|
|
57
|
-
- **Verify:** Load, close, load again: the second load transfers only the entry document. Change one asset, deploy, reload: only that file and the entry document transfer.
|
|
76
|
+
- **Verify:** Load, close, load again: the second load transfers only the entry document. Change one asset, deploy, reload: only that file and the entry document transfer. Deploy while a page is mid-boot: it finishes on its own build.
|
|
58
77
|
|
|
59
78
|
### Fetches retry, and a stalled load is caught by a byte deadline
|
|
60
79
|
- **Invariant:** Every fetch can time out and retry, a load that stops receiving bytes is detected and reported, a slow load that is still receiving bytes continues, and a failed load ends on a retry button rather than an automatic page reload.
|
|
61
|
-
- **Technique:** Wrap every fetch with an idle timeout reset on each chunk received, retries with backoff and jitter, and a size or hash check on the result. Tell slow from stalled by bytes over time. Show a "slow connection" notice after a stretch with no bytes, keep retrying, and give up only after a long deadline with a button to try again. Cap concurrent requests. Check that a wrapper keeps the platform's own checks, such as range-response handling.
|
|
62
|
-
- **Reference configuration:** OC's runtime never retried a failed file, so a load waited on it forever, stuck at 97% (fixed R185). An earlier loader sat at 2% for 74 s after 244 failed requests with no timeout or error path. The page-side guard took 5 revisions over about 2 h, because a first wrapper bypassed range-response checks, and a later version's give-up turned into an "arena stalled" crash. The settings that shipped: the notice only after 20 s with zero bytes, retry with backoff while bytes arrive, and phone requests capped from 128 at a time to 24.
|
|
80
|
+
- **Technique:** Wrap every fetch with an idle timeout reset on each chunk received, retries with backoff and jitter, and a size or hash check on the result. Tell slow from stalled by bytes over time. Show a "slow connection" notice after a stretch with no bytes, keep retrying, and give up only after a long deadline with a button to try again. Cap concurrent requests, and measure the cap against an uncapped cold boot, since a cap can be the stall. Check that a wrapper keeps the platform's own checks, such as range-response handling.
|
|
81
|
+
- **Reference configuration:** OC's runtime never retried a failed file, so a load waited on it forever, stuck at 97% (fixed R185). An earlier loader sat at 2% for 74 s after 244 failed requests with no timeout or error path. The page-side guard took 5 revisions over about 2 h, because a first wrapper bypassed range-response checks, and a later version's give-up turned into an "arena stalled" crash. The settings that shipped: the notice only after 20 s with zero bytes, retry with backoff while bytes arrive, and phone requests capped from 128 at a time to 24. OS's cap of 16 reads slowed one load from 5.7 to 24 s ("The biggest recovery and load-time lever is one I caused"). A stall watchdog that frees what a failed load reserved is in `opengame-stability`.
|
|
63
82
|
- **Applies when:** Every game that fetches assets after the first document.
|
|
64
83
|
- **Verify:** Fail one asset's first three requests (Playwright `page.route` aborting them): the load completes. Fail it every time: the notice appears, the page does not reload, and the error names the file. Throttle to a slow but steady link: no notice.
|
|
65
84
|
|
|
66
|
-
###
|
|
67
|
-
- **Invariant:** The
|
|
68
|
-
- **Technique:** Take each file's size from the manifest, count bytes as response chunks arrive, and give shader compiles, environment maps and scene builds their own weights. Advance the shown number toward the true one at a capped rate so it moves in small steps. Hide the
|
|
69
|
-
- **Reference configuration:** OC's bar stuck at 60% and jumped to 100% ("Baking light" was hard-coded at 60% for about 8 s of work), and stuck at 97% for 20 s before a reload. Fixed, it climbs 1% at a time, holds no number for more than about 0.75 s (0.68-0.73 s measured) and shows only after 0.6 s. A shader warm-up curtain had added 2.5 s of blank screen. The owner asked 3 times.
|
|
85
|
+
### The count reads 100 only when play can start, and never goes back
|
|
86
|
+
- **Invariant:** The loading count follows bytes received plus weighted non-network work, climbs in small even steps, never goes backward or stands still for long, and reaches 100 only when a run can start; any time-left estimate shown has proved itself accurate.
|
|
87
|
+
- **Technique:** Take each file's size from the manifest, count bytes as response chunks arrive, and give shader compiles, environment maps and scene builds their own weights. On a return visit, weight each stage by the seconds it took last time, since time is what the player waits through. Count to the moment play can start, not to the title. Advance the shown number toward the true one at a capped rate so it moves in small steps, and drive it with compositor-only transforms so it keeps moving while shaders compile. Split any stage that holds the number still. Show a time-left estimate only if it held close through whole boots in testing. Hide the count on loads short enough to finish before it would be read. [helpers/loading-count.mjs](helpers/loading-count.mjs) does the counting and reports the longest hold.
|
|
88
|
+
- **Reference configuration:** OC's bar stuck at 60% and jumped to 100% ("Baking light" was hard-coded at 60% for about 8 s of work), and stuck at 97% for 20 s before a reload. Fixed, it climbs 1% at a time, holds no number for more than about 0.75 s (0.68-0.73 s measured) and shows only after 0.6 s. A shader warm-up curtain had added 2.5 s of blank screen. The owner asked 3 times. LC's first count read 91% at 0.8 s with play 17-21 s away; weighted by the last visit and counted to play, it reached 100% at 22.1 s with play ready at 21.8 s, rising at most 30 points a second and standing no more than about 1.5-2 s. LC's time-left estimate was 2.8-10.3 s off and was turned off. OS's count hung at 22% on a hard-coded 0.22, first "fixed" with a moving band that measured nothing.
|
|
70
89
|
- **Applies when:** Every load the player waits through, first boot and match entry alike.
|
|
71
|
-
- **Verify:** Under the stated throttle with a load of 8 s or more,
|
|
90
|
+
- **Verify:** Under the stated throttle with a load of 8 s or more, film the count and read it from the pixels every frame: it only rises, holds no value past the cap, and reaches 100 within a frame of play accepting input. The helper's `longestHold()` stays under the cap.
|
|
91
|
+
|
|
92
|
+
### The menu answers the moment it shows
|
|
93
|
+
- **Invariant:** When the menu appears, every row opens its page at once, nothing hidden is still uploading, and the GPU has caught up, so a press on the menu is answered in the same moment.
|
|
94
|
+
- **Technique:** Request the menu pages' code chunk when the interface is built, before any world asset, because fetches at the same priority are served first come first served and script cannot be raised above high. Upload nothing hidden before the menu: an engine that builds a geometry's buffers on its first draw will build every hidden mesh in one frame of a warm-up, so trickle them nearest-first in small batches as the GPU answers. Show the menu after the GPU has finished its submitted work (`device.queue.onSubmittedWorkDone()` in WebGPU), with a cap. If a page's code is still late, open its frame at once and fill it on arrival. Find idle stretches of the network line and fill them.
|
|
95
|
+
- **Reference configuration:** LC's owner: "buttons are unresponsive on main menu ... and they take like 10s after i hit button for it to open the pag?". The menu pages' 21 KB script was queued behind 170 MB of world fetches; requested when the interface was built, Settings opened in 0.10 s at 5 Mbit instead of 23.0 s, and a late page opens its frame ("OPENING") in 26 ms. LC's 346 hidden litter meshes made 72-134 MB of buffers in one second before the menu; trickled, the menu's wait on a busy card went from 15.7 s to 0.28 s. Showing the menu only after the GPU drained (capped at 12 s) took Enter to a fresh frame from 4.2-9.9 s to 0.54-0.86 s, at a cost of 0.35 s on a quiet card and 1.7-9.6 s on a shared one. At 5 Mbit, 12-13 s of LC's boot had nothing on the line.
|
|
96
|
+
- **Applies when:** Every web game that streams after the first screen.
|
|
97
|
+
- **Verify:** On a cold boot at a slow link, click every menu row by a real pointer at 1, 3, 6 and 12 s after it appears: each page opens at once. The network log shows the menu chunk before the first world asset.
|
|
72
98
|
|
|
73
99
|
### What the player sees first is loaded first, and never as a stand-in
|
|
74
|
-
- **Invariant:** The equipped weapon, the player's own character and their sounds load at top priority and are resident before the screen that shows them
|
|
75
|
-
- **Technique:** Run fetches through a
|
|
76
|
-
- **Reference configuration:** OC's runtime had no priority control, so request order was the only control it had. Weapons the player was given arrived 2.5-7 s late (about 40 s for the heaviest) as mitten hands or black shapes, which spoiled captures in 3 streams and caused a false regression. One lazy-load change put low-poly guns in 6 places; the owner: "dont show the low poly versions anywhere anytime for any weapon anywhere in the game". Gun sounds were silent for 11-16 s, queued behind 35 MB of audio banks.
|
|
100
|
+
- **Invariant:** The equipped weapon, the player's own character and their sounds load at top priority and are resident before the screen that shows them, so no partial, mixed or generic stand-in and no empty hand appears; a complete light copy shows only where `opengame-weapons` allows one, and anything else late shows the previous complete asset or a designed loading state.
|
|
101
|
+
- **Technique:** Run fetches through a ranked queue with a few files in flight (measured against an uncapped boot), and order requests by need. Request the chosen loadout from the title as soon as it is chosen, and after the press that starts play let nothing else start while those files fly. Gate screens, purchases and pickups on the asset being ready. Load the equipped weapon's sounds with its model. Keep the old complete model on screen until the new one is fully ready. Stream variety by seconds of play, one texture per task with idle time after it.
|
|
102
|
+
- **Reference configuration:** OC's runtime had no priority control, so request order was the only control it had. Weapons the player was given arrived 2.5-7 s late (about 40 s for the heaviest) as mitten hands or black shapes, which spoiled captures in 3 streams and caused a false regression. One lazy-load change put low-poly guns in 6 places; the owner: "dont show the low poly versions anywhere anytime for any weapon anywhere in the game". Gun sounds were silent for 11-16 s, queued behind 35 MB of audio banks. LC keeps at most 4 files in flight (8 in a run); asking for the chosen weapons from the title took Enter to play at 5 Mbit from 3.99-5.32 s to 0.49-0.65 s. OS's rival models waited over 20 s behind a queue full of audio, and backpressure brought 31 posed rivals from 24.4 s to 2.0 s. OS's owner met the opposite failure: "we cant have a situatoinw here not all the gun models load..."; its weapon cards now wait and fade in together (10-25 s became 0.1-0.24 s), and the trade between a complete light model and bare hands is in `opengame-weapons`.
|
|
77
103
|
- **Applies when:** Every game with a loadout, a character select or items that appear mid-game.
|
|
78
|
-
- **Verify:** On a cold cache under throttle, go straight to play and fire: the first frame of the weapon is the full model and the first shot is heard. Capture every path that hands over an item.
|
|
104
|
+
- **Verify:** On a cold cache under throttle, go straight to play and fire: the first frame of the weapon is the full model and the first shot is heard. Capture every path that hands over an item. The network log shows the loadout first.
|
|
105
|
+
|
|
106
|
+
### The lobby is the loading screen: count down only on a shown map, and fetch nothing in play
|
|
107
|
+
- **Invariant:** In a match-based game, the chosen map streams and compiles during the lobby and countdown, the countdown starts only on a fully shown map and runs straight into play, and the first minute of play downloads nothing new.
|
|
108
|
+
- **Technique:** One "shown" gate: the build is done, spawns are validated, pipelines have been ready for two frames, no reads are in flight, and textures are on the GPU. Only after the map is shown, warm the sets the first match draws (killstreak art, rivals' weapons) during the countdown. Slice map building into resumable jobs with a per-frame time budget that guarantees at least one unit of progress a frame and has a hard cap.
|
|
109
|
+
- **Reference configuration:** OS's owner: "it says 10 seconds, then 5, 4 and then nothing happens and the game just keeps loading?...". Before the gate, one map showed props over a blue void; after it, ten maps were shown in 1.0-3.1 s. Downloads in the first 60 s of play went from 41.5 MB to 0.0-0.2 MB; warming at the reveal instead had stretched the hold from 21.3 to 41.7 s. A build budget of 6 ms a frame (4 ms on weak machines) took seen frames over 16.7 ms from 24 of 26 to none, and a split without guaranteed progress held the title for 671 s. OS's largest first-match download was 19.6 MB of streak art, now warmed in the countdown. This narrows AW's rule in `opengame-performance`: a countdown may warm, but only what the first match draws, and only once the map is shown.
|
|
110
|
+
- **Applies when:** Match-based games with lobbies or countdowns.
|
|
111
|
+
- **Verify:** A request log bucketed by phase from a fresh boot through the real lobby shows nothing in the first minute of play. On a throttled run, the countdown waits for the shown gate.
|
|
112
|
+
|
|
113
|
+
### Images decode off the main thread, and textures ship by role
|
|
114
|
+
- **Invariant:** No image decode or texture upload blocks a frame the player sees, and each texture's GPU format is chosen for its role by measurement, so the card holds what the frame draws and no more.
|
|
115
|
+
- **Technique:** Decode images with `fetch` and `createImageBitmap` (or `ImageBitmapLoader`), never through an `<img>` element on the main thread. Ship KTX2: ETC1S where colour is seen at a distance, UASTC for normal and data maps unless measurement says ETC1S is enough, and mips stored smallest first so a file's prefix is a smaller valid texture that can be fetched first and sharpened in place. Upload one large texture per task with idle time after it. The measuring is in `opengame-performance`; per-class texture caps for phones are in `opengame-mobile`.
|
|
116
|
+
- **Reference configuration:** LC's world textures on the card went from 800.7 MB to 172 MB with ETC1S colour and UASTC data; its in-browser encoder took about 100 s per 2048 map. Decoding through `<img>` had cost 2.5 s of main thread, and a 2048 upload is a 130-650 ms long task. LC's 88 first-set KTX2 files are 22.6 MB whole, 8.0 MB without the top level and 4.1 MB without two, and each prefix transcodes to exactly the bytes of the full file's smaller mips. AW measured ETC1S good enough for its normals at a sixth of UASTC's bytes.
|
|
117
|
+
- **Applies when:** Every textured game.
|
|
118
|
+
- **Verify:** A boot trace shows no image decode on the main thread and no upload task over the frame budget in play. KTX2 statistics list each texture's codec by role.
|
|
79
119
|
|
|
80
120
|
### Changing quality never reloads the page
|
|
81
121
|
- **Invariant:** Tier and pixel ratio change at runtime without navigation, and a capability probe's result is stored for the next visit instead of applied by reloading.
|
|
@@ -93,7 +133,7 @@ loaders, compression, Vite and service-worker detail is in
|
|
|
93
133
|
|
|
94
134
|
### A self-hosted build keeps code off the asset path
|
|
95
135
|
- **Invariant:** When the game is hosted outside a game platform, heavy assets come from a static host or CDN with no per-request code, with the headers the runtime needs and range requests where the runtime uses them.
|
|
96
|
-
- **Technique:** Put the page shell and the heavy assets on separate hosts if one host's limits are smaller than the game. Serve assets as plain static files. If the game uses threads (`SharedArrayBuffer`), send `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` on the page and `Cross-Origin-Resource-Policy` on the asset host. Check the served build after each deploy (see `opengame-stability`).
|
|
97
|
-
- **Reference configuration:** OC split a 106 MB page shell from 3.07 GB of assets on a CDN under per-build paths. A worker function on every asset request billed about 5,000 requests per load.
|
|
136
|
+
- **Technique:** Put the page shell and the heavy assets on separate hosts if one host's limits are smaller than the game. Serve assets as plain static files under content-hash keys. If the game uses threads (`SharedArrayBuffer`), send `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` on the page and `Cross-Origin-Resource-Policy` on the asset host. Check the served build after each deploy (see `opengame-stability`).
|
|
137
|
+
- **Reference configuration:** OC split a 106 MB page shell from 3.07 GB of assets on a CDN under per-build paths. A worker function on every asset request billed about 5,000 requests per load. OS put its page on a static host and its assets in a public object bucket under keys of a 12-character content hash plus size, immutable and Brotli, with no code in front, and called a deploy done only when production showed 3,168 requests, 0 failed, 0 console errors and a running match.
|
|
98
138
|
- **Applies when:** Games deployed to your own hosting. On OpenGame, `opengame-deploy` covers packaging and the platform serves the files.
|
|
99
139
|
- **Verify:** One cold load's request log shows no function invocations for asset files, the isolation headers on the page and the asset responses, and `206` responses where the runtime sends `Range`.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A loading count that tells the truth. Copy this file into the game; it imports nothing
|
|
3
|
+
* and touches no page element. It turns the stages of a boot into one number that only
|
|
4
|
+
* rises, rises in small steps, never reads 100 until the game says play can start, and
|
|
5
|
+
* reports how long it ever stood still, so a stage that needs splitting is found by a
|
|
6
|
+
* number rather than by a player.
|
|
7
|
+
*
|
|
8
|
+
* import { createLoadingCount } from "./loading-count.mjs";
|
|
9
|
+
*
|
|
10
|
+
* const saved = JSON.parse(localStorage.getItem("boot-times") ?? "{}");
|
|
11
|
+
* const count = createLoadingCount({
|
|
12
|
+
* stages: [{ name: "shell", weight: 2e6 }, { name: "world", weight: 40e6 }, { name: "shaders", weight: 8e6 }],
|
|
13
|
+
* previous: saved, // last visit's seconds per stage, if any
|
|
14
|
+
* });
|
|
15
|
+
* count.report("world", bytesSoFar / worldBytes); // as chunks arrive
|
|
16
|
+
* count.begin("shaders"); // a stage with nothing to report until done
|
|
17
|
+
* count.report("shaders", 1);
|
|
18
|
+
* count.ready(); // only when a run can start
|
|
19
|
+
* const shown = count.step(dt); // each frame; draw this number
|
|
20
|
+
* localStorage.setItem("boot-times", JSON.stringify(count.durations()));
|
|
21
|
+
*
|
|
22
|
+
* Weights are bytes (or any cost) on a first visit. When the previous visit timed every
|
|
23
|
+
* stage, its seconds become the weights, because the wait a player sits through is time,
|
|
24
|
+
* and a compile that downloads nothing can be most of it.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
export function createLoadingCount({
|
|
28
|
+
stages,
|
|
29
|
+
previous = {},
|
|
30
|
+
maxRate = 30,
|
|
31
|
+
now = () => (typeof performance !== "undefined" ? performance.now() : Date.now()) / 1000,
|
|
32
|
+
} = {}) {
|
|
33
|
+
if (!Array.isArray(stages) || stages.length === 0) throw new Error("createLoadingCount needs at least one stage");
|
|
34
|
+
const timed = stages.every((stage) => Number(previous[stage.name]) > 0);
|
|
35
|
+
const weights = new Map(stages.map((stage) => [stage.name, Math.max(0, timed ? Number(previous[stage.name]) : Number(stage.weight ?? 1))]));
|
|
36
|
+
const total = [...weights.values()].reduce((sum, weight) => sum + weight, 0) || 1;
|
|
37
|
+
const fraction = new Map(stages.map((stage) => [stage.name, 0]));
|
|
38
|
+
const started = new Map();
|
|
39
|
+
const finished = new Map();
|
|
40
|
+
const created = now();
|
|
41
|
+
let isReady = false;
|
|
42
|
+
let shownExact = 0;
|
|
43
|
+
let shown = 0;
|
|
44
|
+
let still = 0;
|
|
45
|
+
let longest = 0;
|
|
46
|
+
|
|
47
|
+
function known(name) {
|
|
48
|
+
if (!fraction.has(name)) throw new Error(`unknown loading stage "${name}"`);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Start a stage's clock before it has progress to report (a compile, a scene build). */
|
|
52
|
+
function begin(name) {
|
|
53
|
+
known(name);
|
|
54
|
+
if (!started.has(name)) started.set(name, now());
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function report(name, value) {
|
|
58
|
+
known(name);
|
|
59
|
+
const clamped = Math.min(1, Math.max(0, Number(value) || 0));
|
|
60
|
+
if (!started.has(name)) {
|
|
61
|
+
// A stage whose first report is its completion did its work unseen. Time it from the
|
|
62
|
+
// last stage that finished before it (or from the start of the boot), never from
|
|
63
|
+
// now, or it would weigh nothing next visit and the count would stand still through it.
|
|
64
|
+
const before = [...finished.values()].reduce((latest, end) => Math.max(latest, end), created);
|
|
65
|
+
started.set(name, clamped >= 1 ? before : now());
|
|
66
|
+
}
|
|
67
|
+
// A stage never goes back: a retry that restarts a download keeps the count where it was.
|
|
68
|
+
if (clamped > fraction.get(name)) fraction.set(name, clamped);
|
|
69
|
+
if (fraction.get(name) >= 1 && !finished.has(name)) finished.set(name, now());
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** The true share of the work done, as a percentage; 99 at most until ready(). */
|
|
73
|
+
function truth() {
|
|
74
|
+
if (isReady) return 100;
|
|
75
|
+
let done = 0;
|
|
76
|
+
for (const [name, weight] of weights) done += weight * fraction.get(name);
|
|
77
|
+
return Math.min(99, (100 * done) / total);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Advance the shown number toward the truth by at most maxRate points a second. */
|
|
81
|
+
function step(dt) {
|
|
82
|
+
const seconds = Math.max(0, Number(dt) || 0);
|
|
83
|
+
const target = truth();
|
|
84
|
+
const before = shown;
|
|
85
|
+
if (shownExact < target) shownExact = Math.min(target, shownExact + maxRate * seconds);
|
|
86
|
+
shown = Math.max(shown, Math.floor(shownExact + 1e-9));
|
|
87
|
+
if (shown === before && !isReady) {
|
|
88
|
+
still += seconds;
|
|
89
|
+
longest = Math.max(longest, still);
|
|
90
|
+
} else {
|
|
91
|
+
still = 0;
|
|
92
|
+
}
|
|
93
|
+
return shown;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Seconds each finished stage took, to pass back as `previous` on the next visit. */
|
|
97
|
+
function durations() {
|
|
98
|
+
const out = {};
|
|
99
|
+
for (const [name, end] of finished) out[name] = Math.max(1e-3, end - started.get(name));
|
|
100
|
+
return out;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
return {
|
|
104
|
+
begin,
|
|
105
|
+
report,
|
|
106
|
+
ready() { isReady = true; },
|
|
107
|
+
truth,
|
|
108
|
+
step,
|
|
109
|
+
shown: () => shown,
|
|
110
|
+
durations,
|
|
111
|
+
/** The longest the shown number stood still before ready(), in seconds. */
|
|
112
|
+
longestHold: () => longest,
|
|
113
|
+
weightedBy: timed ? "previous visit" : "given weights",
|
|
114
|
+
};
|
|
115
|
+
}
|