@opengamehq/cli 0.0.0-stage → 0.4.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 +235 -0
- package/CHANGELOG.md +9 -0
- package/README.md +128 -2
- package/dist/cli.mjs +1415 -0
- package/dist/opengame-global.js +3 -0
- package/dist/opengame-global.js.LEGAL.txt +1 -0
- package/dist/preflight-worker.mjs +13 -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 +512 -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 +204 -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 +254 -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 +83 -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,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-api
|
|
3
|
+
description: Call the OpenGame creator API directly over HTTPS. Covers the base URL, creator tokens and scopes, the OpenAPI document, the error shape and retry fields, deploying without the CLI, and checking whether OpenGame is open. Use when the person wants to deploy from their own tool or CI without the CLI, asks about the OpenGame REST API, api/v1, openapi.json or a creator token, or an API call returned an error code you need to read.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.3"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Call the OpenGame creator API
|
|
9
|
+
|
|
10
|
+
OpenGame opens on 17 November 2026. Until OpenGame launches, every route except the status route and sign-in answers 403
|
|
11
|
+
with the error `not_launched` and the message "OpenGame is not launched." for any account
|
|
12
|
+
outside the OpenGame team. Check before anything else:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
curl -s https://opengame.io/api/v1/status
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
It answers `{ "launched": false, "access": null }` before launch. Sent with a token,
|
|
19
|
+
`access` says whether that account may use OpenGame now. Do not retry a
|
|
20
|
+
`not_launched` refusal in a loop; tell the person.
|
|
21
|
+
|
|
22
|
+
Most integrations should run the CLI (`opengame-cli`), which builds, checks, packages
|
|
23
|
+
and resumes uploads. Use the API when the CLI cannot run.
|
|
24
|
+
|
|
25
|
+
## Base URL and authentication
|
|
26
|
+
|
|
27
|
+
- Creator API: `https://opengame.io/api/v1`.
|
|
28
|
+
- Send a creator token as `Authorization: Bearer ...`. `opengame login` makes one with
|
|
29
|
+
`read`, `deploy` and `submit` scopes; one made in the browser can have fewer scopes
|
|
30
|
+
and be limited to one game. Give a job only the scopes it needs.
|
|
31
|
+
- Keep the token in the runner's secret store as `OPENGAME_TOKEN`. Never log it, put it
|
|
32
|
+
in a command argument or ship it in a game. Send it only to the creator API: never
|
|
33
|
+
to a storage upload URL.
|
|
34
|
+
- Refuse redirects on authenticated requests, so a token is never replayed elsewhere.
|
|
35
|
+
|
|
36
|
+
Check a token with `GET /api/v1/auth/me`, which returns the handle and the
|
|
37
|
+
credential's scopes.
|
|
38
|
+
|
|
39
|
+
A running game does not use this API. It talks to OpenGame through the SDK with a
|
|
40
|
+
session token the OpenGame page supplies (`opengame-sdk`).
|
|
41
|
+
|
|
42
|
+
## The contract
|
|
43
|
+
|
|
44
|
+
The OpenAPI document is `openapi.json` in the `opengamehq/opengame` repository and in
|
|
45
|
+
the docs' API reference. Each operation there lists its request, its responses and the
|
|
46
|
+
authentication it needs. Read it rather than guessing a field.
|
|
47
|
+
|
|
48
|
+
## Deploy without the CLI
|
|
49
|
+
|
|
50
|
+
1. `POST /api/v1/deploys` with the archive's size, file count, SHA-256 hash and manifest, and
|
|
51
|
+
an `Idempotency-Key`. Save the operation ID and the key before uploading.
|
|
52
|
+
2. `PUT` the archive bytes to the returned `upload` URL with the headers it names, and
|
|
53
|
+
no creator token.
|
|
54
|
+
3. `PUT /api/v1/operations/{id}/upload` to confirm. A `POST` to the same path gives a
|
|
55
|
+
fresh upload URL if the upload was interrupted.
|
|
56
|
+
4. Poll `GET /api/v1/operations/{id}` until it is `ready`, `failed` or `expired`.
|
|
57
|
+
|
|
58
|
+
Reuse one `Idempotency-Key` for every retry of the same deploy; a new key starts a new
|
|
59
|
+
operation. Submitting a release to review is separate: `POST /api/v1/submissions`.
|
|
60
|
+
|
|
61
|
+
## Errors
|
|
62
|
+
|
|
63
|
+
Errors are JSON with a stable `error` code and a `message` to show the person. Branch
|
|
64
|
+
on `error`. Other fields, when present:
|
|
65
|
+
|
|
66
|
+
| Field | Meaning |
|
|
67
|
+
| --- | --- |
|
|
68
|
+
| `retry` | `now`, `after-fix`, `later` or `never`. |
|
|
69
|
+
| `retryAfterSeconds` | How long to wait, on a rate limit. |
|
|
70
|
+
| `url` | The page where the fix happens. |
|
|
71
|
+
| `requestId` | Quote it when reporting a failure. |
|
|
72
|
+
|
|
73
|
+
Some answers to know:
|
|
74
|
+
|
|
75
|
+
- `not_launched` (403): OpenGame has not opened yet for this account.
|
|
76
|
+
- `not_member` or `account_inactive` (403): the account has no access, or is suspended.
|
|
77
|
+
- `uploads_closed` (403): new uploads are not open to this account; nothing started.
|
|
78
|
+
- `entries_closed` (403, `retry` is `never`): entries have closed, so no game can be
|
|
79
|
+
deployed or updated. Published games stay live. Do not retry; tell the person.
|
|
80
|
+
- `upload_expired`: start a new deploy with a new `Idempotency-Key`.
|
|
81
|
+
- A path that is not a route gets 404 `not_found`; a method a route does not take gets
|
|
82
|
+
405 with no JSON body, so check the status before parsing.
|
|
83
|
+
|
|
84
|
+
Rate limits and bundle limits change; read them with `GET /api/v1/limits` or
|
|
85
|
+
`opengame limits --json` rather than from a page.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-assets
|
|
3
|
+
description: Generate and import a browser game's models, textures, sounds and menu films so they match, load and look right. Covers content over tuning with scanned CC0 materials, an import lint for scale, axes, origin, material defaults, packed channels and normals, deduplicated textures, spend caps per provider, every asset seen in game, and paid jobs bought once. Use when the person says generate models, use Meshy, ElevenLabs or fal, assets look black or chrome, or downloads are big.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Generated assets
|
|
9
|
+
|
|
10
|
+
Generation is cheap compared with what it costs to ship an asset that does not belong:
|
|
11
|
+
a model in a different style, a sword with a glow modelled as geometry, a sound whose
|
|
12
|
+
attack lands after the hit. The rules below keep a game's assets consistent, loadable
|
|
13
|
+
and paid for once.
|
|
14
|
+
|
|
15
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
16
|
+
|
|
17
|
+
**Keys never go in the game.** Generation runs on the creator's machine at build time,
|
|
18
|
+
with keys from the environment, and only the finished files ship. A key in a game is a
|
|
19
|
+
key on a public CDN, and OpenGame rejects an upload that contains one (see `opengame-deploy`).
|
|
20
|
+
|
|
21
|
+
## Rules
|
|
22
|
+
|
|
23
|
+
### Content over tuning
|
|
24
|
+
- **Invariant:** When the frame misses the concept, the next change adds authored content the concept has and the build lacks (a scanned material, a sculpted kit piece, a prop layer, a light, an effect) instead of another pass on grade, fog or procedural parameters.
|
|
25
|
+
- **Technique:** Before tuning, list what the concept shows that the frame does not, and check the renderer is already at its top settings. Use scanned CC0 material sets for surfaces and keep procedural work for wear, wetness and variation layered over them. Build kits from sculpted or image-to-3D pieces made from crops of the concept, then dress them densely. Ask before reversing an owner's earlier call on how something is made.
|
|
26
|
+
- **Reference configuration:** After hours of grading (`opengame-quality-bar` has that story), an OC orchestrator found Ultra, TAAU, GTAO and SSR already on, so the gap was "missing content, not tuning", and the rule became "each commit has to add something the concept has and we don't". Procedural stone read "flat" next to the concept's "dense scanned/sculpted surfaces", and the world moved to Poly Haven CC0 scans under procedural wetness and wear; the agent asked first, because it reversed the owner's "environment procedural" call. Image-to-3D from concept crops gave a 24-piece kit in about 15 minutes, and a 28-piece kit cost about $20.90 on Meshy plus $4.70 on fal. OC's project review ranked this second among the changes that moved its quality most, after scored concept sheets.
|
|
27
|
+
- **Applies when:** 3D games aiming at a painted or photographic concept. A flat or stylised look may be procedural by choice.
|
|
28
|
+
- **Verify:** Each round's change list names the content added, and the paired concept and build frames show it.
|
|
29
|
+
|
|
30
|
+
### Material defaults and packed channels are checked on import
|
|
31
|
+
- **Invariant:** Every imported material has plausible metalness and roughness, its packed texture channels hold what the shader reads, its normals face out, and all of this is proven before anyone tunes light or colour.
|
|
32
|
+
- **Technique:** Lint each material on import: metalness zero on flesh, cloth and stone; a roughness factor that does not erase its map; a texture format that keeps every channel the shader reads; two-channel normal formats reconstructing Z; the occlusion, roughness and metal order the shader expects. Count vertices whose normals oppose their face winding. When a look is wrong in game, render albedo, normals, roughness and the lit result separately before touching any light.
|
|
33
|
+
- **Reference configuration:** OC: the importer's metal default of 1.0 made mirror slabs, and zombie bodies came back chrome-black whenever the renderer rebuilt a material from those defaults. Metal and roughness compressed to a two-channel format dropped the channel the shader read metal from, so iron armour rendered "like painted stone" until a four-channel format was forced. An avatar shader read a blue channel that its two-channel normal texture did not have, which inverted the normals and washed out the outfit. Opposed normals on 7.7 to 25.8% of zombie vertices made "the black horde", tuned through 10 rounds of albedo, fill and fire tint before anyone checked normals; the fix took white aprons from 12 to 34% of pixels to 0%. Zombie materials took 6 or more blind passes by 4 agents. 58 of 60 guns lacked AO. Iron without a metal flag read as grey cloth.
|
|
34
|
+
- **Applies when:** Every imported or generated PBR asset.
|
|
35
|
+
- **Verify:** The import report lists metalness, roughness, texture formats and the opposed-normal share for every asset; a studio-lit sheet shows each asset next to its channel views.
|
|
36
|
+
|
|
37
|
+
### Models follow one convention: metres, Y up, origin at the feet
|
|
38
|
+
- **Invariant:** Every model arrives in metres, with Y up, facing the same forward axis, with its origin at the feet or the base, so nothing is scaled, rotated or offset by hand in game code.
|
|
39
|
+
- **Technique:** Write the convention down on day one and convert at import, not at runtime. Check each model's bounding box for height and that its lowest point is at the origin. Leave skeleton fields that shift a skin's root unset unless the engine needs them.
|
|
40
|
+
- **Reference configuration:** OC found by trial that models must be metres, Y up, facing +Z, origin at the feet; the axes and units match glTF's own. A set skeleton field on the skin made every animated zombie float by its own hip height. OC's pipeline took 57 hero guns through one converter with world LODs, 32 props with 2 LODs and a 28-piece kit with 3 LODs, all in metres.
|
|
41
|
+
- **Applies when:** Every 3D game that imports models.
|
|
42
|
+
- **Verify:** Load every model at the origin beside a one-metre reference cube and capture the row from the side.
|
|
43
|
+
|
|
44
|
+
### One import lint runs on every asset and names each failure
|
|
45
|
+
- **Invariant:** Every asset passes one automated check on import, and a failure names the asset and the problem instead of shipping a broken file or changing it without a word.
|
|
46
|
+
- **Technique:** One script runs over every model, texture and sound and checks the convention above, triangle and texture budgets, material defaults and channels, opposed normals, skin weights (`opengame-characters`), clip counts, sockets, alpha mode and duplicate embedded images. Keep import output out of the source tree, or make it deterministic, so a rebuild never dirties the checkout. Break the lint on purpose once to prove it catches each fault.
|
|
47
|
+
- **Reference configuration:** OC's importer turned soft alpha into a hard cutoff, reset three materials to the default shader on every build without a warning, processed materials one pass late so a model failed to load, and could not read WebP. Its import output dirtied the tree on almost every merge.
|
|
48
|
+
- **Applies when:** Every game with more than a handful of assets.
|
|
49
|
+
- **Verify:** Run the lint on the whole asset folder and on a file broken on purpose; the second run fails and names the file.
|
|
50
|
+
|
|
51
|
+
### Embedded textures are deduplicated and sized by role
|
|
52
|
+
- **Invariant:** No texture ships twice, every texture is sized for how close the player sees it, and approved art is never cut to meet a budget without asking.
|
|
53
|
+
- **Technique:** Deduplicate images inside and across model files, cap texture size per role and level of detail, subset fonts, and free CPU-side copies after GPU upload. Measure tab memory on a real phone. When a budget is tight, cut residency and shader cost before cutting approved art, and bring the tradeoff to the owner.
|
|
54
|
+
- **Reference configuration:** OC: the titan file was 55.7 MB because it embedded its textures three times; deduplication and a cap per level of detail took its albedo from 11.2 MB to 2.8 MB. One session's download fell from 225 MB to 103 MB raw (about 51 MB deflated) after deduplication and font subsetting; eight font atlases had cost 34 MB. Textures default to 1024 px, hero items get 2048, enemies are capped at 1024. The cap flipped between 2048 and 1024 three times. Approved art and the owner's veto on cuts are in `opengame-quality-bar`.
|
|
55
|
+
- **Applies when:** Every game with textured models, above all on the web and on phones.
|
|
56
|
+
- **Verify:** List every image by hash across the shipped bundle; no hash appears twice. Compare each texture's size with its role's cap.
|
|
57
|
+
|
|
58
|
+
### Spend is capped per provider and logged before every call
|
|
59
|
+
- **Invariant:** Each paid provider has a cap the owner set, every paid call is logged with its cost before the next one starts, and the running total comes from the log, not from memory.
|
|
60
|
+
- **Technique:** Keep one spend log per project with provider, job, cost and running total, written before each call. Give each stream its own cap inside the provider's. Stop and ask before a call would cross a cap. Check shared accounts for spend from other sessions.
|
|
61
|
+
- **Reference configuration:** OC spent $178.13 by 19 Oct (Meshy $115.70, fal $34.87, ElevenLabs $27.56) against caps of $250, $150 and $500. The first day bought 55 concept images for $23.48, 1,275 audio files for $11.70, and a titan plus 5 zombies on Meshy for $10.84; 40 mocap clips cost about $2.40 and a canon titan $1.40. Per-stream caps such as art at $80 Meshy and $35 fal were tracked; one agent misread "$30.96 of its $35 fal cap" when about $27 was left. Another session spent about $1.20 unlogged on the shared Meshy account. Voice slots ran out at 37 of 30, which blocked 9,900 lines.
|
|
62
|
+
- **Applies when:** Every game that uses paid generation.
|
|
63
|
+
- **Verify:** The log's total for each provider matches the provider's own dashboard.
|
|
64
|
+
|
|
65
|
+
### Hero props are authored with named parts and sockets
|
|
66
|
+
- **Invariant:** A prop the player handles or studies is an authored model with separate moving parts and named attachment points, and generated meshes get a cleanup pass before they ship.
|
|
67
|
+
- **Technique:** Model hero props with each moving part as its own named mesh, empties for sockets (muzzle, ejection, grips, sight), and a manifest of pivots and travel. Clean generated meshes: remesh to budget, fix melted detail, bake AO. Never ship code-built primitives as hero props.
|
|
68
|
+
- **Reference configuration:** OC's hero guns are GLBs with named moving parts, `socket_*` empties and a manifest; about 24k triangles at 2048 in first person and 10k at 512 in the world. Code-built guns were "rejected on sight since r0", and raw generated guns were called "melted, raw Meshy output". `opengame-weapons` has the rest.
|
|
69
|
+
- **Applies when:** Games with held, inspected or animated props.
|
|
70
|
+
- **Verify:** Open each hero prop's file and list its parts and sockets against the manifest, then capture it in use.
|
|
71
|
+
|
|
72
|
+
### One reference frame drives everything
|
|
73
|
+
- **Invariant:** Every generated asset in a game shares one art direction, taken from one composed reference image of the game seen from the player's camera.
|
|
74
|
+
- **Technique:** Make a single composed frame of the game from the real camera (player or weapon, opponents, environment, HUD space) at the quality bar, write every later prompt from the game's own source and that frame, and pass it as a reference to every image request.
|
|
75
|
+
- **Reference configuration:** Our originals write one composed frame per game and use it both as image-to-3D input and as the bar to climb against. Dragline's key art came out right because the prompt was built from the game's own art code; a prompt that describes a genre produces art that looks like that genre.
|
|
76
|
+
- **Applies when:** Every game that generates assets.
|
|
77
|
+
- **Verify:** Put captures of every generated asset in play beside the reference frame; a reviewer with fresh context names any that do not belong.
|
|
78
|
+
|
|
79
|
+
### Model each item from a clean reference of itself
|
|
80
|
+
- **Invariant:** A held, thrown or collected item is a model of that item, made from an image of the item alone.
|
|
81
|
+
- **Technique:** Generate a neutral reference per item class: the item centred on a plain background, no rim light, glow, frame or sparkles, using the game's reference frame and the item's HUD icon as inputs. One model per class, tinted for variants; the container an item comes out of is a class of its own.
|
|
82
|
+
- **Reference configuration:** ST: image-to-3D models a glow as geometry, so references never glow. ST plans item models in the same first batch as the actors and ships a procedural version that meets the item bar only when a model has not landed in time.
|
|
83
|
+
- **Applies when:** 3D games with a modelled look. Drawn, pixel and 2D styles make each item a single standalone image instead.
|
|
84
|
+
- **Verify:** Capture each item class on the ground and in use, at play distance, beside its HUD icon.
|
|
85
|
+
|
|
86
|
+
### Paid jobs are pinned, saved and never bought twice
|
|
87
|
+
- **Invariant:** Every paid generation is reproducible from a recorded request, saved locally as soon as it finishes, and recovered rather than repurchased when a request times out.
|
|
88
|
+
- **Technique:** Pin the model version in every request. Record the request, the provider's job id and the returned files' hashes. Download results immediately; never store a provider URL. On a timeout, poll the existing job by id before submitting anything. Check the balance before a batch.
|
|
89
|
+
- **Reference configuration:** Meshy deletes results after 3 days. MC measured 30 credits per textured image-to-3D job on meshy-6 and 5 per remesh. MC also found two characters generated with identical parameters came back at different quality, so inspect each one.
|
|
90
|
+
- **Applies when:** Every paid provider.
|
|
91
|
+
- **Verify:** Every generated file in the game has a manifest entry with its request, job id and hash; no file is referenced by a provider URL.
|
|
92
|
+
|
|
93
|
+
### Clean, then rig, then animate
|
|
94
|
+
- **Invariant:** A character is rigged from its cleaned, final-polygon-count mesh, and every character has idle, locomotion and its signature action before it appears.
|
|
95
|
+
- **Technique:** Set the target polygon count on the generation or remesh, inspect and clean the mesh, then rig that file, then add clips. Choose animations by id from the provider's library rather than paying to see what one is.
|
|
96
|
+
- **Reference configuration:** MC sets a 22,000 triangle target before rigging, because a rig binds to the mesh it was given. Meshy's rig has 24 joints and no fingers, returns one 0.3 s animation, and numbers its torso bones in the opposite direction to Mixamo, so code that assumes `Spine` is the lowest bone bends the belly. ST keeps Meshy's 678-action library as a searchable table.
|
|
97
|
+
- **Applies when:** Generated characters and creatures.
|
|
98
|
+
- **Verify:** The rest pose, a stretch pose and every clip in play pass the gates in `opengame-characters`.
|
|
99
|
+
|
|
100
|
+
### Web-ready files, checked through the real loader
|
|
101
|
+
- **Invariant:** Every model and texture in the bundle is in a web-ready format, compressed only where the game's own loader can read it, and opens in the game.
|
|
102
|
+
- **Technique:** GLB with meshopt or Draco geometry and KTX2 textures where the decoders ship in the bundle; otherwise plain GLB and WebP. Load every shipped model through the game's own loader in a check that prints mesh, triangle and clip counts.
|
|
103
|
+
- **Reference configuration:** Our originals delivered thirty models into eight games where only two games had a GLTF loader at all; a missing loader is a blank page with nothing in the console. `clips=0` in that check means the model is not animated, whatever a manifest says. AW encodes KTX2 per texture class after measuring (see `opengame-performance`).
|
|
104
|
+
- **Applies when:** Every 3D game.
|
|
105
|
+
- **Verify:** The loader check opens every shipped model and its clip count matches what the game plays.
|
|
106
|
+
|
|
107
|
+
### Sound prompts are directions to a recordist
|
|
108
|
+
- **Invariant:** A generated sound fits its action: the right source, attack and tail, starting on the frame of contact.
|
|
109
|
+
- **Technique:** Describe source and material, attack, body, tail, distance, duration and whether it loops, in one consistent acoustic space per family. Then edit like a recordist: trim unwanted silence before the attack, keep real tails, and remeasure loudness and true peak after any edit.
|
|
110
|
+
- **Reference configuration:** ST's sound pipeline trims leading silence with a short pad and keeps the source; our originals budget 50 to 400 recorded samples per game. MC and AW measure every shipped file into a loudness manifest (see `opengame-audio`).
|
|
111
|
+
- **Applies when:** Every game generating sound.
|
|
112
|
+
- **Verify:** Line each cue up with its animation contact in a recording; the attack lands on the contact frame.
|
|
113
|
+
|
|
114
|
+
### Menu films keep the camera and the title still
|
|
115
|
+
- **Invariant:** A menu or banner film moves only the atmosphere: the camera is locked, nothing enters or leaves, and the title stays exactly as drawn.
|
|
116
|
+
- **Technique:** Animate the approved still with an image-to-video model using a prompt that is mostly refusals (camera locked, no figure changes pose, nothing appears or disappears, only atmosphere moves). Keep the title out of the animated pixels or protect it, then play the clip out and back so the loop has no visible join.
|
|
117
|
+
- **Reference configuration:** Our originals use fal's MiniMax image-to-video for banner films, about three seconds played out and back; one game's clip lost its title and turned lasers into fire, and is kept as the failure to avoid. ST generates the banner at 2048 x 1152, above the 1920 x 1080 publishing minimum and divisible by 16.
|
|
118
|
+
- **Applies when:** Games with a menu film, banner or hover clip.
|
|
119
|
+
- **Verify:** Step through every frame of the loop: the title's pixels and position do not change.
|
|
120
|
+
|
|
121
|
+
## Further reading
|
|
122
|
+
|
|
123
|
+
Generation as it runs on OpenGame's own Studio, including model and sound batching, plus OC's import lint checklist and spend log:
|
|
124
|
+
[references/pipeline.md](references/pipeline.md).
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# How the Studio plans and integrates generated assets
|
|
2
|
+
|
|
3
|
+
OpenGame's Studio (ST) builds games with agents and has to get assets right without a
|
|
4
|
+
person checking each one. Its production plan is worth copying even for a game built by
|
|
5
|
+
hand.
|
|
6
|
+
|
|
7
|
+
## Plan rows, not files
|
|
8
|
+
|
|
9
|
+
Keep one compact plan of requirements, made from the brief and the reference frame
|
|
10
|
+
before asking for anything:
|
|
11
|
+
|
|
12
|
+
- one row per signature actor, mount, machine, landmark and core interaction;
|
|
13
|
+
- one row per class of item, pickup, collectible and projectile the player sees;
|
|
14
|
+
- one row per sound family, pointing at a cue map;
|
|
15
|
+
- each row with a construction choice (`image_to_3d`, `authored_3d`, `procedural`,
|
|
16
|
+
`sprite` or `reuse`), a status (`missing` or `integrated`), and the final files.
|
|
17
|
+
|
|
18
|
+
A saved file alone is not integrated. A row is integrated when the game loads its files
|
|
19
|
+
on the real route and a capture shows them. Never delete a row to make the plan look
|
|
20
|
+
finished; an unfinished requirement stays visible.
|
|
21
|
+
|
|
22
|
+
## Choose the medium per asset
|
|
23
|
+
|
|
24
|
+
The art style and the player camera decide. A drawn, sketchbook, pixel, flat or 2D look,
|
|
25
|
+
a weapon drawn onto the first-person view, billboard enemies and icons are sprites, and
|
|
26
|
+
that choice is its own justification. Rigging is for a 3D character whose motion the
|
|
27
|
+
player sees, never for a sprite, a static prop or a drawn weapon. Replacing a signature
|
|
28
|
+
actor with procedural geometry needs a specific visual reason, compared at the player
|
|
29
|
+
camera against the concept; generation latency and cost are not reasons.
|
|
30
|
+
|
|
31
|
+
## Start long jobs early
|
|
32
|
+
|
|
33
|
+
Begin independent model and sound jobs while the core loop is being built, not after
|
|
34
|
+
it. Inspecting a finished creature must not delay its rider's references. Put the hero's
|
|
35
|
+
model first; queue item models behind it.
|
|
36
|
+
|
|
37
|
+
## Cue map
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{ "families": [{ "id": "footsteps-sand", "event": "Player steps on sand", "trigger": "js/audio.js",
|
|
41
|
+
"files": ["assets/audio/step-sand-a.ogg", "assets/audio/step-sand-b.ogg", "assets/audio/step-sand-c.ogg"],
|
|
42
|
+
"minimumVariants": 3 }] }
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`trigger` names the source that plays the family; `files` are real recordings. Distinct
|
|
46
|
+
bytes are different files, not audible variety: audition them in their real triggers.
|
|
47
|
+
|
|
48
|
+
## Banner and menu art
|
|
49
|
+
|
|
50
|
+
ST makes one strong original 16:9 banner with the game's title in it, animates that exact
|
|
51
|
+
image for the menu film, keeps the still as the poster and the social image, and reuses
|
|
52
|
+
the one film behind every menu screen rather than buying a clip per screen. A film with a
|
|
53
|
+
different aspect ratio can sit behind a menu with an inspected crop, but it is not a
|
|
54
|
+
publishing asset.
|
|
55
|
+
|
|
56
|
+
## Import lint checklist (OC)
|
|
57
|
+
|
|
58
|
+
What OC's agents found by trial and wished one check had caught. Run it on every model,
|
|
59
|
+
texture and sound at import, and make every failure name the file.
|
|
60
|
+
|
|
61
|
+
- **Units and axes.** Metres, Y up, facing +Z, origin at the feet or base. Report the
|
|
62
|
+
bounding-box height and the lowest point.
|
|
63
|
+
- **Skins.** Root and skeleton fields that do not offset the mesh (OC's zombies floated
|
|
64
|
+
by their own hip height); waist ratio per clip; no thigh weight above the hip or across
|
|
65
|
+
legs; left and right parts the same size.
|
|
66
|
+
- **Materials.** Metalness 0 on flesh, cloth and stone; a roughness factor that leaves
|
|
67
|
+
its map visible; alpha mode kept as authored (OC's import turned soft alpha into a hard
|
|
68
|
+
cutoff).
|
|
69
|
+
- **Packed channels.** The compressed format keeps every channel the shader reads (a
|
|
70
|
+
two-channel format dropped OC's metal); two-channel normals rebuild Z; the occlusion,
|
|
71
|
+
roughness, metal order matches the shader (glTF puts occlusion in R, roughness in G,
|
|
72
|
+
metal in B).
|
|
73
|
+
- **Normals.** The share of vertices whose normal opposes the face winding. OC's horde
|
|
74
|
+
ran 7.7 to 25.8%.
|
|
75
|
+
- **Textures.** No image embedded twice, sizes within the role's cap, AO present on
|
|
76
|
+
hero props.
|
|
77
|
+
- **Animation.** Clip count matches what the game plays; locomotion clips present.
|
|
78
|
+
- **Sockets.** Every socket the code reads exists in the file.
|
|
79
|
+
- **Repeatability.** Import output lands outside the source tree or is identical on
|
|
80
|
+
every run, so a rebuild leaves the checkout clean.
|
|
81
|
+
|
|
82
|
+
In a three.js project, `gltf-transform` covers several of these from the command line:
|
|
83
|
+
`gltf-transform inspect` for a report, `gltf-transform dedup` for duplicate images and
|
|
84
|
+
accessors, and `gltf-transform resize` for texture caps.
|
|
85
|
+
|
|
86
|
+
## Spend log (OC)
|
|
87
|
+
|
|
88
|
+
One line per paid call, written before the call is made:
|
|
89
|
+
|
|
90
|
+
```json
|
|
91
|
+
{"t":"2026-10-15T09:12:00Z","provider":"meshy","stream":"art","job":"kit-arch-03","usd":0.60,"provider_total":71.74,"cap":80}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
OC measured these unit costs. A Meshy textured job 30 credits ($0.60), a Meshy clip 3
|
|
95
|
+
credits ($0.06), fal images $0.057 to $0.108 each, ElevenLabs about 11 credits per second
|
|
96
|
+
of sound effect and $0.000183 per credit. Check the log before buying anything that may
|
|
97
|
+
already exist.
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-audio
|
|
3
|
+
description: Make a browser game sound finished. Covers sound from the first press, a check that the shipped build plays sound on every device, listening before shipping, harshness and loudness gates, a distance model that keeps far sounds audible, voice priority, reload sounds on the beat, a master chain, buses and shuffled takes. Use when the person says the game is silent, silent on iPhone, sounds cheap, harsh or thin, clips, gets muddy in fights, repeats sounds, or needs music or sound effects.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Audio
|
|
9
|
+
|
|
10
|
+
Sound is most of the distance between a prototype and a game. Our three reference games
|
|
11
|
+
ship between 337 and 7,459 audio files; our first prototypes shipped 34. Count is not
|
|
12
|
+
the goal, though. Four hundred samples played without a chain, a voice budget and a
|
|
13
|
+
no-repeat rule sound worse than forty played through them.
|
|
14
|
+
|
|
15
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
16
|
+
[helpers/audio-chain.js](helpers/audio-chain.js) builds the chain, the buses and the
|
|
17
|
+
voice pool; its `selfTest()` plants a bus that bypasses the limiter, a clip curve that
|
|
18
|
+
adds gain, a duck with no lead and an oldest-voice pool, and proves each is caught.
|
|
19
|
+
|
|
20
|
+
The first seven rules come from OC, where sound was raised about 13 times (silent
|
|
21
|
+
loading, missing effects, no gunfire on iPhone) and harsh sounds 4 more. Start there.
|
|
22
|
+
|
|
23
|
+
## Rules
|
|
24
|
+
|
|
25
|
+
### Sound from the first press, loading screen included
|
|
26
|
+
- **Invariant:** The game makes sound from the player's first press: the loading screen, the title and every menu have music or ambience, and the first shot of the first run is heard.
|
|
27
|
+
- **Technique:** A press-to-start screen over key art gives the browser the gesture it needs while the download runs. Create and resume one audio context inside that first key or pointer handler, with no separate "tap for sound" prompt. Load the menu set first, then the sounds the player makes (the equipped weapon's bank) ahead of the rest of the run's audio. Hand the loading music to the menu theme with a crossfade, and log when the theme is up so the two never overlap. In three.js, call `THREE.AudioContext.getContext().resume()` in the handler; `AudioListener` uses that shared context.
|
|
28
|
+
- **Reference configuration:** OC: the press lands a hit on the music downbeat 60 ms after the key; loading music at -20 LUFS over a -27 LUFS bed, a tick for every 5% of progress and an anvil hit at 100%, then a 3 s music fade and a 5 s bed fade into the menu theme. Tiered sets: menu 10.4 MB, combat core 22 MB. A gun granted in the first 20 s of a run was silent for 11 to 16 s behind 35 MB of queued audio, until a trickle loader moved the first fire cue from 12.0 s to 2.1 s at 3 MB/s. The owner asked three times: "even our loading screen should have sfx and music and environmental ambience sounds too ... not just be silent".
|
|
29
|
+
- **Applies when:** Every browser game with sound.
|
|
30
|
+
- **Verify:** In a fresh profile on a throttled connection, press a key on the first screen and record the tab: sound starts on the press, the loading screen is never silent, and the first shot of the first run is audible.
|
|
31
|
+
|
|
32
|
+
### The shipped build makes sound on every platform
|
|
33
|
+
- **Invariant:** On every device and browser the game ships to, the deployed build plays the menu, the player's weapon and the voices at the levels the mix intends, and a build that cannot play sound tells the player.
|
|
34
|
+
- **Technique:** For each device and browser in the test matrix, record the deployed build through real input (menu, first shot, reload, a voice line) and measure loudness per segment; a silent segment fails. Resume the audio context on every touch, on visibility change and after an interruption, and treat a suspended context as a fault, never as the player's mute. If a fallback build has no sound, show a notice. Prove a mute setting by measured loudness, not by the click that set it. Emulators and headless captures are muted or lie about audio, so they prove nothing here.
|
|
35
|
+
- **Reference configuration:** OC: real iPhones had no in-game sound across at least three builds ("when I started the game there was ZERO sound"; later "game audio was playing but NOT gunfire sounds") while emulation passed. OC's single-threaded build had no audio at all, so iPhones moved to the threaded build (R169). A latency clamp set below the mixer's lead garbled audio on every device and was reverted (R195). OC's proposed fix was a 1 s resume watchdog plus `navigator.audioSession.type = "playback"` before creating any context; the notes do not record whether the session type helped. On the gameplay montage the settings-menu mute clicks never landed, found only when loudness was measured (-24.5 against -37.4 dB), and all 9 segments were reshot. The owner raised iPhone sound about 7 times.
|
|
36
|
+
- **Applies when:** Every game with sound, and above all games that ship to phones.
|
|
37
|
+
- **Verify:** On a real iPhone and a real Android phone, open the live URL, play to the first reload and record: gunfire, reload and a voice line are each audible. Turn sound off in settings and measure the drop.
|
|
38
|
+
|
|
39
|
+
### Nobody ships a sound nobody listened to
|
|
40
|
+
- **Invariant:** Every sound in the build has been heard in the running game by a person before it ships. Meters gate a sound; a listener decides it.
|
|
41
|
+
- **Technique:** Meter first (loudness, peak, harshness), then record a short clip from the game in context at a normal listening level and send it to a person with a plain question. Keep a listened-by field per cue in the registry; a cue with no listener is reported as unheard. An agent cannot listen, so it hands over the clip and reports the sound as unheard until a person answers. A spectrogram is evidence for a meter, not for taste.
|
|
42
|
+
- **Reference configuration:** OC on 16 Oct: "None of the audio has been listened to by a person: every pick was made by measurement." The wonder weapon's third sound was pushed to -12 LUFS with stacked crackle and whistle, marked "Not listened to by anyone", and rejected as "too aggressive" and "distorted"; its crest factor was 9.7 against the reference's 13.8.
|
|
43
|
+
- **Applies when:** Every game with sound.
|
|
44
|
+
- **Verify:** Every cue in the registry names who heard it and when, and links the in-game clip they heard.
|
|
45
|
+
|
|
46
|
+
### Every sound is clean
|
|
47
|
+
- **Invariant:** No sound is harsh, distorted, clipped or unpleasant to sit through, including the ones that repeat fastest, and one harsh sound starts a sweep of its whole class.
|
|
48
|
+
- **Technique:** Batch-meter every file for true peak, loudness, crest factor, the share of energy in the upper-mid presence band, hiss, DC offset and clicks at the loop point, and flag outliers against their family. Fix at the file. When anyone calls one sound harsh, meter and audition every sound in its class. Rapid-fire weapons get a short sound per shot and a cap on overlapping shots. Player characters have no breathy, moaning or groaning takes; a death is a short clean grunt. A soft tonal design beats stacked crackle, sizzle and whistle layers.
|
|
49
|
+
- **Reference configuration:** OC's owner: "the death machine SFX is OBNOXIOUS ... every sound needs to be elegant and clean and pleasant to the ear ... make sure no others like that!" Its 1.8 s file fired 25 times a second, about 12 dB louder than the Thompson, with 39% of its energy at 2-5 kHz (Thompson 12%); a 2 s in-game spray went from -13.0 LUFS and 23% to -17.7 LUFS and 5.4% (Thompson -16.4 and 9.7%, M1911 -17.2 and 5.5%). The sweep softened 54 more files and fixed 6 clicks at loop points (R167-R169). A death groan that "sounds sexual" became a 210-240 ms "oof". Gate: true peak at or under -1 dBTP, codec SNR at least 33 dB, 2,895 files with none clipped; rapid fire caps simultaneous shots at 2 and plays a casing every 6th round.
|
|
50
|
+
- **Applies when:** Every game with sound; weapons and voices first.
|
|
51
|
+
- **Verify:** The batch meter prints every file's numbers and the outliers in each family; a person listens to every rapid-fire weapon held down and to the loudest ten seconds of the busiest fight.
|
|
52
|
+
|
|
53
|
+
### Far sounds the player needs can be heard
|
|
54
|
+
- **Invariant:** Before anyone balances levels, every sound the player needs is audible at the distances the game is played at, and the mixer plays the cues the game sends.
|
|
55
|
+
- **Technique:** Check the distance model first: one falloff for every source makes the biggest sources inaudible at the distance they matter. Set reference distance and rolloff per sound family, keep the player's own hits above a floor, and count cues requested against cues played during a busy fight. In three.js, set `PositionalAudio.setRefDistance`, `setRolloffFactor` and `setDistanceModel` per family.
|
|
56
|
+
- **Reference configuration:** OC: one 3 m falloff left the boss at -28 dB. Per-family falloff became boss 30 m, explosions 12 m, zombies 6 m, impacts 5 m, with the player's own hits never below -8 dB. The mixer had been dropping 75% of cues (peak 41 voices, creature vocals capped at 4 with 13 dropped). The whole mix moved from -24.9 to -16.9 LUFS. The owner: "i dont hear any sfx really in game?"
|
|
57
|
+
- **Applies when:** 3D games with positional sound.
|
|
58
|
+
- **Verify:** Stand at the far edge of the arena and trigger the boss's loudest attack; log requested against played cues over a minute of the busiest fight.
|
|
59
|
+
|
|
60
|
+
### Gunfire beats groans
|
|
61
|
+
- **Invariant:** When the voice budget is full, the sounds the player causes and needs (their weapon, hits, interface, music, announcer) always play, and enemy vocals give way first.
|
|
62
|
+
- **Technique:** Priority classes in the voice pool. The player's weapon, hit confirmation, interface, music and announcer are never culled; enemy vocals are capped to the nearest few within a radius; everything else competes by audibility as in the stealing rule below. Phones keep the same classes with a smaller pool.
|
|
63
|
+
- **Reference configuration:** OC: player fire, hits, interface, music and announcer always mixed; enemy vocals capped to the nearest 6 within 20-30 m; about 40 voices in the mix. Before the classes existed, iPhones played "game audio ... but NOT gunfire sounds".
|
|
64
|
+
- **Applies when:** Games where many sounds overlap.
|
|
65
|
+
- **Verify:** Spawn the largest horde and hold the trigger; the pool log shows no player shot refused or stolen, and a recording of the fight has every shot in it.
|
|
66
|
+
|
|
67
|
+
### Sound follows the animation beat by beat
|
|
68
|
+
- **Invariant:** Every sound tied to a visible action lands on the frame of its contact, beat by beat, and stops when the action is interrupted.
|
|
69
|
+
- **Technique:** Author multi-part actions (reloads, inspections, interactions) as named beats with times exported from the animation into one shared file. Audio schedules each beat from that file on the audio clock, never as one whole-action file or a guessed delay, and cancels the remaining beats when the action is cancelled. Subtitles take the clip's real length and close when the line is cut.
|
|
70
|
+
- **Reference configuration:** OC's fire cue rises within 3 ms of the shot, and its reload sounds land within 12 ms of hand contact after running up to 0.74 s late; the beat specs and per-gun numbers are in `opengame-weapons`. The owner: "sweat the details with micro sfx even for like each part of a reload animation".
|
|
71
|
+
- **Applies when:** Games with authored animations that make contact sounds.
|
|
72
|
+
- **Verify:** Frame-step a recording of every reload beside its waveform and measure each beat's offset from its contact frame.
|
|
73
|
+
|
|
74
|
+
### Everything goes through one master chain
|
|
75
|
+
- **Invariant:** Every sound the game makes reaches the speakers through one chain that holds overlapping sounds together and puts a ceiling on the output.
|
|
76
|
+
- **Technique:** Master gain into a glue compressor, make-up gain before (not after) a limiter so its threshold is the real ceiling, then a soft clip for the transient the limiter's attack lets through. Route HTML audio and video through the same graph if they belong in the mix. `createMasterChain` in the helper.
|
|
77
|
+
- **Reference configuration:** AW and MC: glue at -15 dB, 4:1, knee 14, 6 ms attack, 180 ms release; limiter at -1.2 dB, 20:1, 1 ms, 60 ms; make-up 1.25 before the limiter (after it, the real ceiling rose to about +0.7 dBFS). SR glues more gently at -12 dB, 2:1. AW measured three 50 ms windows a minute peaking above 0 dBFS after the limiter alone.
|
|
78
|
+
- **Applies when:** Every game with sound.
|
|
79
|
+
- **Verify:** `chainProperties(chain)` returns no failures, and a recording of the busiest moment in the game has no sample above the ceiling.
|
|
80
|
+
|
|
81
|
+
### Buses with separate volume and duck
|
|
82
|
+
- **Invariant:** Music, ambience, effects, voice and interface sounds can each be turned down by the player and ducked by the game, and the two never fight.
|
|
83
|
+
- **Technique:** Each bus is a volume gain into a duck gain into the master. The player's slider writes the volume; the game's ducking writes the duck. Mute and pause apply to every bus without changing the saved levels.
|
|
84
|
+
- **Reference configuration:** AW's buses are sfx, music, voice and ui, with ambience riding under the music slider but ducking on its own. OC ducks music 5 dB on big hits; its announcer ducks effects 4 dB and music and voice 6 dB.
|
|
85
|
+
- **Applies when:** Every game with more than one kind of sound.
|
|
86
|
+
- **Verify:** Set the music slider to half, trigger a duck, let it release: the music returns to half, not to full.
|
|
87
|
+
|
|
88
|
+
### A duck lets its cause be heard first
|
|
89
|
+
- **Invariant:** A sound that lowers the rest of the mix is itself heard at full level before the mix drops.
|
|
90
|
+
- **Technique:** Hold the ducked bus at unity for a short lead, then fade it down; overlapping ducks keep the deepest.
|
|
91
|
+
- **Reference configuration:** AW's concussion duck with no lead muffled the very gunshot that caused it, which made its loudest rifle the quietest weapon at its own shooter's ear. A 0.12 s lead recovered 4.8 LU and 7 dB of true peak on that shot and left every other case unchanged.
|
|
92
|
+
- **Applies when:** Any duck triggered by a game sound, such as concussions, voice lines or big impacts.
|
|
93
|
+
- **Verify:** `duckHoldsLead(chain)` is true; render the triggering sound with and without the duck and compare its loudness.
|
|
94
|
+
|
|
95
|
+
### Busy moments steal the quietest voice, gently
|
|
96
|
+
- **Invariant:** When too many sounds play at once, the least audible one gives way, without a click, and information-bearing sounds are the last to go.
|
|
97
|
+
- **Technique:** A bounded voice pool; when full, fade the quietest unprotected voice over a few milliseconds and start the new one after it. Reclaim voices by their scheduled end time, not by `onended`, which a busy event loop delivers late. Protect hit confirmation, warnings and voice. `createVoicePool` in the helper.
|
|
98
|
+
- **Reference configuration:** AW's 72-voice pool saturated in 0.16 s with twelve combatants. Taking the oldest voice with a hard stop retired voices as loud as the mix average (101%) and clicked; taking the quietest with a 6 ms fade retired voices at 46% of the mix average.
|
|
99
|
+
- **Applies when:** Any game where many sounds can overlap.
|
|
100
|
+
- **Verify:** `stealFailures(stealBehaviour(...))` is empty; drive the busiest fight and count voices stolen, refused and protected voices cut.
|
|
101
|
+
|
|
102
|
+
### Takes in shuffled bags
|
|
103
|
+
- **Invariant:** A sound that repeats often never plays the same take twice in a row, and frequent actions have enough takes that the player stops hearing a sample.
|
|
104
|
+
- **Technique:** Several recorded takes per frequent event, played from a shuffled bag that empties before refilling. Spend the count where repetition is: footsteps per surface, impacts per material, actions at several strengths, beginnings, middles and ends. Voice lines also get a recurrence lockout and a chance to fire, so frequent events do not talk every time.
|
|
105
|
+
- **Reference configuration:** Our originals budget 50 to 400 recorded samples per game, spent where the game earns it. AW's hit, headshot and kill confirmations each have three takes in bags, so all three are heard before any repeats. Per-play variation of pitch 2 to 3% and gain 1.5 dB on top (DK, MC). OC's voice director: no-repeat bags, a 5-minute recurrence lockout, 8-15 s of quiet after any line, kill lines on 14% of kills and reload lines on 18%, 474-522 lines per character over 77 events, and 6-8 takes for frequent sounds. The owner had said "the character is also repeating stuff too much".
|
|
106
|
+
- **Applies when:** Every game with repeated actions.
|
|
107
|
+
- **Verify:** Log the take played for a hundred footsteps: no immediate repeats, and every take used.
|
|
108
|
+
|
|
109
|
+
### Loudness is measured, per family
|
|
110
|
+
- **Invariant:** Every shipped audio file has a measured loudness and true peak, grouped by family and normalised to that family's target after the codec, and the measurements cover exactly the files that ship.
|
|
111
|
+
- **Technique:** Generate a loudness manifest from the files on disk, never by hand, with integrated or short-window loudness and true peak per file, and fail when a file and the manifest disagree in either direction. Normalise each family to its target, level-match takes within a class, and measure again after every re-encode. Then audition the assembled mix, because per-file numbers do not balance a game.
|
|
112
|
+
- **Reference configuration:** AW's manifest is generated from the library and its check reports how many files it measured, because an empty library and an empty manifest otherwise agree perfectly. AW's confirmation levels: hit about -25 LUFS, headshot -23, kill -21, measured over the loudest 200 ms. OC's targets: weapons -17 LUFS (-19 to -16), voice -19, steps -25, ambience loops -26, ceiling -1 dBTP, one-shots on their loudest 200 ms K-weighted window; takes within a class level-matched to 0.1 dB; a new gun at or below the existing ones; fire 13-15 dB over the ambient bed. OC generated 1,275 files for $11.70 at the start and shipped 2,895; spend and credit rates are in the mix notes.
|
|
113
|
+
- **Applies when:** Every game with recorded audio.
|
|
114
|
+
- **Verify:** The manifest check prints a file count equal to the number of shipped audio files, and every family's median is on its target.
|
|
115
|
+
|
|
116
|
+
### One ranked confirmation channel
|
|
117
|
+
- **Invariant:** Hit, headshot and kill confirmations never pile up; a stronger verdict replaces a weaker one, and a weaker one never plays over a stronger one.
|
|
118
|
+
- **Technique:** Treat confirmations as one priority channel on a dry, protected interface bus with no world position. A new cue of equal or higher rank fades its predecessor out quickly; a lower one waits. Collapse duplicate reports from one frame.
|
|
119
|
+
- **Reference configuration:** AW: kill over headshot over hit, a 12 ms fade on replacement, a 28 ms floor for ordinary hits and 45 ms for headshots and kills, with a 100-event burst test.
|
|
120
|
+
- **Applies when:** Games with hit confirmation.
|
|
121
|
+
- **Verify:** Fire a shotgun into a target that dies: one kill cue plays, no hit cues under it.
|
|
122
|
+
|
|
123
|
+
### Distance is authored, not filtered
|
|
124
|
+
- **Invariant:** A far sound is a different sound, not the near one made quieter.
|
|
125
|
+
- **Technique:** Distant takes for loud sources, plus physically based air absorption that removes high frequencies with distance, attenuation from current positions, occlusion, and a reverb per zone. Keep interface sounds and narrators out of the world.
|
|
126
|
+
- **Reference configuration:** AW: at 300 m, 8 kHz is 45 dB down while 250 Hz loses 0.3 dB; its distant weapon set varies by duration and low-frequency content, from a pistol's 0.22 s to a launcher's 0.70 s. AAA bar values: gain `ref / (ref + k (d - ref))`, a low-pass from 16 to 20 kHz near to 1.5 kHz at 40 m, occlusion about 0.43 of gain, zone reverbs from 0.38 s (courtyard) to 2.2 s (hall).
|
|
127
|
+
- **Applies when:** 3D games with sounds at distance.
|
|
128
|
+
- **Verify:** Record the same source at near, mid and far range, and behind a wall; each is audibly different in tone, not only level.
|
|
129
|
+
|
|
130
|
+
### The audio clock schedules sound
|
|
131
|
+
- **Invariant:** Every sound that must land at a time is scheduled on the audio context's clock, not on a timer.
|
|
132
|
+
- **Technique:** Schedule against `AudioContext.currentTime`. Where a long sequence must not reserve voices up front, wake a little early with a timer and place each cue exactly on the audio clock. Cancel both the scheduled sources and the pending wake-ups.
|
|
133
|
+
- **Reference configuration:** AW's reload reserved one voice per phase for its whole length, 132 voices against a pool of 72 at twelve combatants, until it moved to a 120 ms look-ahead. AW found four separate faults from gating sound on a clock other than the audio clock.
|
|
134
|
+
- **Applies when:** Every game with timed or sequenced sound.
|
|
135
|
+
- **Verify:** Grep for `setTimeout` near a `start(` or `play(` call; each one is a look-ahead wake-up, not the timing itself.
|
|
136
|
+
|
|
137
|
+
### Every file has a caller, and music streams
|
|
138
|
+
- **Invariant:** Every audio file in the build is reachable from a call site, and long music never sits decoded in memory.
|
|
139
|
+
- **Technique:** One cue registry that names each file and the event that triggers it, and preload derived from that registry. Stream music through a media element routed into the music bus; keep short cues in a bank that decodes on first use, and warm the first use of a rare sound the round before it plays.
|
|
140
|
+
- **Reference configuration:** AW shipped 35 weapon files no weapon reached. A decoded sound is float PCM, about 23 MiB per stereo minute; ST found one game spending 134 MiB that way before its first frame of play. AW measured 266.9 MB of decoded audio against a 200 MB budget. In OC the first play of a rare sound was silent until warmed.
|
|
141
|
+
- **Applies when:** Every game with recorded audio.
|
|
142
|
+
- **Verify:** List audio files and grep each name in source; list decoded buffers at runtime and sum their sizes.
|
|
143
|
+
|
|
144
|
+
### Open the front door once
|
|
145
|
+
- **Invariant:** Every public method of the game's audio engine runs without throwing on a live engine.
|
|
146
|
+
- **Technique:** A smoke test that calls each method once with plausible arguments against a real or stub context and counts the sources it started, so a run where everything early-returns cannot pass.
|
|
147
|
+
- **Reference configuration:** AW's audio had five green checks while a deleted constant threw on the first footstep, inside the frame update, which players reported as the game jittering.
|
|
148
|
+
- **Applies when:** Every game with an audio module.
|
|
149
|
+
- **Verify:** The smoke test reports zero errors and a non-zero count of sources started.
|
|
150
|
+
|
|
151
|
+
## Further reading
|
|
152
|
+
|
|
153
|
+
Where the reference numbers came from, the soft-clip measurement, the sound families a
|
|
154
|
+
shooter needs and what OC's library cost: [references/mix-notes.md](references/mix-notes.md).
|