@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,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-quality-bar
|
|
3
|
+
description: The bar a browser game is judged against on OpenGame, and how to judge your own game against it without fooling yourself. Covers the sixteen cheap tells, blunt scores against the concept and a named reference game, sweeping a whole class from one report, the ninety-second stranger test and a fresh-context reviewer. Use when the person asks is my game good enough, make it feel AAA, polish it, review my game, what is missing, after a first playable, or before submitting to a jam.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# The quality bar
|
|
9
|
+
|
|
10
|
+
Frontier models make scenes that look impressive in a still. They fail when the frame
|
|
11
|
+
stops and someone looks closely, or starts playing: a hero drawn as a capsule, a menu
|
|
12
|
+
that is a button on black, silence, a wall you walk through. A stranger notices in
|
|
13
|
+
seconds. This skill is the check for that, and the other `opengame-` craft skills are
|
|
14
|
+
how to fix what it finds.
|
|
15
|
+
|
|
16
|
+
## How the rules are written
|
|
17
|
+
|
|
18
|
+
Every rule carries five tags, because a number that worked in one of our games is a
|
|
19
|
+
reference, not a law:
|
|
20
|
+
|
|
21
|
+
- **Invariant:** what must stay true in any game it applies to.
|
|
22
|
+
- **Technique:** one way to get there.
|
|
23
|
+
- **Reference configuration:** where specific values worked, and which game they came
|
|
24
|
+
from. DK is Der Koloss, MC Modern Claudefare, AW World at War and Astral War, SR
|
|
25
|
+
Skybreak and Smash Royale, ST the Studio that builds games on OpenGame, OC OG Clash,
|
|
26
|
+
a first-person wave shooter with a boss, built for WebGPU.
|
|
27
|
+
- **Applies when:** the genres, cameras and scales it fits.
|
|
28
|
+
- **Verify:** how to show it holds, by doing something rather than by reading code.
|
|
29
|
+
|
|
30
|
+
## Rules
|
|
31
|
+
|
|
32
|
+
### No cheap tells in what a stranger sees first
|
|
33
|
+
- **Invariant:** None of the cheap tells is visible on the route a new player takes: the title, the menu, the first minute of play, and the loading screen before them.
|
|
34
|
+
- **Technique:** Walk the list in [references/cheap-tells.md](references/cheap-tells.md) against captures from the real route, and fix them in its order: core loop first, then every generated asset in the game, then the front end, then a playtest.
|
|
35
|
+
- **Reference configuration:** ST holds a new game's first version until a review passes it, and that review names each tell it sees. DK, MC, AW and SR clear the first twelve; they are where the list came from. OC added the last four: one lazy-load change put low-poly guns in 6 places, a wall gun charged points while its model was missing, and real iPhones crash-looped during load after every emulated phone check had passed.
|
|
36
|
+
- **Applies when:** Every game, every genre. A flat or minimal style changes what counts as a tell (flat light is then the style, not a defect), as long as the creator chose it.
|
|
37
|
+
- **Verify:** A reviewer with fresh context, given the captures and the list, marks each tell present or absent and cites the capture.
|
|
38
|
+
|
|
39
|
+
### The bar is a frame from a named game
|
|
40
|
+
- **Invariant:** Before work starts on a screen, the target for it is a specific frame from a specific shipped game in the genre, named in writing beside the concept art. The concept is the floor and the named frame is the bar.
|
|
41
|
+
- **Technique:** For each screen (combat, HUD, menus, boss, results) pick the genre leader and save one frame from it at the same camera and action as the concept. Put both on every comparison sheet. When the owner raises the bar mid-project, write the new reference down the same day and rescore against it.
|
|
42
|
+
- **Reference configuration:** OC used BO3 and BO6 for combat and the HUD, Fortnite for building and the third-person camera, Hades and Astro Bot for menus. The owner moved the bar from concept parity to "game of the year" on day 3; the critic then kept two scores, and from R67 to R77 the concept score went 4.4 to 5.3 while the reference-game score went 2.6 to 3.5. OC's HUD clusters took 25% of screen width; sized to the reference frame they take 13-15%.
|
|
43
|
+
- **Applies when:** Every game whose owner names a quality bar ("AAA", "like game X"). A game in its own invented style uses its best concept frame as both floor and bar.
|
|
44
|
+
- **Verify:** Every comparison sheet shows 3 panels per screen (concept, named reference frame, build) with the reference game's name on it.
|
|
45
|
+
|
|
46
|
+
### Score by eye on side-by-side sheets, bluntly
|
|
47
|
+
- **Invariant:** Each screen gets a 0 to 10 score by eye against its concept and its reference frame, from fixed hero frames on a side-by-side sheet. A pixel or colour metric can support a score and never closes an item on its own.
|
|
48
|
+
- **Technique:** Shoot the same hero frames every round. Have a critic who did not build the round mark every element in the concept present, wrong or missing, with its place in the frame. Cap the score at 5 until every element is present, and name the 3 biggest misses per frame. Ask the owner to score one sheet early and compare: a critic far above the owner is too soft and gets rewritten.
|
|
49
|
+
- **Reference configuration:** OC's CIELAB metric improved from 16.56 to 14.68 while the frames were about 2/10, and it scored a black loading page 29.1; "parity 7.3" labels were later called meaningless. Once frames were scored by eye against one concept each, the critic rose from 3.5 to 6.4 over about 25 rounds. The owner rated comparable builds 1/10, 2/10 and 5/10, so OC treats a critic-owner gap over 2 points as a soft critic.
|
|
50
|
+
- **Applies when:** Every game with concept art or a reference, from the first build the owner sees.
|
|
51
|
+
- **Verify:** Feed the scorer a death frame and a loading frame: both score near 0. The critic's score on one sheet is within the agreed gap of the owner's.
|
|
52
|
+
|
|
53
|
+
### One report means a sweep of the whole class
|
|
54
|
+
- **Invariant:** When the owner reports a defect on one instance, every instance of the same class meets the same bar before the fix is reported.
|
|
55
|
+
- **Technique:** Name the class (every gun, every sight, every pickup path, every perk label, every character), list its members, fix at the shared source where there is one, and capture every member on one sheet. Report the class, its count and the members that failed, not the one example.
|
|
56
|
+
- **Reference configuration:** OC fixed one optic on its own; a sweep of all 61 weapons, done only after the owner pushed, found 3 more defective guns. One electricity complaint led to 13 more draw sites. A launch audit found 57 of 61 guns had never been captured by QA. OC's gun sheet is 61 guns by hip, aim and third person by base, upgrade and camo, 549 views, plus 152 acquisition cases. The owner, after finding an old perk name the rename missed: "how am i finding shit like this and u arent?"
|
|
57
|
+
- **Applies when:** Every defect report on a member of a set. The bigger the set, the more a single fix misleads.
|
|
58
|
+
- **Verify:** The fix report links a sheet with every member of the class, each marked pass or fail.
|
|
59
|
+
|
|
60
|
+
### Add what the concept has; remove what it lacks
|
|
61
|
+
- **Invariant:** Each round adds something the concept or reference frame has and the build lacks (a model, a light, a prop layer, an effect), or removes something neither has. Retuning one layer (sky, grade, fog) while the models, surfaces, lights and density still miss is not progress.
|
|
62
|
+
- **Technique:** Name one person who owns the frame as a picture and one who owns the renderer, on day one. Before tuning, list what the concept shows that the build does not, and check the renderer's limits (light count, model count) against what the scene needs. Try removing a cheap element before adding a new one.
|
|
63
|
+
- **Reference configuration:** OC spent hours grading before the owner called the build "made with a crayon"; the frame had no owner. The render audit that finally ran found a 32-light cap against 218 fire sites, and the content side of the fix is in `opengame-assets`. A flat cyan visor strip took 3 h 40 min and 3 private builds to remove, after which the owner called that visor perfect.
|
|
64
|
+
- **Applies when:** Every game being pushed toward a concept or reference, most of all in 3D.
|
|
65
|
+
- **Verify:** Each round's notes name what was added or removed and point at it on the sheet.
|
|
66
|
+
|
|
67
|
+
### A stranger wants a second minute
|
|
68
|
+
- **Invariant:** Someone who has never seen the game, starting from the real menu with no explanation, understands what to do, does it, and wants to keep going.
|
|
69
|
+
- **Technique:** The ninety-second stranger test: open the published or preview build cold, go through the real menu (never a developer shortcut past it), play for ninety seconds, and write down every moment of confusion, waiting or boredom.
|
|
70
|
+
- **Reference configuration:** The bar our originals are held to: a person clicks one game, plays it for ninety seconds and forms an opinion about the studio. A game that boots to black has already answered them.
|
|
71
|
+
- **Applies when:** Every game.
|
|
72
|
+
- **Verify:** Record the ninety seconds as video or a frame sequence with input. A pass names the first action taken, when it happened, and the first consequence the player saw.
|
|
73
|
+
|
|
74
|
+
### The builder never grades its own work
|
|
75
|
+
- **Invariant:** The verdict on a piece of work comes from someone who did not build it and who sees the artifact, not the builder's explanation of it.
|
|
76
|
+
- **Technique:** Give a separate agent with fresh context the bar, the captures and the running build, never your summary. It marks every area met, gap or unverified, and names the single largest gap. Fix that gap, then ask again. The prompt is in [references/review-prompt.md](references/review-prompt.md).
|
|
77
|
+
- **Reference configuration:** ST runs an independent reviewer on every first version. In our own repository, a second review of one day's fixes found the first review's fixes carried the same defect classes they were fixing. OC's first independent review after integration found 30 ranked defects that every self-check had passed, and later an adversarial review of each delivery found a real bug in every one.
|
|
78
|
+
- **Applies when:** Every game, at every checkpoint the person will see.
|
|
79
|
+
- **Verify:** The review names a single largest gap, cites a capture for each verdict, and marks anything it could not observe as unverified rather than met.
|
|
80
|
+
|
|
81
|
+
### Everything made for the game is in the game
|
|
82
|
+
- **Invariant:** Every model, rig, sound, clip and image generated for this game is loaded and seen or heard on the real route, and nothing a stand-in occupies has a finished asset waiting unused. An asset counts once someone has seen it in the running game.
|
|
83
|
+
- **Technique:** Keep a list of every generated asset with the call site that uses it. Grep for each file name in the game's source; play to where it appears.
|
|
84
|
+
- **Reference configuration:** ST fails a first version on any generated work left unused, and lists those first in every playtest report. Our originals once shipped thirty models into eight games where only two games loaded a model at all. OC paid for mocap attack clips that sat in the zombie files unused, generated props were flagged because "nobody has looked at them in-engine", and the title scene's cigar clip did not play until R102, after the owner asked "where is the cigar smoking?" 3 times.
|
|
85
|
+
- **Applies when:** Every game that generated assets.
|
|
86
|
+
- **Verify:** For each asset, a source line that loads it and a capture or recording where it appears in play.
|
|
87
|
+
|
|
88
|
+
### Judge the frame people play
|
|
89
|
+
- **Invariant:** Quality is judged from the player's camera, at play distance, while moving, not from an editor view or a hero still.
|
|
90
|
+
- **Technique:** Capture from the real camera during real input: a still one second after Play, a pan, a sprint, a hit. Compare against the concept at the same camera and action.
|
|
91
|
+
- **Reference configuration:** ST compares player-camera captures against each selected concept view; a canvas-only capture cannot prove a HUD exists, so its captures include the DOM. OC's owner moved from judging stills to playing on day 2, and his first play-test list that evening had 50 items.
|
|
92
|
+
- **Applies when:** Every game with a camera.
|
|
93
|
+
- **Verify:** The captures are timestamped, include the HUD and are taken through the real menu path.
|
|
94
|
+
|
|
95
|
+
### Approved quality is never traded without asking
|
|
96
|
+
- **Invariant:** Art, effects or fidelity the owner has approved are not cut, lowered or swapped for a budget, a device or a deadline unless the owner agrees to that specific trade.
|
|
97
|
+
- **Technique:** When a budget is missed, optimise residency, streaming and shader cost first. If a cut is still needed, show the owner the before and after and the measured saving, and wait for a yes. Never let a device tier or fallback lower quality without saying so on screen.
|
|
98
|
+
- **Reference configuration:** OC agents cut camos to save memory and the owner reversed it ("do NOT cut down the sick camos"). Phone builds shipped with fewer enemies, smaller textures and half the sky without asking; all of it was reverted at R179. The owner overrode a blanket "bytes only go down" rule when the tradeoff was shown.
|
|
99
|
+
- **Applies when:** Every game with an owner or art director, and every budget or device fallback.
|
|
100
|
+
- **Verify:** Each quality cut in the change log links the owner's approval.
|
|
101
|
+
|
|
102
|
+
### Report what was observed
|
|
103
|
+
- **Invariant:** Every claim about the game is marked observed pass, observed failure, unverified or not applicable, and a source read is never reported as an observation.
|
|
104
|
+
- **Technique:** A checklist of at most six rows per checkpoint: check, route, action and expected result, observed result, evidence, next fix. Carry unresolved rows forward.
|
|
105
|
+
- **Reference configuration:** ST's checkpoint table, which keeps "unverified" as a first-class status so an untested claim cannot read as a pass. OC's ask register marked each ask fixed, partial, not fixed or could not check, with frame proof, after an audit found 0 of 67 inherited asks closed with on-screen proof.
|
|
106
|
+
- **Applies when:** Every report to the person, every submission note.
|
|
107
|
+
- **Verify:** Every row marked pass links a capture, clip time or test output.
|
|
108
|
+
|
|
109
|
+
## The other craft skills
|
|
110
|
+
|
|
111
|
+
Look: `opengame-look`. Light: `opengame-lighting`. Collision and movement:
|
|
112
|
+
`opengame-world-physics`. Geometry defects: `opengame-scene-audit`. Feel:
|
|
113
|
+
`opengame-game-feel`. Characters: `opengame-characters`. Sound: `opengame-audio`.
|
|
114
|
+
Menus and HUD: `opengame-front-end`. Frame time: `opengame-performance`. Generated
|
|
115
|
+
assets: `opengame-assets`. Systems: `opengame-depth`.
|
|
116
|
+
Proving it works: `opengame-verification`. Everyone can play: `opengame-accessibility`.
|
|
117
|
+
First-person weapons and viewmodels: `opengame-weapons`. Enemy AI, navigation, hordes,
|
|
118
|
+
bosses and deaths: `opengame-enemies`. Boot, streaming, caching and honest progress:
|
|
119
|
+
`opengame-loading`. Touch, phone memory and real Safari: `opengame-mobile`. Crash-free
|
|
120
|
+
play, budgets for every pool and error reporting: `opengame-stability`. Filming and
|
|
121
|
+
screenshots with a fixed clock, a clean feed and a free camera: `opengame-capture`.
|
|
122
|
+
Running the build loop with agents over many rounds: `opengame-production`.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# The sixteen cheap tells
|
|
2
|
+
|
|
3
|
+
Each is something a stranger notices in seconds, drawn from what our own games had to
|
|
4
|
+
fix (DK, MC, AW, SR, OC) and what the Studio's reviewer finds in first versions (ST). For
|
|
5
|
+
each: what it looks like, how to see it, and which skill fixes it. Tells 13 to 16 came
|
|
6
|
+
from OC, a large 3D game played on desktops and phones.
|
|
7
|
+
|
|
8
|
+
| # | Tell | What it looks like | How to see it | Fix with |
|
|
9
|
+
| --- | --- | --- | --- | --- |
|
|
10
|
+
| 1 | Primitive stand-ins | A hero, creature, vehicle, item or landmark drawn as a box, sphere, capsule or cone where a designed thing belongs | Grep for `BoxGeometry`, `SphereGeometry`, `CapsuleGeometry` under item and actor names; look at play distance | `opengame-assets`, `opengame-characters` |
|
|
11
|
+
| 2 | Default materials | Flat colour, roughness 1 or one roughness everywhere, no maps, metal that reflects nothing | Grep `MeshStandardMaterial({ color` with no maps; look at a surface while moving | `opengame-look` |
|
|
12
|
+
| 3 | Flat light | Shadowed surfaces nearly as bright as lit ones, no cast or contact shadows, no warm and cool contrast | Compare a lit wall and its shadowed neighbour; isolate the ambient term | `opengame-lighting` |
|
|
13
|
+
| 4 | Missing post | No tone curve or grade, bloom on lit walls, a milky horizon, a frame flatter than the concept | Capture with the grade off and on; look at the horizon | `opengame-look` |
|
|
14
|
+
| 5 | An empty world | A ground plane with props on a grid, nothing overhead, no wear, props floating or intersecting | Run the scene audit; pan slowly at a grazing angle | `opengame-depth`, `opengame-scene-audit` |
|
|
15
|
+
| 6 | Placeholder UI | Browser-default fonts, debug text, unstyled boxes, emoji or Unicode glyphs as icons, a title that is a button on black | Load the menu cold; inspect computed fonts | `opengame-front-end` |
|
|
16
|
+
| 7 | Silence or thin sound | No music or ambience, one sample for every action, clipping when sounds overlap | Play with headphones through a busy minute | `opengame-audio` |
|
|
17
|
+
| 8 | No hit feedback | A hit with no marker, flash, sound or reaction; a kill with no beat of its own | Hit something and watch the next half second frame by frame | `opengame-game-feel` |
|
|
18
|
+
| 9 | A dead camera | Rigid follow, no easing, no response to sprint or impact, shake that never decays, a camera inside walls | Sprint, land, take a hit, back into a wall | `opengame-game-feel` |
|
|
19
|
+
| 10 | Stiff animation | Sliding feet, clips that pop with no crossfade, no hit reaction or death, a T-pose anywhere | Watch feet at slow, normal and sprint speed; kill something | `opengame-characters` |
|
|
20
|
+
| 11 | Hitches | A stall on the first shot or effect (shader compile), frame-time spikes from allocation | Record frame times through first combat; read p95 and p99 | `opengame-performance` |
|
|
21
|
+
| 12 | Generated work left out | A model, rig or clip made for this game that the game never loads, while a stand-in sits in its place | List generated files; grep each name in source | `opengame-quality-bar` |
|
|
22
|
+
| 13 | Stand-ins while loading | A low-poly copy, a silhouette, a wrong variant or a half-built mesh shown in a menu, a pickup, a reward spin or a customisation preview while the real asset loads | Throttle the network, open every menu and acquisition path, and capture the first frame each item appears | `opengame-loading`, `opengame-assets` |
|
|
23
|
+
| 14 | A black or white held item | The gun or hands in first person read as a black shape or a blown-out white one, in dark corners or after a shot | Capture the held item in the darkest and brightest spots of the map and on the frame after firing | `opengame-weapons`, `opengame-lighting` |
|
|
24
|
+
| 15 | Stuck enemies | Enemies or allies pressed against a wall, pacing on a ledge, frozen in the air, or a round that never ends because one is stranded | Stand at every spot the player can reach and count how many enemies arrive | `opengame-enemies` |
|
|
25
|
+
| 16 | Crash or reload during load | The tab reloads, the browser says a problem repeatedly occurred, or the game drops back to the menu near the end of the bar | Cold loads on a real phone in Safari and on a throttled desktop, several in a row | `opengame-stability`, `opengame-loading`, `opengame-mobile` |
|
|
26
|
+
|
|
27
|
+
## The order to fix them in
|
|
28
|
+
|
|
29
|
+
When time is short, in this order, because each step makes the next one worth doing:
|
|
30
|
+
|
|
31
|
+
1. The game loads and plays without crashing on the target devices, and the core loop
|
|
32
|
+
and its flagship moment work and feel right.
|
|
33
|
+
2. Every generated asset is in the game where it belongs, and no stand-in shows while
|
|
34
|
+
it loads.
|
|
35
|
+
3. The title, menus, pause and results are real screens in the game's own language.
|
|
36
|
+
4. A playtest from the real menu, reviewed by somebody who did not build it.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# A prompt for the fresh-context reviewer
|
|
2
|
+
|
|
3
|
+
Give this to a separate agent that has not seen the build conversation. Attach the
|
|
4
|
+
captures and the build's address, never a summary of what you changed.
|
|
5
|
+
|
|
6
|
+
> You are reviewing a browser game against a quality bar. You did not build it and you
|
|
7
|
+
> owe its builder nothing. Use only what you can observe in the attached captures and by
|
|
8
|
+
> playing the build at the address given, starting from its real menu.
|
|
9
|
+
>
|
|
10
|
+
> 1. For each of the sixteen cheap tells (listed below), say present or absent and cite
|
|
11
|
+
> the capture or the moment in play. If you could not observe it, say unverified.
|
|
12
|
+
> 2. Play for ninety seconds as a stranger. Write the first action you took, when you
|
|
13
|
+
> took it, and the first consequence you saw. Write every moment you were confused,
|
|
14
|
+
> waiting or bored.
|
|
15
|
+
> 3. For each area (control, look, light, sound, feedback, camera, animation, menus,
|
|
16
|
+
> performance, world), mark met, gap, unverified or not applicable, with evidence
|
|
17
|
+
> or a reason it does not apply to this game.
|
|
18
|
+
> 4. Name the single largest gap: the one change that would most raise how this game
|
|
19
|
+
> reads to a stranger. Be specific about where and what.
|
|
20
|
+
>
|
|
21
|
+
> Do not grade effort or intent. Do not accept an explanation in place of an
|
|
22
|
+
> observation. A "fine" that you cannot point at is unverified.
|
|
23
|
+
|
|
24
|
+
Then paste the table from [cheap-tells.md](cheap-tells.md).
|
|
25
|
+
|
|
26
|
+
Fix the single largest gap, capture again, and ask a fresh reviewer, not the same one:
|
|
27
|
+
a reviewer who has seen the previous round starts to see what they expect.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-router
|
|
3
|
+
description: Build, test and submit a browser game on OpenGame. Routes game work to the deploy guide, whole-game review and relevant craft skills. Use when someone asks to make a game, improve a game, check it, deploy it or enter an OpenGame jam.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.4"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Work on an OpenGame game
|
|
9
|
+
|
|
10
|
+
OpenGame opens on 17 November 2026, and jam entries open on 18 November.
|
|
11
|
+
Until OpenGame launches, the CLI and the creator API answer "OpenGame is not launched."
|
|
12
|
+
to everybody outside the OpenGame team. That is the platform's answer, not a fault in the
|
|
13
|
+
game: tell the person, and keep working on the game itself, which they can still build and
|
|
14
|
+
play in a browser.
|
|
15
|
+
|
|
16
|
+
Read [the working process](references/process.md) before changing the game. Keep the
|
|
17
|
+
user's scope and budget. Read only the specialists that apply to the next change.
|
|
18
|
+
|
|
19
|
+
The starting set is this router, `opengame-deploy` and `opengame-quality-bar`.
|
|
20
|
+
Run `opengame skills list --json` to see the installed CLI's catalog. Use
|
|
21
|
+
`opengame help --json` for its skill selection options before installing a specialist.
|
|
22
|
+
|
|
23
|
+
| Work | Skill |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| Check, deploy, private preview, submit | `opengame-deploy` |
|
|
26
|
+
| A CLI command, its output or its exit code | `opengame-cli` |
|
|
27
|
+
| Calling the API from your own tool or CI | `opengame-api` |
|
|
28
|
+
| Review the whole game | `opengame-quality-bar` |
|
|
29
|
+
| Controls, feedback, camera motion | `opengame-game-feel` |
|
|
30
|
+
| Lighting or color | `opengame-lighting`, `opengame-look` |
|
|
31
|
+
| Collision and movement | `opengame-world-physics` |
|
|
32
|
+
| Geometry, props or stairs | `opengame-scene-audit` |
|
|
33
|
+
| Frame time or memory | `opengame-performance` |
|
|
34
|
+
| Models, textures or audio assets | `opengame-assets`, `opengame-audio` |
|
|
35
|
+
| Characters, animation, or the player's own OG | `opengame-characters` |
|
|
36
|
+
| Menus or HUD | `opengame-front-end` |
|
|
37
|
+
| Keyboard, focus or accessibility | `opengame-accessibility` |
|
|
38
|
+
| Rules, goals or progression | `opengame-depth` |
|
|
39
|
+
| Integrating with OpenGame: the SDK, the player and every name field, boards, achievements, events, fullscreen and keys in the frame | `opengame-sdk` |
|
|
40
|
+
| Tests and evidence | `opengame-verification` |
|
|
41
|
+
| First-person guns, sights and viewmodels | `opengame-weapons` |
|
|
42
|
+
| Enemy AI, navigation, hordes, bosses, deaths | `opengame-enemies` |
|
|
43
|
+
| Boot time, streaming, caching, progress bar | `opengame-loading` |
|
|
44
|
+
| Touch, phone memory, Safari on a real phone | `opengame-mobile` |
|
|
45
|
+
| Crashes, pool budgets, error reporting | `opengame-stability` |
|
|
46
|
+
| Trailers, screenshots, filming the game | `opengame-capture` |
|
|
47
|
+
| A long build with agents and owner feedback rounds | `opengame-production` |
|
|
48
|
+
| Jam fields and eligibility | `opengame-jam` |
|
|
49
|
+
|
|
50
|
+
Run the whole-game review before handing over a finished game. Mark checks that do
|
|
51
|
+
not apply with a reason. Missing tools or evidence mean unverified.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Working process
|
|
2
|
+
|
|
3
|
+
Start by reading the user's request, repository instructions and current changes.
|
|
4
|
+
Keep other people's edits. When several agents share a checkout, agree on file
|
|
5
|
+
ownership before editing. Use the host's permissions and available tools.
|
|
6
|
+
|
|
7
|
+
Choose the smallest change that completes the request. Ask for missing information
|
|
8
|
+
only when it changes what can be done safely or correctly. Keep publication and
|
|
9
|
+
account actions within the user's authorization. A deploy is a private preview;
|
|
10
|
+
public release needs its own approval.
|
|
11
|
+
|
|
12
|
+
Use the user's time, spend and reporting limits. Set a bounded checkpoint before
|
|
13
|
+
starting uncertain research or a paid call. Stop at that checkpoint and report the
|
|
14
|
+
result. Do not invent permission, credentials, a budget or tools that are absent.
|
|
15
|
+
|
|
16
|
+
Inspect the result through the player's route. Keep evidence of input, state changes
|
|
17
|
+
and the frame the player sees. Run relevant checks in sequence. A changed check
|
|
18
|
+
needs a deliberate failing case before its passing result is useful.
|
|
19
|
+
|
|
20
|
+
Ask an independent reviewer to examine the result when the host permits delegation.
|
|
21
|
+
Give them the running artifact and its acceptance criteria. If independent review
|
|
22
|
+
is unavailable, say so and review the diff separately from the implementation.
|
|
23
|
+
|
|
24
|
+
Report what changed, what was observed and what remains uncertain. State blocked
|
|
25
|
+
work and the next useful action. Continue within the agreed scope; do not repeat
|
|
26
|
+
unchanged checks or start another polish pass without a concrete gap.
|
|
27
|
+
|
|
28
|
+
Keep public packages free of credentials, personal data and private transcripts.
|
|
29
|
+
Publish distilled lessons and synthetic examples. Inspect the packed files as well
|
|
30
|
+
as the source before releasing them.
|
|
31
|
+
|
|
32
|
+
## Long builds with feedback rounds
|
|
33
|
+
|
|
34
|
+
When a game is built over many rounds of the owner's feedback, most lost rounds have
|
|
35
|
+
process causes. OG Clash took about 190 numbered builds to reach its final game. Read
|
|
36
|
+
`opengame-production` before the first build: it covers the bar file written in the
|
|
37
|
+
first hour, the ask register, one integrator, frozen rounds with receipts, the latest
|
|
38
|
+
playable address, usage limits, machine load and status updates.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opengame-scene-audit
|
|
3
|
+
description: Audit a 3D browser game's geometry with a script. It finds floating and buried props, solids inside each other, coplanar faces that z-fight, solids with no collider or a collider that does not fit, cameras inside solids and duplicate actors, runs a walk bot up every staircase without jumping, and proves each check on a planted defect first. Use when the person says things float, z-fighting, I can walk through things, the screen goes black, stairs are broken, or before calling a level finished.
|
|
4
|
+
metadata:
|
|
5
|
+
version: "1.0.0"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Scene audit
|
|
9
|
+
|
|
10
|
+
A scene that looks right in a still can be full of geometry that is wrong: a crate
|
|
11
|
+
hovering a hand's width above the floor, two wall panels in one plane flickering as the
|
|
12
|
+
camera moves, a fence nobody can collide with. These are answerable from the scene's own
|
|
13
|
+
geometry, headless, in seconds. [helpers/scene-audit.js](helpers/scene-audit.js) does it;
|
|
14
|
+
copy it into the game.
|
|
15
|
+
|
|
16
|
+
Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
|
|
17
|
+
|
|
18
|
+
## Running it
|
|
19
|
+
|
|
20
|
+
In the browser, against the scene the game actually builds:
|
|
21
|
+
|
|
22
|
+
```js
|
|
23
|
+
import * as THREE from 'three'
|
|
24
|
+
import { runSceneAudit, fromThreeScene, formatReport } from './scene-audit.js'
|
|
25
|
+
|
|
26
|
+
const scene = fromThreeScene(THREE, world, { colliders: collisionBoxes, groundY: 0 })
|
|
27
|
+
scene.routes = [{ name: 'tower stairs', from: [4, 0, 12], to: [4, 6, -2] }]
|
|
28
|
+
const report = runSceneAudit(scene)
|
|
29
|
+
console.log(formatReport(report))
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Mark meshes through `userData`: `collider: true` for collision geometry,
|
|
33
|
+
`nocollide: 'foliage'` for drawn things a body may pass, `hangs: 'lamp on a chain'` for
|
|
34
|
+
things held up by design, `group: 'truck'` for parts of one object that touch on
|
|
35
|
+
purpose, `decal: true` for layered decals. In Node, build the same `{ parts, colliders,
|
|
36
|
+
routes }` shape from the level's own layout data; the file imports nothing.
|
|
37
|
+
|
|
38
|
+
`report.ok` is true when the applicable checks caught their planted defects, examined
|
|
39
|
+
the scene and found no defects. For a level with no stairs or ramps, pass
|
|
40
|
+
`{ notApplicable: { stairs: "This level has no stairs or ramps" } }`. List a reason for
|
|
41
|
+
each omitted check. An empty check without a reason remains a failure. Findings name the part, the world position and why.
|
|
42
|
+
|
|
43
|
+
The adapter reads each visible mesh as one world-space box plus its triangles. It skips
|
|
44
|
+
skinned meshes (characters are judged in `opengame-characters`), and reads an
|
|
45
|
+
`InstancedMesh` as one box around all its instances, so expand instanced props that
|
|
46
|
+
matter into one part per instance before auditing them.
|
|
47
|
+
|
|
48
|
+
## Rules
|
|
49
|
+
|
|
50
|
+
### Every check proves itself first
|
|
51
|
+
- **Invariant:** No check reports on the real scene until it has found a known defect planted in it, and an applicable check that examined nothing is a failure.
|
|
52
|
+
- **Technique:** Before measuring, plant a floating crate, a buried prop, two interpenetrating crates, two coplanar panels and a collider-less wall at an open site chosen from the real scene, and a staircase with one riser too tall. Report how many things each check examined.
|
|
53
|
+
- **Reference configuration:** DK's first coplanar audit clipped triangles with inverted winding and measured 0 m² on every prop, including one already known to have 0.4 m². AW plants a defect for each of its eight checks into every map under test, and its plants have found two bugs in the checks themselves.
|
|
54
|
+
- **Applies when:** Every audit, every run.
|
|
55
|
+
- **Verify:** `formatReport` prints `plant caught` and a non-zero examined count for every check.
|
|
56
|
+
|
|
57
|
+
### No camera inside a solid
|
|
58
|
+
- **Invariant:** No camera (gameplay, cinematic, menu or capture) has its near plane inside geometry, and no framed shot is mostly blocked by near cover.
|
|
59
|
+
- **Technique:** Before using a camera position, test a sphere the size of the near plane against the colliders and cast from the subject to the camera; pull the camera in, or reject the position. Aim framed shots from the subject's live joints, so a change of scale moves the camera with it. Reject shots where near cover fills a large share of the frame. In a debug build, log every frame whose camera is inside a collider. In three.js run the test against the physics world (Rapier's shape-intersection queries) or `Box3.containsPoint` on collider boxes, and raycast from the subject with `Raycaster.far` set to the camera distance.
|
|
60
|
+
- **Reference configuration:** OC's game-over screen rendered a black 3D layer from r57 to r66, about 7 hours, because its camera was 0.3 m inside a stone ledge: black at 66.33 m, the full scene at 66.22 m. A light at infinity was blamed first. OC's victory camera ended inside rubble, then inside the boss, and a change to the boss's scale broke every framed shot. OC rejects a shot with more than 25% near cover.
|
|
61
|
+
- **Applies when:** Every 3D game with scripted, menu, capture or follow cameras.
|
|
62
|
+
- **Verify:** Sample every authored camera and every ending camera at each boss scale and arena variant: the audit reports zero cameras inside solids, and the captures contain no black frame with the HUD still drawn.
|
|
63
|
+
|
|
64
|
+
### Nothing floats
|
|
65
|
+
- **Invariant:** Every part is held up by the ground through some chain of contact, unless it hangs by design and says so.
|
|
66
|
+
- **Technique:** Seed the supported set from parts resting on the ground or a published floor, then spread support through contact until nothing changes. Two parts touching each other in mid-air do not hold each other up.
|
|
67
|
+
- **Reference configuration:** AW: a base more than 0.12 m (a hand's width) above its support floats; parts within 0.08 m touch. Ten AW boulders hung 0.13 m over a cliff path for nine rounds because each rock's base touched its own cap.
|
|
68
|
+
- **Applies when:** Any 3D scene with props and structures.
|
|
69
|
+
- **Verify:** The float check reports zero, and a planted crate above the floor is reported.
|
|
70
|
+
|
|
71
|
+
### Nothing is sunk
|
|
72
|
+
- **Invariant:** A prop stands on the floor, not in it, while foundations and footings may go as deep as they need.
|
|
73
|
+
- **Technique:** Compare each prop's base with the floor under its centre; anything larger than a prop is structure and is not judged.
|
|
74
|
+
- **Reference configuration:** AW: a prop's base more than 0.25 m under the floor is buried; anything over 2.5 m in plan or height is structure.
|
|
75
|
+
- **Applies when:** Any scene with props on floors or terrain.
|
|
76
|
+
- **Verify:** The buried check reports zero.
|
|
77
|
+
|
|
78
|
+
### Solids do not share volume
|
|
79
|
+
- **Invariant:** Two solid objects that are not one authored object do not occupy the same space.
|
|
80
|
+
- **Technique:** Judge overlap two ways, because each misses what the other sees: depth past the thinner part's own thickness catches a wall through a wall; a fraction of the smaller part catches two equal crates inside each other. A wall corner overlapping by one thickness is a joint, not a defect.
|
|
81
|
+
- **Reference configuration:** AW: shared volume above 0.02 m³ and either more than 20% of the smaller part or deeper than the thinner part plus 0.05 m. AW's depth-only version missed its own planted defect.
|
|
82
|
+
- **Applies when:** Any scene with placed solids.
|
|
83
|
+
- **Verify:** The interpenetration check reports zero.
|
|
84
|
+
|
|
85
|
+
### No two faces in one plane
|
|
86
|
+
- **Invariant:** No two visible opaque faces lie in the same plane facing the same way and overlapping, so nothing flickers as the camera moves.
|
|
87
|
+
- **Technique:** Bin faces by normal and plane distance, clip candidate pairs against each other in their shared plane, and sum the overlap. Repair the geometry (cut, inset, overrun one member a few millimetres into the other) before reaching for depth bias; use polygon offset only for a real layered surface such as a decal.
|
|
88
|
+
- **Reference configuration:** AW and DK: faces within 2 mm of one plane with more than 0.02 m² of overlap. DK's triangle audit found 187.7 m² of fighting surface, 150 m² of it from every crate drawing its rails twice. AW holds wall decals 4 to 90 mm off the wall.
|
|
89
|
+
- **Applies when:** Every scene with opaque geometry, distant scenery included: a face that flickers on the skyline flickers on screen.
|
|
90
|
+
- **Verify:** The coplanar check reports zero area. Then pan slowly at a grazing angle past the busiest joins.
|
|
91
|
+
|
|
92
|
+
### Every visible solid blocks the body
|
|
93
|
+
- **Invariant:** Anything drawn solid has a collider or a stated reason it does not.
|
|
94
|
+
- **Technique:** Compare visible solids with the collision layer; give each uncovered one a collider or a `nocollide` reason. Check fit as well as presence: report any collider whose box covers clearly less than its mesh, and any walkable or blocking prop (railing, low wall, pier, roof, fence) with none.
|
|
95
|
+
- **Reference configuration:** AW's body-physics gate found bodies reaching positions inside drawn opaque volume with no collider on every map. OC's palisade, fences, railings and roofs had no collider, and its building boxes covered 84% of the footprint (`opengame-world-physics` has the rest).
|
|
96
|
+
- **Applies when:** Every game with a walking body.
|
|
97
|
+
- **Verify:** The colliders check reports zero; the walk bot reports no walk-throughs. The walk bot only sees the routes you give it, so the colliders check is the one that covers the whole level.
|
|
98
|
+
|
|
99
|
+
### Every staircase climbed forward-only
|
|
100
|
+
- **Invariant:** The walk bot reaches the top of every flight holding forward, with no jump.
|
|
101
|
+
- **Technique:** Add a route for every staircase, ramp and ladder-free climb in the level. The bot is a capsule that steps up at most one step height and slides along whatever blocks it.
|
|
102
|
+
- **Reference configuration:** AW's body radius 0.35 m, height 1.8 m and step 0.42 m are the bot's defaults; pass the game's own numbers as `tolerances`. OC's owner raised stairs that needed a jump 3 times; OC settled on a 0.4 m step for the player and the zombies alike. Run the routes a second time with the AI body's numbers when they differ from the player's (`opengame-world-physics`).
|
|
103
|
+
- **Applies when:** Any game with stairs or ramps.
|
|
104
|
+
- **Verify:** The stairs check examined as many routes as the level has flights and reports zero.
|
|
105
|
+
|
|
106
|
+
### Freeze the frame and look closely
|
|
107
|
+
- **Invariant:** The places a person would inspect have been inspected: contact points, joins, roofs, terrain edges, the skyline.
|
|
108
|
+
- **Technique:** Six fixed cameras placed once per level (two at grazing angles along major walls, one looking up at a ceiling join, one along a terrain edge, one across the busiest floor at prop height, one at the skyline) captured every round, so the same views can be compared before and after.
|
|
109
|
+
- **Reference configuration:** DK's report of a cabinet whose side fought its skin came from a player's photograph at exactly such a join.
|
|
110
|
+
- **Applies when:** Every 3D level.
|
|
111
|
+
- **Verify:** Six captures per round, with the same camera transforms, reviewed by somebody who did not build the level.
|
|
112
|
+
|
|
113
|
+
### Each actor is drawn once
|
|
114
|
+
- **Invariant:** Each screen shows the expected number of each actor: one boss, one player character, no frozen leftover copy.
|
|
115
|
+
- **Technique:** At the title, in play and on the results screen, count live root objects per actor type in the scene and compare with a table of expected counts. After any rebuild or clone, apply per-instance overrides again.
|
|
116
|
+
- **Reference configuration:** OC shipped "two titans one moving one frozen". A hidden-head flag that was not reset on a material rebuild gave one character a double head.
|
|
117
|
+
- **Applies when:** Every game with characters, bosses or scripted scenes.
|
|
118
|
+
- **Verify:** The count check passes on every screen, including after a character switch and a restart.
|
|
119
|
+
|
|
120
|
+
## Tuning
|
|
121
|
+
|
|
122
|
+
Every tolerance is in `TOLERANCES` and can be overridden per run. Change them for a
|
|
123
|
+
different scale (a miniature world, a giant), never to make a finding go away.
|