@opengamehq/cli 0.10.0 → 0.11.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.
@@ -2,7 +2,7 @@
2
2
  name: opengame-deploy
3
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 hands the creator the page where they confirm the details after 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
4
  metadata:
5
- version: "1.1.7"
5
+ version: "1.1.9"
6
6
  ---
7
7
 
8
8
  # Deploy a browser game to OpenGame
@@ -20,6 +20,7 @@ Deploy the creator's game to a private preview and give them its link. Review st
20
20
 
21
21
  ```bash
22
22
  npm i -g @opengamehq/cli
23
+ opengame setup
23
24
  ```
24
25
 
25
26
  Once `opengame` is installed, confirm it and read the command reference:
@@ -31,7 +32,9 @@ opengame help --json
31
32
 
32
33
  `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
 
34
- Install the OpenGame skills for the agent you run in, from the game folder:
35
+ `opengame setup` installs every OpenGame skill in the home folder of each coding agent it finds (Claude Code, Codex, Cursor and OpenCode), and later commands keep them current. If your session started before that, read `opengame-router/SKILL.md` in the folder it names.
36
+
37
+ To commit the skills with the game instead:
35
38
 
36
39
  ```bash
37
40
  opengame skills add .
@@ -109,7 +112,7 @@ opengame init . --title "My game" --json
109
112
  opengame init . --title "Doom but blue" --kind mod --based-on "Doom" --json
110
113
  ```
111
114
 
112
- Do not ask the creator for a description or a genre before deploying. When you know them, pass `--description` (40 characters or more) and `--genre`; when you do not, leave them out. Every field defaults to Auto: review writes the description and the genre from the game, and the creator accepts or changes them on the deploy's page, where they also enter the jam. After the deploy you can set the description yourself with `opengame details --description "..." --json`. If the file already exists, leave `init` alone and edit the file.
115
+ Do not ask the creator for a description or a genre before deploying. When you know them, pass `--description` (40 characters or more) and `--genre`; when you do not, leave them out. Every field defaults to Auto: review writes the description and the genre from the game, and the creator accepts or changes them on the deploy's page, where they also enter the jam. A title or description you pass is offered back with its casing and grammar tidied, and `opengame publish --keep-words` keeps it as written. After the deploy you can set the description yourself with `opengame details --description "..." --json`. If the file already exists, `init` fills in only the fields it leaves blank; edit the file to change the rest.
113
116
 
114
117
  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:
115
118
 
@@ -132,7 +135,7 @@ opengame deploy . --json
132
135
  | `data.deploymentUrl` | The deploy's page. Give it to the creator straight away: it shows each check and plays the preview once they pass. |
133
136
  | `data.state` | `uploading`, `queued`, `checking`, `ready`, `failed` or `expired`. |
134
137
  | `data.done` | `true` once the server has finished. |
135
- | `data.releaseId` | The release. Keep it for `submit`. |
138
+ | `data.releaseId` | The release. Keep it: `opengame publish --release` takes it. |
136
139
  | `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. |
