@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.
Files changed (75) hide show
  1. package/AGENTS.md +238 -0
  2. package/CHANGELOG.md +22 -0
  3. package/README.md +129 -2
  4. package/dist/cli.mjs +1432 -0
  5. package/dist/opengame-global.js +49 -0
  6. package/dist/opengame-global.js.LEGAL.txt +1 -0
  7. package/dist/preflight-worker.mjs +20 -0
  8. package/dist/runtime-builder.mjs +800 -0
  9. package/dist/runtime-catalog.json +1 -0
  10. package/dist/runtime-catalog.sha256 +1 -0
  11. package/dist/runtime-shells/runtime-shell.html +4 -0
  12. package/dist/runtime-shells/runtime-shell.js +91 -0
  13. package/dist/safe-fs.py +242 -0
  14. package/dist/skills/manifest.json +516 -0
  15. package/dist/skills/opengame-accessibility/SKILL.md +90 -0
  16. package/dist/skills/opengame-api/SKILL.md +85 -0
  17. package/dist/skills/opengame-assets/SKILL.md +124 -0
  18. package/dist/skills/opengame-assets/references/pipeline.md +97 -0
  19. package/dist/skills/opengame-audio/SKILL.md +154 -0
  20. package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
  21. package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
  22. package/dist/skills/opengame-capture/SKILL.md +108 -0
  23. package/dist/skills/opengame-capture/references/pipeline.md +82 -0
  24. package/dist/skills/opengame-capture/references/threejs.md +145 -0
  25. package/dist/skills/opengame-characters/SKILL.md +129 -0
  26. package/dist/skills/opengame-characters/references/integration.md +144 -0
  27. package/dist/skills/opengame-characters/references/player-og.md +160 -0
  28. package/dist/skills/opengame-cli/SKILL.md +118 -0
  29. package/dist/skills/opengame-deploy/SKILL.md +207 -0
  30. package/dist/skills/opengame-deploy/references/json-events.md +62 -0
  31. package/dist/skills/opengame-deploy/references/manifest.md +83 -0
  32. package/dist/skills/opengame-deploy/references/packaging.md +117 -0
  33. package/dist/skills/opengame-depth/SKILL.md +130 -0
  34. package/dist/skills/opengame-enemies/SKILL.md +103 -0
  35. package/dist/skills/opengame-enemies/references/threejs.md +134 -0
  36. package/dist/skills/opengame-front-end/SKILL.md +143 -0
  37. package/dist/skills/opengame-front-end/references/launch.md +50 -0
  38. package/dist/skills/opengame-front-end/references/menus.md +47 -0
  39. package/dist/skills/opengame-game-feel/SKILL.md +137 -0
  40. package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
  41. package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
  42. package/dist/skills/opengame-jam/SKILL.md +103 -0
  43. package/dist/skills/opengame-lighting/SKILL.md +94 -0
  44. package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
  45. package/dist/skills/opengame-loading/SKILL.md +99 -0
  46. package/dist/skills/opengame-loading/references/threejs.md +116 -0
  47. package/dist/skills/opengame-look/SKILL.md +114 -0
  48. package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
  49. package/dist/skills/opengame-mobile/SKILL.md +90 -0
  50. package/dist/skills/opengame-performance/SKILL.md +140 -0
  51. package/dist/skills/opengame-performance/references/measuring.md +72 -0
  52. package/dist/skills/opengame-production/SKILL.md +131 -0
  53. package/dist/skills/opengame-production/references/templates.md +63 -0
  54. package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
  55. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
  56. package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
  57. package/dist/skills/opengame-router/SKILL.md +51 -0
  58. package/dist/skills/opengame-router/references/process.md +38 -0
  59. package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
  60. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
  61. package/dist/skills/opengame-sdk/SKILL.md +270 -0
  62. package/dist/skills/opengame-sdk/references/engines.md +93 -0
  63. package/dist/skills/opengame-sdk/references/frame.md +107 -0
  64. package/dist/skills/opengame-sdk/references/identity.md +112 -0
  65. package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
  66. package/dist/skills/opengame-sdk/references/radio.md +71 -0
  67. package/dist/skills/opengame-stability/SKILL.md +84 -0
  68. package/dist/skills/opengame-verification/SKILL.md +136 -0
  69. package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
  70. package/dist/skills/opengame-weapons/SKILL.md +109 -0
  71. package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
  72. package/dist/skills/opengame-weapons/references/threejs.md +169 -0
  73. package/dist/skills/opengame-world-physics/SKILL.md +114 -0
  74. package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
  75. package/package.json +38 -4
