@opengamehq/cli 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/AGENTS.md +238 -0
  2. package/CHANGELOG.md +22 -0
  3. package/README.md +129 -2
  4. package/dist/cli.mjs +1432 -0
  5. package/dist/opengame-global.js +49 -0
  6. package/dist/opengame-global.js.LEGAL.txt +1 -0
  7. package/dist/preflight-worker.mjs +20 -0
  8. package/dist/runtime-builder.mjs +800 -0
  9. package/dist/runtime-catalog.json +1 -0
  10. package/dist/runtime-catalog.sha256 +1 -0
  11. package/dist/runtime-shells/runtime-shell.html +4 -0
  12. package/dist/runtime-shells/runtime-shell.js +91 -0
  13. package/dist/safe-fs.py +242 -0
  14. package/dist/skills/manifest.json +516 -0
  15. package/dist/skills/opengame-accessibility/SKILL.md +90 -0
  16. package/dist/skills/opengame-api/SKILL.md +85 -0
  17. package/dist/skills/opengame-assets/SKILL.md +124 -0
  18. package/dist/skills/opengame-assets/references/pipeline.md +97 -0
  19. package/dist/skills/opengame-audio/SKILL.md +154 -0
  20. package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
  21. package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
  22. package/dist/skills/opengame-capture/SKILL.md +108 -0
  23. package/dist/skills/opengame-capture/references/pipeline.md +82 -0
  24. package/dist/skills/opengame-capture/references/threejs.md +145 -0
  25. package/dist/skills/opengame-characters/SKILL.md +129 -0
  26. package/dist/skills/opengame-characters/references/integration.md +144 -0
  27. package/dist/skills/opengame-characters/references/player-og.md +160 -0
  28. package/dist/skills/opengame-cli/SKILL.md +118 -0
  29. package/dist/skills/opengame-deploy/SKILL.md +207 -0
  30. package/dist/skills/opengame-deploy/references/json-events.md +62 -0
  31. package/dist/skills/opengame-deploy/references/manifest.md +83 -0
  32. package/dist/skills/opengame-deploy/references/packaging.md +117 -0
  33. package/dist/skills/opengame-depth/SKILL.md +130 -0
  34. package/dist/skills/opengame-enemies/SKILL.md +103 -0
  35. package/dist/skills/opengame-enemies/references/threejs.md +134 -0
  36. package/dist/skills/opengame-front-end/SKILL.md +143 -0
  37. package/dist/skills/opengame-front-end/references/launch.md +50 -0
  38. package/dist/skills/opengame-front-end/references/menus.md +47 -0
  39. package/dist/skills/opengame-game-feel/SKILL.md +137 -0
  40. package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
  41. package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
  42. package/dist/skills/opengame-jam/SKILL.md +103 -0
  43. package/dist/skills/opengame-lighting/SKILL.md +94 -0
  44. package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
  45. package/dist/skills/opengame-loading/SKILL.md +99 -0
  46. package/dist/skills/opengame-loading/references/threejs.md +116 -0
  47. package/dist/skills/opengame-look/SKILL.md +114 -0
  48. package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
  49. package/dist/skills/opengame-mobile/SKILL.md +90 -0
  50. package/dist/skills/opengame-performance/SKILL.md +140 -0
  51. package/dist/skills/opengame-performance/references/measuring.md +72 -0
  52. package/dist/skills/opengame-production/SKILL.md +131 -0
  53. package/dist/skills/opengame-production/references/templates.md +63 -0
  54. package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
  55. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
  56. package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
  57. package/dist/skills/opengame-router/SKILL.md +51 -0
  58. package/dist/skills/opengame-router/references/process.md +38 -0
  59. package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
  60. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
  61. package/dist/skills/opengame-sdk/SKILL.md +270 -0
  62. package/dist/skills/opengame-sdk/references/engines.md +93 -0
  63. package/dist/skills/opengame-sdk/references/frame.md +107 -0
  64. package/dist/skills/opengame-sdk/references/identity.md +112 -0
  65. package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
  66. package/dist/skills/opengame-sdk/references/radio.md +71 -0
  67. package/dist/skills/opengame-stability/SKILL.md +84 -0
  68. package/dist/skills/opengame-verification/SKILL.md +136 -0
  69. package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
  70. package/dist/skills/opengame-weapons/SKILL.md +109 -0
  71. package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
  72. package/dist/skills/opengame-weapons/references/threejs.md +169 -0
  73. package/dist/skills/opengame-world-physics/SKILL.md +114 -0
  74. package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
  75. package/package.json +38 -4