137
140
  | `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. |
138
141
 
@@ -176,16 +179,16 @@ Review starts automatically once a deploy is ready, so you submit no release. Re
176
179
 
177
180
  When review passes, a game's first release waits to be published. `opengame status --json` shows `data.review.state: "awaiting_details"`, `data.review.next: "opengame publish"` and the deploy's page in `data.review.url`.
178
181
 
179
- - **The creator asked you to publish it.** Run `opengame publish --json`. It confirms the title, description and genre review wrote, publishes, waits until the game is live and prints the address to share in `data.url`. Change what review wrote with `--description`, `--genre` and the other flags in `opengame publish --help`. While a new game goes on OpenGame only as a jam entry, pass the jam's track and the models used with `--track` and `--models`; `opengame jams <slug> --json` lists them.
182
+ - **The creator asked you to publish it.** Run `opengame publish --json`. It confirms the title, description and genre review wrote, publishes, waits until the game is live and prints the address to share in `data.url`. Change what review wrote with `--description`, `--genre` and the other flags in `opengame publish --help`. While a new game or an update goes on OpenGame only as a jam entry, pass the jam's track and the models used with `--track` and `--models`; `opengame jams <slug> --json` lists them.
180
183
  - **They did not ask.** Give them `data.review.url`. Signed in, they check the details, enter the jam and publish on that page.
181
184
 
182
185
  To publish in one step, `opengame deploy --publish --json` stays until review passes, then publishes, and takes the same jam flags.
183
186
 
184
187
  An update to a game that is already live publishes by itself once it passes review. It keeps the live game's details, including the genre when the deploy left it to Auto, and its jam entry. The token that deployed it has to hold `submit`, as the `opengame login` token does. When the creator asked only for a preview of an update to a live game, deploy with a token made in their settings with `deploy` alone, set as `OPENGAME_TOKEN`, so the release waits for them.
185
188
 
186
- `opengame submit` does not confirm a release that is already in review. The server keeps that submission and prints a `jam_answers_unused` notice: the jam answers you passed were not used. Pass them to `opengame publish` once review passes.
189
+ `opengame submit` does not confirm a release that is already in review. The server keeps that submission, and the CLI prints a `jam_answers_unused` notice: the jam answers you passed were not used. Pass them to `opengame publish` once review passes.
187
190
 
188
- While Game Jam #1 runs, a new game goes on OpenGame only as a jam entry, up to 2 for each account. Mods and decomps publish outside the jam at any time and never enter it. When the jam cannot take a build, for example because the account already has 2 entries, the build is not sent to review, and the deploy's page explains why. [Enter a jam](https://docs.opengame.io/guides/jams) has the rules.
191
+ While Game Jam #1 runs, a new game or an update goes on OpenGame only as a jam entry, up to 2 for each account. Mods and decomps publish outside the jam at any time and never enter it. When the jam cannot take a build, for example because the account already has 2 entries, the build is not sent to review, and the deploy's page explains why. [Enter a jam](https://docs.opengame.io/guides/jams) has the rules.
189
192
 
190
193
  Follow the release to the end:
191
194
 
@@ -196,10 +199,14 @@ opengame status --watch --json
196
199
  | `data.review.state` | What to do |
197
200
  | --- | --- |
198
201
  | `review`, `playtesting`, `waiting` | Review is running. Watch again. |
202
+ | `approved` | Review passed. When `data.review.next` is `opengame publish`, do as for `awaiting_details`; otherwise watch again. |
199
203
  | `awaiting_details` | Run `opengame publish --json` when the creator asked you to publish. Otherwise give them `data.review.url`, and watch again once they say they have published. |
200
204
  | `needs_certification` | Give the creator `data.review.url`. Watch again once they say they have done it. |
201
- | `publishing`, `published` | The game is going live. `data.submission.gameUrl` is its page. |
202
- | `returned` | Read the findings, fix the game and deploy again. The new deploy is reviewed automatically. |
205
+ | `publishing`, `published` | The game is going live. Once it is, `data.submission.live.url` is the address to share. |
206
+ | `returned` | Read the findings and run `data.review.next`. Usually that means fix the game and deploy again, and the new deploy is reviewed automatically. A jam entry returned for a fault on our side gets `opengame submit --release <id>` instead: the game needs no change, and the command names any jam answer it still needs. |
207
+ | `blocked` | Review refused the game. Give the creator `data.review.message`. |
208
+ | `withdrawn` | The creator withdrew this submission. Nothing more happens to it unless they ask you to enter it again. |
209
+ | `superseded` | Another submission took its place, and `data.submission.replacedBy` names it. Run `opengame status --json` again to follow that one. |
203
210
 
204
211
  ## What a game may do
205
212
 
@@ -1,11 +1,13 @@
1
1
  # Reading the CLI's JSON
2
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`.
3
+ With `--jsonl` 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`. With `--json`, the default
5
+ in an agent, the command prints only that last object, carrying the same findings and
6
+ notices in its `findings` and `notices` arrays.
5
7
 
6
8
  | `type` | Meaning | What to do |
7
9
  | --- | --- | --- |
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 |
10
+ | `progress` | A stage started or moved on: `install`, `build`, `package`, `check`, `upload`, then the server's own stages for the deploy, `review:<state>` while publish or submit follows review, `approval` for a login | Nothing; it is a heartbeat |
9
11
  | `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
