@opengamehq/cli 0.0.0-stage → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +238 -0
- package/CHANGELOG.md +22 -0
- package/README.md +129 -2
- package/dist/cli.mjs +1432 -0
- package/dist/opengame-global.js +49 -0
- package/dist/opengame-global.js.LEGAL.txt +1 -0
- package/dist/preflight-worker.mjs +20 -0
- package/dist/runtime-builder.mjs +800 -0
- package/dist/runtime-catalog.json +1 -0
- package/dist/runtime-catalog.sha256 +1 -0
- package/dist/runtime-shells/runtime-shell.html +4 -0
- package/dist/runtime-shells/runtime-shell.js +91 -0
- package/dist/safe-fs.py +242 -0
- package/dist/skills/manifest.json +516 -0
- package/dist/skills/opengame-accessibility/SKILL.md +90 -0
- package/dist/skills/opengame-api/SKILL.md +85 -0
- package/dist/skills/opengame-assets/SKILL.md +124 -0
- package/dist/skills/opengame-assets/references/pipeline.md +97 -0
- package/dist/skills/opengame-audio/SKILL.md +154 -0
- package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
- package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
- package/dist/skills/opengame-capture/SKILL.md +108 -0
- package/dist/skills/opengame-capture/references/pipeline.md +82 -0
- package/dist/skills/opengame-capture/references/threejs.md +145 -0
- package/dist/skills/opengame-characters/SKILL.md +129 -0
- package/dist/skills/opengame-characters/references/integration.md +144 -0
- package/dist/skills/opengame-characters/references/player-og.md +160 -0
- package/dist/skills/opengame-cli/SKILL.md +118 -0
- package/dist/skills/opengame-deploy/SKILL.md +207 -0
- package/dist/skills/opengame-deploy/references/json-events.md +62 -0
- package/dist/skills/opengame-deploy/references/manifest.md +83 -0
- package/dist/skills/opengame-deploy/references/packaging.md +117 -0
- package/dist/skills/opengame-depth/SKILL.md +130 -0
- package/dist/skills/opengame-enemies/SKILL.md +103 -0
- package/dist/skills/opengame-enemies/references/threejs.md +134 -0
- package/dist/skills/opengame-front-end/SKILL.md +143 -0
- package/dist/skills/opengame-front-end/references/launch.md +50 -0
- package/dist/skills/opengame-front-end/references/menus.md +47 -0
- package/dist/skills/opengame-game-feel/SKILL.md +137 -0
- package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
- package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
- package/dist/skills/opengame-jam/SKILL.md +103 -0
- package/dist/skills/opengame-lighting/SKILL.md +94 -0
- package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
- package/dist/skills/opengame-loading/SKILL.md +99 -0
- package/dist/skills/opengame-loading/references/threejs.md +116 -0
- package/dist/skills/opengame-look/SKILL.md +114 -0
- package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
- package/dist/skills/opengame-mobile/SKILL.md +90 -0
- package/dist/skills/opengame-performance/SKILL.md +140 -0
- package/dist/skills/opengame-performance/references/measuring.md +72 -0
- package/dist/skills/opengame-production/SKILL.md +131 -0
- package/dist/skills/opengame-production/references/templates.md +63 -0
- package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
- package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
- package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
- package/dist/skills/opengame-router/SKILL.md +51 -0
- package/dist/skills/opengame-router/references/process.md +38 -0
- package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
- package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
- package/dist/skills/opengame-sdk/SKILL.md +270 -0
- package/dist/skills/opengame-sdk/references/engines.md +93 -0
- package/dist/skills/opengame-sdk/references/frame.md +107 -0
- package/dist/skills/opengame-sdk/references/identity.md +112 -0
- package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
- package/dist/skills/opengame-sdk/references/radio.md +71 -0
- package/dist/skills/opengame-stability/SKILL.md +84 -0
- package/dist/skills/opengame-verification/SKILL.md +136 -0
- package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
- package/dist/skills/opengame-weapons/SKILL.md +109 -0
- package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
- package/dist/skills/opengame-weapons/references/threejs.md +169 -0
- package/dist/skills/opengame-world-physics/SKILL.md +114 -0
- package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
- package/package.json +38 -4
|
@@ -0,0 +1,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).
|