@@ -0,0 +1,118 @@
1
+ ---
2
+ name: opengame-cli
3
+ description: Drive the OpenGame command line tool from an agent. Covers installing it, signing in with the person, every command, JSON and JSONL output, exit codes, findings and how to retry. Use when the person mentions the opengame command, the OpenGame CLI, installing @opengamehq/cli, opengame login, check, dev, deploy, status, submit or token, or a command exited with an error you need to read.
4
+ metadata:
5
+ version: "1.0.4"
6
+ ---
7
+
8
+ # Use the OpenGame CLI
9
+
10
+ OpenGame opens on 17 November 2026, and the CLI on 18 November. Until 18 November, every command except `version`, `help`, `login`, `logout` and `whoami` prints
11
+ "OpenGame opens for creators on 18 November." for anybody outside the OpenGame team, and exits with the
12
+ `not_launched` code (7) that `opengame help --json` lists. That is the platform's answer,
13
+ not a broken install: tell the person, and do not retry, reinstall or look for a way round it.
14
+
15
+ For the whole deploy procedure, read `opengame-deploy`. This skill is the reference
16
+ for the tool itself.
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ npm i -g @opengamehq/cli
22
+ ```
23
+
24
+ Once `opengame` is installed, confirm it and read the command reference:
25
+
26
+ ```bash
27
+ opengame version --json
28
+ opengame help --json
29
+ ```
30
+
31
+ `help --json` is the authority on commands, flags and exit codes for the version that
32
+ is installed. Read it before using a flag this page does not show.
33
+
34
+ ## Sign in with the person
35
+
36
+ ```bash
37
+ opengame whoami --json
38
+ ```
39
+
40
+ If that exits 3, start a login. In JSON or agent mode it prints a URL and a code and
41
+ exits 3 with `login_pending` straight away:
42
+
43
+ ```bash
44
+ opengame login --json
45
+ ```
46
+
47
+ Give the person the URL and the code. They open it, type the code and press Allow
48
+ access; you cannot approve it for them. Once they say they have, finish:
49
+
50
+ ```bash
51
+ opengame login --continue --json
52
+ ```
53
+
54
+ `login_expired` or `no_pending_login` means start again with `login --json`.
55
+
56
+ For CI, use a token the person makes in their browser with `opengame token create`,
57
+ supplied as `OPENGAME_TOKEN` or on standard input with `--token-stdin`. Never put a
58
+ token in a command argument, a file in the project, a log or a reply.
59
+
60
+ ## Commands
61
+
62
+ | Command | What it does |
63
+ | --- | --- |
64
+ | `opengame init [dir]` | Create opengame.json for an existing game. |
65
+ | `opengame check [dir]` | Find local build and asset problems before uploading. |
66
+ | `opengame dev [dir]` | Serve a local export with the game runtime's headers. |
67
+ | `opengame login` | Sign in through the browser. |
68
+ | `opengame deploy [dir]` | Build, check and upload a release to a private preview. |
69
+ | `opengame status [dir]` | Show the latest deploy for this folder, with its findings. |
70
+ | `opengame deployments [dir]` | List the linked game's deploys, newest first. |
71
+ | `opengame open [dir]` | Open the linked game's private page. |
72
+ | `opengame submit [dir]` | Send one release to review, and enter it in a jam. |
73
+ | `opengame jams [slug]` | List open jams, or show one jam's tracks and flags. |
74
+ | `opengame games` | List your games and their latest deploy. |
75
+ | `opengame link [dir]` | Connect this folder to an existing game. |
76
+ | `opengame pull [dir]` | Bring website metadata into this folder. |
77
+ | `opengame stats [game or dir]` | Read a week of analytics for a game you own. |
78
+ | `opengame whoami` | Show the account and permissions for this token. |
79
+ | `opengame token create, list or revoke` | Manage tokens, in the browser. |
80
+ | `opengame logout` | Revoke this device's token and remove it. |
81
+ | `opengame limits` | Show bundle limits and the account's remaining allowance. |
82
+ | `opengame vendor [dir]` | Make a separate export with dependencies downloaded and pinned. |
83
+ | `opengame skills add or list` | Install the OpenGame skills for a coding agent. |
84
+ | `opengame upgrade` | Install the current CLI, or print the line that does. |
85
+ | `opengame version` | Print the CLI version. |
86
+
87
+ ## Read the output
88
+
89
+ Add `--json` for one final object, or `--jsonl` for progress events with the result
90
+ or error as the last line. Every result has `type`, `ok`, `findings` and `notices`. A
91
+ success carries its values in `data`. An error carries `code`, `message` and, where it
92
+ helps, `retry`, `retryAfterSeconds` and `next`, the command to run next.
93
+
94
+ | Exit | Name | What to do |
95
+ | --- | --- | --- |
96
+ | 0 | `ok` | Done. A deploy with `data.done: false` is still being checked; follow it with `opengame status --watch --json`. |
97
+ | 1 | `check` | The game needs a change. Read the findings, fix, and run each finding's `verify` command. |
98
+ | 2 | `input` | A flag, a choice or a different command is needed. The message names it. |
99
+ | 3 | `auth` | Sign in, or use a token with the right scope. Run the error's `next` when it has one. |
100
+ | 4 | `rateLimited` | An allowance is used. Wait `retryAfterSeconds`, then run the same command. |
101
+ | 5 | `server` | Our side or the network; the game is fine. Follow `retry`. |
102
+ | 6 | `upgrade` | This CLI is too old. Run `opengame upgrade --json`. |
103
+
104
+ `not_launched` has an exit code of its own, listed by `help --json`. Branch on the
105
+ error's `code` rather than the number wherever you can.
106
+
107
+ ## Act on findings
108
+
109
+ Each finding has `fault`, `certainty` and `retry`:
110
+
111
+ - `fault: game`: make the change its `fix` describes, then run its `verify` command.
112
+ - `certainty: heuristic`: check the evidence before changing code that works.
113
+ - `fault: platform`: leave the game alone and follow `retry`. `now` means run the same
114
+ command again, `later` means wait, and `after-fix` or `never` means waiting will not
115
+ help, so read `fix`.
116
+
117
+ Keep retries bounded. If the same platform failure repeats, give the person the
118
+ command, the error code and the evidence instead of trying again.
@@ -0,0 +1,207 @@
1
+ ---
2
+ name: opengame-deploy
3
+ description: Put a browser game online with OpenGame, the marketplace and game jam for browser games. Packages the game, checks it locally, uploads it to a private preview only the owner can play, reads and fixes findings, then submits one exact release for review. Use when the person says deploy my game, put it online, host it, share it, upload it, publish it, get me a link, make it playable for friends, or asks where to put a browser game or a Three.js game.
4
+ metadata:
5
+ version: "1.0.9"
6
+ ---
7
+
8
+ # Deploy a browser game to OpenGame
9
+
10
+ OpenGame opens on 17 November 2026. The CLI, uploads and jam entries open on 18 November.
11
+ Until then, every CLI command except `version`, `help`, `login`, `logout` and `whoami`
12
+ prints "OpenGame opens for creators on 18 November." for anybody outside the OpenGame team, and the API
13
+ refuses with `not_launched`. Nothing is wrong with the game or the install: tell the
14
+ person, and do not retry, reinstall or work around it.
15
+
16
+ <!-- generated:procedure -->
17
+ Deploy the creator's game to a private preview, give them its link, and submit it only when they ask. Read each command's result before you run the next one.
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ npm i -g @opengamehq/cli
23
+ ```
24
+
25
+ Once `opengame` is installed, confirm it and read the command reference:
26
+
27
+ ```bash
28
+ opengame version --json
29
+ opengame help --json
30
+ ```
31
+
32
+ `help --json` lists every command, flag, exit code, environment variable and event, with the finding schema. Read it rather than guessing a flag.
33
+
34
+ Install the OpenGame skills for the agent you run in, from the game folder:
35
+
36
+ ```bash
37
+ opengame skills add .
38
+ ```
39
+
40
+ The CLI talks to `https://opengame.io`. Never put a token in a command argument, a file in the repository, a log or a reply. For CI, set `OPENGAME_TOKEN` or pipe the token with `--token-stdin`.
41
+
42
+ ## Output
43
+
44
+ Every command takes `--json`. When stdout is not a terminal, or `CI`, `CLAUDECODE` or another agent's variable is set, `--json` is the default. A command then prints one object:
45
+
46
+ ```json
47
+ {
48
+ "type": "result",
49
+ "command": "deploy",
50
+ "data": { "state": "queued", "done": false },
51
+ "ok": true,
52
+ "url": "https://opengame.io/settings/deployments/<id>",
53
+ "next": "opengame status --watch",
54
+ "findings": [],
55
+ "notices": []
56
+ }
57
+ ```
58
+
59
+ An error has `"type": "error"`, `"ok": false`, a `code`, a `message`, an `exitCode` and, when there is one, a `next` command to run. `--jsonl` streams one event per line instead: `progress`, `notice`, `finding`, then a `result` or `error` last. In either mode there are no prompts and no browser opens.
60
+
61
+ | Exit | Meaning | What to do |
62
+ | --- | --- | --- |
63
+ | 0 | Done | Read `data`. `data.done: false` means the server is still working. |
64
+ | 1 | The game needs a change | Fix each finding, then run its `verify` command. |
65
+ | 2 | The command needs input | Read the message. It names the missing flag or choice. |
66
+ | 3 | Sign in, or a token with the right scope | Run `next` when the error has one. |
67
+ | 4 | An allowance is used up | Wait `retryAfterSeconds`, then run the same command. |
68
+ | 5 | Our side or the network | Leave the game as it is. Run `next` when the error has one; otherwise wait and retry, at most a few times. |
69
+ | 6 | The CLI is too old | Run `opengame upgrade --json`, then the npm command in `data.command`. |
70
+ | 7 | OpenGame is not open to creators yet | Stop. Tell the creator the CLI and uploads open on 18 November. |
71
+
72
+ ## Sign in with the creator
73
+
74
+ ```bash
75
+ opengame whoami --json
76
+ ```
77
+
78
+ Exit 0 means a saved login works. Exit 3 means start one:
79
+
80
+ ```bash
81
+ opengame login --json
82
+ ```
83
+
84
+ `login --json` prints the approval link and code as a `device_approval` notice, then exits 3 with `login_pending`. Give the creator both. They open the link, sign in, type the code and press Allow access. You cannot approve it for them. When they say they have, finish:
85
+
86
+ ```bash
87
+ opengame login --continue --json
88
+ ```
89
+
90
+ `--continue` waits up to 10 seconds for the approval.
91
+
92
+ | Result | What to do |
93
+ | --- | --- |
94
+ | Exit 0 | Signed in. `data.handle` is the creator's handle. |
95
+ | Exit 3, `login_pending` | Not approved yet. Run `login --continue --json` again once the creator has pressed Allow access. |
96
+ | Exit 3, `access_denied` | The creator pressed Deny, or the account cannot be used. Read the message to them. |
97
+ | `login_expired` or `no_pending_login` | The code ran out. Run `login --json` for a new one. |
98
+
99
+ ## Deploy a private preview
100
+
101
+ Run these from the game folder.
102
+
103
+ If the folder has no `opengame.json`, create one. Ask the creator whether it is a game, a world, a decomp or a mod; a decomp or a mod names the game it is based on:
104
+
105
+ ```bash
106
+ opengame init . --title "My game" --json
107
+ opengame init . --title "Doom but blue" --kind mod --based-on "Doom" --json
108
+ ```
109
+
110
+ Then fill in `description` (40 characters or more) and `genre` in `opengame.json`. If the file already exists, leave `init` alone and edit the file.
111
+
112
+ For a game that already exists on OpenGame, in a new checkout, link the folder first so the deploy does not create a second game:
113
+
114
+ ```bash
115
+ opengame games --json
116
+ opengame link --game <id> --json
117
+ ```
118
+
119
+ Check, then deploy:
120
+
121
+ ```bash
122
+ opengame check . --build --json
123
+ opengame deploy . --json
124
+ ```
125
+
126
+ `deploy` runs the manifest's build command, checks the output and uploads it, up to 1 GiB zipped. It returns once the upload is in, with exit 0 and `data.done: false`, while the checks run on the server. Keep `.opengame/`: later commands resume and follow the same deploy from it. Use `--no-build` only when the creator says the export is already built and its build cannot run here, never to get past a failing build.
127
+
128
+ | Field | What it holds |
129
+ | --- | --- |
130
+ | `data.deploymentUrl` | The deploy's page. Give it to the creator straight away: it shows each check and plays the preview once they pass. |
131
+ | `data.state` | `uploading`, `queued`, `checking`, `ready`, `failed` or `expired`. |
132
+ | `data.done` | `true` once the server has finished. |
133
+ | `data.releaseId` | The release. Keep it for `submit`. |
134
+ | `data.previewUrl` | The private preview link, once `state` is `ready`. It can be `null` on a ready release the server will not play; the deploy's page says why. |
135
+ | `data.gameOrigin` | The origin the published game runs at, such as `https://k3v9q2m7x4ab.opengame.gg`. Give it to the creator when the game talks to their own servers. `null` when the server sent none, or sent one this CLI cannot read. |
136
+
137
+ To follow the checks, run `status --watch`, which follows the deploy for up to 300 seconds. Set `--timeout <seconds>` for a short tool call; when it runs out the command exits 5 with `checks_pending` and the checks carry on.
138
+
139
+ ```bash
140
+ opengame status --watch --timeout 60 --json
141
+ ```
142
+
143
+ To block on the outcome in one command, deploy with `--wait`:
144
+
145
+ ```bash
146
+ opengame deploy . --wait --json
147
+ ```
148
+
149
+ Tell the creator the preview is ready only when a result says `data.state: "ready"` and `data.done: true`. Give them `data.previewUrl` and `data.releaseId`. Play it, or ask them to, before you say the game works.
150
+
151
+ ## Fix findings
152
+
153
+ Each finding has a `fault`, a `certainty` and a `retry`:
154
+
155
+ | Finding | What to do |
156
+ | --- | --- |
157
+ | `fault: game` | Read `evidence`, make the change in `fix`, then run the command in `verify`. |
158
+ | `certainty: heuristic` | Check the evidence before you change working code. |
159
+ | `fault: platform` | Leave the game as it is. Follow `retry`: `now` runs again, `later` waits `retryAfterSeconds`, `after-fix` and `never` mean waiting will not help, so read `fix`. |
160
+ | `fault: unknown` | A person decides at review. Report it to the creator. |
161
+
162
+ A plain `deploy` resumes a saved upload, or starts a fresh one with an `upload_restarted` notice when the saved one can no longer finish. A deploy started with `--idempotency-key` exits 2 instead. Start a fresh one with a new key, or without the flag:
163
+
164
+ ```bash
165
+ opengame deploy . \
166
+ --idempotency-key <a new key> --json
167
+ ```
168
+
169
+ Before a large batch of deploys, run `opengame limits --json` for the upload limits and the allowance left on the account. If the same platform failure repeats, stop and give the creator the command, the error code and the evidence.
170
+
171
+ ## Submit only on request
172
+
173
+ A deploy makes a private preview that only the creator's account can open. `opengame submit` sends a release to review, and the game goes public once review approves it and it is published. Submit only when the creator asks, and send the exact `releaseId` they played.
174
+
175
+ ```bash
176
+ opengame jams --json
177
+ opengame submit --release <releaseId> --no-wait --json
178
+ ```
179
+
180
+ OpenGame decides where submissions go. When that is a jam, the submission is the creator's entry: read the form with `opengame jams <slug> --json`, ask the creator for their track, the models they used and any sponsor evidence, and pass them as `--track`, `--models`, `--sponsor` and `--evidence-<sponsor>`. A missing answer exits 2 and names the flag. A decomp or a mod cannot enter a jam.
181
+
182
+ When `data.state` is `needs_certification`, give the creator `data.certifyUrl`, which the CLI also prints as a `certify_required` notice. They certify in their own browser that they have the rights to the game. You cannot do it for them. Follow the review with:
183
+
184
+ ```bash
185
+ opengame status --watch --json
186
+ ```
187
+
188
+ ## What a game may do
189
+
190
+ OpenGame hosts static browser exports. The build needs `index.html` at the root of its output folder.
191
+
192
+ At runtime the game may call its own origin, `https://api.opengame.gg`, and any other `https:` or `wss:` host. Each call comes from the player's browser, so that host sees the player's IP address. Keep API keys on the creator's server, never in the bundle: players can read every file in it. The review sandbox has no internet, so the game must draw its first frame without its server.
193
+
194
+ The published game runs at `https://<label>.opengame.gg`, one origin per game, and `opengame deploy` returns it as `data.gameOrigin`. While an experiment runs, players load each version taking part from a `v-` origin instead. If the creator's servers check `Origin` (WebSocket) or send CORS headers (HTTP), they reject the game's requests until that exact origin is on their list, and online play fails with a closed socket, a 401 or 403 on the upgrade, or a CORS error in the console. Tell the creator to add it, and to add a version's `v-` origin before starting an experiment with it. Never suggest allowing `*.opengame.gg`, `null` or any pattern on `opengame.gg`, because other people's games are served there too and a pattern lets them call the creator's server. Use a token in a header or the first socket message, not a cookie. A private preview runs on a temporary `p-` origin, not the game's. That address is a private link, so keep it out of committed config and logs. [Games that talk to your own servers](https://docs.opengame.io/guides/packaging#games-that-talk-to-your-own-servers) has server examples.
195
+
196
+ A game may not take payments, use crypto, make players create an account or give an email address, show ads, or carry ad pixels or session recording. [Packaging](https://docs.opengame.io/guides/packaging) has every rule and every check.
197
+
198
+ ## Engines
199
+
200
+ OpenGame supports games built with Three.js, Unity, Godot, Kaigen and WebAssembly, and static web builds from any JavaScript engine. `opengame check` and the server detect the engine from the build. Any other static browser export uploads as a custom build, under the same file, scan and runtime checks.
201
+
202
+ Run `opengame init . --engine <id>` to record an engine's export folder. `opengame help --json` lists the IDs, and `init` prints the export steps and the guide for the one you choose. The [engine overview](https://docs.opengame.io/engines/overview) links every engine page.
203
+
204
+ Play the private preview before you tell the creator the game works.
205
+ <!-- /generated:procedure -->
206
+
207
+ For field definitions, read [references/manifest.md](references/manifest.md). For the full packaging contract, read [references/packaging.md](references/packaging.md). For sample findings, read [references/json-events.md](references/json-events.md). Read `opengame-jam` for eligibility, certifications and judging rules.
@@ -0,0 +1,62 @@
1
+ # Reading the CLI's JSON
2
+
3
+ With `--json` every line of output is one JSON object. Four kinds can appear before the
4
+ last line, and the last line is always a `result` or an `error`.
5
+
6
+ | `type` | Meaning | What to do |
7
+ | --- | --- | --- |
8
+ | `progress` | A stage started or moved on: `build`, `check`, `upload`, then the server's own stages for the deploy, `certify` and `review:<state>` for a submit, `approval` for a login | Nothing; it is a heartbeat |
9
+ | `notice` | Something the person should know: excluded files, kept website metadata, a resumed upload, a sign-in URL | Read `code` and `message`; pass sign-in and kept-metadata notices on |
10
+ | `finding` | One problem in the game or one check that could not decide | Fix or report it, by its `fault`, `certainty` and `retry` |
11
+ | `result` | The command finished; `data` holds its answer | Read `data` |
12
+ | `error` | The command stopped; `code`, `message`, `exitCode`, `retry`, and `next`, `retryAfterSeconds` or `finding` when they apply | Run `next` when there is one; otherwise act on the exit code below |
13
+
14
+ ## Exit codes
15
+
16
+ | Code | Meaning | What an agent does |
17
+ | --- | --- | --- |
18
+ | 0 | Done | Read the result |
19
+ | 1 | A check failed | Fix the findings, run `opengame check`, then deploy again |
20
+ | 2 | Input missing or invalid | The message names the flag or value to supply |
21
+ | 3 | Not signed in, or the token lacks permission. A login waiting for approval also exits 3, with code `login_pending` | `login_pending`: show the person the URL and code, then run `next` (`opengame login --continue`) until it exits 0. Otherwise `opengame whoami`, then `opengame login`, or ask for a token with the right scope |
22
+ | 4 | Rate limited | Wait `retryAfterSeconds` if the error has it, otherwise a few minutes, then run the same command once. Do not loop |
23
+ | 5 | Our side failed, or a local file could not be read or written | The game is fine. Retry later; never change the game for this |
24
+ | 6 | This CLI is too old for the server | Run `next`, which is `opengame upgrade`. Signed out, run `opengame login` first; it works on this version |
25
+
26
+ ## A worked repair
27
+
28
+ A game whose `index.html` loads `./Game.js` while the file on disk is `game.js`. It runs
29
+ on the creator's Mac, because the Mac's file system ignores case, and is a missing file for every
30
+ player. `opengame check . --json` printed, from a real run:
31
+
32
+ ```json
33
+ {"type":"finding","finding":{"release":null,"check":"case-mismatch","checkVersion":"packaging@1","state":"failed","certainty":"certain","fault":"game","evidence":{"observed":"index.html line 1 asks for Game.js, but the file is game.js.","file":"index.html:1"},"fix":"macOS and Windows do not care about capitalisation. The servers that hand your game to a player do. So this loads on your machine and the file is missing for everybody else. Fix the reference or rename the file so the two match exactly.","verify":"opengame check, then opengame deploy","retry":"after-fix"}}
34
+ {"type":"finding","finding":{"release":null,"check":"platform-engine","checkVersion":"packaging@1","evidence":{"observed":"Could not confirm Three.js in this build."},"state":"inconclusive","certainty":"heuristic","fault":"unknown","fix":"The build can proceed. A reviewer will confirm the engine before publication. Nothing has to change now; you can deploy as it is.","verify":"opengame deploy","retry":"never"}}
35
+ {"type":"error","code":"check_failed","message":"This build has blockers. Fix them, then run opengame check again.","exitCode":1,"retry":"after-fix"}
36
+ ```
37
+
38
+ Reading it:
39
+
40
+ 1. The first finding is `failed`, `certain` and `fault: "game"`, so it is the game's to
41
+ fix. `evidence.file` says `index.html:1`. Change `./Game.js` to `./game.js` there
42
+ (or rename the file), then run what `verify` says.
43
+ 2. The second finding is `inconclusive`, `heuristic` and `fault: "unknown"`, with
44
+ `retry: "never"`. It does not block anything. Do not add a fake Three.js import to make
45
+ it go away; a person confirms the engine.
46
+ 3. After the fix, `opengame check . --json` ends in a `result` and exits 0.
47
+
48
+ ## Findings that are ours
49
+
50
+ A finding with `fault: "platform"`, or an error with exit code 5, means a scanner, the
51
+ test machine, a moderation provider or storage failed. The CLI says so in plain words.
52
+ Leave the game alone, wait `retryAfterSeconds` when the finding or error has it (a few
53
+ minutes when it does not), and run the same command again. Rewriting a working game to satisfy a broken check is the failure this rule
54
+ exists to prevent.
55
+
56
+ ## Results worth keeping
57
+
58
+ - `deploy`: `operationId`, `state` (`uploading`, `queued`, `checking`, `ready`,
59
+ `failed`, `expired`), `gameId`, `releaseId`, `url`, and `timingsMs` when it finished.
60
+ Keep `releaseId`: submitting names it.
61
+ - `check`: `files`, `bytes`, `excluded` and `findings`.
62
+ - `whoami`: the signed-in handle and the token's scopes.
@@ -0,0 +1,83 @@
1
+ # opengame.json
2
+
3
+ The game's manifest, committed with its code. `opengame init` writes it; the website
4
+ edits the same fields. The game's id is never in this file: it lives in
5
+ `.opengame/project.json`, which is git-ignored, so a fork never deploys over somebody
6
+ else's game. Jam answers (track, certification) are never stored here either, because
7
+ they belong to one entry, not to the game.
8
+
9
+ ```json
10
+ {
11
+ "$schema": "https://opengame.io/schema/opengame.json",
12
+ "title": "Night shift",
13
+ "description": "Survive until dawn with a torch and a dwindling battery.",
14
+ "genre": "shooter-survival",
15
+ "kind": "game",
16
+ "build": { "command": "npm run build", "output": "dist" },
17
+ "controls": ["keyboard", "mouse"],
18
+ "leaderboards": [{ "key": "rounds", "order": "desc", "label": "Rounds survived", "min": 0, "max": 75 }]
19
+ }
20
+ ```
21
+
22
+ | Field | Rule |
23
+ | --- | --- |
24
+ | `title` | 3 to 40 characters |
25
+ | `tagline` | Optional, up to 140 characters |
26
+ | `description` | 40 to 500 characters. Say what the player does |
27
+ | `genre` | Exactly one slug from the table below |
28
+ | `kind` | Optional. One of the four kinds below; leaving it out means `game`. `opengame init` always writes it |
29
+ | `basedOn` | The name of the game a `decomp` or a `mod` is made from, up to 60 characters, shown as "Mod of Doom". Required for a `decomp` or a `mod`, and not allowed for a `game` or a `world` |
30
+ | `build.command` | Optional, up to 1,000 characters. Run before checking; may read environment variables but must not contain a secret |
31
+ | `build.output` | The folder holding `index.html` after the build, or `.` |
32
+ | `cover` | Not used. OpenGame makes the cover after approval. A file that still names one passes `check`, and the CLI does not upload it; leave the field out |
33
+ | `controls` | One or more of `keyboard`, `mouse`, `gamepad`, each once |
34
+ | `requires` | Optional. `threads: true` for a build that cannot start without them, `renderer` (`webgl`, `webgl2` or `webgpu`), `desktopOnly`, `gamepad`. The game page lists them, and a browser that cannot run threads is told so instead of getting a black frame |
35
+ | `leaderboards` | Up to 10 boards: `key` (lowercase, starts with a letter, up to 48 characters), `order` (`asc` or `desc`), `label` (up to 60 characters), optional `min` and `max` |
36
+ | `achievements` | Up to 100: `id` (lowercase letters, digits, `-` and `_`, up to 48 characters), `title`, optional `description`. A deploy saves them when its preview is ready |
37
+ | `sdk` | Optional. A version string, or `{ "inject": false, "version": "..." }`. `inject: false` is honoured only on the older contract whose serving tree the pipeline rewrites; the contracts that add `/_og/sdk.js` at the edge always add it |
38
+ | `runtimes` | Optional. Settings for a runtime the platform serves pinned (js-dos, Ruffle, Pyodide, wasmoon, Flutter's CanvasKit); the engine's guide says which |
39
+
40
+ Write the title and description from the game itself. Read the code, play it if you
41
+ can, and describe what is there. A description that promises modes the game does not
42
+ have is a review finding.
43
+
44
+ ## Genres
45
+
46
+ | Slug | Genre |
47
+ | --- | --- |
48
+ | `shooter-survival` | Shooter & survival |
49
+ | `action-adventure` | Action & adventure |
50
+ | `rpg` | RPG |
51
+ | `platformer` | Platformer |
52
+ | `strategy` | Strategy |
53
+ | `simulation-management` | Simulation & management |
54
+ | `racing-sports` | Racing & sports |
55
+ | `fighting` | Fighting |
56
+ | `puzzle-casual` | Puzzle & casual |
57
+ | `party-social-sandbox` | Party, social & sandbox |
58
+
59
+ ## Kinds
60
+
61
+ Ask the person which one it is rather than guessing from the code. A mod or a decomp is
62
+ made from someone else's game, which is a fact about where it came from, not about how
63
+ it plays.
64
+
65
+ | Kind | What it is | `basedOn` | Can enter the jam |
66
+ | --- | --- | --- | --- |
67
+ | `game` | Something to play, with goals, rules or a way to win | Not allowed | Yes |
68
+ | `world` | A place to explore or hang out in, with nothing you have to win | Not allowed | Yes |
69
+ | `decomp` | An existing game rebuilt from its decompiled code | Required | No |
70
+ | `mod` | Changes to an existing game, like new levels, rules or art | Required | No |
71
+
72
+ `opengame init --kind mod --based-on "Doom"` writes both. Without `--kind`, init asks a
73
+ person in a terminal and makes a game for an agent.
74
+
75
+ ## Who owns which value
76
+
77
+ Metadata on the server has revisions. A deploy sends the manifest with the revision it
78
+ was last synced from. If the website is newer, the deploy keeps the website's values
79
+ and says which fields it kept. `kind` and `basedOn` are among those fields: a reviewer
80
+ can correct a kind on the website, and a pull brings the correction down. `opengame pull` writes the website's values into this
81
+ file, backing up the previous one in `.opengame/manifest-before-pull.json`.
82
+ `opengame deploy --metadata=local` replaces the website's values on purpose; use it
83
+ only when the person asked for that.
@@ -0,0 +1,117 @@
1
+ # The packaging contract
2
+
3
+ Every number here is read from the platform's own limits when this skill is built, so
4
+ it matches what the CLI and the server enforce. The canonical contract for agents is
5
+ also published at opengame.io/agent.md.
6
+
7
+ ## The archive
8
+
9
+ | Rule | Limit | What happens |
10
+ | --- | --- | --- |
11
+ | Entry point | `index.html` at the root of the build output | Refused |
12
+ | Compressed size | 1024 MiB | Refused |
13
+ | Uncompressed size | 1536 MiB | Refused |
14
+ | File count | 10,000 | Refused |
15
+ | Compression ratio | 200 : 1 | Refused, as a zip bomb guard |
16
+ | Paths | Case matches the file on disk; no `../`, no symlinks, no absolute paths | Refused |
17
+ | Excluded | `node_modules/`, `.git/`, `.env*`, source maps, OS junk | Stripped, with a `files_excluded` notice |
18
+ | `opengame.json`, `.opengame/`, `opengame-assets/` | Project files, not game files | Stripped silently |
19
+
20
+ `opengame.json` stays out of the bundle on purpose: the manifest describes the game to
21
+ the platform and is not one of the game's files.
22
+
23
+ ## Games past the archive limits
24
+
25
+ A decompilation, mod or recompilation with gigabytes of game data can send its large
26
+ files outside the archive on the `large-game-v1` plan: at most
27
+ 12 GiB in 32,768
28
+ files, and 1 GiB for one file. The archive keeps the
29
+ limits above. The account needs large-asset access, which the OpenGame team enables; without
30
+ it the deploy exits 3 with `large_asset_lane_not_granted`, so ask the person to request it.
31
+
32
+ Write `{"delivery": "large-game-v1", "assets": "auto"}` to a file and pass it as
33
+ `--external-assets <file>` to both `opengame check` and `opengame deploy`. With `"auto"` the
34
+ CLI sends every file of 1 MiB
35
+ or more separately, then the largest of the rest until the archive fits. HTML, JavaScript,
36
+ CSS, XML, SVG, wasm, web manifests, SWF and PDF stay in the archive, and so does
37
+ `opengame.json`. A Kaigen build uses `kaigen-assets-v1` instead.
38
+
39
+ ## Credentials
40
+
41
+ A credential inside any file is refused, comments included, because a game is served
42
+ from a public CDN. The patterns searched for: an OpenGame creator token; an AWS access key id; an AWS secret access key; a GitHub token; a GitHub fine-grained token; an Anthropic API key; an OpenAI API key; a Stripe secret key; a Slack token; a Google API key; a private key block; a Supabase service-role key name; a Twilio auth token; a SendGrid API key.
43
+ Something shaped like a private key header without its key beside it; an assignment that looks like a secret is a warning, not a
44
+ refusal. If a match is a real key, rotate it; removing it from the next build does not
45
+ take it back.
46
+
47
+ Identity, leaderboards and achievements come from the page through the SDK (see
48
+ `opengame-sdk`), so those need no key. To call an API that does need one, such as an AI
49
+ model, put the key on the creator's own server and have the game call that server.
50
+
51
+ ## Where a game may connect
52
+
53
+ Besides the game's own origin, `https://api.opengame.gg`,
54
+ `wss://rtc.opengame.gg` and `https://rtc.opengame.gg`, a new release
55
+ may reach any `https:` or `wss:` host: an AI model, a third-party API, the creator's own
56
+ server, and scripts, stylesheets, fonts and media from a CDN. Releases made
57
+ before 26 Oct 2026 keep a contract that allows OpenGame's hosts only.
58
+
59
+ Before the game calls out:
60
+
61
+ - Each call goes from the player's browser, so that host gets the player's IP address.
62
+ - The review sandbox does not reach the internet. The game must still draw its first
63
+ frame when its server is out of reach.
64
+ - The game page is `https:`, so the browser blocks `http://` and `ws://` requests.
65
+ - A build that uses threads is cross-origin isolated. There a script or image from
66
+ another host loads only if that host sends CORS or `Cross-Origin-Resource-Policy`
67
+ headers.
68
+ - A library from a CDN can be slow, go down or change after review. Bundle it when you
69
+ can.
70
+
71
+ ## What a game may not do
72
+
73
+ Refused whatever host the game uses. `opengame check`, the upload scan and the review
74
+ sandbox look for the common services and code shapes, and automatic review plays every game.
75
+
76
+ - **Payments.** Games on OpenGame are free to play. A game may not take money, tips, donations or card details, or send players to a page that does.
77
+ - **Crypto.** Games on OpenGame may not use crypto wallets, tokens, NFTs or blockchains, and may not mine.
78
+ - **Accounts.** Players start playing without making an account, signing in, or giving an email address. OpenGame gives every game a player through the SDK, so a game never needs its own sign-in. An anonymous sign-in to the
79
+ game's own backend, such as Firebase anonymous auth, is fine, because the player is
80
+ never asked for anything.
81
+ - **Ads.** Games on OpenGame may not show ads. A portal SDK such as Poki's or CrazyGames' serves ads, so remove it.
82
+ - **Tracking.** Games on OpenGame may not carry ad pixels or session recording. Use the SDK's events for analytics.
83
+
84
+ A game also may not put another site in an iframe, post a form, or open a popup. Links
85
+ out go through `og.openLink`. OpenGame does not open links to the payment, crypto and sign-in services on its list, judged by the address the game passes, not by where it redirects. Do not hide a service from the checks by renaming or encoding it; the reviewer
86
+ plays the game against the rule, not against the list.
87
+
88
+ ## What the checks measure
89
+
90
+ | Check | What it asks | Who decides | Blocks |
91
+ | --- | --- | --- | --- |
92
+ | `malware` | Malware scan | automatic | yes |
93
+ | `archive` | Archive is safe to open | automatic | yes |
94
+ | `entry` | index.html at root | automatic | yes |
95
+ | `boot` | Boots and renders | automatic | yes |
96
+ | `net` | No disallowed origins | automatic | yes |
97
+ | `size` | Initial download | automatic | no, a warning |
98
+ | `tti` | Time to playable | automatic | no, a warning |
99
+ | `mem` | Peak memory | automatic | no, a warning |
100
+ | `fps` | Frame rate | automatic | no, a warning |
101
+ | `desktop` | Works at every size | automatic | no, a warning |
102
+ | `content` | Content and conduct | a person | yes |
103
+ | `engine` | Declared engine | a person | yes |
104
+ | `ip` | Originality and IP | a person | yes |
105
+ | `fresh` | Built after kickoff | a person | yes |
106
+
107
+ Thresholds that warn rather than refuse: an initial download over
108
+ 50 MiB before the first playable frame, time to
109
+ playable over 10 seconds, a median frame rate under
110
+ 45 on the test machine. A first frame later than
111
+ 30 seconds fails the boot check. The desktop check loads the
112
+ game at 1920 x 1080 (primary), 1366 x 768, 2560 x 1440, 3440 x 1440, 1024 x 640 and expects it to respond to resize.
113
+
114
+ ## Manifest limits
115
+
116
+ `opengame.json` itself is at most 64 KiB, with at most
117
+ 10 leaderboards. See [manifest.md](manifest.md).