12
  | `finding` | One problem in the game or one check that could not decide | Fix or report it, by its `fault`, `certainty` and `retry` |
11
13
  | `result` | The command finished; `data` holds its answer | Read `data` |
@@ -28,22 +30,21 @@ last line, and the last line is always a `result` or an `error`.
28
30
 
29
31
  A game whose `index.html` loads `./Game.js` while the file on disk is `game.js`. It runs
30
32
  on the creator's Mac, because the Mac's file system ignores case, and is a missing file for every
31
- player. `opengame check . --json` prints:
33
+ player. `opengame check . --jsonl` prints:
32
34
 
33
35
  ```json
34
36
  {"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"}}
35
- {"type":"finding","finding":{"release":null,"check":"platform-engine","checkVersion":"packaging@1","evidence":{"observed":"Browser compatibility needs a playtest."},"state":"inconclusive","certainty":"heuristic","fault":"unknown","fix":"Built with Three.js r170, from window.__THREE__ registration. Static browser exports from any engine, or none, go to review, where a playtest checks that this one runs. Every game must pass the same runtime and safety checks before publication. Nothing has to change now; you can deploy as it is.","verify":"opengame deploy","retry":"never"}}
37
+ {"type":"notice","code":"platform-engine","message":"Browser compatibility needs a playtest. Custom browser export: custom code. Static browser exports from any engine, or none, go to review, where a playtest checks that this one runs. Every game must pass the same runtime and safety checks before publication."}
36
38
  {"type":"error","code":"check_failed","message":"This build has blockers. Fix them, then run opengame check again.","exitCode":1,"retry":"after-fix"}
37
39
  ```
38
40
 
39
41
  Reading it:
40
42
 
41
- 1. The first finding is `failed`, `certain` and `fault: "game"`, so it is the game's to
43
+ 1. The finding is `failed`, `certain` and `fault: "game"`, so it is the game's to
42
44
  fix. `evidence.file` says `index.html:1`. Change `./Game.js` to `./game.js` there
43
45
  (or rename the file), then run what `verify` says.
44
- 2. The second finding is `inconclusive`, `heuristic` and `fault: "unknown"`, with
45
- `retry: "never"`. It does not block anything. Do not add a fake Three.js import to make
46
- it go away; the playtest in review checks that the game runs.
46
+ 2. The `platform-engine` line is a notice, not a finding. It blocks nothing. Do not add a
47
+ fake engine import to change it; the playtest in review checks that the game runs.
47
48
  3. After the fix, `opengame check . --json` ends in a `result` and exits 0.
48
49
 
49
50
  ## Findings that are ours
@@ -58,6 +59,6 @@ exists to prevent.
58
59
 
59
60
  - `deploy`: `operationId`, `state` (`uploading`, `queued`, `checking`, `ready`,
60
61
  `failed`, `expired`), `gameId`, `releaseId`, `url`, and `timingsMs` when it finished.
61
- Keep `releaseId`: submitting names it.
62
+ Keep `releaseId`: `opengame publish --release` and `opengame submit --release` name it.
62
63
  - `check`: `files`, `bytes`, `excluded` and `findings`.
63
64
  - `whoami`: the signed-in handle and the token's scopes.
@@ -3,7 +3,7 @@
3
3
  The game's manifest, committed with its code. `opengame init` writes it; the website
4
4
  edits the same fields. The game's id is never in this file: it lives in
