@opengamehq/cli 0.0.0-stage → 0.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/AGENTS.md +238 -0
- package/CHANGELOG.md +22 -0
- package/README.md +129 -2
- package/dist/cli.mjs +1432 -0
- package/dist/opengame-global.js +49 -0
- package/dist/opengame-global.js.LEGAL.txt +1 -0
- package/dist/preflight-worker.mjs +20 -0
- package/dist/runtime-builder.mjs +800 -0
- package/dist/runtime-catalog.json +1 -0
- package/dist/runtime-catalog.sha256 +1 -0
- package/dist/runtime-shells/runtime-shell.html +4 -0
- package/dist/runtime-shells/runtime-shell.js +91 -0
- package/dist/safe-fs.py +242 -0
- package/dist/skills/manifest.json +516 -0
- package/dist/skills/opengame-accessibility/SKILL.md +90 -0
- package/dist/skills/opengame-api/SKILL.md +85 -0
- package/dist/skills/opengame-assets/SKILL.md +124 -0
- package/dist/skills/opengame-assets/references/pipeline.md +97 -0
- package/dist/skills/opengame-audio/SKILL.md +154 -0
- package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
- package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
- package/dist/skills/opengame-capture/SKILL.md +108 -0
- package/dist/skills/opengame-capture/references/pipeline.md +82 -0
- package/dist/skills/opengame-capture/references/threejs.md +145 -0
- package/dist/skills/opengame-characters/SKILL.md +129 -0
- package/dist/skills/opengame-characters/references/integration.md +144 -0
- package/dist/skills/opengame-characters/references/player-og.md +160 -0
- package/dist/skills/opengame-cli/SKILL.md +118 -0
- package/dist/skills/opengame-deploy/SKILL.md +207 -0
- package/dist/skills/opengame-deploy/references/json-events.md +62 -0
- package/dist/skills/opengame-deploy/references/manifest.md +83 -0
- package/dist/skills/opengame-deploy/references/packaging.md +117 -0
- package/dist/skills/opengame-depth/SKILL.md +130 -0
- package/dist/skills/opengame-enemies/SKILL.md +103 -0
- package/dist/skills/opengame-enemies/references/threejs.md +134 -0
- package/dist/skills/opengame-front-end/SKILL.md +143 -0
- package/dist/skills/opengame-front-end/references/launch.md +50 -0
- package/dist/skills/opengame-front-end/references/menus.md +47 -0
- package/dist/skills/opengame-game-feel/SKILL.md +137 -0
- package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
- package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
- package/dist/skills/opengame-jam/SKILL.md +103 -0
- package/dist/skills/opengame-lighting/SKILL.md +94 -0
- package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
- package/dist/skills/opengame-loading/SKILL.md +99 -0
- package/dist/skills/opengame-loading/references/threejs.md +116 -0
- package/dist/skills/opengame-look/SKILL.md +114 -0
- package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
- package/dist/skills/opengame-mobile/SKILL.md +90 -0
- package/dist/skills/opengame-performance/SKILL.md +140 -0
- package/dist/skills/opengame-performance/references/measuring.md +72 -0
- package/dist/skills/opengame-production/SKILL.md +131 -0
- package/dist/skills/opengame-production/references/templates.md +63 -0
- package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
- package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
- package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
- package/dist/skills/opengame-router/SKILL.md +51 -0
- package/dist/skills/opengame-router/references/process.md +38 -0
- package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
- package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
- package/dist/skills/opengame-sdk/SKILL.md +270 -0
- package/dist/skills/opengame-sdk/references/engines.md +93 -0
- package/dist/skills/opengame-sdk/references/frame.md +107 -0
- package/dist/skills/opengame-sdk/references/identity.md +112 -0
- package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
- package/dist/skills/opengame-sdk/references/radio.md +71 -0
- package/dist/skills/opengame-stability/SKILL.md +84 -0
- package/dist/skills/opengame-verification/SKILL.md +136 -0
- package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
- package/dist/skills/opengame-weapons/SKILL.md +109 -0
- package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
- package/dist/skills/opengame-weapons/references/threejs.md +169 -0
- package/dist/skills/opengame-world-physics/SKILL.md +114 -0
- package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
- package/package.json +38 -4
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-mobile
|
|
3
|
+
description: Make a browser game run, sound and stay up on real phones. Covers tab memory measured on a real phone in Safari, freeing CPU copies after GPU upload, texture caps per device class, tier and pixel ratio before the first frame, touch input that keeps every release, audio unlock with a real check, phone frame rates, no blur over the canvas on iPhone, and WebGPU fallback. Use when the game crashes or reloads on a phone, is silent on iPhone, lags on mobile or has stuck touch controls.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Mobile
|
|
9
|
+
|
|
10
|
+
A phone is a different machine, and a desktop browser set up to imitate one hides the
|
|
11
|
+
failures that matter. OC (OG Clash) passed every phone gate in Chrome's iPhone emulation
|
|
12
|
+
while the owner's real iPhone crash-looped during load, played no gunfire, and ran at
|
|
13
|
+
10-20 fps. Emulation does not enforce Safari's memory limit, its touch quirks or its
|
|
14
|
+
audio rules. Put a real phone in the loop on the first day.
|
|
15
|
+
|
|
16
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes. Download
|
|
17
|
+
size and caching are in `opengame-loading`; crash counting and recovery in
|
|
18
|
+
`opengame-stability`; frame-time measurement in `opengame-performance`.
|
|
19
|
+
|
|
20
|
+
## Rules
|
|
21
|
+
|
|
22
|
+
### Phone memory is measured on a real phone in real Safari
|
|
23
|
+
- **Invariant:** The game's tab memory on the weakest target phone stays under a written budget through a full session, measured on the device in its own browser, and a build that has passed only emulation has not passed.
|
|
24
|
+
- **Technique:** Connect the phone to a Mac and use Safari's Web Inspector (Timelines, with the Memory instrument) while playing title, menus, a full match and results twice in a row. Add Android Chrome through remote debugging. Treat "A problem repeatedly occurred" or a silent reload as a memory kill. Keep a per-subsystem memory table in the game itself (textures, geometry, audio, WebAssembly heap) so the number has owners. Avoid fixed large up-front memory reservations; let WebAssembly memory grow from a modest start.
|
|
25
|
+
- **Reference configuration:** OC's owner set about 500 MB per tab; it was never met (the desktop tab sat at 3.5 GB, and an iPhone peaked at 3.9 GB). iPhones crash-looped from R165 to R195 after every emulated gate passed. Halving a fixed 4 GiB WebAssembly reservation changed nothing, because only about 0.8 GB of it was the game's own memory. Playwright's WebKit has no WebGPU, so OC had no local iOS reproduction, and fixes were blind until the owner tried his phone.
|
|
26
|
+
- **Applies when:** Every game that claims to run on phones, most of all iPhones, where Safari kills tabs over memory with no warning.
|
|
27
|
+
- **Verify:** On the real phone, two full sessions back to back: the tab stays up without a reload, and Web Inspector's peak stays under the budget. Record the phone model and OS version with the result.
|
|
28
|
+
|
|
29
|
+
### CPU-side copies are freed after GPU upload
|
|
30
|
+
- **Invariant:** Once a texture or mesh is on the GPU, the decoded pixels and vertex arrays held for it in JavaScript or WebAssembly memory are released, and the source URL is kept so they can be fetched again after a context loss.
|
|
31
|
+
- **Technique:** After upload, drop references to decoded image data and typed arrays the renderer no longer needs. Keep a table of URLs per asset so a restore can refetch. Three.js: load images with `ImageBitmapLoader`, and with `WebGLRenderer` close the bitmap in `texture.onUpdate` (`texture.image.close()`) once it is uploaded; for meshes you never raycast, morph or rebuild, free each attribute's array after upload with `attribute.onUpload(function () { this.array = null; })`. Test a resize and a forced context loss afterwards, since a texture that must be re-uploaded needs its source again.
|
|
32
|
+
- **Reference configuration:** OC measured about 690 MB of duplicate texture memory, leaving the tab at 4.4 GB ("444 MB is duplicate copies of textures already on the graphics card"), and 180-270 MB on phones. Its runtime had no public way to drop the CPU bytes and keep the GPU texture; a patch of about 30 lines to release them saved about 450 MB.
|
|
33
|
+
- **Applies when:** Every textured game on phones; on desktop when tab memory matters.
|
|
34
|
+
- **Verify:** Compare tab memory at the title with release on and off on the real phone. Then force a context loss (`WEBGL_lose_context.loseContext()` and `restoreContext()`): every texture draws again.
|
|
35
|
+
|
|
36
|
+
### Texture size and mips are capped per device class
|
|
37
|
+
- **Invariant:** Each device class has an agreed maximum texture size and downloads only the mip levels it will draw, and any cut in phone fidelity is agreed with the owner before it ships.
|
|
38
|
+
- **Technique:** Pick the device class before loading textures, and point the manifest at per-class files with the top mips trimmed, so a phone downloads only the detail it draws. Keep hero items one step above the rest. Write each cap down with its memory saving and the owner's decision beside it. Three.js: KTX2 files per class through `KTX2Loader`, checked against `renderer.capabilities.maxTextureSize`.
|
|
39
|
+
- **Reference configuration:** OC's phone textures went from 1,063.8 MB to 222.3 MB. The phone cap went from 2048 to 1024 to 512 while crashes continued. Phones had been fetching top mips and discarding them. Unasked phone cuts (16 enemies, 1024 px textures, half-resolution sky) shipped and were reverted after the owner said "i dont want phones to get worse quality".
|
|
40
|
+
- **Applies when:** Every game that ships textures larger than a phone needs.
|
|
41
|
+
- **Verify:** Per device class, sum the texture bytes transferred and resident at the title and in play; the hero items in a phone capture match the desktop capture at phone viewing size.
|
|
42
|
+
|
|
43
|
+
### Tier and pixel ratio are chosen before the first frame
|
|
44
|
+
- **Invariant:** The quality tier, pixel ratio and worker count are set from a device check before the renderer draws anything, so a phone starts at phone settings from its first frame.
|
|
45
|
+
- **Technique:** Classify the device from touch support, screen size, `navigator.hardwareConcurrency`, the GPU adapter and any stored result from an earlier visit, and default phones to the phone tier. Treat a GPU that reports no memory or a generic name as unknown and use the phone tier on a touch device. Set the pixel-ratio cap before the first `render`. Size worker pools from measured speed on the device, not from the reported core count. Three.js: `renderer.setPixelRatio(Math.min(devicePixelRatio, cap))` before the first frame, and `renderer.compileAsync` for the chosen tier only.
|
|
46
|
+
- **Reference configuration:** OC's phones warmed up at the top tier at full Retina before its caps applied. Safari's GPU reported a generic vendor with 0 bytes and read as desktop, so phones got the top tier. Safari reported 2-4 cores, which would have started 16 threads, so OC fixed workers at 4; on desktop, 8-12 workers ran slower than 4. The pixel budget behind the cap is in `opengame-performance`.
|
|
47
|
+
- **Applies when:** Every game with tiers or a pixel-ratio cap that runs on phones.
|
|
48
|
+
- **Verify:** On the real phone, log the tier and drawing-buffer size of the first frame: both are already the phone values.
|
|
49
|
+
|
|
50
|
+
### Every touch release arrives, even when the system cancels it
|
|
51
|
+
- **Invariant:** Every touch that starts has an end the game sees, including when the OS cancels it, the finger leaves the canvas or the tab loses focus, so no ghost finger owns the camera and no button stays held.
|
|
52
|
+
- **Technique:** Use pointer events with `setPointerCapture`, and handle `pointerup`, `pointercancel`, `lostpointercapture` and `touchcancel`. Listen for releases on `window`, not on the canvas. Clear every active touch on `visibilitychange` and `blur`. Key touches by identifier, and do not cap the event queue in a way that can drop ends. Set `touch-action: none` on the canvas. Keep the game in touch mode unless a real keyboard or mouse is used for a while.
|
|
53
|
+
- **Reference configuration:** OC's input had no `touchcancel` and a 20-event queue that dropped ends, leaving "a ghost finger that owns the camera forever"; iOS touch ids are unique, so the ghost never cleared, while Chromium emulation hid it. A mouse release heard only on the canvas made 60 of 60 clicks miss after an overlay. One tap flipping the HUD to desktop mode needed a 30-frame guard.
|
|
54
|
+
- **Applies when:** Every game with touch controls, and every game with DOM overlays over the canvas.
|
|
55
|
+
- **Verify:** On the real phone, start a look drag and pull down the notification shade or start the home gesture, return, and drag again: the camera follows the new finger. In automation, send a touch start then a `touchcancel`: no input stays active.
|
|
56
|
+
|
|
57
|
+
### Sound unlocks on the first touch and is checked by measurement
|
|
58
|
+
- **Invariant:** Sound plays from the first touch on a phone, comes back after calls, locks and tab switches, and is proven by measured output on the device, not by the audio context's state or a log line.
|
|
59
|
+
- **Technique:** Create or resume one `AudioContext` inside the first touch handler, and resume again on every touch, on `visibilitychange` and when the context reports `suspended` or `interrupted`, with a short watchdog. On Safari, set `navigator.audioSession.type = 'playback'` before creating the context where the API exists, so the silent switch does not mute the game. Load the player's own weapon sounds first. Give the player's weapon, UI and music priority over enemy voices. Check the output with an `AnalyserNode` on the master bus during a shot, and have a person listen on the phone.
|
|
60
|
+
- **Reference configuration:** OC had no gunfire on iPhone across 3 or more builds, and the owner raised in-game iPhone sound 7 times ("game audio was playing but NOT gunfire sounds"). The phone build's audio functions were stubs while the log still said "unlocked ... 48000 Hz out". Setting the audio session to playback was proposed and its effect was never confirmed. Enemy vocals were capped to the nearest 6 within 20-30 m and the mix to about 40 voices.
|
|
61
|
+
- **Applies when:** Every game with sound that runs on phones.
|
|
62
|
+
- **Verify:** On the real phone with the silent switch on and off: the probe reads a peak on the first shot, after locking and unlocking, and after switching apps and back; a person hears it.
|
|
63
|
+
|
|
64
|
+
### Phones have their own frame-rate floor, measured on the phone
|
|
65
|
+
- **Invariant:** The phone has a written floor and target, measured on the phone in menus, loading and combat, and it holds a steady rate rather than bouncing between two.
|
|
66
|
+
- **Technique:** Budget draw calls and per-enemy costs separately for phones, since phones are bound by draw calls and CPU sooner than by fill. If the phone cannot hold its target, cap at a lower rate it holds evenly. Measure on the device with an on-screen counter and Web Inspector, at the same tier players get. Target the phones most players own, not the oldest or smallest.
|
|
67
|
+
- **Reference configuration:** OC's targets on phones: at least 30 fps, aim 60, with Safari capping animation frames at 60. The owner measured 15-20 fps on his iPhone ("i dont want to cur quality / fidelity") and OC ended at 10-20 fps at R195. Target devices: iPhone 11 and 12, SE 2 and 3, and mid-range Android ("dont overfit to iphone 5se").
|
|
68
|
+
- **Applies when:** Every game played on phones.
|
|
69
|
+
- **Verify:** On the weakest target phone, record frame times through title, menus, a loading screen and a minute of the heaviest fight: the one-percent low holds the phone floor.
|
|
70
|
+
|
|
71
|
+
### No backdrop blur over the canvas on iPhone
|
|
72
|
+
- **Invariant:** On iPhone, menus and overlays over the game canvas use pre-blurred or darkened images rather than a live backdrop blur.
|
|
73
|
+
- **Technique:** Replace `backdrop-filter: blur()` over the canvas with a darkened frame, a blurred still captured once, or a solid panel. Keep CSS filters off full-screen layers above WebGL or WebGPU content on phones.
|
|
74
|
+
- **Reference configuration:** OC removed `backdrop-filter` blur over its WebGPU canvas on iPhone, on the suspicion that it cost memory. Nobody measured the memory cost; the cause was a guess.
|
|
75
|
+
- **Applies when:** Every game with DOM menus or HUD panels over the canvas on iOS.
|
|
76
|
+
- **Verify:** On the real phone, compare Web Inspector memory and frame time with the pause menu open and closed; the difference is small.
|
|
77
|
+
|
|
78
|
+
### Missing WebGPU gets a message or a fallback within a second
|
|
79
|
+
- **Invariant:** Before the large download, the game checks whether this browser can run it, and a device without the needed API gets a fallback renderer or a card that names the reason and what to do.
|
|
80
|
+
- **Technique:** Check `navigator.gpu`, then `requestAdapter()` (it can return null even when `navigator.gpu` exists) and the features and limits the game needs, then WebGL 2. Decide before fetching the world. If the game falls back, test the fallback path as a real build. Three.js: `WebGPURenderer` falls back to its WebGL 2 backend when WebGPU is missing (`forceWebGL: true` forces it for testing); check `renderer.backend.isWebGPUBackend` after `await renderer.init()`.
|
|
81
|
+
- **Reference configuration:** OC's capability gate ran in 310-626 ms and named the reason and the fix. Its "No WebGPU" card showed on 60 of 60 boots in testing.
|
|
82
|
+
- **Applies when:** Every game built for WebGPU, and every game needing WebGL 2 extensions.
|
|
83
|
+
- **Verify:** Boot with WebGPU unavailable (remove `navigator.gpu` in an init script, or a browser without it): the card or the fallback appears in under 1 s, before any large request in the network log.
|
|
84
|
+
|
|
85
|
+
### Touch layout is thumb-sized, landscape and install-aware
|
|
86
|
+
- **Invariant:** Every touch target is large enough for a thumb, the game plays in landscape with a clear prompt in portrait, and players are offered the installed web-app mode without being forced into it.
|
|
87
|
+
- **Technique:** Size targets in points against the safe area, place main actions in the thumb arc, and pause behind a rotate card in portrait. Detect installed mode with `matchMedia('(display-mode: standalone)')` and `navigator.standalone`; show a short per-platform guide to add the game to the home screen with a remembered "play in browser" choice. Declare `display: fullscreen` and `orientation: landscape` in the web app manifest. iOS Safari in a tab has no fullscreen API, no orientation lock and no vibration, so do not depend on them.
|
|
88
|
+
- **Reference configuration:** OC's touch targets are at least 44 pt; its title rows had measured 20-25 px, and some buttons 29 pt. Main buttons sit in the right 30% of the screen, with 12 buttons at most.
|
|
89
|
+
- **Applies when:** Every game with a touch layout.
|
|
90
|
+
- **Verify:** Screenshot every menu and the HUD at a phone landscape size (OC used 844 x 390) and measure each target; play a round on the phone with thumbs only.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-performance
|
|
3
|
+
description: Keep a browser game smooth on an ordinary laptop, with three.js specifics. Covers frame-time variance and one-percent lows, per-system timing, writes only on change, menus and previews at high pixel ratio, quiet-machine A/B measurement, draw and memory budgets, shader prewarm, textures decoded once, dynamic resolution and no per-frame allocation. Use when the person says the game stutters, hitches, lags, drops frames, swings between frame rates, has a slow menu or freezes on the first explosion.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Performance
|
|
9
|
+
|
|
10
|
+
A game is smooth when its worst frames are fast, not when its average is. Players feel
|
|
11
|
+
the 99th percentile: the hitch on the first explosion, the stall when a new material
|
|
12
|
+
compiles, the sawtooth of the garbage collector. They feel the spread as well: OC's owner
|
|
13
|
+
asked about 25 times for a stable frame rate and put it as "MINIMIZE VARIANCE (... not
|
|
14
|
+
bouncing 60-120)". Measure the tails and the spread, on the real route, and fix what the
|
|
15
|
+
measurement names.
|
|
16
|
+
|
|
17
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes. Loading
|
|
18
|
+
and download size have their own skill, `opengame-loading`; phones have `opengame-mobile`.
|
|
19
|
+
|
|
20
|
+
## Measure the running game
|
|
21
|
+
|
|
22
|
+
Install `opengame-verification` with `opengame skills add --skill opengame-verification`
|
|
23
|
+
and use its `opengame-verification/helpers/browser-evidence.mjs` for frame-time samples and input evidence.
|
|
24
|
+
Set a frame-time tolerance from the target hardware's measured baseline. Record the
|
|
25
|
+
CPU throttle and soak duration alongside the result. Compare the same scene and
|
|
26
|
+
player route before and after a change. Inspect memory separately when diagnosing a
|
|
27
|
+
leak; frame-time samples do not measure retained memory.
|
|
28
|
+
|
|
29
|
+
## Rules
|
|
30
|
+
|
|
31
|
+
### Low variance beats a high average
|
|
32
|
+
- **Invariant:** After warm-up the frame time stays close to its median: the one-percent low holds the floor, no frame runs far past the usual, and every average is reported with the spread beside it.
|
|
33
|
+
- **Technique:** Record every frame's duration on the real route after a warm-up, and report the median, p99, the one-percent low (the frame rate of the slowest hundredth of frames), the worst frame as a multiple of the median, and the count of frames over twice the median. Show an FPS counter that is green at the floor and yellow below it. When a game cannot hold its top rate, cap it at a rate it holds rather than letting it swing. Three.js: time frames in the `setAnimationLoop` callback with `performance.now()`, use stats.js for the on-screen counter, and fix the pixel ratio while measuring.
|
|
34
|
+
- **Reference configuration:** OC's targets: desktop floor 60 fps, aim 120 (phone targets are in `opengame-mobile`); one-percent low at least 60 at 1280 x 720; p99 at most 1.5x the median; no frame over 2x the usual once warm; counter green at 60 and up and yellow below, with no red. Averages hid the problem: OC measured combat at 74 fps average with a 35 fps one-percent low, one build at 64 and 13, another at 31 and 8.6.
|
|
35
|
+
- **Applies when:** Every real-time game. Turn-based and puzzle games still need it in menus and transitions.
|
|
36
|
+
- **Verify:** The measurement script prints the one-percent low and the count of frames over twice the median for the busiest route; a run whose average clears the floor while its one-percent low does not is reported as a failure.
|
|
37
|
+
|
|
38
|
+
### Budgets are tails, measured on the real route
|
|
39
|
+
- **Invariant:** The game has written budgets for frame-time tails and for what each frame draws, and every number reported against them came out of one measurement script on the real path: menu, Play, live play.
|
|
40
|
+
- **Technique:** Drive the production path with input, record frame times, and report p50, p95, p99 and long tasks, plus draw calls, triangles, texture and geometry memory, and JS allocation rate. Print the machine's load and the throttle actually achieved beside every result, because milliseconds move with load and counts do not.
|
|
41
|
+
- **Reference configuration:** AW, at 1920 x 1080 on its high tier with 12 combatants under a 4x CPU throttle: p50 16.7 ms, p95 25.0 ms, p99 33.3 ms, long tasks 300 ms per 20 s, 700 draw calls, 900,000 triangles, 320 MB of textures, 160 MB of geometry, 200 MB of decoded audio, 4 MB/s of allocation. AW estimates 2x throttle is about an M1 Air's CPU and 4x pessimistic by design; the throttle does nothing to the GPU.
|
|
42
|
+
- **Applies when:** Every 3D game. Smaller games set smaller budgets, but the shape (tails, counts, one script) stays.
|
|
43
|
+
- **Verify:** The script prints all of the above for the busiest route, and fails when a map did not actually load (AW measured a grey stand-in arena under a map's name, and it looked faster than the truth).
|
|
44
|
+
|
|
45
|
+
### Every slow frame has an owner
|
|
46
|
+
- **Invariant:** Frame time is split by system and by render pass, so every frame over budget names the system that made it slow, and only a small share of an ordinary frame is unattributed.
|
|
47
|
+
- **Technique:** Wrap each system's update and each pass in a timer that writes into a rolling per-system histogram. On any frame over twice the median, log the top systems for that frame. Spread one-off heavy jobs (path searches, camera searches, spawning a set piece) over several frames instead of running them in one. Keep logging off the hot path, since writing log lines is a cost too. Three.js: `performance.now()` around each system, `renderer.info.render` per pass, and GPU timestamp queries (`EXT_disjoint_timer_query_webgl2` on WebGL 2, the `timestamp-query` feature on WebGPU) for passes.
|
|
48
|
+
- **Reference configuration:** OC began with about 40% of the frame not broken out, and found spikes by parsing logs (1,096 frames over 25 ms in one session, the worst 159 ms) until its agents wrote a per-system profiler. Once timed, all game systems together cost 0.4-2.5 ms and the large items were the engine's update, render sync and audio mix (3.8-7 ms for 30-46 voices). Named fixes followed: ally pathing went from 18 calls to 1, a held-gun shader at 1.6-1.8 ms (28% of a combat frame) got a 0.4 ms target, and 13 log lines on one frame turned out to cause a hitch.
|
|
49
|
+
- **Applies when:** Every game with more than a handful of systems, and always before anyone guesses at a cause.
|
|
50
|
+
- **Verify:** Plant a busy-wait of known length in one system: the next slow-frame log names that system and the planted time. The per-system table for an ordinary frame sums to within a few percent of the measured frame.
|
|
51
|
+
|
|
52
|
+
### A verdict needs a quiet machine and an interleaved A/B
|
|
53
|
+
- **Invariant:** A change is called faster or slower only from paired runs of both builds, alternated in one session on a machine with nothing else competing for it, with the competing load logged for every run.
|
|
54
|
+
- **Technique:** Alternate A, B, A, B on the same scene, route, settings and pixel ratio. Warm up, then sample. Log other processes' CPU for each run by their full command line, and throw out runs where other work used a large share of the cores. Keep the browser at foreground priority. Drop frames that overlap a screenshot or a recording. When the measuring machine also builds and renders, book a quiet window for measurement and run nothing heavy in it.
|
|
55
|
+
- **Reference configuration:** OC held R143 as a regression for a round: other Chrome processes were using 131%, 107% and 55% CPU. A background-priority daemon cut headless Chrome from 105 to 5.6 fps for about 4.5 h. OC's protocol: 30 s warm-up, 120 s sample, reject runs above about 50% of cores in competing use, and exclude frames that overlap a screenshot. Paired runs caught the R143 contention, and R159 was reverted after losing 6 of 9 pairs. See [references/measuring.md](references/measuring.md).
|
|
56
|
+
- **Applies when:** Every performance claim, most of all on a machine shared with builds, captures or other agents.
|
|
57
|
+
- **Verify:** Run A against A first: the difference stays within noise. Then plant a known slowdown in B: the A/B flags it. Every run in the report lists its competing-CPU figure.
|
|
58
|
+
|
|
59
|
+
### Every number names the quality it ran at
|
|
60
|
+
- **Invariant:** Adaptive quality never changes anything unseen: every frame-time number records the tier and render scale it ran at, benchmarks run with adaptation pinned, and a player's explicit choice is lowered only with a notice and never below an agreed floor.
|
|
61
|
+
- **Technique:** Log each change of tier or render scale with its time and reason. Give benchmarks a flag that pins tier and scale. Show the effective tier in settings. Step down at most once, with a banner, outside menus and loading, and stop at the floor the owner agreed.
|
|
62
|
+
- **Reference configuration:** OC's adaptive mode dropped render scale to 58% while its numbers were compared with fixed runs: one adaptive run read 119.4 fps average and 70.5 one-percent low beside a fixed combat run at 74 and 35. Its "Dynamic" mode lowered Ultra to Low or Medium while settings still said Ultra, and captures came out with 8 of 224 lights. The owner hit it 3 or more times ("Let's make Ultra the base... fall back to High, but not below"). The policy that held: one step from Ultra to High after 8 s at a GPU median above 17.5 ms, with a banner, never below High and never in menus.
|
|
63
|
+
- **Applies when:** Every game with dynamic resolution or automatic tiers.
|
|
64
|
+
- **Verify:** A benchmark report shows the tier and scale track for its whole run. A long session started on the top tier ends on it, or shows the banner and the logged reason.
|
|
65
|
+
|
|
66
|
+
### State is written only when it changes
|
|
67
|
+
- **Invariant:** An update that leaves a value as it was does not write it, so nothing downstream re-uploads, re-syncs, re-sorts or re-lays out.
|
|
68
|
+
- **Technique:** Compare before writing anything that marks state dirty, such as visibility, transforms, material parameters, uniforms, instance buffers and HUD text. Watch for APIs where asking for write access counts as a change even when no value moves. Three.js: set `visible`, `material.needsUpdate`, `texture.needsUpdate` and `instanceMatrix.needsUpdate` only on a real change; set `matrixAutoUpdate = false` on static objects and call `updateMatrix()` when they move; set DOM `textContent` only when the string differs.
|
|
69
|
+
- **Reference configuration:** In OC, taking write access to a value marked it changed whether or not anything was written. A force field's per-frame write was behind the R159 hitches, and audits found about 20 such call sites. Comparing before writing cut main-thread CPU by 30% and frame spikes from 225 to 102 a minute.
|
|
70
|
+
- **Applies when:** Every game, most of all one with many hidden or idle objects.
|
|
71
|
+
- **Verify:** Count dirty marks and uploads per frame with the game idle in a menu: the count is zero. In combat, the count tracks what moved.
|
|
72
|
+
|
|
73
|
+
### Menus and previews draw only what changed
|
|
74
|
+
- **Invariant:** A menu, pause screen or 3D preview costs what its motion needs: a still preview does not rewrite its scene every frame, and a menu holds the same floor as play.
|
|
75
|
+
- **Technique:** Give menu scenes the same per-system timing as play. Rebuild a preview's scene only when its subject or camera changes, and write its visibility and materials on change. Draw the 3D preview at its own capped resolution, and stop rendering scenes that are fully covered. Measure menus in a headed browser at the display's native pixel ratio, since a headless run at pixel ratio 1 hides the cost. Three.js: render a preview into a small `WebGLRenderTarget`, call `renderer.render` for it only when a dirty flag is set, and `setAnimationLoop(null)` for scenes off screen.
|
|
76
|
+
- **Reference configuration:** OC's owner measured a menu at 24 fps (p99 90 ms) and the main menu at 20 fps (p99 136 ms) on a Retina laptop while headless runs read 110-120. The owner had asked for menus at the play floor 3 or more times.
|
|
77
|
+
- **Applies when:** Every game with a 3D menu, loadout preview or character screen.
|
|
78
|
+
- **Verify:** With the menu idle at native pixel ratio, the per-system table shows no scene rebuilds, and the one-percent low meets the play floor.
|
|
79
|
+
|
|
80
|
+
### Pixel ratio is capped by a pixel budget
|
|
81
|
+
- **Invariant:** The number of pixels drawn is chosen from a budget in device pixels, so a high-density display does not multiply the GPU cost of the frame.
|
|
82
|
+
- **Technique:** Choose the pixel ratio from a target pixel count in device pixels rather than CSS size, and run full-screen post at the internal resolution. Apply the cap before the first frame. Three.js: `renderer.setPixelRatio(Math.min(devicePixelRatio, cap))`, and check the result against `renderer.domElement.width * height` (or `drawingBufferWidth` on the context).
|
|
83
|
+
- **Reference configuration:** At pixel ratio 2, OC's menu GPU time was 22.6 ms, of which the 3D was about 2 ms; the rest was full-resolution post. A cap written in CSS pixels never applied (17.6 fps) and shipped for 14 h before the fix. Ultra drew 2x the pixels on Retina, and the phone menu drew 3.4x the pixels of the run.
|
|
84
|
+
- **Applies when:** Every game that runs on Retina laptops, 4K monitors or phones.
|
|
85
|
+
- **Verify:** Log the drawing-buffer size on a high-density display at every screen: it stays at or under the budget, and the frame time matches the same size at pixel ratio 1.
|
|
86
|
+
|
|
87
|
+
### Nothing compiles during play
|
|
88
|
+
- **Invariant:** No shader program links after the loading cover lifts.
|
|
89
|
+
- **Technique:** Prewarm every material through the same render target, colour space and cameras the frame really uses, under an opaque fade, and keep the light count fixed (see `opengame-lighting`). A prewarm through the canvas compiles the wrong variant when the world draws into a linear target. Prewarm first-use effects and sounds the round before they appear, not on the frame they first play.
|
|
90
|
+
- **Reference configuration:** AW's prewarm ran with no target bound and compiled the sRGB variant of every material while every real frame drew into a linear target; nothing it compiled was used. Fixed, the countdown went from 16 long tasks totalling 3,607 ms to none, and programs linking after the veil from 10 to 0. OC: a quality switch that recompiled pipelines hitched for about 10 s (worst frame 48.7 ms), so it prewarms boss effects and sounds the round before and builds the death and results screens ahead of time.
|
|
91
|
+
- **Applies when:** Every three.js game with more than a handful of materials.
|
|
92
|
+
- **Verify:** Count `renderer.info.programs.length` when the loading cover lifts and again after the first fight; it does not change.
|
|
93
|
+
|
|
94
|
+
### Statics merged, repeats instanced
|
|
95
|
+
- **Invariant:** Draw calls scale with the number of materials, not the number of objects.
|
|
96
|
+
- **Technique:** Merge static geometry per material, instance repeated props in spatial chunks with level of detail and hysteresis, and check that skinned and instanced bounds are right so culling does not remove visible things.
|
|
97
|
+
- **Reference configuration:** DK draws its props in about 9 calls; MC's Rust map in 24. AW gives one map's own geometry a budget of 44 draws inside the 700. OC's arena drew about 6,190 separate objects with none grouped, and cutting resolution by 60% saved only 16% of the frame.
|
|
98
|
+
- **Applies when:** Every scene with many static objects.
|
|
99
|
+
- **Verify:** Read `renderer.info.render.calls` with the busiest view on screen.
|
|
100
|
+
|
|
101
|
+
### Textures by measurement, one decode per image
|
|
102
|
+
- **Invariant:** Every image is fetched, decoded and uploaded once however many materials use it, and its GPU format was chosen by measuring size and quality.
|
|
103
|
+
- **Technique:** Cache textures by URL and hand out clones that share the source; register only the original for disposal. Encode KTX2 per texture class after measuring bytes on the wire, GPU residency and quality on the real surface, with a fallback to the original image when the transcoder or device cannot do it.
|
|
104
|
+
- **Reference configuration:** AW: sharing sources took GPU residency from 492.1 MB to 440.3 MB; 65% of its texture memory was loaded images, the only part KTX2 can reach. AW measured ETC1S with its normal-map mode at no extra cost for normals where UASTC cost about six times the bytes, and chose ETC1S throughout; SR encodes character textures as full-resolution UASTC.
|
|
105
|
+
- **Applies when:** Every textured game. Measure by `Texture.source`, not by texture objects, or a working cache looks like a failed fix.
|
|
106
|
+
- **Verify:** Count distinct sources and sum their bytes at runtime; KTX2 statistics report how many loaded compressed and how many fell back.
|
|
107
|
+
|
|
108
|
+
### Resolution scales before content does
|
|
109
|
+
- **Invariant:** When the GPU cannot keep up, the game lowers render resolution smoothly and raises it again only when it is clearly safe, without oscillating.
|
|
110
|
+
- **Technique:** Measure missed presentations against the display's real period, require several agreeing checks to change, a longer dwell before raising after a drop, and a cooldown after any change. Lowering resolution cannot fix a CPU stall, so do not use it to hide one. Log every change (see the rule on naming the quality a number ran at).
|
|
111
|
+
- **Reference configuration:** AW checks every 2 s, waits 8 s after any change and 20 s after a drop before raising, drops on 2 agreeing votes and raises on 4, drops by 0.15 and raises by 0.1, treating more than 5% missed frames as stutter and under 1% as clean.
|
|
112
|
+
- **Applies when:** 3D games that must run across very different GPUs.
|
|
113
|
+
- **Verify:** Log the scale over a long busy session on a slow machine: it settles rather than bouncing.
|
|
114
|
+
|
|
115
|
+
### Quality tiers that keep the look
|
|
116
|
+
- **Invariant:** The lowest tier still reads as the same game, and every tier stays inside its budget.
|
|
117
|
+
- **Technique:** Tiers drop expensive passes in order (occlusion, then volumetrics, then bloom and multisampling), cap device pixel ratio and shadow resolution, and shrink the light pool. Never change collision, input or what the player can see of a threat.
|
|
118
|
+
- **Reference configuration:** DK's low tier drops occlusion, volumetrics, motion blur, depth of field and reflections and keeps bloom and FXAA. The ST starter drops occlusion, then bloom and multisampling.
|
|
119
|
+
- **Applies when:** Every game with post or many lights.
|
|
120
|
+
- **Verify:** Capture the same view at every tier and measure each against the budget.
|
|
121
|
+
|
|
122
|
+
### Nothing allocates per frame
|
|
123
|
+
- **Invariant:** An ordinary frame of play allocates nothing, so the garbage collector does not cut a sawtooth through the frame times.
|
|
124
|
+
- **Technique:** Reuse scratch vectors and matrices, fixed particle pools and ring buffers for decals, tracers and casings; update the HUD on change, not every frame; avoid layout reads in the hot path.
|
|
125
|
+
- **Reference configuration:** DK's pools: 900 smoke and 900 spark particles. AW budgets 4 MB/s of allocation during play; above it the collector runs every second.
|
|
126
|
+
- **Applies when:** Every game.
|
|
127
|
+
- **Verify:** An allocation profile of a busy minute shows a flat heap and names no per-frame allocation site in game code.
|
|
128
|
+
|
|
129
|
+
### Loading pays only for what is needed
|
|
130
|
+
- **Invariant:** The menu appears quickly, a returning player downloads almost nothing, and nothing cosmetic downloads during a countdown or the first seconds of play.
|
|
131
|
+
- **Technique:** Bundle the boot tier, preload only what the first actionable scene needs, stage the rest after play starts, and serve with validators so unchanged files are not re-sent. The full set of loading rules is in `opengame-loading`.
|
|
132
|
+
- **Reference configuration:** AW: time to menu 1,500 ms and under 4 MB fetched before the menu; a repeat visit dropped from 34.36 MB to 0.39 MB once its server sent `no-cache` with an ETag instead of `no-store`. Moving a 2.70 MB model prewarm out of the countdown took countdown downloads from 3.02 MB to 0.32 MB.
|
|
133
|
+
- **Applies when:** Every game, most of all large 3D ones.
|
|
134
|
+
- **Verify:** A network waterfall bucketed by phase: boot, menu, countdown, first seconds of play.
|
|
135
|
+
|
|
136
|
+
## Further reading
|
|
137
|
+
|
|
138
|
+
What AW's measurement script got wrong before it was trusted, and how contention on a
|
|
139
|
+
shared machine made OC chase a regression that did not exist:
|
|
140
|
+
[references/measuring.md](references/measuring.md).
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Measuring without fooling yourself
|
|
2
|
+
|
|
3
|
+
World at War (AW) built a frame-budget harness and a gate that grades its newest
|
|
4
|
+
measurement. Before it could be trusted it had reported a clean bill of health three
|
|
5
|
+
ways that were all wrong. Each is a check worth copying.
|
|
6
|
+
|
|
7
|
+
## A run that cannot be evaluated is not a pass
|
|
8
|
+
|
|
9
|
+
1. **The map did not load.** A map whose loader threw fell back to a grey stand-in arena.
|
|
10
|
+
The match still started, the HUD still came up, a screenshot still came back, and the
|
|
11
|
+
harness measured a grey box under the map's name. Fewer draws and triangles made the
|
|
12
|
+
wrong run look better than the truth. Check the loaded map's identity before
|
|
13
|
+
measuring, and abort with the page's own error.
|
|
14
|
+
2. **The shell did not boot.** One module-level syntax error emptied the menu, every
|
|
15
|
+
menu selection did nothing, with no error, and every capture was of a dead menu. Gate the
|
|
16
|
+
run on a boot check that names the error.
|
|
17
|
+
3. **The match ended under the sample.** Menu frames are cheap, so a sample that outlives
|
|
18
|
+
the match reports a better median. Assert the game is still in play at the end of the
|
|
19
|
+
sample.
|
|
20
|
+
|
|
21
|
+
## The gate fails in four cases that used to read as green
|
|
22
|
+
|
|
23
|
+
- No measurement at all.
|
|
24
|
+
- A measurement older than the newest source file: it grades a build that no longer
|
|
25
|
+
exists.
|
|
26
|
+
- A level missing from the measurement.
|
|
27
|
+
- A level whose arms declared themselves unevaluable.
|
|
28
|
+
|
|
29
|
+
## Read the machine before the milliseconds
|
|
30
|
+
|
|
31
|
+
Print the load average before and after, the CPU throttle actually achieved (time a fixed
|
|
32
|
+
workload at rate 1 and at the requested rate), and the display's frame period. On a box
|
|
33
|
+
running several other browsers, AW asked for 4x and measured 1.56x; that run's
|
|
34
|
+
milliseconds are a pessimistic bound, not a cost. Counts (draw calls, triangles, bytes,
|
|
35
|
+
allocation sites) do not move with load; milliseconds do.
|
|
36
|
+
|
|
37
|
+
## Prove the instrument bites
|
|
38
|
+
|
|
39
|
+
Plant a busy-wait and require the frame budget to fail; plant a full-screen flash and
|
|
40
|
+
require the flash check to fire. A harness that has never failed has not been shown to
|
|
41
|
+
measure anything.
|
|
42
|
+
|
|
43
|
+
## Phases the frame harness never saw
|
|
44
|
+
|
|
45
|
+
Twenty seconds of live play leaves out boot, the menu, the match build and the
|
|
46
|
+
countdown, which is where AW's players' complaints were. A phase timeline under one
|
|
47
|
+
continuous profile found the countdown hitching for 3.6 s of long tasks, the map being
|
|
48
|
+
built twice, and 266.9 MB of decoded audio against a 200 MB budget. Measure every phase a
|
|
49
|
+
player sits through, not only the one that is easiest to sample.
|
|
50
|
+
|
|
51
|
+
## Contention that read as a regression
|
|
52
|
+
|
|
53
|
+
OC (OG Clash) built, captured, rendered a launch film and measured performance on one
|
|
54
|
+
16-core machine shared by many agents, with load averages from 100 to over 360. Three
|
|
55
|
+
things went wrong in its numbers, and each has a check.
|
|
56
|
+
|
|
57
|
+
1. **Other browsers on the same machine.** R143 was held as a regression. Other Chrome
|
|
58
|
+
processes were at 131%, 107% and 55% CPU. Comparing load averages alone missed it.
|
|
59
|
+
Log competing CPU per process for every run, matched on the full command line, and
|
|
60
|
+
reject runs where other work used more than about half the cores. Test the filter
|
|
61
|
+
once by starting a known busy process and checking that it shows up.
|
|
62
|
+
2. **Process priority.** A background-priority daemon put headless Chrome into the
|
|
63
|
+
background scheduling class, and it fell from 105 to 5.6 fps for about 4.5 h. Check
|
|
64
|
+
the browser's scheduling class before a run; on macOS, OC restored it with
|
|
65
|
+
`taskpolicy -B`.
|
|
66
|
+
3. **Screenshots in the sample.** Frames that overlap a screenshot are slow for reasons
|
|
67
|
+
that have nothing to do with the game. Exclude them, or capture in a separate run.
|
|
68
|
+
|
|
69
|
+
The protocol that held up alternates the two builds (A, B, A, B) in one session, warms
|
|
70
|
+
up for 30 s, samples for 120 s, keeps the pixel ratio and settings fixed, and uses quiet
|
|
71
|
+
windows booked for measurement alone. Run A against A first to learn the noise. OC
|
|
72
|
+
caught the R143 contention this way and reverted R159 after it lost 6 of 9 pairs.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-production
|
|
3
|
+
description: Run a browser game build with one or many agents so the owner's feedback lands in few rounds. Covers the owner's bar written in the first hour, one ask register across handoffs, one integrator, frozen snapshots with a receipt per round, one latest playable link, status on a fixed cadence, usage limits, machine load and reference-first iconic items. Use when a game will take many rounds of owner feedback, when several agents share one game, or when rounds are slow or fixes never reach builds.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Production
|
|
9
|
+
|
|
10
|
+
A game built over many rounds of an owner's feedback loses most of its rounds to
|
|
11
|
+
process. OC took about 190 numbered builds in 7 days. About 75 of them never became an
|
|
12
|
+
accepted build, about 40 for agent or process reasons, about 22 for engine limits and
|
|
13
|
+
about 10 for changes of taste. The owner asked "are you there", "work faster" or "how
|
|
14
|
+
are we still on" this round more than 80 times. To run the loop in fewer rounds, front-load the bar,
|
|
15
|
+
keep one record of what the owner asked, integrate in one place, and show only what a
|
|
16
|
+
build the owner can open proves.
|
|
17
|
+
|
|
18
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes. The
|
|
19
|
+
templates for the register, a delivery, a round receipt and a status update are in
|
|
20
|
+
[references/templates.md](references/templates.md).
|
|
21
|
+
|
|
22
|
+
## The first hour
|
|
23
|
+
|
|
24
|
+
Settle these with the owner before the first build, and write them into one bar file
|
|
25
|
+
that every agent reads. Where the owner has not decided, propose a value and mark it
|
|
26
|
+
proposed.
|
|
27
|
+
|
|
28
|
+
1. **Concept art per screen.** One hero frame at the player's camera for the title,
|
|
29
|
+
each menu, loading, each play area, the HUD, the boss, death and results. A canon
|
|
30
|
+
sheet per character: turnarounds fix identity, scene paintings only composition.
|
|
31
|
+
2. **The reference games.** One named shipped game per area, with a saved frame per
|
|
32
|
+
screen at the same camera as the concept (see `opengame-quality-bar`).
|
|
33
|
+
3. **Frame rate and devices.** A floor and a typical frame rate for desktop and for
|
|
34
|
+
phones, on named devices and browsers. Mainstream phones, not the oldest. A real
|
|
35
|
+
phone on the desk from the first playable (see `opengame-mobile`).
|
|
36
|
+
4. **Budgets.** Bytes and seconds to the title and to play, first visit and returning;
|
|
37
|
+
tab memory; draw calls, lights and enemies on screen; paid generation spend. Check
|
|
38
|
+
the engine's fixed caps (lights, models, particles, handles) against what the
|
|
39
|
+
concept needs now (see `opengame-stability`).
|
|
40
|
+
5. **Iconic items.** Anything players will compare with a version they know. Collect
|
|
41
|
+
its reference before anyone models it.
|
|
42
|
+
6. **The loop.** The ask register file, the latest playable address, the build clock,
|
|
43
|
+
the status interval, the agent count, the heavy-job cap and the compute share
|
|
44
|
+
between teams. Who owns the frame, who owns the renderer, who integrates.
|
|
45
|
+
7. **Calibration.** Ask the owner to score one comparison sheet 0 to 10, so the critic
|
|
46
|
+
can be held to the owner's eye from round one.
|
|
47
|
+
|
|
48
|
+
In OC each of these was found late. The first-person lens sat at 66.5 degrees against the
|
|
49
|
+
concepts' 50-55. A 32-light cap met 218 fire sites. The first written budget came at R79
|
|
50
|
+
(360 MB to the title, a 3.5 GB tab) against the owner's ask of a tab under 500 MB. The
|
|
51
|
+
latest playable address arrived on day 5, and the first real iPhone crash reports came
|
|
52
|
+
after launch.
|
|
53
|
+
|
|
54
|
+
## Rules
|
|
55
|
+
|
|
56
|
+
### The owner's bar is written down before the first build
|
|
57
|
+
- **Invariant:** Concept frames per screen, the reference games, the frame-rate floor and target devices, and the budgets are in one bar file before the first build, and every spec number lives in that file and nowhere else.
|
|
58
|
+
- **Technique:** Work through the first-hour list with the owner. Other documents link to the bar file instead of copying its numbers. When the owner raises or changes the bar, update the file that day and add a register row quoting the change.
|
|
59
|
+
- **Reference configuration:** OC's kickoff asked for "60fps minimum but up to 120/240fps", and the first written budget came at R79. Boss HP in code was 60,000 against a spec of 400,000; the boss had 3 phases against 4; gate angles changed 3 times across 3 agents. The character canon said 2.2 heads tall where the turnaround measured 2.7. The owner, briefing the film team: "i do NOT want to have to keep watching shitty takes and giving u feedbaxk thqt u should be able to know ill give u".
|
|
60
|
+
- **Applies when:** Every game an owner will review over more than a few rounds.
|
|
61
|
+
- **Verify:** Grep the repository for each spec number: it appears in the bar file and in the code that reads it. A new agent answers "what is the phone frame-rate floor" from the file alone.
|
|
62
|
+
|
|
63
|
+
### Done means it shows in a build the owner can open
|
|
64
|
+
- **Invariant:** Nothing is reported to the owner as done until it is seen or heard in a promoted build at the latest playable address, reached through the real menu, with a capture as proof.
|
|
65
|
+
- **Technique:** Track each change through written, merged, built, seen in the built round, and promoted. Report only the last two as done and call the rest in progress. Declare a launch build only when every top-priority register row is closed with proof from that build. See `opengame-verification` for proving a change ran.
|
|
66
|
+
- **Reference configuration:** OC's reports of work never seen in a build are in `opengame-verification`. One register sync closed 4 of about 330 rows. "Launch build" was declared at R164, R181, R184, R186, R187, R193 and R196.
|
|
67
|
+
- **Applies when:** Every report to an owner, every round.
|
|
68
|
+
- **Verify:** Every "done" in a status update links a capture from the promoted build that the same update names.
|
|
69
|
+
|
|
70
|
+
### One ask register that every handoff reads first
|
|
71
|
+
- **Invariant:** Every request the owner has made is a row in one file, in the owner's own words, with a status and evidence, and every agent that takes over reads it before working.
|
|
72
|
+
- **Technique:** Turn each new owner message into rows before starting work. A row holds the quote, the date, the class it belongs to, the status (fixed, partial, not fixed, cannot check yet) and the build and capture that prove it. Add only asks the owner made, and check a relayed decision against the owner's quote before acting on it. Close the top-priority rows before taking new scope.
|
|
73
|
+
- **Reference configuration:** OC built its register on day 5 from 384 owner messages spread over several agent threads, which gave 179 requirements; "66 of 67 inherited acceptance rows remain open" after about 25 handoffs. It grew to 331 rows with 321 open, so a register alone does not close asks. One orchestrator told workers the owner had asked "several times" for a plain rifle; he had not. New game modes were added while the frame-rate floor and phone boot were still open.
|
|
74
|
+
- **Applies when:** Every project with more than one agent session or more than a day of feedback.
|
|
75
|
+
- **Verify:** Pick owner messages at random from the chat history: each maps to a row with a status and an evidence link.
|
|
76
|
+
|
|
77
|
+
### One integrator merges every change
|
|
78
|
+
- **Invariant:** One agent merges every change into the source that rounds are built from. Workers deliver small patches against a named base and never edit the integration tree.
|
|
79
|
+
- **Technique:** Each delivery is a patch, the base commit or file hash it was written against, the files it touches, and a capture or test from the worker's private copy. The integrator merges three-way, sends back any delivery on a stale base, has an agent that did not write it review each one for defects, and lands it inside the open round. Run one worker per stream and one root at a time, with a lock file for the root.
|
|
80
|
+
- **Reference configuration:** OC once had 19 workers staging dozens of patches while 66 of 67 gates stayed open from 03:18 to 21:12. A stale-base delivery reverted a feature and broke 2 builds. With two teams sharing builds, rounds went from about every 15 min to about every 40. From R138 one integrator with a review per delivery ran the loop; every review found a real bug, and film notes went from waiting on a shipping round to 10 of 11 shipped in about 36 h. Before that, duplicate workers ran in 9 or more streams and two roots ran at once for 27 min.
|
|
81
|
+
- **Applies when:** Any build with more than one agent writing code.
|
|
82
|
+
- **Verify:** The integration branch has one committer, and each merge links its delivery's base hash and review.
|
|
83
|
+
|
|
84
|
+
### Rounds are frozen snapshots on a fixed clock, each with a receipt
|
|
85
|
+
- **Invariant:** Each round is built from an instant copy of the integrated source taken at a set time, nobody edits that copy, and the round's receipt says what is in it.
|
|
86
|
+
- **Technique:** Cut on a clock agreed with the owner. Take the snapshot as a commit or a copy-on-write clone so the freeze lasts seconds. A change that misses the cut goes in the next round. Write a receipt per round with the source commit, build id, file hashes, the register rows it addresses and its test results. Promote only after a smoke test through the real menu with real input.
|
|
87
|
+
- **Reference configuration:** OC agreed a 25-min build clock with sub-minute snapshot freezes, after code freezes of about 20 min per build had slowed the loop. An optic fix landed 9 min after the R91 snapshot and shipped a round late; one cut came 2 h late while private builds held the slots; snapshots failed when source changed during the build at R166, R186 and R189-R190. OC built from frozen source clones from R90, checked 701 artifacts per build from R108, and smoke-tested 60-90 s of normal play before promotion.
|
|
88
|
+
- **Applies when:** Every project with more than a handful of rounds.
|
|
89
|
+
- **Verify:** For any promoted round, the receipt's hashes match the served files and the snapshot time is later than every commit in it.
|
|
90
|
+
|
|
91
|
+
### One latest playable address
|
|
92
|
+
- **Invariant:** One permanent address always opens the newest promoted build, every round also keeps its own address, and the sender opens a link before sending it.
|
|
93
|
+
- **Technique:** Serve builds from a supervised server on a fixed host and port, started outside any agent session so agent restarts leave it running. Promotion moves the latest address to the new round; older rounds stay at their own paths for comparison and rollback. Label an unpromoted build as untested when you share it. Show the build id on screen in the game.
|
|
94
|
+
- **Reference configuration:** OC's owner asked which localhost was the latest about 12 times. A latest address existed only from day 5, and it was then down for 3 days. "Localhost not up" was reported 6 times, and agent restarts killed preview servers up to 9 times a day, 20-40 min each. The stable build was not promoted from R96 to R137. The owner: "every time a new round is ready show me the build link where i can play it".
|
|
95
|
+
- **Applies when:** Every project where the owner plays builds.
|
|
96
|
+
- **Verify:** Restart every agent session: the latest address still serves the newest promoted build, and its on-screen build id matches the last receipt.
|
|
97
|
+
|
|
98
|
+
### A usage-limit death loses nothing
|
|
99
|
+
- **Invariant:** When every agent stops at once, the work done so far is on disk, committed or saved as a patch, and fresh agents resume from the files alone.
|
|
100
|
+
- **Technique:** Keep concurrent agents under the account's usage budget. Commit or save a patch often. Keep a brief per role on disk and a ledger line per unit of work, and have each handoff name the predecessor's last line and last report. Run builds and long jobs detached from agent sessions. After a death, start fresh agents from the reports on disk rather than resuming dead contexts.
|
|
101
|
+
- **Reference configuration:** OC had about 25 whole-team usage-limit deaths in about 7 days, each stopping 8-25 agents in the middle of edits and leaving 27-211 dirty files; about 36 of the 160 hours before launch made no progress. Each new wave spent 20-60 min re-auditing. Cutting from 20 agents to 17 did not prevent the next death; the root later capped itself at 4. One orchestrator died having committed nothing, and its diffs survived only as patch files. OC commits every 20-30 min.
|
|
102
|
+
- **Applies when:** Every build that uses agents on metered accounts.
|
|
103
|
+
- **Verify:** Stop every agent at a random moment: fresh agents resume from the files and lose no more than the commit interval.
|
|
104
|
+
|
|
105
|
+
### Heavy jobs are capped against load, and measurements wait for a quiet window
|
|
106
|
+
- **Invariant:** Builds, browsers, captures and renders run under a job cap set from the machine's cores, load and free disk, and every performance number comes from a run with no competing heavy work.
|
|
107
|
+
- **Technique:** Run heavy jobs through one slot wrapper whose cap someone set from the hardware. Agree the compute share between teams in writing before production. Log competing CPU with every perf run and reject runs over the limit. Keep a free-disk floor and pause captures before it. Schedule quiet windows for perf work, measure interleaved A/B pairs inside them, and leave screenshot frames out of timing.
|
|
108
|
+
- **Reference configuration:** OC's 16-core machine ran at load averages of 150-361, with 19-36 jobs waiting for 3-6 slots; the slot cap "was just a default". Jobs hit their own timeouts while waiting, free disk fell to 400 MB and killed a run, and the owner's own play lagged. The perf-run rejection rule and OC's false regression are in `opengame-verification`. The game and film teams agreed a 45/45/10 split after more than 40 h of contention, and quiet windows blocked builds for 20-60 min each.
|
|
109
|
+
- **Applies when:** Every project running several agents, browsers or renders on one machine.
|
|
110
|
+
- **Verify:** Each perf result prints the load and competing CPU during its run, and the wrapper's log shows the cap held.
|
|
111
|
+
|
|
112
|
+
### Batch the owner's feedback and sweep the class
|
|
113
|
+
- **Invariant:** Each owner message or play session becomes register rows, each fix covers every instance of its class, and the batch lands in one round instead of one item per round.
|
|
114
|
+
- **Technique:** Read the whole batch before starting. Name each item's class and list its members. Split the batch across workers in parallel, integrate it in one round, and reply per item with the round and a capture. Ask the owner only what blocks a decision; decide the rest and say what you decided. When tuning a value the owner disliked, change one variable at a time.
|
|
115
|
+
- **Reference configuration:** OC's owner sent a 50-item play-test list on day 2. "we should NOT just be fixing things piecemeal if i send you one example you should be sweeping to make sure by yourself that doesnt exist with anything else of the same thing." The class sweep and OC's gun numbers are in `opengame-quality-bar`. Difficulty swung from "not even killing me" to death in 0.37 s, then settled at 3 hits to down once changes were made one at a time. On day 7: "im not gonna answer any more questions, ive asked for this to be fixed many times".
|
|
116
|
+
- **Applies when:** Every owner message with more than one item, and every report about one member of a set.
|
|
117
|
+
- **Verify:** The reply to a batch lists every item with its round and capture, and each class fix links a sheet of all its members.
|
|
118
|
+
|
|
119
|
+
### Reference first for iconic items
|
|
120
|
+
- **Invariant:** An item with a canonical look (a famous weapon, a real vehicle, a known creature) is built from measured reference of the real shape before its first build, and judged side by side with that reference under one camera.
|
|
121
|
+
- **Technique:** Collect a reference model or several orthographic views first. Extract proportions and a materials list, match the reference camera, compare silhouettes from the side, top and back, and write a beat-by-beat spec for how it animates. Keep reference files and trademarked names out of the shipped build.
|
|
122
|
+
- **Reference configuration:** OC's Ray Gun went through about 14 builds made from a texture sheet and a 64 px icon, and the owner rejected all of them in one message. The agent: "I built the earlier version without enough reference work." It passed only after the owner sent 6 images and the proportions were measured; the numbers are in `opengame-weapons`.
|
|
123
|
+
- **Applies when:** Every item the owner or players will compare with a version they already know.
|
|
124
|
+
- **Verify:** A split-view sheet shows reference and build under one camera with the silhouette overlap.
|
|
125
|
+
|
|
126
|
+
### Status on a fixed cadence
|
|
127
|
+
- **Invariant:** The owner hears from the project at an agreed interval, and each update says what to play, what changed and what is next, with the link and the comparison sheets shown inline.
|
|
128
|
+
- **Technique:** Agree the interval in the first hour. Post improved, failing and next, with sheets as images, never file paths or hashes. Skip an update with no news, and do not go quiet past the interval: say what is running and when it lands. A blocked agent names the exact blocker and what it needs, or moves to the next item.
|
|
129
|
+
- **Reference configuration:** OC's owner asked for updates every 10-15 min. About 60% of one transcript was heartbeat boilerplate ("why do you keep sayin gno change?"). One agent spent about 11 h reporting an old blocked status and then wrote: "There's no current code or permission blocker... That was my mistake."
|
|
130
|
+
- **Applies when:** Every project where the owner waits on rounds.
|
|
131
|
+
- **Verify:** The update log has no gap longer than the agreed interval, and each update has a link and at least one sheet.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Templates
|
|
2
|
+
|
|
3
|
+
Plain files on disk, so a fresh agent can pick them up after a usage limit or a restart.
|
|
4
|
+
Keep them in the repository beside the bar file.
|
|
5
|
+
|
|
6
|
+
## Ask register row
|
|
7
|
+
|
|
8
|
+
One row per ask. The quote is the owner's own words, copied from the message.
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
| id | date | quote | class | priority | status | round | evidence |
|
|
12
|
+
| A-41 | 18 Oct | "never load any low poly versions of guns ANYWHERE" | every gun, every path that shows one | P0 | partial | R92 | sheets/r92-guns.png (box spin still shows a stand-in) |
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Status is one of fixed, partial, not fixed, cannot check yet. "Fixed" needs a capture
|
|
16
|
+
from a promoted round. The class column names what the sweep covers. A relayed request
|
|
17
|
+
gets a row only after someone finds the owner's own message for it.
|
|
18
|
+
|
|
19
|
+
## Delivery note
|
|
20
|
+
|
|
21
|
+
What a worker hands the integrator with each patch.
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
stream: weapons-optics
|
|
25
|
+
base: 3f2a9c1 (or the sha256 of each file the patch was written against)
|
|
26
|
+
files: src/weapons/optics.ts, assets/guns/manifest.json
|
|
27
|
+
register rows: A-41, A-57
|
|
28
|
+
proof: captures from the worker's private copy, with the build id on screen
|
|
29
|
+
known gaps: third-person view not captured
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The integrator sends back any delivery whose base is older than the current
|
|
33
|
+
integration tree for the same files.
|
|
34
|
+
|
|
35
|
+
## Round receipt
|
|
36
|
+
|
|
37
|
+
Written by the integrator when the round is cut, before anyone tests it.
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
round: R164
|
|
41
|
+
snapshot: 2026-10-20T23:40Z, source commit 8e01d77
|
|
42
|
+
build id shown in game: R164-8e01d77
|
|
43
|
+
files: manifest of path and sha256 for every shipped file
|
|
44
|
+
addresses rows: A-12 (fixed), A-41 (partial), A-57 (not fixed)
|
|
45
|
+
smoke test: menu to match to results through real input, result and log path
|
|
46
|
+
promoted: yes, latest playable now points here
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
After a deploy, hash what the server returns and compare it with this manifest.
|
|
50
|
+
|
|
51
|
+
## Status update
|
|
52
|
+
|
|
53
|
+
Sent at the agreed interval. Sheets go inline as images.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
Play: <latest playable address> (R164, promoted 23:58)
|
|
57
|
+
Improved: hip size per gun class now matches the reference frame (sheet)
|
|
58
|
+
Failing: real iPhone still reloads at the end of the load bar; cause narrowed to texture memory
|
|
59
|
+
Next: R165 at 00:25 with the phone memory fix and the reload sweep
|
|
60
|
+
Decided without asking: kept Ultra as the default and added a one-step fallback to High
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Leave out hashes, internal stream names and heartbeats with no news.
|