@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
package/AGENTS.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# OpenGame CLI: guidance for agents
|
|
2
|
+
|
|
3
|
+
How a coding agent deploys a creator's game with the `opengame` command. The command and exit code tables at the end are the CLI's own help; `opengame help --json` has every flag.
|
|
4
|
+
|
|
5
|
+
<!-- generated:procedure -->
|
|
6
|
+
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.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm i -g @opengamehq/cli
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Once `opengame` is installed, confirm it and read the command reference:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
opengame version --json
|
|
18
|
+
opengame help --json
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
`help --json` lists every command, flag, exit code, environment variable and event, with the finding schema. Read it rather than guessing a flag.
|
|
22
|
+
|
|
23
|
+
Install the OpenGame skills for the agent you run in, from the game folder:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
opengame skills add .
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
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`.
|
|
30
|
+
|
|
31
|
+
## Output
|
|
32
|
+
|
|
33
|
+
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:
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"type": "result",
|
|
38
|
+
"command": "deploy",
|
|
39
|
+
"data": { "state": "queued", "done": false },
|
|
40
|
+
"ok": true,
|
|
41
|
+
"url": "https://opengame.io/settings/deployments/<id>",
|
|
42
|
+
"next": "opengame status --watch",
|
|
43
|
+
"findings": [],
|
|
44
|
+
"notices": []
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
| Exit | Meaning | What to do |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| 0 | Done | Read `data`. `data.done: false` means the server is still working. |
|
|
53
|
+
| 1 | The game needs a change | Fix each finding, then run its `verify` command. |
|
|
54
|
+
| 2 | The command needs input | Read the message. It names the missing flag or choice. |
|
|
55
|
+
| 3 | Sign in, or a token with the right scope | Run `next` when the error has one. |
|
|
56
|
+
| 4 | An allowance is used up | Wait `retryAfterSeconds`, then run the same command. |
|
|
57
|
+
| 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. |
|
|
58
|
+
| 6 | The CLI is too old | Run `opengame upgrade --json`, then the npm command in `data.command`. |
|
|
59
|
+
| 7 | OpenGame is not launched | Stop. Tell the creator their account cannot use OpenGame until launch. |
|
|
60
|
+
|
|
61
|
+
## Sign in with the creator
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
opengame whoami --json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Exit 0 means a saved login works. Exit 3 means start one:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
opengame login --json
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`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:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
opengame login --continue --json
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`--continue` waits up to 10 seconds for the approval.
|
|
80
|
+
|
|
81
|
+
| Result | What to do |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| Exit 0 | Signed in. `data.handle` is the creator's handle. |
|
|
84
|
+
| Exit 3, `login_pending` | Not approved yet. Run `login --continue --json` again once the creator has pressed Allow access. |
|
|
85
|
+
| Exit 3, `access_denied` | The creator pressed Deny, or the account cannot be used. Read the message to them. |
|
|
86
|
+
| `login_expired` or `no_pending_login` | The code ran out. Run `login --json` for a new one. |
|
|
87
|
+
|
|
88
|
+
## Deploy a private preview
|
|
89
|
+
|
|
90
|
+
Run these from the game folder.
|
|
91
|
+
|
|
92
|
+
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:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
opengame init . --title "My game" --json
|
|
96
|
+
opengame init . --title "Doom but blue" --kind mod --based-on "Doom" --json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
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.
|
|
100
|
+
|
|
101
|
+
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:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
opengame games --json
|
|
105
|
+
opengame link --game <id> --json
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Check, then deploy:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
opengame check . --build --json
|
|
112
|
+
opengame deploy . --json
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`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.
|
|
116
|
+
|
|
117
|
+
| Field | What it holds |
|
|
118
|
+
| --- | --- |
|
|
119
|
+
| `data.deploymentUrl` | The deploy's page. Give it to the creator straight away: it shows each check and plays the preview once they pass. |
|
|
120
|
+
| `data.state` | `uploading`, `queued`, `checking`, `ready`, `failed` or `expired`. |
|
|
121
|
+
| `data.done` | `true` once the server has finished. |
|
|
122
|
+
| `data.releaseId` | The release. Keep it for `submit`. |
|
|
123
|
+
| `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. |
|
|
124
|
+
|
|
125
|
+
To follow the checks, run `status --watch`, which follows the deploy for up to 5 minutes. Set `--timeout <seconds>` for a short tool call; when it runs out the command exits 5 with `checks_pending` and the checks carry on.
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
opengame status --watch --timeout 60 --json
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
To block on the outcome in one command, deploy with `--wait`:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
opengame deploy . --wait --json
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
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.
|
|
138
|
+
|
|
139
|
+
## Fix findings
|
|
140
|
+
|
|
141
|
+
Each finding has a `fault`, a `certainty` and a `retry`:
|
|
142
|
+
|
|
143
|
+
| Finding | What to do |
|
|
144
|
+
| --- | --- |
|
|
145
|
+
| `fault: game` | Read `evidence`, make the change in `fix`, then run the command in `verify`. |
|
|
146
|
+
| `certainty: heuristic` | Check the evidence before you change working code. |
|
|
147
|
+
| `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`. |
|
|
148
|
+
| `fault: unknown` | A person decides at review. Report it to the creator. |
|
|
149
|
+
|
|
150
|
+
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:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
opengame deploy . \
|
|
154
|
+
--idempotency-key <a new key> --json
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
## Submit only on request
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
opengame jams --json
|
|
165
|
+
opengame submit --release <releaseId> --no-wait --json
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
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.
|
|
169
|
+
|
|
170
|
+
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:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
opengame status --watch --json
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## What a game may do
|
|
177
|
+
|
|
178
|
+
OpenGame hosts static browser exports. The build needs `index.html` at the root of its output folder.
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
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.
|
|
183
|
+
|
|
184
|
+
## Engines
|
|
185
|
+
|
|
186
|
+
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.
|
|
187
|
+
|
|
188
|
+
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.
|
|
189
|
+
|
|
190
|
+
Play the private preview before you tell the creator the game works.
|
|
191
|
+
<!-- /generated:procedure -->
|
|
192
|
+
|
|
193
|
+
## Where it runs
|
|
194
|
+
|
|
195
|
+
`dev`, `vendor`, `check --vendor`, `deploy --vendor` and Unity asset uploads need Python 3 on macOS or Linux: they read files with a small Python helper that opens each one relative to a held directory, so a symlink swapped into the path mid-read cannot send it outside the project. The CLI looks for Python 3 at `/usr/bin/python3`, `/opt/homebrew/bin/python3`, `/usr/local/bin/python3` and `/bin/python3`, never through `PATH`; without one those commands stop with `filesystem_unsupported` before reading anything, and the fix is to install Python 3 from python.org or Homebrew. Plain `check` and `deploy` use the same helper when Python is found and otherwise read with a Node fallback, after a `node_reader_fallback` notice; they work either way.
|
|
196
|
+
|
|
197
|
+
## Commands and exit codes
|
|
198
|
+
|
|
199
|
+
<!-- generated:commands -->
|
|
200
|
+
| Command | What it does |
|
|
201
|
+
| --- | --- |
|
|
202
|
+
| `opengame init [dir] [options]` | Create opengame.json for an existing game. |
|
|
203
|
+
| `opengame check [dir] [options]` | Find local build and asset problems before uploading. |
|
|
204
|
+
| `opengame dev [dir] [options]` | Serve a local export with game-runtime headers. Under a contract that adds the SDK, pages also get the host runtime and SDK, as they do when hosted. If the contract supports opting out, sdk.inject: false leaves out the SDK. |
|
|
205
|
+
| `opengame login [options]` | Sign in through your browser. |
|
|
206
|
+
| `opengame deploy [dir] [options]` | Build, check and upload a release, then return with the address of its deployment page, where the checks run and the private preview plays once they pass. Add --wait to stay until they finish. Once the preview is ready, the achievements opengame.json declares are saved by deploy --wait or by the next opengame status in this folder. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
|
|
207
|
+
| `opengame status [dir] [options]` | Show the most recent deploy for this folder, with its findings. Finishes saving its declared achievements if the deploy could not. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
|
|
208
|
+
| `opengame deployments [dir] [options]` | List the linked game's deploys, newest first: status, when, size, who started each one, why any stopped, and each one's page or preview. |
|
|
209
|
+
| `opengame open [dir] [options]` | Open the linked game's private page in your browser. |
|
|
210
|
+
| `opengame submit [dir] [options]` | Send one release to review, and enter it in a jam. |
|
|
211
|
+
| `opengame jams [slug] [options]` | List open jams, or show one jam's tracks and flags. |
|
|
212
|
+
| `opengame games [options]` | List your games and their latest deploy. |
|
|
213
|
+
| `opengame link [dir] [options]` | Connect this folder to an existing game. |
|
|
214
|
+
| `opengame pull [dir] [options]` | Bring website metadata into this folder. |
|
|
215
|
+
| `opengame stats [game\|dir] [options]` | Read analytics for a game you own, or this folder's linked game, for one complete ISO week, Monday to Sunday in UTC. Average playtime is total playtime divided by distinct players in the week. |
|
|
216
|
+
| `opengame whoami [options]` | Show the account and permissions for this token. |
|
|
217
|
+
| `opengame token create\|list\|revoke [options]` | Create, list or revoke tokens in your browser. |
|
|
218
|
+
| `opengame logout [options]` | Revoke this device's token and remove it locally. |
|
|
219
|
+
| `opengame limits [options]` | Show bundle limits and your remaining account allowance. |
|
|
220
|
+
| `opengame vendor [dir] [options]` | Create a separate export with dependencies downloaded at their exact versions, rewritten and hashed. |
|
|
221
|
+
| `opengame skills add\|list [dir] [options]` | Install the OpenGame skills for your coding agent. |
|
|
222
|
+
| `opengame upgrade [options]` | Install the current CLI, or print the line that does. |
|
|
223
|
+
| `opengame version [options]` | Print the CLI version. |
|
|
224
|
+
|
|
225
|
+
| Exit | Name | Meaning |
|
|
226
|
+
| --- | --- | --- |
|
|
227
|
+
| 0 | `ok` | Done. With done:false in the result, the deploy is still running on our side: open data.url to watch it, or follow it with opengame status --watch. |
|
|
228
|
+
| 1 | `check` | The game needs a change. Read the finding events, or the error's finding and message when there are none, fix it, then run the finding's verify command. |
|
|
229
|
+
| 2 | `input` | The command needs input: a flag, a choice or a different command. The message names it. With retry never, running the same command again cannot help. |
|
|
230
|
+
| 3 | `auth` | Sign in, or use a token with the right scope. Run the error's next command when it has one. With retry never, signing in again will not help: the account itself has no access. |
|
|
231
|
+
| 4 | `rateLimited` | An allowance is used. Wait retryAfterSeconds when the error has it, then run the same command. |
|
|
232
|
+
| 5 | `server` | Our side or the network, and the game is fine. Run the error's next command when it has one. With retry after-fix or never, waiting will not help; read the message. Otherwise wait (retryAfterSeconds when given) and run the same command. |
|
|
233
|
+
| 6 | `upgrade` | This CLI is too old. Run opengame upgrade. |
|
|
234
|
+
| 7 | `notLaunched` | OpenGame is not launched yet, so nothing ran. Nothing about the game, the command or the login is wrong. Retrying will not help before launch. |
|
|
235
|
+
<!-- /generated:commands -->
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
- First release on npm. This version is published by hand and has no npm provenance
|
|
6
|
+
statement; versions published from this repository's workflow will.
|
|
7
|
+
- Add the launch check and the `not_launched` exit code (7): when OpenGame has not opened
|
|
8
|
+
for the account, a command that needs it says so and stops.
|
|
9
|
+
- `AGENTS.md` is in the package: the procedure a coding agent follows to deploy a game.
|
package/README.md
CHANGED
|
@@ -1,3 +1,129 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @opengamehq/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Deploy browser games to [OpenGame](https://opengame.io) from your terminal. The `opengame`
|
|
4
|
+
command checks a game folder, uploads it and gives you a private preview to play.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
<!-- install:cli -->
|
|
9
|
+
```bash
|
|
10
|
+
npm i -g @opengamehq/cli
|
|
11
|
+
```
|
|
12
|
+
<!-- /install -->
|
|
13
|
+
|
|
14
|
+
It needs Node.js 18.17 or later. `opengame --version` prints the version you have.
|
|
15
|
+
|
|
16
|
+
## Sign in
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
opengame login
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Your browser opens on opengame.io. Sign in with Google or an emailed code and press
|
|
23
|
+
Allow access. The CLI keeps the token in the macOS Keychain, and elsewhere in a private
|
|
24
|
+
file under `~/.config/opengame`. In CI, pass a token through `OPENGAME_TOKEN` or
|
|
25
|
+
`--token-stdin`, never as a command argument.
|
|
26
|
+
|
|
27
|
+
When OpenGame has not opened for your account, a command that needs the platform prints
|
|
28
|
+
`OpenGame is not launched.` and exits with code 7. Signing in works either way.
|
|
29
|
+
|
|
30
|
+
## Deploy a game
|
|
31
|
+
|
|
32
|
+
Run these from the folder that holds your game's `index.html`, or its source when the
|
|
33
|
+
build writes one.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
opengame init .
|
|
37
|
+
opengame check .
|
|
38
|
+
opengame deploy .
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`init` writes `opengame.json`, the manifest with your game's title, description and
|
|
42
|
+
build. `check` runs the same checks the upload will, on your machine. `deploy` builds,
|
|
43
|
+
checks and uploads a release, then prints its deployment page:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
Uploaded. The checks run on our side, so you can close this terminal.
|
|
47
|
+
Your upload is queued for checks.
|
|
48
|
+
Watch them, and play the preview once it is ready, at https://opengame.io/settings/deployments/<id>
|
|
49
|
+
Or follow them here with opengame status --watch.
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The private preview plays on that page once the checks pass. Add `--wait` to stay in the
|
|
53
|
+
terminal until they finish. When the preview is ready, `opengame submit` sends the
|
|
54
|
+
release to review.
|
|
55
|
+
|
|
56
|
+
## Scripts and agents
|
|
57
|
+
|
|
58
|
+
Every command takes `--json` and prints one result object. For `deploy`:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"type": "result",
|
|
63
|
+
"command": "deploy",
|
|
64
|
+
"ok": true,
|
|
65
|
+
"data": { "operationId": "<id>", "done": false, "deploymentUrl": "https://opengame.io/settings/deployments/<id>" },
|
|
66
|
+
"url": "https://opengame.io/settings/deployments/<id>",
|
|
67
|
+
"next": "opengame status --watch",
|
|
68
|
+
"findings": [],
|
|
69
|
+
"notices": []
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
A failure prints `"type": "error"` with `ok: false`, a `code` such as `not_launched`, a
|
|
74
|
+
`message` and the process exits with a non-zero code. `opengame help --json`
|
|
75
|
+
lists every command, flag, error code and exit code. `--jsonl` streams progress events.
|
|
76
|
+
|
|
77
|
+
`opengame skills add .` installs the OpenGame skills for Claude Code, Codex, Cursor or
|
|
78
|
+
OpenCode, so a coding agent can do all of the above for you.
|
|
79
|
+
|
|
80
|
+
## Commands
|
|
81
|
+
|
|
82
|
+
<!-- generated:commands -->
|
|
83
|
+
| Command | What it does |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `opengame init [dir] [options]` | Create opengame.json for an existing game. |
|
|
86
|
+
| `opengame check [dir] [options]` | Find local build and asset problems before uploading. |
|
|
87
|
+
| `opengame dev [dir] [options]` | Serve a local export with game-runtime headers. Under a contract that adds the SDK, pages also get the host runtime and SDK, as they do when hosted. If the contract supports opting out, sdk.inject: false leaves out the SDK. |
|
|
88
|
+
| `opengame login [options]` | Sign in through your browser. |
|
|
89
|
+
| `opengame deploy [dir] [options]` | Build, check and upload a release, then return with the address of its deployment page, where the checks run and the private preview plays once they pass. Add --wait to stay until they finish. Once the preview is ready, the achievements opengame.json declares are saved by deploy --wait or by the next opengame status in this folder. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
|
|
90
|
+
| `opengame status [dir] [options]` | Show the most recent deploy for this folder, with its findings. Finishes saving its declared achievements if the deploy could not. Removing an achievement from opengame.json does not switch it off. To retire one, send PUT /api/v1/games/{id}/achievements with achievementId, title, description and active: false. Unlocks are never deleted. |
|
|
91
|
+
| `opengame deployments [dir] [options]` | List the linked game's deploys, newest first: status, when, size, who started each one, why any stopped, and each one's page or preview. |
|
|
92
|
+
| `opengame open [dir] [options]` | Open the linked game's private page in your browser. |
|
|
93
|
+
| `opengame submit [dir] [options]` | Send one release to review, and enter it in a jam. |
|
|
94
|
+
| `opengame jams [slug] [options]` | List open jams, or show one jam's tracks and flags. |
|
|
95
|
+
| `opengame games [options]` | List your games and their latest deploy. |
|
|
96
|
+
| `opengame link [dir] [options]` | Connect this folder to an existing game. |
|
|
97
|
+
| `opengame pull [dir] [options]` | Bring website metadata into this folder. |
|
|
98
|
+
| `opengame stats [game\|dir] [options]` | Read analytics for a game you own, or this folder's linked game, for one complete ISO week, Monday to Sunday in UTC. Average playtime is total playtime divided by distinct players in the week. |
|
|
99
|
+
| `opengame whoami [options]` | Show the account and permissions for this token. |
|
|
100
|
+
| `opengame token create\|list\|revoke [options]` | Create, list or revoke tokens in your browser. |
|
|
101
|
+
| `opengame logout [options]` | Revoke this device's token and remove it locally. |
|
|
102
|
+
| `opengame limits [options]` | Show bundle limits and your remaining account allowance. |
|
|
103
|
+
| `opengame vendor [dir] [options]` | Create a separate export with dependencies downloaded at their exact versions, rewritten and hashed. |
|
|
104
|
+
| `opengame skills add\|list [dir] [options]` | Install the OpenGame skills for your coding agent. |
|
|
105
|
+
| `opengame upgrade [options]` | Install the current CLI, or print the line that does. |
|
|
106
|
+
| `opengame version [options]` | Print the CLI version. |
|
|
107
|
+
|
|
108
|
+
| Exit | Name | Meaning |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| 0 | `ok` | Done. With done:false in the result, the deploy is still running on our side: open data.url to watch it, or follow it with opengame status --watch. |
|
|
111
|
+
| 1 | `check` | The game needs a change. Read the finding events, or the error's finding and message when there are none, fix it, then run the finding's verify command. |
|
|
112
|
+
| 2 | `input` | The command needs input: a flag, a choice or a different command. The message names it. With retry never, running the same command again cannot help. |
|
|
113
|
+
| 3 | `auth` | Sign in, or use a token with the right scope. Run the error's next command when it has one. With retry never, signing in again will not help: the account itself has no access. |
|
|
114
|
+
| 4 | `rateLimited` | An allowance is used. Wait retryAfterSeconds when the error has it, then run the same command. |
|
|
115
|
+
| 5 | `server` | Our side or the network, and the game is fine. Run the error's next command when it has one. With retry after-fix or never, waiting will not help; read the message. Otherwise wait (retryAfterSeconds when given) and run the same command. |
|
|
116
|
+
| 6 | `upgrade` | This CLI is too old. Run opengame upgrade. |
|
|
117
|
+
| 7 | `notLaunched` | OpenGame is not launched yet, so nothing ran. Nothing about the game, the command or the login is wrong. Retrying will not help before launch. |
|
|
118
|
+
<!-- /generated:commands -->
|
|
119
|
+
|
|
120
|
+
`opengame <command> --help` prints that command's flags and examples.
|
|
121
|
+
|
|
122
|
+
## Documentation
|
|
123
|
+
|
|
124
|
+
The full guide, the API reference and the limits are at
|
|
125
|
+
[docs.opengame.io](https://docs.opengame.io).
|
|
126
|
+
|
|
127
|
+
## License
|
|
128
|
+
|
|
129
|
+
Apache-2.0
|