@@ -0,0 +1,105 @@
1
+ # Leaderboards
2
+
3
+ ## Declare the board
4
+
5
+ Every board the game uses is declared in `opengame.json`, up to
6
+ 10 of them:
7
+
8
+ ```json
9
+ { "leaderboards": [{ "key": "rounds", "order": "desc", "label": "Rounds survived", "min": 0, "max": 75 }] }
10
+ ```
11
+
12
+ `order` is `desc` when bigger is better and `asc` for times. `min` and `max` reject the
13
+ absurd; they do not stop cheating. Changing a board's bounds, order, keep rule, columns or
14
+ variants starts a fresh board locally.
15
+
16
+ ## The calls
17
+
18
+ ```js
19
+ const board = og.leaderboard('rounds')
20
+ const saved = await board.submit(14, { mode: 'coop' }) // value: { score, state, best, preview }
21
+ const top = await board.top({ limit: 10 }) // value: { entries, order, preview, source }
22
+ const mine = await board.me() // value: an entry, or null before a score
23
+ const nearby = await board.around() // entries around the player
24
+ ```
25
+
26
+ - `submit` takes a finite number. The stored `state` is `ok`, `clamped` (pulled back
27
+ inside the board's bounds) or `rejected`. `best` says whether it beat the player's
28
+ previous best; only accepted scores appear in reads.
29
+ - `top` reads up to 100 entries, 50
30
+ by default. `around` returns up to 10 entries
31
+ either side of the player. Reads are cached for 30 seconds.
32
+ - Entries carry `name`, `score`, `meta`, `createdAt`, `rank` and `isMe`. Show `name` as
33
+ given; a few old rows are `null`.
34
+ - `source` is always `game_reported`. Show it as the game's own scoreboard, never as a
35
+ verified result or a prize standing.
36
+
37
+ ## Columns, variants and runs
38
+
39
+ A board can declare stat `columns` beside its score, `variants` a run is tagged with, and
40
+ `keep`: `best` shows each player once, and `runs` keeps every run, up to a per-player count
41
+ the board declares for each combination of tags. The SDK README has a full declaration.
42
+
43
+ ```js
44
+ const run = await board.submitRun({ value: 14, stats: { kills: 212, time: 1284.5 }, tags: { mode: 'coop' } })
45
+ const solo = await board.top({ sort: 'kills', filter: { mode: 'solo' }, limit: 25, offset: 25 })
46
+ const mine = await board.me({ filter: { mode: 'coop' } })
47
+ ```
48
+
49
+ - `submit(value, meta)` is `submitRun({ value, meta })`. A stat the board does not declare
50
+ is dropped and named in the receipt's `ignored`; a tag it does not declare fails with
51
+ `invalid_run`, whose reason names the field. Stats are checked against their column's
52
+ `min` and `max` like the score, and they are the game's claim too.
53
+ - `sort` is `score` or a sortable column, `filter` names declared variant values, and
54
+ `offset` pages `top()`. Anything else fails with `invalid_query`.
55
+ - Entries carry `stats` and `tags`. A page carries `total` (rows under the filter),
56
+ `offset`, `sort`, `filter` and `shape`, the board's labels and formats for drawing it.
57
+ - Locally a board keeps one entry, this browser's best, whatever its keep rule.
58
+
59
+ ## Metadata
60
+
61
+ Allowed keys and types: `label` (string), `mode` (string), `level` (string), `character` (string), `duration_ms` (number), `accuracy` (number), `combo` (number). Strings up to
62
+ 24 characters, 384 bytes in
63
+ all. Contact-like text is refused, including short email addresses and long digit runs.
64
+ Use metadata for game context ("coop", "hard", "level 3"), never personal details.
65
+
66
+ ## Results, not exceptions
67
+
68
+ Every call resolves to `{ ok: true, value }` or `{ ok: false, error, reason }`. The
69
+ errors to handle: `rate_limited`, `board_unavailable`, `invalid_score`, `invalid_meta`,
70
+ `invalid_run`, `invalid_board`, `invalid_limit`, `invalid_query`, `invalid_manifest`,
71
+ `invalid_request` and `unavailable`. Requests stop after
72
+ 5 seconds. Show a quiet "Scores are unavailable right now"
73
+ and let the player keep playing; never block a retry screen on a leaderboard.
74
+
75
+ ## Previews and local play
76
+
77
+ Scores from the owner's private preview are kept separate from public scores and say
78
+ `preview: true`. Outside OpenGame, boards live in `localStorage` per page folder; the
79
+ first board call reads `./opengame.json` beside the page, or pass the imported manifest
80
+ to `og.init({ manifest })` when the build moves it.
81
+
82
+ ## Achievements
83
+
84
+ Declare each one in `opengame.json`, up to 100:
85
+
86
+ ```json
87
+ { "achievements": [{ "id": "first_win", "title": "First win", "description": "Win a round." }] }
88
+ ```
89
+
90
+ `opengame check` validates them, and a deploy saves them when its preview is ready.
91
+ Removing one from the file does not switch it off; the SDK README says how.
92
+
93
+ ```js
94
+ const unlocked = await og.achievements.unlock('first_win') // value: { achievementId, unlocked, firstUnlock, unlockedAt, source }
95
+ const mine = await og.achievements.list() // value: every declared achievement, unlocked or not
96
+ ```
97
+
98
+ - Unlock once per moment, not every frame: keep a set of what this run already sent.
99
+ - A private preview answers `unavailable_in_preview`, so a declared achievement first
100
+ unlocks on the published game. Other failures are `invalid_achievement` (an id that
101
+ is malformed or not declared), `achievement_unavailable`, `unavailable` (no session),
102
+ `session_changed`, `network` and `invalid_response`.
103
+ - Outside OpenGame, and before `og.init()` has resolved, every achievement call answers
104
+ `unavailable`. Unlike boards, achievement results carry `error` and no `reason`.
105
+ - Like scores, every unlock is `source: 'game_reported'`: the game's own claim.
@@ -0,0 +1,71 @@
1
+ # OG Radio
2
+
3
+ `radio` lets players browse OG Radio and listen while they play. The OpenGame page
4
+ plays the music at the player's own radio volume and keeps playing it in the site's player
5
+ after the game closes. The game never receives audio, so nothing changes in its audio
6
+ graph or its content security policy.
7
+
8
+ Reach it as `OpenGame.radio` in a game served by OpenGame, or bundle it:
9
+
10
+ ```js
11
+ import { radio } from '@opengamehq/sdk/radio'
12
+ ```
13
+
14
+ Check `radio.available`. It is false outside OpenGame and under `opengame dev`, where
15
+ every call returns `unavailable`: test the radio in a private preview.
16
+
17
+ ## The picker
18
+
19
+ ```js
20
+ const picker = radio.mountPicker(menuElement, { theme: { accent: '#ff3b30', radius: '4px' }, title: 'Music' })
21
+ picker.destroy() // when the menu closes
22
+ ```
23
+
24
+ All radios and each station with its song count down the left; a search field, the
25
+ station's genres and a numbered A to Z song list on the right; play, previous, next,
26
+ shuffle, repeat and volume along the bottom. Theme it with `theme` (`background`,
27
+ `surface`, `text`, `muted`, `accent`, `accentText`, `border`, `radius`, `font`), the same
28
+ values as `--og-radio-*` custom properties, or `::part()` (`panel`, `stations`, `station`,
29
+ `search`, `genres`, `genre`, `list`, `song`, `controls`, `control`, `volume`, `status`).
30
+ Keys inside it (`/`, arrows, Enter, Space, N, P, S, R, - and =) stop at the picker;
31
+ `{ shortcuts: false }` turns the letters off.
32
+
33
+ ## Your own controls
34
+
35
+ ```js
36
+ const stations = await radio.stations() // A to Z, with counts and genres
37
+ const page = await radio.tracks({ station: 'pixel', genre: '8bit', q: 'dawn', offset: 0 })
38
+ row.onclick = () => radio.play({ track: song.id, genre: '8bit' })
39
+ radio.onChange(state => render(state.playing, state.track))
40
+ ```
41
+
42
+ - `radio.tracks({ station, genre, q, offset, limit })`: `station` is a station id or `'all'`
43
+ (the default). `genre` needs a station. `q` searches titles within that scope only,
44
+ ignoring case and accents. At most 200 songs a page,
45
+ always A to Z by title; `total` counts every match.
46
+ - `radio.play()` resumes; `radio.play({ track })` plays a song (Next stays on its station, or
47
+ within `genre` when given); `radio.play({ station, genre })` tunes a station or genre.
48
+ - `radio.pause()`, `radio.next()`, `radio.previous()`, `radio.setShuffle(on)`,
49
+ `radio.setRepeat(on)`, `radio.setVolume(level)` with a level from 0 to 1.
50
+ - A song has `id`, `title`, `station`, `stationName`, `genre`, `genreLabel`, `palette` and
51
+ `attribution`. `art` is null (no cover art) and `duration` is null until it plays.
52
+ - `radio.state` is the last state reported. Its `station`, `track`, `genre`, `volume`,
53
+ `shuffle` and `repeat` stay null until the game has played the radio itself, so it never
54
+ learns what the player chose elsewhere or what another game left. `playing` is always there.
55
+
56
+ ## Rules
57
+
58
+ - Sound needs a press: `play`, `next`, `previous`, shuffle, repeat and turning the volume
59
+ up, from a click or key handler, or `gesture_required`. A press counts for a few
60
+ seconds, as the browser's own rule does.
61
+ - `muted` while the player has the game's sound off on OpenGame, or another part of the page
62
+ has the speakers; turning the game's sound off pauses radio the game started. Pausing and turning down always work.
63
+ - A pause the player makes in OpenGame's own player stands: the game cannot restart the
64
+ radio for a few seconds, and then only from a new press.
65
+ - `setVolume` goes up only as far as the player set the radio, in steps of 0.05. A volume
66
+ a game sets goes back to the player's when the game closes and is never remembered.
67
+ - 120 requests a minute (`busy` past that),
68
+ searches up to 64 characters, `timeout` after
69
+ 5 seconds.
70
+ - `not_found` for an unknown station, genre or song id; `invalid_request` for a bad argument.
71
+ - Show a song's `attribution` wherever the game credits music.
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: opengame-stability
3
+ description: Make a browser game crash-free on every device and browser, and prove it. Covers zero crashes as the release bar, soak tests over hundreds of full sessions, fixed pools named, counted and warned before full, crash reports that survive reload, a watchdog that tells a slow load from a hang, recovery that never loops, GPU device loss, dev commands off in public builds and the served build checked after each deploy. Use when the game crashes, freezes, reloads itself or breaks after a deploy.
4
+ metadata:
5
+ version: "1.0.0"
6
+ ---
7
+
8
+ # Stability
9
+
10
+ A crash ends the session and usually the player. OC's (OG Clash's) owner asked for zero
11
+ crashes about 25 times ("we CANNOT have any crashES EVER on ANY device ANYWHERE").
12
+ Crashes took about five days to close from the first ask, among the slowest of any
13
+ problem, and stayed open on iPhone after launch. In the end a gate of full sessions on
14
+ real devices held, along with crash reports that named the cause and pools that warned
15
+ before they were full.
16
+
17
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. Phone
18
+ memory kills are in `opengame-mobile`; load stalls and retries in `opengame-loading`;
19
+ proving a fix ran in `opengame-verification`.
20
+
21
+ ## Rules
22
+
23
+ ### Zero crashes is the release gate
24
+ - **Invariant:** A build ships only when full sessions on every target device and browser end with no crash, freeze, self-reload or lost input, and a load that times out counts as a failure, not as clean.
25
+ - **Technique:** Keep a matrix of device class by browser by flow: cold boot to play, a full match with real input, pause and resume, a returning player with saved settings, a tab switch, a resize or rotation storm, and a GPU device loss. Drive it with real key, mouse and touch input from the title, not a shortcut into the match. Stress each crash class the game has: ammo refills, corpse and debris load, spawn bursts, character and weapon switches. Treat release-build assertions as live code: guard divisions by zero, negative indices and non-finite values. Count time on both the game clock and the wall clock.
26
+ - **Reference configuration:** OC's bar: 200 or more consecutive clean sessions, 20 cold boots per device class including a 6x CPU throttle, 60 s of live combat, pause and resume, and a returning player, with load timeouts never counted as clean. Real devices belong in the matrix (`opengame-mobile`).
27
+ - **Applies when:** Every game anyone outside the team will play.
28
+ - **Verify:** The gate prints its matrix with a clean or failed verdict per cell and the session count behind each; one failed cell blocks the release.
29
+
30
+ ### Soak full runs and count crashes per hundred sessions
31
+ - **Invariant:** Stability is measured as a crash count over many complete runs with real input, long enough to reach the late-game states where crashes live, not by one smoke test.
32
+ - **Technique:** Run whole matches end to end, many times, on every platform in the matrix, and keep a running crash count per build. Include cold loads as their own count. Make each soak session start from a cold boot and end at results, and log the build id, device and the last screen in every record. A short smoke test before promotion is a boot check, not a stability claim.
33
+ - **Reference configuration:** OC's crashes hit 57-437 s into play (a physics write past the end of an array, read as memory exhaustion for about 40 rounds) and 78-185 s into play (R94-R101), past the 90 s smoke test. After fixes: 0 WebAssembly traps in 300 or more gate sessions (R163-R181), 45 of 45 on the R163 matrix, and 60 of 60 cold loads on each of 3 platforms. That R164 "60/60" ran in Chrome emulation, and the real iPhone crashed within a day of launch.
34
+ - **Applies when:** Every game with sessions longer than a minute.
35
+ - **Verify:** The release note states sessions run, crashes seen, and cold loads per platform, each tied to the build id, and lists which counts came from real devices.
36
+
37
+ ### Every fixed pool is named, counted live and warned before it is full
38
+ - **Invariant:** Every fixed-size table (materials, textures, particles, decals, lights, trails, handles, audio voices, touch slots, instance buffers) has a declared size, a live count and a recorded peak, and warns before it fills; on overflow the game drops the lowest-priority item and logs an error that names the pool.
39
+ - **Technique:** Register every pool in one table with its name, size, current count and peak. Show the table in a debug overlay and write it into crash reports. Warn when a pool passes a high share of its size. On overflow in development, throw an error naming the pool and its size; in release, drop the lowest-priority item, log once, and keep running. Where pool sizes are sums written by hand, compute them at build time from the content instead. Three.js: read `renderer.info.memory` (geometries, textures) and `renderer.info.programs.length`, keep your own counts for particle, decal and voice pools, and `dispose()` on unload.
40
+ - **Reference configuration:** OC hit at least 15 distinct caps: at least 8 crashed or hung a build and at least 4 failed with no message (audio sources, touch buttons, local lights, hide lists). A trail cap of 444, a sum typed by hand, crashed R78 at boot and slipped 25 min of every agent's work by a round. Others: handles at 128 and 512, particle materials in a fixed 512 KB buffer, lights at 280 with overflow a crash, decals 256 of 256, batch instances 192 of 192. A material table of 4,096 filled at about 85 a second because one retry ran 2,432 times. The audio mixer dropped 75% of cues without a word.
41
+ - **Applies when:** Every game, and every engine or library with fixed capacities.
42
+ - **Verify:** A stress run (maximum enemies, every effect, every weapon) prints the pool table with peaks; each pool pushed past its warning logs its name, and pushed past its size the game keeps running.
43
+
44
+ ### A crash report names what crashed and survives the reload
45
+ - **Invariant:** Every crash leaves a record with the error, a symbolised stack, the build id, the device, the screen and the last events before it, written locally before the page dies, uploaded on the next load, and kept until the upload is confirmed and readable by the team.
46
+ - **Technique:** Catch `error`, `unhandledrejection`, GPU validation and device-loss events. Keep a ring buffer of recent events (screen changes, spawns, loads, input) and write it with the error to local storage at once. Set a session flag at start and clear it on a clean exit, so the next boot can count a session that died with no error, such as a memory kill. Send a `pagehide` beacon with the outcome. Keep source maps and WebAssembly symbol maps for every release build, private to the team, and keep stacks whole. Give the team a way to read reports back, not only write them.
47
+ - **Reference configuration:** OC's WebAssembly stacks had no names (`f1974 -> f1975`) and the fatal text was lost when the module trapped, so agents rebuilt address maps by hand on every build from R98 to R109. Its reset screen "confirms the recovery handler ran; it does not reveal the cause". Local records were deleted after upload, the report endpoint was write-only, and phone memory kills left nothing. The game cut stacks to 160 characters, which hid the caller for 3 rounds; the cap went to 4,000. The owner was asked to paste DevTools expressions before reloading. OC's run-end analytics event later reported crashes through a `pagehide` beacon.
48
+ - **Applies when:** Every game played outside the developer's machine.
49
+ - **Verify:** Throw from inside one system during a run and reload: the next boot shows or uploads a record whose stack names that function. Kill the tab from the OS: the next boot counts an unclean session.
50
+
51
+ ### The watchdog tells a slow load from a hang
52
+ - **Invariant:** A stall detector measures progress (bytes received, load steps done, frames ticked), keeps a slow but moving load going, trips only on a real hang, names what it was waiting for, and never reloads the page on its own.
53
+ - **Technique:** Give each long job a heartbeat that resets its deadline when it makes progress. Fetch retries and the byte deadline for downloads are in `opengame-loading`. Watch loading by bytes and steps and the main loop by ticks, as separate detectors. When one trips, report the guard, the job and its last progress, and show a recovery card. Keep test-script timeouts out of player builds, and make sure a scripted test that runs past its script ends with a clean message, not a crash.
54
+ - **Reference configuration:** OC's runtime trapped any wait over 10 s, in release. It fired during loads under machine load and on slow phones, showed a crash card and auto-reloaded: "a big part of last night's iPhone crash and reload near 100% loops". A 12.8 s stall loading boss music ended a run. A test-runner timeout message was taken for a game crash by at least 7 streams. Turning the watchdog off with a URL flag was spotted by the owner in the address bar, and a reviewer noted "Watchdog-off suppresses detection; it does not resolve stalls". It was the most widely reported problem, in 14 notes.
55
+ - **Applies when:** Every game with a watchdog, timeout or "loading too long" handler.
56
+ - **Verify:** Throttle the network to slow but steady: no trip. Block one request for good: the trip names that file. Busy-wait the main loop: the frame detector names the system.
57
+
58
+ ### Recovery never loops and never hides a downgrade
59
+ - **Invariant:** After a crash the game recovers to a known screen without reloading itself in a loop, and any fallback build or reduced mode it switches to is shown to the player and keeps every feature.
60
+ - **Technique:** Count unclean sessions per build. Switch to a fallback only after repeated unclean sessions, for a limited time, keyed to that build so a fixed build starts fresh. Show a notice naming the fallback. Test the fallback as a real build with sound, input and saves. Never call `location.reload()` from an error handler.
61
+ - **Reference configuration:** OC's fallback pinned after 2 unclean sessions, for 24 h, per build. One fallback build shipped with no sound.
62
+ - **Applies when:** Every game with a crash handler, a fallback bundle or automatic quality steps.
63
+ - **Verify:** Force two crashes in a row: the third boot runs the fallback with its notice, plays sound and accepts input; deploy a new build: it starts on the full version.
64
+
65
+ ### The game survives losing the GPU
66
+ - **Invariant:** Losing the GPU device or context (a driver reset, a phone reclaiming memory, a long time in the background) leads to a restored game or a one-tap resume card, never a frozen frame.
67
+ - **Technique:** Listen for `webglcontextlost` (call `preventDefault()` so a restore can happen) and `webglcontextrestored`, or for WebGPU's `device.lost` promise, then request a new device and rebuild GPU resources from kept source URLs. Pause the simulation while the device is gone. Three.js: `WebGLRenderer` handles the WebGL events itself, so check that your own render targets, data textures and freed CPU copies come back; for `WebGPURenderer`, check your release's device-loss callback and test it.
68
+ - **Reference configuration:** OC's loading froze at 80% after a GPU device loss, with no recovery, for two rounds. Its runtime could not recreate the device, so OC showed a tap-to-reload card, and device loss joined the crash matrix.
69
+ - **Applies when:** Every WebGL and WebGPU game, most of all on phones and laptops that switch GPUs.
70
+ - **Verify:** Mid-match, call `WEBGL_lose_context.loseContext()` then `restoreContext()` (or `device.destroy()` on WebGPU): the game comes back or shows the card, and play continues after it.
71
+
72
+ ### Dev commands do not work in public builds
73
+ - **Invariant:** A public build has no URL parameter, console hook or key that changes game state, grants items, skips progress or turns off a safety check, and runs that used a dev command never reach a leaderboard.
74
+ - **Technique:** Strip dev code at build time behind a build flag. If a dev surface must ship, gate it behind a key the server checks or a stored hash, never a plain parameter. Mark runs that used dev commands and have the leaderboard server reject them. Search the shipped bundle for dev markers as part of the release check.
75
+ - **Reference configuration:** OC's `?commands=` parameter and a global command hook worked on the public host; an agent guessed a URL could hand out a wonder weapon. OC fixed it with a key stored only as a SHA-256 hash.
76
+ - **Applies when:** Every game with debug commands, cheats or test hooks.
77
+ - **Verify:** On the public URL, try every dev parameter and console hook: nothing changes. Grep the shipped files for the dev command names: none match.
78
+
79
+ ### The served build is checked against the tested build after every deploy
80
+ - **Invariant:** After each deploy, the files the public URL serves match, by hash, the build that passed the gate, and the previous good build can be restored in about a minute.
81
+ - **Technique:** Write a build receipt listing every file and its hash. After deploy, fetch the entry document and every file, or at least every entry point and binary, from the public URL with caches bypassed, and compare. Make the deploy script stop with an error on a mismatch instead of logging and carrying on. Keep earlier builds on the host under their hashed names so a rollback only points the entry document back. Rebuild every platform variant from the same source on every round. After the hash check, run a cold boot on production.
82
+ - **Reference configuration:** OC's R162 served a binary that did not match its receipt, and "the outer launcher hid that failure". OC checked 701-714 file hashes per round and kept a 1-minute rollback. Its iOS bundle was "last built Oct 17" and shipped stale every round until R160. Production stayed on an old round while a deploy worker tried CDN experiments, and one redeploy did nothing because the script skipped the round being served.
83
+ - **Applies when:** Every self-hosted game. On OpenGame, play the private preview from `opengame-deploy` before calling the release good.
84
+ - **Verify:** Deploy, run the check: it passes. Corrupt one file on the host: it fails and names the file. Time a rollback to the previous build.
@@ -0,0 +1,136 @@
1
+ ---
2
+ name: opengame-verification
3
+ description: Prove a browser game works by using it as a player does. Covers the frame after Play, input that moves the player, a state contract, captures checked for build and screen before judging, the served build matched to its receipt, gates that fail closed, real phones over emulation, and checks that fail once on purpose. Use when the person asks does it work, test my game, verify the fix, before deploying or submitting, after a big change, or when a test passes but the game is broken.
4
+ metadata:
5
+ version: "1.0.1"
6
+ ---
7
+
8
+ # Verification
9
+
10
+ Every defect worth knowing about in our own games was found by playing, not by a build,
11
+ a type check or a test suite, and several were hidden by the very check that should
12
+ have caught them: a test script that entered a sign-in code by focusing each cell by its
13
+ label, which no person can do; an audit that measured zero because it measured nothing.
14
+ So the question to ask is not only "does the check pass" but "what is making this look
15
+ fine?"
16
+
17
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
18
+
19
+ ## Run a player check
20
+
21
+ Use [helpers/browser-evidence.mjs](helpers/browser-evidence.mjs) from a project with
22
+ Playwright installed. The helper starts a muted headless browser, clears network
23
+ cache, clicks Play, holds a key, reads position changes and captures the page.
24
+ Run it through the host's heavy-job wrapper when one is required.
25
+
26
+ Create a synthetic scenario file with `url`, `playSelector`, `key`, `screenshot`,
27
+ `statePath` and `positionPath`. Example paths are `["__og", "state"]` and
28
+ `["player", "position"]`; use the game's actual read-only contract. Supply
29
+ `criteria.movementMin` in game units and `criteria.frameP95MsMax` from a measured
30
+ baseline and the target hardware. `holdMs`, `soakMs` and `cpuThrottle` set the budget.
31
+
32
+ Run `node <installed-skill>/helpers/browser-evidence.mjs scenario.json`. Exit zero
33
+ means movement, frame time and browser error criteria passed. Inspect the screenshot
34
+ and confirm the level and phase yourself. A script result alone cannot establish
35
+ that the correct game is visible. Re-run with a blocked player or delayed frames to
36
+ verify that the measurement fails. Keep credentials out of the scenario and capture.
37
+
38
+ ## Rules
39
+
40
+ ### Capture the frame one second after Play
41
+ - **Invariant:** The first moment of play is seen, through the real menu, on every change that could affect it.
42
+ - **Technique:** Drive a real browser from a cold load through the title and menu with real clicks and keys, press Play, wait one second, and capture the composited page (canvas and HUD together). Serve the build without caching so the browser runs the code on disk.
43
+ - **Reference configuration:** ST captures the frame after Play on every checkpoint; our originals' rule is to serve with no-store, because a caching static server ran stale modules for three separate agents.
44
+ - **Applies when:** Every game.
45
+ - **Verify:** The capture shows the game world, the HUD and the player in control, not a loading screen, a black frame or the menu.
46
+
47
+ ### Check what a capture shows before anyone judges it
48
+ - **Invariant:** Every frame or clip used as evidence is confirmed to show the build, screen, camera and moment it is labelled with, with the player alive, in frame and in control, and every asset loaded, before it is scored or compared.
49
+ - **Technique:** Stamp each capture with the build id, the screen name, the camera mode, the player's health and the loaded-asset count read from the state contract. Run a validator that rejects any capture where those disagree with its label, where a loading, death, title or pause screen shows, or where the HUD has not settled. Report how many captures it rejected and why.
50
+ - **Reference configuration:** OC scored 15 death screens as a gameplay baseline, and its first parity round was game-over frames that still scored 14-19 on the metric. A "shoulder view" was first person, a "gun" shot was the title screen, "profile" shots showed the main menu, "after" frames were taken before models loaded, and a folder named R121 held R86. Coverage reported all valid on those frames. OC waits 300 ms for the UI to settle.
51
+ - **Applies when:** Every capture that a person or a script will score, compare or cite as proof.
52
+ - **Verify:** Plant a death frame, a loading frame and a frame from an older build in a capture set: the validator rejects all of them by name.
53
+
54
+ ### The build under test is the build that was served
55
+ - **Invariant:** Every result names the build it ran on, and the files the browser loaded match that build's receipt.
56
+ - **Technique:** When a build is cut, write a receipt: source commit, build id and a hash of every shipped file. Have the game report its build id in the state contract. Before testing, and after every deploy, hash the files the server returns and compare them with the receipt; any mismatch fails the run and names the file. Rebuild every target (desktop, phone, threaded and not) from the same source each round.
57
+ - **Reference configuration:** OC's R162 served a wasm that did not match its receipt, and the launcher around the check hid the failure. Its iOS bundle had last been built on 17 Oct and shipped stale every round until R160. A claim that two builds matched came from a stale binary copied after a killed build, and shader edits went untested for 3-8 builds because the test build never recompiled them.
58
+ - **Applies when:** Every game with a build step, a CDN, a cache or more than one build target.
59
+ - **Verify:** Change one shipped file after the receipt is written: the check fails and names that file.
60
+
61
+ ### The change is seen running in a built round
62
+ - **Invariant:** A fix counts as done once it is seen or heard in a build from the merged source, reached through real input, with a log line or state value showing its code path ran.
63
+ - **Technique:** Give each change a marker it emits when its path runs (a counter, a log line, a state field). After the round is built, play to it through the real menu and capture it. A change whose marker never fired is not done, however the code reads. Finish endings with real deaths and real wins, with god mode off.
64
+ - **Reference configuration:** OC had about 25 reports in a row say none of the work had been seen in a build, and complaints stayed open 4-5 rounds because fixes landed minutes after the snapshot. Visuals gated on a health value hid the menu chains for 6 rounds; cutscenes set their camera too late in the frame and were "probably never shown"; after a "no proof captures" speed rule, the upright-corpse fix shipped on a path that ran zero times.
65
+ - **Applies when:** Every change reported as fixed, most of all visual and audio changes and anything behind a condition.
66
+ - **Verify:** The report links the capture and the marker count from the built round.
67
+
68
+ ### Gates fail closed
69
+ - **Invariant:** A gate that fails, times out, crashes or did not run reports failure, and its exit status says so.
70
+ - **Technique:** Propagate exit status through every wrapper (no trailing command that resets it). Treat a timeout, a missing validator and a missing result file as failure. Read "it ran" markers written by the game, never lines the test script prints itself. Inject one known failure into each gate when it is written and whenever it changes.
71
+ - **Reference configuration:** OC's gate wrappers ended in an `echo` and exited 0 after a failure; failed acceptance checks still wrote PASS. Timeouts counted as done, "ran" flags matched the test script's own log, a missing validator returned pass, and frame-count QA passed a film cut with 402 frozen frames.
72
+ - **Applies when:** Every script, gate and wrapper whose result anyone acts on.
73
+ - **Verify:** Each gate's history shows one deliberate failing run with a non-zero exit.
74
+
75
+ ### Keep test-script bugs apart from game bugs
76
+ - **Invariant:** Before a failure is filed against the game, someone has shown it happens through real play and not only inside the test script, and each bot run covers what its report says it tested.
77
+ - **Technique:** Review test scripts like game code. Fail fast when the run-start marker is missing. Drive bots with real input and count what they did (shots fired, hits, kills, time spent at the target) from game telemetry. Use staging (god mode, an empty map, extra points, a jump to any round) to reach a moment, and judge feel only on unstaged runs.
78
+ - **Reference configuration:** In one OC range most "failures" were test-script errors: a fixture placed 10 m inside a base, the player sent back to spawn, script overruns read as crashes, and a regex that matched only audio cues. One bot hit the boss's weak points for 8 of 489 s; another fired 240 shots and hit nothing because it aimed at the sky. OC's pass bar became 546 shots and 17 kills, counted from telemetry.
79
+ - **Applies when:** Every automated playtest, bot run or scripted capture.
80
+ - **Verify:** Each bot report states its counts, and a run whose counts fall under the bar fails as a test-script failure.
81
+
82
+ ### A phone pass comes from a real phone
83
+ - **Invariant:** A claim that the game works on phones is backed by a run on a real phone in its real browser, and emulation results are labelled as emulation.
84
+ - **Technique:** Put a mainstream phone in the loop from the first playable build. Cold-load it several times in a row through the real menu, play a full match, and record memory, frame rate, audio and any reload. Desktop emulation of a phone checks layout and touch input and nothing else.
85
+ - **Reference configuration:** Every OC phone gate passed in Chrome's phone emulation while real iPhones crash-looped during load after launch. Emulation also hid missing in-game audio and a real frame rate of 10-20 fps.
86
+ - **Applies when:** Every game that claims phone support.
87
+ - **Verify:** The phone report names the device model, OS version and browser, and links a recording from the device.
88
+
89
+ ### Input moves the player, not just the screen
90
+ - **Invariant:** Pressing a movement or action key changes the game's state, not only the pixels.
91
+ - **Technique:** Read the player's position (or the game's equivalent) before and after holding a key for a fixed time through real key events, and check the change against the expected speed. Do the same for the main action and its consequence.
92
+ - **Reference configuration:** A rule shared across DK, MC, AW and ST. The failure it prevents: a camera that bobs or sways on input makes a frame-difference test pass while the player is stuck against geometry.
93
+ - **Applies when:** Every game with player control.
94
+ - **Verify:** Hold forward through real key events and see the position change by roughly speed times duration; hold it against a wall and see it stop.
95
+
96
+ ### A state contract to assert against
97
+ - **Invariant:** A test can read what the game believes (phase, player position and health, score, what is loaded) without reaching into its internals.
98
+ - **Technique:** In development builds, expose a small read-only snapshot such as `window.__og.state` with the few values tests need, built by the game from its real state each frame. Never let tests write to it.
99
+ - **Reference configuration:** AW reads the loaded map's identity before measuring after a failed load fell back without an error to a stand-in arena that measured faster than the real map.
100
+ - **Applies when:** Every game that will be tested by a script or an agent.
101
+ - **Verify:** The contract reports the real loaded level and phase, and a planted failure (block a required asset) shows up in it.
102
+
103
+ ### Nothing built is left uncalled
104
+ - **Invariant:** Every module, component and asset in the game is reachable from where the game starts.
105
+ - **Technique:** Grep for each new module's name and each generated file's name in the source; follow imports from the entry point. Ban optional calls (`?.()`) at seams between parts of the game, because a call that does nothing, with no error, when its target is missing hides exactly the half-finished handover that breaks games.
106
+ - **Reference configuration:** OpenGame's own platform found a play counter imported nowhere (plays were never counted) and art uploaded to quarantine that was never promoted (every cover 404'd), each with every test green. AW shipped 35 sound files no weapon reached.
107
+ - **Applies when:** Every game, at every handover between two pieces of work.
108
+ - **Verify:** A script lists files under the game's source and assets that nothing references, and the list is empty or explained.
109
+
110
+ ### One check loads the real thing the real way
111
+ - **Invariant:** At least one check exercises each dependency the way production does: the real loader, the real network library, the real audio engine.
112
+ - **Technique:** Alongside fast tests with stand-ins, keep one test that loads every shipped model through the game's own loader, one that makes the game's real network calls in a real browser, and one that calls every public method of the audio engine on a live context.
113
+ - **Reference configuration:** A networking feature once shipped dead because every validator injected its own stand-in and the real script tag was missing. AW's audio had five green checks while a deleted constant threw on the first footstep.
114
+ - **Applies when:** Every game with external libraries, assets or networking.
115
+ - **Verify:** Delete the real dependency on purpose (remove the script tag, rename a model): the real-path check fails, and the stand-in tests do not notice.
116
+
117
+ ### Every check can fail
118
+ - **Invariant:** Every automated check has been seen to fail on a defect it is meant to catch, and reports how many things it examined.
119
+ - **Technique:** Plant the defect (a floating crate, a missing file, a busy-wait in the frame) and require the check to catch it before trusting its zero. A check that examined nothing fails.
120
+ - **Reference configuration:** DK's coplanar audit measured 0 m² on every prop until a planted defect showed its clipping was inverted. AW plants a defect for every map check in every map, and its plants found two bugs in the checks. OC's corpse-spin metric improved with heavier corpses while the corpses looked worse, and the change was reverted after a blind video comparison.
121
+ - **Applies when:** Every audit, gate and test the game relies on.
122
+ - **Verify:** Each check's output names its plant and its examined count.
123
+
124
+ ### Judge motion and sound as sequences
125
+ - **Invariant:** Animation, camera feel, transitions and the mix are judged from recordings over time, never from a single still or a number.
126
+ - **Technique:** Record frame sequences with input for motion; record the mix during the busiest moment and listen to it at a consistent level. Report listening as its own result, separate from loudness numbers.
127
+ - **Reference configuration:** ST records the mix during its playtests and treats peak and loudness readings as never counting as a listening verdict. MC's foot sliding and AW's slideshow remote players were invisible in stills. OC's wonder-weapon sound v3 was pushed to a loudness number without anyone listening, and the owner rejected it on first listen as distorted.
128
+ - **Applies when:** Every game with motion or sound.
129
+ - **Verify:** The report links a recording for every motion and audio claim.
130
+
131
+ ### When two measurements disagree, compare the machines
132
+ - **Invariant:** A disagreement between two runs of the same check is investigated as a fact about the runs before it is treated as a fact about the game.
133
+ - **Technique:** Compare runtime versions, machine load, throttle actually achieved, browser and GPU before changing code. Run heavy suites one at a time.
134
+ - **Reference configuration:** Eight honest reports in OpenGame's own repository disagreed for two days because they ran on two Node versions. AW measured a requested 4x throttle at 1.56x on a saturated machine. OC held a build as a regression when the cause was other browsers on the machine at 131%, 107% and 55% CPU, and a background-priority daemon cut headless Chrome from 105 to 5.6 fps for about 4.5 h. OC rejects a perf run when competing processes use more than about half the cores.
135
+ - **Applies when:** Every time results disagree.
136
+ - **Verify:** The report states the runtime, the load and the throttle for each run being compared.
@@ -0,0 +1,74 @@
1
+ import { createRequire } from "node:module";
2
+ import { readFile, mkdir } from "node:fs/promises";
3
+ import { dirname, resolve } from "node:path";
4
+ import { fileURLToPath } from "node:url";
5
+
6
+ export function assessEvidence({ before, after, framesMs, pageErrors }, criteria) {
7
+ const coordinate = value => Array.isArray(value) && value.length > 0 && value.every(Number.isFinite);
8
+ if (!coordinate(before) || !coordinate(after) || before.length !== after.length || !framesMs.length || !framesMs.every(value => Number.isFinite(value) && value > 0)) throw new Error("Missing position or frame-time evidence.");
9
+ if (!Number.isFinite(criteria.movementMin) || criteria.movementMin <= 0 || !Number.isFinite(criteria.frameP95MsMax) || criteria.frameP95MsMax <= 0) throw new Error("Provide positive game-specific movement and frame-time limits.");
10
+ const distance = Math.hypot(...after.map((value, index) => value - before[index]));
11
+ const sorted = [...framesMs].sort((a, b) => a - b);
12
+ const frameP95Ms = sorted[Math.ceil(sorted.length * 0.95) - 1];
13
+ return { ok: distance >= criteria.movementMin && frameP95Ms <= criteria.frameP95MsMax && pageErrors.length === 0,
14
+ distance, frameP95Ms, frameSamples: framesMs.length, pageErrors: [...pageErrors], criteria };
15
+ }
16
+
17
+ /** Drive player input and measure the game's position contract, rather than inferring
18
+ * movement from changed pixels. The host chooses its own tolerances and soak budget. */
19
+ export async function browserEvidence(config) {
20
+ const url = new URL(config.url);
21
+ if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Use an HTTP(S) game URL without credentials.");
22
+ const require = createRequire(resolve(process.cwd(), "package.json"));
23
+ const { chromium } = require("playwright");
24
+ const holdMs = config.holdMs ?? 500;
25
+ const soakMs = config.soakMs ?? 1000;
26
+ const throttle = config.cpuThrottle ?? 1;
27
+ if (![holdMs, soakMs, throttle].every(value => Number.isFinite(value) && value > 0) || !Array.isArray(config.statePath) || !Array.isArray(config.positionPath) || !config.playSelector || !config.key || !config.screenshot) throw new Error("Specify statePath, positionPath, playSelector, key, screenshot and positive measurement budgets.");
28
+ const browser = await chromium.launch({ headless: true, args: ["--mute-audio"] });
29
+ const errors = [];
30
+ try {
31
+ const context = await browser.newContext({ viewport: config.viewport ?? { width: 1280, height: 720 }, serviceWorkers: "block" });
32
+ const page = await context.newPage();
33
+ page.on("pageerror", error => errors.push(error.message));
34
+ const session = await context.newCDPSession(page);
35
+ await session.send("Network.enable");
36
+ await session.send("Network.setCacheDisabled", { cacheDisabled: true });
37
+ await session.send("Emulation.setCPUThrottlingRate", { rate: throttle });
38
+ const start = performance.now();
39
+ await page.goto(url.href, { waitUntil: "domcontentloaded", timeout: config.loadTimeoutMs ?? 30000 });
40
+ await page.locator(config.playSelector).click();
41
+ await page.waitForFunction(({ statePath, positionPath }) => {
42
+ const read = (value, path) => path.reduce((node, key) => node?.[key], value);
43
+ const position = read(read(window, statePath), positionPath);
44
+ return Array.isArray(position) && position.length > 0 && position.every(Number.isFinite);
45
+ }, { statePath: config.statePath, positionPath: config.positionPath });
46
+ const position = () => page.evaluate(({ statePath, positionPath }) => {
47
+ const read = (value, path) => path.reduce((node, key) => node?.[key], value);
48
+ return read(read(window, statePath), positionPath);
49
+ }, { statePath: config.statePath, positionPath: config.positionPath });
50
+ const before = await position();
51
+ await page.keyboard.down(config.key);
52
+ await page.waitForTimeout(holdMs);
53
+ await page.keyboard.up(config.key);
54
+ const after = await position();
55
+ const framesMs = await page.evaluate(duration => new Promise(resolve => {
56
+ const frames = []; let previous = null; let stopped = false;
57
+ const tick = now => { if (stopped) return; if (previous !== null) frames.push(now - previous); previous = now; requestAnimationFrame(tick); };
58
+ requestAnimationFrame(tick);
59
+ setTimeout(() => { stopped = true; resolve(frames); }, duration);
60
+ }), soakMs);
61
+ await mkdir(dirname(resolve(config.screenshot)), { recursive: true });
62
+ await page.screenshot({ path: resolve(config.screenshot), fullPage: true });
63
+ return { ...assessEvidence({ before, after, framesMs, pageErrors: errors }, config.criteria), coldLoadToCaptureMs: performance.now() - start,
64
+ holdMs, soakMs, cpuThrottle: throttle, screenshot: resolve(config.screenshot) };
65
+ } finally { await browser.close(); }
66
+ }
67
+
68
+ if (process.argv[1] === fileURLToPath(import.meta.url)) {
69
+ try {
70
+ const result = await browserEvidence(JSON.parse(await readFile(process.argv[2], "utf8")));
71
+ console.log(JSON.stringify(result, null, 2));
72
+ if (!result.ok) process.exitCode = 1;
73
+ } catch (error) { console.error(error.message); process.exitCode = 1; }
74
+ }
@@ -0,0 +1,109 @@
1
+ ---
2
+ name: opengame-weapons
3
+ description: Build first-person weapons and view models that hold up next to a shipped shooter. Covers iconic guns built from the real reference, view model size per gun class, beat-by-beat reloads with exported timings, hands that touch and never clip, no low-poly stand-ins, aiming through the real sight, kill reactions per weapon, camos and upgrades, wonder weapons and mystery-box odds. Use when the person says the gun looks like a toy or is too big, reloads look fake, hands clip, or add a weapon or box.
4
+ metadata:
5
+ version: "1.0.0"
6
+ ---
7
+
8
+ # Weapons
9
+
10
+ In a first-person shooter the gun is on screen for the whole game, so every flaw in it
11
+ is seen thousands of times. OC's owner raised gun fidelity about 30 times, its wonder
12
+ weapon about 22 times and hands about 15 times. Four habits cost most of those rounds.
13
+ Agents built a famous gun from an icon, fixed one gun when sixty had the defect, checked
14
+ size by eye, and showed a cheap model while the real one loaded.
15
+
16
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. The
17
+ three.js view model pass, depth handling, coverage masks and model loading are in
18
+ [references/threejs.md](references/threejs.md). Recoil springs, shake and hit feedback are
19
+ in `opengame-game-feel`; hands and arms are in `opengame-characters`.
20
+
21
+ **One defect is a defect in the whole class.** When the owner flags one gun, sight, camo
22
+ or pickup, sweep every gun on every path before reporting it fixed. The rule and OC's
23
+ numbers are in `opengame-quality-bar`.
24
+
25
+ ## Rules
26
+
27
+ ### Famous weapons are built from the real reference
28
+ - **Invariant:** A weapon the genre has made iconic matches the original's proportions and silhouette from the side, top and back, as seen from the camera players know it from, before anyone works on surface detail; it is built from the original, not from an icon, a texture sheet or memory, and the reference files stay out of the build.
29
+ - **Technique:** Get the original model or clear footage first. Extract its proportions, render it beside the candidate under one camera, and score the silhouette overlap from side, top and back. Write a materials list and a reload beat list from the reference, and recover its handling data (magazine, reload time, cadence, projectile speed, splash). Keep reference files outside the build folder, hash-check the shipped files against them, and ship original names.
30
+ - **Reference configuration:** OC built its Ray Gun for about 14 builds from "a texture sheet and a 64-pixel icon, never the actual model", and the owner rejected all of them in one message ("ur not even fucking CLOSE"). It took about 30 builds over 3 days. Six owner images and measured proportions fixed it: side outline overlap 0.947 to 0.954 against a bar of 0.95, first-person framing from directly behind as in the original, and triangles held at or below the heaviest loadout gun (24.9k; the first attempt was 47k). The reference data was a 20-round magazine, a 3 s reload empty or partial, a 330 ms cadence, 81.28 m/s base and 106.68 m/s upgraded, and a 1.6256 m splash. The materials list was worn maroon enamel, chipped edges, brass patina, visible cells, a gauge with a needle, rivets, a decal and grime. A hash check found 0 of 44 private reference files among 12,987 shipped, while trademarked names were still in the build at the launch audit. An agent's own note: "more surface detail alone won't address your criticism".
31
+ - **Applies when:** Any weapon, vehicle or prop the audience already knows from another game or film.
32
+ - **Verify:** Each round, a sheet of reference and build side by side from the same side, top, back and first-person cameras, with the overlap score for each view.
33
+
34
+ ### View model size is measured per class, in every pose, on several screens
35
+ - **Invariant:** Every gun of a class covers about the same share of the screen at hip, aimed, sprinting and drawing, on wide, standard and phone screens, checked against a frame from the genre's reference game; the gun is always in hand and clear of the HUD.
36
+ - **Technique:** Render the weapon layer alone to a mask and count its pixels in each pose at each screen size. Keep a table of target shares per class. Change one shared scale, then rerun every gun. Also check the resting angle, the muzzle position and near-plane cuts on long rifles at phone aspect.
37
+ - **Reference configuration:** OC hip targets, as a share of a 1280 x 720 frame: pistol about 6%, SMG about 8%, rifle about 9%, LMG about 9.5%, wonder pistol 7 to 9%. The Ray Gun shipped at about 40% and went to 5 to 7% in a hotfix. One fix swung the hip guns from "very small" to "so fucking massive", and the size had been checked against CoD by one agent's eye. The owner rejected guns both as toys and as massive. Within a class OC holds the hip footprint within about 2x (rifles had spread 3.9x and went to 2.1x). Hip yaw above about 13 degrees reads as sideways (one gun sat at 21.5). Screens: 1280 x 720, 1920 x 1080 and 844 x 390. OC's guns are drawn at 1.5x life size against an arm of about 0.52 m, so a true shoulder weld was impossible; the lesson was to fix the scale on day one.
38
+ - **Applies when:** First-person games with held weapons or tools.
39
+ - **Verify:** The coverage table for every gun in all four poses at all three sizes, with each gun inside its class band.
40
+
41
+ ### Nothing low-poly ever shows
42
+ - **Invariant:** The player never sees a placeholder, a low level of detail, a procedural fallback or a wrong variant of a weapon, in the loadout, a menu preview, the mystery box, a wall buy, in hand or in third person, and never pays for a weapon whose model has not loaded.
43
+ - **Technique:** Keep the previous complete weapon on screen until the exact new one has loaded and its shaders are compiled. Preload the likely next weapons: the visible roster, the box pool, nearby wall buys, menu neighbours. Gate a purchase on the model being ready. Where nothing exists yet, show a designed loading state in the UI, not a gun-shaped stand-in. Ship authored hero models with named parts and sockets (see `opengame-assets`); code-built guns do not pass.
44
+ - **Reference configuration:** OC: one lazy-load change put low-poly guns in 6 places, and a wall gun charged points while its model was missing. The owner said it at least 6 times, including "never load any low poly versions of guns ANYWHERE in this game" and "NOTHING low poly shows when spinning box". OC prewarmed its visible roster of 8 guns, about 28 MB.
45
+ - **Applies when:** Any game that streams or swaps models the player sees.
46
+ - **Verify:** Throttle the network, then take every acquisition path and open every menu that shows a gun, stepping the recording at each swap: every frame shows the full model or the previous one.
47
+
48
+ ### Reloads are choreographed beat by beat
49
+ - **Invariant:** Each reload is a sequence of named physical beats specific to its mechanism, readable at a glance, with each beat's time held in one data file that the animation and the sound both read, so every sound lands on its contact.
50
+ - **Technique:** Write a beat spec per mechanism (box magazine, belt, pan, tube, cylinder, energy cells) for empty and partial reloads. Export the timings, trigger each sound from the same table with a short swish before contact, and add a small sound for each part that moves. Make sure every reload state machine exits.
51
+ - **Reference configuration:** The owner on OC: "rn u can barely tell they are reloadin gbut we need lke a sick mag drop / mag out and then mag in and like slap the side of the gun", and later that a magnum should eject the shells inside it. OC's Ray Gun spec was latch, chamber opens, spent cells out, fresh cells in one at a time, snap shut, flicker on, with the timings exported so the audio synced per beat. Reload sounds had run 503 to 743 ms late (SMG bolt 503, rifle magazine 743, pump 649); afterwards they land within 12 ms of hand contact with a swish 110 ms before. OC's bow had an auto-reload cycle that never exited. The fidelity bar was "reload beats frame-for-frame" against the reference.
52
+ - **Applies when:** Every game with reloading weapons, and any tool with a multi-step use animation.
53
+ - **Verify:** Record a reload with sound, step it frame by frame, and check that each beat's sound starts within the game's tolerance of its contact frame, for every gun.
54
+
55
+ ### Hands touch the gun and never pass through it
56
+ - **Invariant:** On every reload, empty and partial, in first and third person, the hands and the magazine touch the parts they hold without sinking into the gun, and the support hand stays on the gun.
57
+ - **Technique:** Author hand and magazine contact points on each gun model. Measure penetration depth per reload phase offline across every gun, flag every row above the threshold, and fix the worst first. A simple hand (a thumb and a mitten, see `opengame-characters`) makes the fit tractable. Measure third person too.
58
+ - **Reference configuration:** OC flags any phase deeper than 8 mm. It fitted 184 contact points over 56 guns; at launch 55 of 114 rows over 57 guns were still over 8 mm, the worst at 20 to 58 mm, and third person was never measured. The support hand stays 2 to 80 mm from the gun. The owner: "we cant have that on any fo the guns". Shotgun shell inserts needed new motion.
59
+ - **Applies when:** Games with visible hands on held items.
60
+ - **Verify:** Run the contact check over every gun and reload; it fails on any row over the threshold. Capture the worst three rows in play.
61
+
62
+ ### Aiming goes through the visible sight
63
+ - **Invariant:** When aimed, the centre of the sight the player sees is on the crosshair, nothing covers the centre of the screen, lenses are clear, the gun stays upright, and the aim is calm and reversible mid-raise.
64
+ - **Technique:** Fit an eye point per gun from the sight mesh's world position, never from a mount socket. Ray-test the sight line through each optic. Ease aiming over the gun's own aim time and allow reversal partway. Draw reticles in a shader, visible only from the eye side, behind dark coated glass, with housings that never take camo. Build aim rotation from yaw and pitch so no roll creeps in. Where a true sight picture cannot look right, aim with the gun lowered and a slight zoom.
65
+ - **Reference configuration:** OC's aim used a socket 343 mm off the ring, a 31 px error. A glove covered 35.29% of the central box on one gun ("your glove completely blocks your ADS"); the fix took it to 0.04%. The sight is within 6 px of the crosshair at 1280 x 720 and 844 x 390 (achieved 0.5 to 2 px). Lenses on 4 rifles marked transparent blocked 385 of 385 rays. 19 of 61 guns had mesh within 0.15 m of the eye and 9 went through it. A 2 to 3 px red dot was unreadable; scope tubes need 48 or more sides; a 0.8 mm glowing torus bloomed into a seven-ring flower. Shortest-arc aim rotation rolled guns 25 to 30 degrees. Aim times run 0.19 s (pistol) to 0.48 s (LMG); the view model lens goes from 75 to 58.5 degrees. For the minigun the fallback was a lowered gun with a slight zoom, since CoD's version is hip-only.
66
+ - **Applies when:** Shooters with aim-down-sights.
67
+ - **Verify:** Aim every gun at desktop and phone sizes and capture: measure sight offset in pixels and the covered share of a central box, and ray-test every lens.
68
+
69
+ ### Handling numbers come from the reference game
70
+ - **Invariant:** Rate of fire, aim time, swap time, draw time, recoil and spray follow the reference game for each gun, and damage is audited as time to kill across the run.
71
+ - **Technique:** Table every gun's handling against its reference. Use real fire rates, authored spray patterns, and recoil springs per class scaled per gun. Audit time to kill at early, middle and late rounds, and treat an outlier gun as a bug.
72
+ - **Reference configuration:** OC from World at War: aim 0.245 s in and 0.25 s out, swap 0.25 s, first draw from a machine 0.8 s, kick settling in 0.15 to 0.2 s, aimed kick at 30 to 40% of hip, muzzle flash 2 frames. Real fire rates (MG42 1,200 rpm, a revolver 120); one revolver had done 1,000 damage at 625 rpm. Spray: rounds 1 to 3 straight up, 4 to 10 along the gun's curve, 11 on flatter and wider. Per-gun recoil scale 0.55 to 1.8x of its class. Time to kill audited at rounds 1, 10, 20 and 30; upgraded automatics kill a round-30 zombie in 0.65 to 1.0 s of headshots. Spring and timing tables are in [references/handling-numbers.md](references/handling-numbers.md).
73
+ - **Applies when:** Shooters, above all those that imitate a known game.
74
+ - **Verify:** The handling table for every gun beside its reference values, and a time-to-kill run per gun at each audited round.
75
+
76
+ ### Each weapon kills in its own way
77
+ - **Invariant:** The body's reaction to a kill matches the weapon: energy weapons drop bodies where they stand, shotguns and explosives throw them, and small arms push them a little.
78
+ - **Technique:** Choose the death response from the weapon that dealt the kill: a directional death clip, then a ragdoll with an impulse set per weapon class. Tag splash damage by what it is, so an energy splash is not treated as an explosion.
79
+ - **Reference configuration:** OC: energy kills rise under 0.15 m and travel under 0.6 m (the Ray Gun at most 0.005 m up and under 0.75 m of slide); a point-blank shotgun throws at 5 to 6 m/s with a sideways part, arm flail, 45 ms of hitstop and stronger shake; a pistol 1.7 m/s; an explosive 4 to 5 m/s out and 3.5 to 4.5 up. The directional death clip plays 0.16 to 0.42 s before the ragdoll. The owner: "ray guns hsouldnt make zombies fly", after the agents had logged "Ray Gun backflip" as a win because its splash was tagged explosive.
80
+ - **Applies when:** Games with several weapon types and visible deaths.
81
+ - **Verify:** Kill the same enemy type at the same range with each weapon class and record it; measure the root's rise and travel against the table.
82
+
83
+ ### Every way to get a gun shows the same gun
84
+ - **Invariant:** A gun from the box, a wall, an upgrade, a pickup, the firing range or a menu preview matches the loadout version in model, scale, camo, optic, grip and angle.
85
+ - **Technique:** Route every acquisition through one path that applies the slot's camo and a compatible optic. Audit every gun in every view against every path; a debug grant does not prove a pickup path. Give the firing range every gun, attachment, camo and upgrade.
86
+ - **Reference configuration:** OC's sheet was 61 guns x hip, aimed and third person x base, upgraded and camo, 549 views, plus 152 acquisition cases. Wall guns fill 82% of their niche at no less than 1.5x held size. Pickup camo had reset to the default, and the Ray Gun was missing from the range preview twice. Wonder weapons come only from the box, which meant auditing all 11 code paths that write a weapon slot.
87
+ - **Applies when:** Games with more than one way to get a weapon.
88
+ - **Verify:** One contact sheet per round of every gun on every path, and a list of slot-writing code paths each with its capture.
89
+
90
+ ### Camos and upgrades look like real materials and feel like an event
91
+ - **Invariant:** Menus and starting gear show the factory finish; every special finish reads as a real material on every gun and is cheap enough to keep; approved camos are never cut to save memory without asking; an upgrade is a staged moment with its own sound on every upgraded shot; ammo and status effects are seen in a capture before they count as done.
92
+ - **Technique:** Bake AO into every gun's material so finishes have something to sit on. Build finishes as material response (sheen by angle, a few clean bolts), not flat colour panels. Budget the held gun's shader cost. Stage the upgrade as a sequence: intake, charge, return, pickup, inspect, voice line.
93
+ - **Reference configuration:** OC: 58 of 60 guns lacked AO and camos read flat, so AO went into the packed material at cavity 0.2 to 0.4 with normals of at least 1024 px. A rejected rainbow camo kept returning to menus; gold read as "lumpy sparkly clay"; lightning camo became at most two clean forked bolts, visible about 2 of 3 frames; prism became a smooth sheen that changes with angle. An 11-octave camo cost 1.6 to 1.8 ms, 28% of a combat frame, and went to about 4 octaves against a 0.4 ms target. The owner: "do NOT cut down the sick camos we had to save memory". The upgrade looked "cheap" 3 times; the spec that followed opens with a knuckle crack before the staged sequence. OC's status effects were reported "Not checked in a capture".
94
+ - **Applies when:** Games with cosmetic finishes, upgrade stations or special ammo.
95
+ - **Verify:** Capture every gun with every finish under the game's own lights, measure the held gun's shader time, and capture an upgrade and an upgraded shot with sound.
96
+
97
+ ### Wonder weapons feel special without breaking the frame or the mix
98
+ - **Invariant:** A wonder weapon is as finished as the best loadout gun, stays in its class's size band, is no louder than the other guns, and its effects stay inside the near-lens caps.
99
+ - **Technique:** Hold it to every rule above, then add character through shape, sound design and projectile, not through size, level or flash. A person listens to its sound before it ships.
100
+ - **Reference configuration:** OC's first loud Ray Gun fire sound was rejected as "too aggressive" and "distorted" (the loudness numbers are in `opengame-audio`), and the shipped Ray Gun's in-game peak of -7.4 dBFS stays within about 4 dB of the others. Projectile streaks are at least 56 px, and its hits stopped counting as explosions. Triangles stay at 20 to 25k like loadout guns, and camos had to work on it too.
101
+ - **Applies when:** Games with a signature or legendary weapon.
102
+ - **Verify:** Fire it beside a loadout gun at a wall 1 m away and at range: compare loudness, flash coverage and screen share, and have a person listen to both.
103
+
104
+ ### Random rewards have written odds, a pity timer and a show
105
+ - **Invariant:** A random reward (a mystery box, a loot crate, a gacha pull) has written odds tuned against the reference game, a pity timer for its rarest reward, a visible rarity for every result, weights that keep the weakest results rare, and a reveal that is an event.
106
+ - **Technique:** Keep the weights in one table and compute the real odds of each result from it. Show rarity through colour, sound and light. Slow the reveal's ticks toward the result. Simulate many pulls and compare the results with the table.
107
+ - **Reference configuration:** OC: wonder weapon chance 3.4% per pull, guaranteed after 16 to 20 misses; rarity shown by beam colour (white, green, blue, purple, gold); crate weights tiered 12/8/5/4; the chance of the box leaving went to 10/20/30% from 15/30/50; the starter pistol's weight went from 12 to 4. Later tables gave the Ray Gun 1 in 56, then 2 of 446 (about 1 in 102), where World at War is about 1 in 20 to 25. The spin lasts 3.4 s (BO3 4.6 s), the offer 12 s, the move 8 s; ticks slow from about 16 a second to 3 with a music-box jingle. The box costs 950 points.
108
+ - **Applies when:** Games with randomised loot from a container, a drop table or a pull. OC's box is the reference here.
109
+ - **Verify:** Simulate ten thousand pulls from the shipped table and compare the counts with the intended odds, then play a pull and record the spin with sound.