5
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
6
+ else's game. Jam answers (track, models, sponsors) are never stored here either, because
7
7
  they belong to one entry, not to the game.
8
8
 
9
9
  ```json
@@ -21,16 +21,16 @@ they belong to one entry, not to the game.
21
21
 
22
22
  | Field | Rule |
23
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 |
24
+ | `title` | 3 to 40 characters, or `auto` |
25
+ | `tagline` | Optional, up to 140 characters, or `auto` |
26
+ | `description` | 40 to 500 characters, or `auto`. Say what the player does |
27
+ | `genre` | Exactly one slug from the table below, or `auto` |
28
28
  | `kind` | Optional. One of the four kinds below; leaving it out means `game`. `opengame init` always writes it |
29
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
30
  | `build.command` | Optional, up to 1,000 characters. Run before checking; may read environment variables but must not contain a secret |
31
31
  | `build.output` | The folder holding `index.html` after the build, or `.` |
32
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 |
33
+ | `controls` | One or more of `keyboard`, `mouse`, `gamepad`, each once, or `auto` |
34
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
35
  | `leaderboards` | Up to 25 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
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 |
@@ -72,12 +72,17 @@ it plays.
72
72
  `opengame init --kind mod --based-on "Doom"` writes both. Without `--kind`, init makes a
73
73
  game; it asks a person nothing but the game's name.
74
74
 
75
- A folder with no description of its own gets a placeholder sentence, which the deploy marks
76
- provisional, and so does a genre init could not read from the game's words. Do not ask the
77
- creator for either before deploying: the deploy's page asks them, `opengame publish
78
- --description` answers it from here once review passes, and `opengame details
79
- --description` sets the description once the game exists. A game cannot publish
80
- with the placeholder.
75
+ ## Auto
76
+
77
+ `title`, `tagline`, `description`, `genre` and `controls` take `"auto"`, and a field that is
78
+ blank or left out means the same. `opengame init` writes `"auto"` for every one of them it is
79
+ not given. Review writes an Auto field from the game itself, and the creator accepts or
80
+ changes what it wrote on the deploy's page before anything publishes; the subgenre is always
81
+ review's. Do not ask the creator for a description or a genre before deploying. Once review
82
+ passes, `opengame publish --description` and `--genre` answer from here instead, and
83
+ `opengame details --description` changes the words once the game exists. A title or
84
+ description the creator typed is theirs: review offers a tidied copy on a first publish, and
85
+ `opengame publish --keep-words` keeps theirs.
81
86
 
82
87
  ## Who owns which value
83
88
 
@@ -2,7 +2,7 @@
2
2
  name: opengame-jam
3
3
  description: Enter a game in an OpenGame jam. Finds the open jams, their tracks and rules, checks the game against them, deploys one exact release, and enters it with the person's own answers, with opengame publish or on the deploy's page. Use when the person says enter the jam, submit to the jam, which track should I pick, am I eligible, what are the jam rules, or mentions the OpenGame Global AI Game Jam.
4
4
  metadata:
5
- version: "1.1.0"
5
+ version: "1.1.1"
6
6
  ---
7
7
 
8
8
  # Enter an OpenGame jam
@@ -109,7 +109,7 @@ its deploy already sent to review: it answers with that submission and a
109
109
  ## What only the person can do
110
110
 
111
111
  Nobody certifies or attests to anything to enter. The person decides whether they are eligible (age, one account), whether they own
112
- the assets, which track they want, and what their sponsor evidence claims.
112
+ the assets, which track they want, and which account they used at each sponsor.
113
113
 
114
114
  ## After submitting
115
115
 
@@ -2,7 +2,7 @@
2
2
  name: opengame-performance
3
3
  description: Keep a browser game smooth on an ordinary laptop and a shared GPU, with three.js and WebGPU specifics. Covers frame-time tails counted from frames the engine ran, bare timing runs, cost over frame rate, frame pacing by what lands, draw calls per pass, a fixed light set and warm-up, uploads that never stall, the world lowered before the gameplay layer, and whole-tab memory. Use when the game stutters, hitches, drops frames, swings between rates, has a slow menu or a mouse that feels slow.
4
4
  metadata:
5
- version: "1.1.1"
5
+ version: "1.1.2"
6
6
  ---
7
7
 
8
8
  # Performance
@@ -24,8 +24,8 @@ upload ring) are in [references/webgpu.md](references/webgpu.md).
24
24
 
25
25
  ## Measure the running game
26
26
 
27
- Install `opengame-verification` with `opengame skills add --skill opengame-verification`
28
- and use its `opengame-verification/helpers/browser-evidence.mjs` for frame-time samples and input evidence.
27
+ `opengame setup` installs `opengame-verification`; to add it to one project, run
28
+ `opengame skills add . --skill opengame-verification`. Use its `opengame-verification/helpers/browser-evidence.mjs` for frame-time samples and input evidence.
29
29
  Set a frame-time tolerance from the target hardware's measured baseline. Record the
30
30
  CPU throttle and soak duration alongside the result. Compare the same scene and
31
31
  player route before and after a change. Inspect memory separately when diagnosing a
@@ -2,7 +2,7 @@
2
2
  name: opengame-router
3
3
  description: Build, test and submit a browser game on OpenGame. Routes game work to the deploy guide, whole-game review and relevant craft skills. Use when someone asks to make a game, improve a game, check it, deploy it or enter an OpenGame jam.
4
4
  metadata:
5
- version: "1.0.8"
5
+ version: "1.0.9"
6
6
  ---
7
7
 
8
8
  # Work on an OpenGame game
@@ -15,13 +15,15 @@ That is not a fault in the game.
15
15
  Read [the working process](references/process.md) before changing the game. Keep the
16
16
  user's scope and budget. Read only the specialists that apply to the next change.
17
17
 
18
- The starting set is this router, `opengame-deploy` and `opengame-quality-bar`.
19
- Run `opengame skills list --json` to see the installed CLI's catalog. Use
20
- `opengame help --json` for its skill selection options before installing a specialist.
18
+ `opengame setup` installs every OpenGame skill for the agents on the machine, and the CLI
19
+ keeps them current. `opengame skills add .` installs a starting set into one project: this
20
+ router, `opengame-deploy` and `opengame-quality-bar`. Run `opengame skills list --json` to
21
+ see the installed CLI's catalog, and add a specialist to the project with
22
+ `opengame skills add . --skill <name>`.
21
23
 
22
24
  | Work | Skill |
23
25
  | --- | --- |
24
- | Check, deploy, private preview, submit | `opengame-deploy` |
26
+ | Check, deploy, private preview, publish | `opengame-deploy` |
25
27
  | A CLI command, its output or its exit code | `opengame-cli` |
26
28
  | Calling the API from your own tool or CI | `opengame-api` |
27
29
  | Review the whole game | `opengame-quality-bar` |
@@ -6,8 +6,11 @@ ownership before editing. Use the host's permissions and available tools.
6
6
 
7
7
  Choose the smallest change that completes the request. Ask for missing information
8
8
  only when it changes what can be done safely or correctly. Keep publication and
9
- account actions within the user's authorization. A deploy is a private preview;
10
- public release needs its own approval.
9
+ account actions within the user's authorization. A deploy of a new game is a private
10
+ preview, and publishing it needs the user's approval. An update of a game that is already
11
+ live publishes by itself once it passes review when the token can submit, as the
12
+ `opengame login` token can, so deploy one only when the user wants players to get it, or
13
+ follow `opengame-deploy` to deploy it as a preview.
11
14
 
12
15
  Use the user's time, spend and reporting limits. Set a bounded checkpoint before
13
16
  starting uncertain research or a paid call. Stop at that checkpoint and report the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opengamehq/cli",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "description": "Deploy browser games to OpenGame from the command line.",
5
5
  "keywords": [
6
6
  "opengame",