hopple 0.1.0-rc.2 → 0.1.0-rc.20

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/README.md CHANGED
@@ -5,10 +5,15 @@ The command-line tool for game developers:
5
5
  - `hopple create` starts a new game with the recommended setup (optional).
6
6
  - `hopple dev` runs a built game in the **dev shell**, a host made for
7
7
  testing, which runs it with the same code as the real clients.
8
- - `hopple check` says whether a game can be published, and `hopple publish`
9
- uploads it to a Hopple server.
10
- - `hopple list`, `login`, `logout` and `whoami` manage what you've published
11
- and who you publish as.
8
+ - `hopple smoke` plays a built game headless, at every screen shape and
9
+ device tier, and says what a player would trip over.
10
+ - `hopple check` says whether a game can be published. `hopple upload`
11
+ uploads it to a Hopple server, for a link to try it, and `hopple publish`
12
+ uploads it and asks for it to be published.
13
+ - `hopple versions`, `withdraw`, `untag`, `unpublish`, `rollback` and
14
+ `listing` say and change where a game's versions stand.
15
+ - `hopple list`, `login`, `logout` and `whoami` manage what you've uploaded
16
+ and who you upload as.
12
17
  - `hopple collaborators` chooses who else may publish a game.
13
18
 
14
19
  It is a dev dependency of the game (`npm install --save-dev hopple`, which
@@ -20,24 +25,24 @@ whatever tool the game uses.
20
25
 
21
26
  ## The project's config
22
27
 
23
- `dev`, `check`, `publish` and `collaborators` work on a **project**: a directory with a hopple
28
+ The commands about a game (`dev`, `check`, `upload`, `publish`, `versions`,
29
+ `withdraw`, `untag`, `unpublish`, `rollback`, `listing`, `collaborators`) work on a **project**: a directory with a hopple
24
30
  config in it. They find it in the current directory, or the nearest one above
25
31
  it (like `tsconfig.json`). The config says everything they need to know:
26
32
 
27
33
  ```ts
28
34
  // hopple.config.ts
29
- import type { HoppleConfig } from '@hopple/sdk';
35
+ import type { HoppleConfig } from 'hopple';
30
36
 
31
37
  export default {
32
38
  build: 'npm run build',
39
+ watch: 'npm run watch',
33
40
  page: 'dist/index.html',
34
41
  manifest: {
35
- schema: 1,
36
42
  id: 'my-game',
37
43
  version: '0.1.0',
38
44
  title: 'My Game',
39
45
  orientation: 'portrait',
40
- sdk: '^0.1.0',
41
46
  audio: null,
42
47
  },
43
48
  } satisfies HoppleConfig;
@@ -46,32 +51,60 @@ export default {
46
51
  - **`build`** (optional) is the command that builds the game. It runs first, in
47
52
  the config's directory, and a failed build stops the command. So
48
53
  `npx hopple publish` can't upload a stale build. `--no-build` skips it.
49
- - **`page`** is the built HTML file, relative to the config. It is the one file
50
- that is played in the dev shell and published, so it must contain the whole
51
- game.
54
+ - **`watch`** (optional) is the command that rebuilds the game on every change
55
+ and keeps running. `hopple dev` runs it, after the build, until it stops.
56
+ - **`page`** is the built HTML file, relative to the config: the `index.html`
57
+ of the build's output directory, which is played in the dev shell and
58
+ published whole. A page beside the config has no output directory, and is
59
+ published alone.
52
60
  - **`manifest`** is what the game is: its id, title, description, and what it
53
- declares. See [the manifest's reference](https://docs.hopple.app/manifest.md).
61
+ declares. See [the manifest's reference](https://docs.hopple.app/manifest.md). Its `api`
62
+ may be left out: every command fills it from the installed `@hopple/sdk`
63
+ (`1.6.2` is `"1.6"`, a pre-release is `"next"`), and refuses a manifest
64
+ whose `api` differs from it. The manifest is checked with the validator the
65
+ installed `@hopple/sdk` carries, which is of that API, so a CLI newer or
66
+ older than the SDK judges it the same; with no SDK installed, with the
67
+ CLI's own. Likewise **`previews.network`**: a project depending on
68
+ `@hopple/sdk-preview-network` (its `package.json` lists it) declares the network
69
+ preview at the installed revision (`0.1.4` is `1`) without saying so, and
70
+ a manifest naming another revision than the one installed, or naming one
71
+ with none installed, is refused. A `@hopple/sdk-preview-network` merely found above the
72
+ project, as another game in a workspace installs it, is checked against
73
+ but declares nothing.
54
74
 
55
75
  Only the page and the manifest are uploaded; `build` and `page` never leave
56
76
  your machine.
57
77
 
58
78
  The config can be `hopple.config.ts`, `hopple.config.js` (both default-export
59
- it) or `hopple.config.json` (which is it). A TypeScript config needs no build
79
+ it) or `hopple.config.json` (which is it). Its type, `HoppleConfig`, is this
80
+ package's: `import type { HoppleConfig } from 'hopple'`, whose `manifest` is
81
+ the type the installed `@hopple/sdk` gives it. A TypeScript config needs no build
60
82
  of its own: Node runs it. Any other key is an error, so a misspelt `build`
61
83
  can't be silently skipped, and two configs in one directory are an error too.
62
84
 
63
85
  A JSON config can start with
64
- `"$schema": "./node_modules/@hopple/sdk/config.schema.json"` for completion
86
+ `"$schema": "./node_modules/hopple/config.schema.json"` for completion
65
87
  and errors in an editor, the manifest's included.
66
88
 
67
89
  ## Commands
68
90
 
69
91
  ```
70
92
  hopple create <dir>
71
- hopple dev [project] [--port <n>] [--no-build]
72
- hopple check [project] [--no-build]
73
- hopple publish [project] [--server <url>] [--no-build]
93
+ hopple dev [project] [--port <n>] [--server <url>] [--no-audio] [--no-build]
94
+ hopple check [project] [--server <url>] [--no-build]
95
+ hopple upload [project] [--anonymous] [--server <url>] [--no-build]
96
+ hopple smoke [project] [--shapes <list>] [--script <file>] [--cover] [--sound | --no-audio] [--out <dir>] [--seed <n>] [--server <url>] [--no-build]
97
+ hopple publish [project] [@<build>] [--beta] [--anonymous] [--no-live-check] [--server <url>] [--no-build]
98
+ hopple versions [project] [--server <url>]
99
+ hopple withdraw [project] [--beta] [--server <url>]
100
+ hopple untag beta [project] [--server <url>]
101
+ hopple unpublish [project] [--server <url>]
102
+ hopple rollback [project] [--server <url>]
103
+ hopple listing [project] [listed | unlisted] [--server <url>]
74
104
  hopple list [--server <url>]
105
+ hopple bugs [project] [--json] [--server <url>]
106
+ hopple bugs download <id | all> [project] [--out <dir>] [--server <url>]
107
+ hopple share <link | id> [--data] [--json] [--server <url>]
75
108
  hopple collaborators [add <handle> | remove <handle>] [project] [--server <url>]
76
109
  hopple login [--server <url>]
77
110
  hopple logout [--server <url>]
@@ -86,13 +119,38 @@ The server is taken from `--server`, then `$HOPPLE_SERVER`, then
86
119
  `https://hopple.app`. It is named by its site; the CLI finds the API under
87
120
  `/api` on it.
88
121
 
122
+ ### Out of date
123
+
124
+ `create`, `dev`, `check`, `upload` and `publish` end by saying when what the
125
+ agent works from is out of date:
126
+
127
+ - **The Hopple skill.** Each copy of the `hopple-game` skill in an agent's
128
+ skills (`~/.agents/skills`, `~/.claude/skills`, `$CLAUDE_CONFIG_DIR/skills`,
129
+ and `.agents/skills` and `.claude/skills` in the project and the
130
+ directories above it) whose `Skill version:` is older than the one
131
+ `https://docs.hopple.app/skill.md` serves is named, with the command that
132
+ updates it: `npx skills update hopple-game -g -y` for one the skills
133
+ installer put there for the user (`npx skills add https://docs.hopple.app
134
+ -g`), `-p -y` in the project for one it put in a project, and for a copy
135
+ made by hand, to install or read the current one.
136
+ - **This CLI.** `create`, `dev` and `check` ask the server whether it would
137
+ refuse this CLI, which it does below the version it supports, and say what
138
+ to update; `upload` and `publish` are told by the server itself.
139
+
140
+ It never fails or slows a command: it runs beside it, each request gives up
141
+ after 1.5 seconds, and what it learns is kept in `updates.json` beside the
142
+ sessions file (the site's skill version for 6 hours, a server's answer for an
143
+ hour). With no skill installed it asks the site nothing, and offline it says
144
+ nothing. `HOPPLE_NO_UPDATE_CHECK=1` turns it off; `$HOPPLE_DOCS` points it at
145
+ another documentation site.
146
+
89
147
  ### `hopple create`
90
148
 
91
149
  ```bash
92
- npx hopple create my-game
150
+ npx hopple create my-game # or --next, for @hopple/sdk@next
93
151
  cd my-game && npm install
94
- npx hopple dev # build, then play it in the dev shell
95
- npm run watch # in another terminal: rebuild on every change, then reload the shell
152
+ npx hopple dev # build, then play it in the dev shell; it rebuilds on every change
153
+ npx hopple upload # build, check, then upload: a link to try it
96
154
  npx hopple publish # build, check, then publish
97
155
  ```
98
156
 
@@ -100,10 +158,26 @@ Writes a new project into `<dir>`, which must be new or empty. The directory's
100
158
  name becomes the game's id (lowercase letters, digits and hyphens). It is the
101
159
  recommended setup, not a requirement:
102
160
 
103
- - **Vite** builds it, with `vite-plugin-singlefile` inlining every script,
104
- style and imported asset into `dist/index.html`.
161
+ - **`@hopple/sdk`** is the one npm's `latest` names now (`^1.6.0`), or with
162
+ `--next` the one `next` names, exactly (`2.0.0-next.3`): `next` is the
163
+ API's next release, which breaks whenever it needs to, so the game stays on
164
+ it until it is moved on by hand. Only accounts an admin allows may publish
165
+ on `next`. `create` asks the registry `npm_config_registry` names, npm's own
166
+ otherwise.
167
+
168
+ - **Vite** builds it into `dist/`, with `base: './'` so every address in it
169
+ is relative, and `dist/index.html` as its page.
170
+ - **`index.html` loads the runtime as its first script**,
171
+ `<script src="_rt/hopple.js"></script>`. The runtime is the SDK, served
172
+ beside the game by whatever runs it; the `@hopple/sdk` package the game
173
+ imports is its types and a stub that forwards to it. So a fix to the SDK
174
+ reaches the game without a rebuild. Keep the tag first.
105
175
  - **`hopple.config.ts`** builds with `npm run build` (typecheck with `tsc`,
106
- then bundle), names `dist/index.html` as the page, and holds the manifest.
176
+ then bundle), rebuilds with `npm run watch` (`vite build --watch`), names
177
+ `dist/index.html` as the page, and holds the manifest.
178
+ - **`vite.config.ts`** turns `HOPPLE_DEV` into `import.meta.env.HOPPLE_DEV`,
179
+ and marks the page of a build for `hopple dev` (see
180
+ [below](#developer-only-builds)).
107
181
  Being TypeScript, a mistake in the manifest is a type error.
108
182
  - **There is no `publish` script**: `npm publish` would run it, then upload the
109
183
  project to the npm registry. The project is also `"private": true`.
@@ -124,8 +198,17 @@ The dev server serves:
124
198
 
125
199
  - `/`: the dev shell.
126
200
  - `/game/`: the config's `page`, and `/game/…` the other files in its
127
- directory, with CORS enabled and caching disabled. Nothing outside that
128
- directory is served.
201
+ directory, with caching disabled. Nothing outside that directory is
202
+ served.
203
+ - `/game/_rt/hopple.js`: the runtime, beside the game as it is beside every
204
+ published version. It is the release of the game's label (the track, the
205
+ major its manifest's `api` names or `next`, then each preview it declares
206
+ at its revision, `next+network.1`) the server's players get, fetched from
207
+ the server (`--server`, as for the other commands) when `hopple dev`
208
+ starts, or this CLI's own build of that label when the server can't be
209
+ reached or answers with another; the terminal says which. A server's
210
+ release can be newer than this CLI's shell understands, and the shell then
211
+ says to update `hopple`.
129
212
 
130
213
  A valid manifest is shown in the shell. An invalid or missing one is reported
131
214
  in the terminal and on the page, naming the bad fields, and the game still
@@ -136,11 +219,97 @@ It plays a build that loads files from beside its page (a separate script, a
136
219
  stylesheet, images), but says in the terminal that it can't be published like
137
220
  that.
138
221
 
222
+ **On a phone.** The dev server listens on this machine alone. *Open on a
223
+ phone*, in the shell's Device panel, opens it to this machine's network too:
224
+ the shell on one port at this machine's address and the game on another, so
225
+ the game keeps an origin of its own, and a QR code of the shell's address
226
+ there, carrying the panel's settings (all but the shape, the host chrome and
227
+ the notch, which the phone has of its own). Scan it on a phone on the same
228
+ Wi-Fi. Everything the dev server serves, the relay included, is open to the
229
+ network from then until *stop network access*, or until the server stops;
230
+ only the shell on this machine can turn it on or off (`/network`, from its
231
+ own origin, with a header no form can send). The terminal says when it is on.
232
+
233
+ **Without sound.** `--no-audio`, or `HOPPLE_NO_AUDIO=1` in the environment,
234
+ starts the shell muted, the way a player's mute does: the game still runs its
235
+ sound and obeys `audio.allowed`, and is told it is muted, so its sound is
236
+ exercised and makes none. The pill over the game shows it muted, and a person
237
+ can unmute it. The developer's own mute setting, kept for the next page, is
238
+ left as it was. Set `HOPPLE_NO_AUDIO=1` once for an agent or a CI machine:
239
+ `hopple smoke` and the check `hopple publish` makes are silent anyway, and
240
+ `--sound` does not turn `hopple smoke`'s sound on while it is set.
241
+
242
+ #### Developer-only builds
243
+
244
+ `hopple dev` runs the config's `build`, then its `watch`, with `HOPPLE_DEV=1`
245
+ in their environment. Every other command runs `build` with `HOPPLE_DEV` taken
246
+ out, even when the terminal has it. So a game can build in what only its
247
+ developers should have, such as cheats or a level select, and leave it out of
248
+ everything else: in a project `hopple create` made,
249
+
250
+ ```ts
251
+ const dev = import.meta.env.HOPPLE_DEV ? await import('./dev.ts') : null;
252
+ ```
253
+
254
+ is `null` in a published build, which doesn't contain `dev.ts`. A runtime test
255
+ (the address, the host) would publish what it guards.
256
+
257
+ A page built this way carries `<meta name="hopple-dev">`, which `check`,
258
+ `upload` and `publish` refuse: a page built by `hopple dev` and uploaded with
259
+ `--no-build`, or rebuilt by its `watch` while they run, is never published.
260
+
261
+ `watch` runs in a process group of its own, stopped with `hopple dev`. When it
262
+ stops by itself, `hopple dev` says so and keeps serving the last build.
263
+
139
264
  **With no project to be found**, the shell starts empty and waits for a URL
140
- like `/?server=<server url>&game=<owner>/<name>@<version>`. The admin pages'
141
- "Dev shell" button opens exactly that, so you can run any uploaded game (yours
142
- or someone else's) in the dev shell. The shell downloads the game and its
265
+ like `/?server=<server url>&game=<owner>/<name>@<build>` (or `@beta`). The dev shell link
266
+ `hopple-admin review` prints for each waiting version is exactly that, and so
267
+ can a link you write for any uploaded game (yours or someone else's). The shell downloads the game and its
143
268
  manifest from that server's feed and runs it exactly as it would a local build.
269
+ Any shell link may add `&device=desktop`, `portrait` or `landscape` to open on
270
+ that device, as pressing its shape and rail switches would.
271
+
272
+ #### Playing with others
273
+
274
+ `hopple dev` runs Hopple's own relay, at `/net` on its port, so a game
275
+ declaring the network preview gets parties and matches on the same rules as
276
+ on the site, with no server and no account. The sheet has the site's
277
+ **Party** tab.
278
+
279
+ A networked game opens on **two players tiled in one window**, each a whole
280
+ dev shell in a frame of its own, already in one party:
281
+
282
+ - **Tiling** works as in an IDE. Drag a player's title bar onto the edge of
283
+ another to split that pane there, or onto its middle to swap the two; drag
284
+ a divider to resize; double-click a title bar (or ⤢) to play that player
285
+ full size. The bar above has side by side, stacked and grid, and **add a
286
+ player**, up to 8. The layout is kept for the game.
287
+ - **The focused player** (the one clicked last, outlined) is the only one
288
+ heard and the one the keyboard reaches. A real pad goes to its player:
289
+ the first pad to Player 1, the second to Player 2.
290
+ - **Each player keeps their own** id, save and connection, as a separate
291
+ device would. A pane's × takes that player out of the party and the match.
292
+ - **`/?player=N`** opens one player alone, at full size. A party's or a
293
+ match's link opens one shell as a guest, which is how a phone on the same
294
+ network joins.
295
+
296
+ The Dev tab's **Network** part, for each player:
297
+
298
+ - **Network**: `none`, `lan`, `wired`, `wifi`, `mobile`, `weak` or `far`,
299
+ the delays, jitter, loss, stalls and bandwidth of `@hopple/netlab`'s
300
+ profiles, put between the player and the relay.
301
+ - **Faults**: drop the connection (it comes back on its own), stall it for
302
+ 3 s, take it offline for 35 s (past the 30 s the relay holds for a player
303
+ coming back), switch away for 5 s, or reload.
304
+ - **Match**: its code, seats, lock, kept messages, and its people with who
305
+ hosts it and who is away or gone.
306
+ - **Traffic**: what the game sent and heard, against the relay's limits (a
307
+ message at most 4096 bytes, 60 a second in bursts of 120), with a warning
308
+ when it comes near them and every refusal counted, and the latest messages
309
+ each way.
310
+
311
+ The shell a server hosts as plain files, with no `hopple dev` behind it, has
312
+ no relay and offers no matches.
144
313
 
145
314
  ### `hopple check`
146
315
 
@@ -152,42 +321,225 @@ npx hopple check --no-build # as it was last built
152
321
  Everything `publish` checks before it uploads, without uploading:
153
322
 
154
323
  1. The manifest validates.
155
- 2. The **page** exists, and loads nothing from outside itself: no
156
- `<script src>`, stylesheet `<link>`, `<img>` or CSS `url()` that isn't a
157
- `data:` URL. Only that one file is published, so it must contain the whole
158
- game, with every script and asset inlined. (Files the game's code fetches
159
- can't be seen this way; they fail the same way.)
324
+ 2. The **page** exists and is its output directory's `index.html`, and loads
325
+ nothing the directory doesn't hold: every `<script src>`, stylesheet
326
+ `<link>`, `<img>` and CSS `url()` is a `data:` URL or a file in the
327
+ directory, referred to relatively. That directory is what is published, at
328
+ the root of the version's own address, and a game reaches nothing else.
329
+ (Files the game's code fetches can't be seen this way; they fail the same
330
+ way.) A page beside its config is published alone, so it must contain the
331
+ whole game. The runtime, `_rt/`, is not the game's: it is served beside
332
+ every game, and the directory may hold nothing there.
333
+ 3. The page loads the runtime as its first script,
334
+ `<script src="_rt/hopple.js"></script>`, as it is, and no page or
335
+ script carries a copy of the SDK.
336
+ 4. Nothing is addressed from the root (`/assets/x.png` names the root of
337
+ whatever serves the game, not the game), no page has a `<base>`, and every
338
+ page is UTF-8.
339
+ 5. No script uses `localStorage`, `sessionStorage`, IndexedDB, Cache
340
+ Storage or `document.cookie`: a game's origin keeps nothing past a reload,
341
+ and the runtime makes them throw. Use `save` instead.
342
+ 6. The runtime the server serves the game's label is not older than the
343
+ installed `@hopple/sdk`: a game may use anything its SDK describes, so on
344
+ an older runtime it can fail as it starts. On `next` every pre-release
345
+ counts; on a major, the minor. Asked of the server (`--server`, else
346
+ `$HOPPLE_SERVER`, else hopple.app), and skipped when it can't be reached.
347
+ `hopple dev` warns of the same.
348
+
349
+ The server checks the same, in the same words. The CLI also refuses a page
350
+ built for `hopple dev` (see [Developer-only builds](#developer-only-builds)).
160
351
 
161
352
  It exits with 1 and says what is wrong, or prints the game's id, version and
162
- size.
353
+ size. Over 2 MB compressed it warns that a player on a phone waits for the
354
+ game, and over 10 MB `publish` refuses it.
355
+
356
+ ### `hopple smoke`
163
357
 
164
- ### `hopple publish`
358
+ ```bash
359
+ npx hopple smoke # every shape the game is played at
360
+ npx hopple smoke --shapes desktop,low-tier # some of them
361
+ npx hopple smoke --script smoke.json # with scripted input
362
+ npx hopple smoke --cover # and a cover
363
+ ```
364
+
365
+ Plays the built game headless, in the real runtime and host, in the Chrome
366
+ or Chromium this machine has (`$HOPPLE_CHROME` names one). The runtime is the
367
+ release players get, as `hopple dev` serves it, and drives the game's clock: time
368
+ moves only when the run steps it, a frame at a time, `Math.random` is seeded
369
+ (`--seed`, 1 unless given), and every press lands on a frame fixed in advance,
370
+ so two runs of one build do the same.
371
+
372
+ **Shapes.** A phone held each way the manifest's `orientation` allows
373
+ (`phone-portrait`, 390 × 844, and `phone-landscape`), a `desktop` (1280 ×
374
+ 800), and `low-tier`, a phone the way the game is held at the low device tier
375
+ with its CPU slowed four times; `tablet` (1024 × 768) when named. Phones are
376
+ touch, with the SDK's on-screen controls; the desktop has a keyboard and
377
+ mouse. Each is laid out as the site lays it out: the rail and a phone's notch
378
+ are reserved out of the frame, or told to a game that draws under them.
379
+
380
+ **What a run does.** It waits up to ten seconds of the game's time for it to
381
+ say it is ready, looks at its title, taps or clicks the middle and presses
382
+ Enter and Space, then for eight seconds presses each declared action's first
383
+ key in turn and, on a touch screen, taps around it. `--script <file>` replaces
384
+ all of that after the boot with a JSON list of steps: `{"wait": frames}`,
385
+ `{"press": "<action or key code>", "frames": n}`, `{"tap": [x, y], "frames":
386
+ n}`, `{"drag": [[x, y], [x, y]], "frames": n}` and `{"shot": "<name>"}`, x and
387
+ y being fractions of the frame from 0 to 1.
388
+
389
+ **What fails it**, each said with the shape it happened at:
390
+
391
+ - the game throws, or never says it is ready;
392
+ - in what the page draws as HTML, at each shot: text under 10 CSS pixels, cut
393
+ off by its box, or past the screen's edge where nothing scrolls it into
394
+ view; text the colour of what is behind it; a control off the screen,
395
+ covered by something a tap lands on instead (the SDK's own on-screen
396
+ controls included), or under the host's rail or the notch;
397
+ - on a desktop, the game drawing in a phone-shaped box less than 60% of the
398
+ screen wide;
399
+ - at the low tier, half the frames taking over 33 ms (under 30 frames a
400
+ second): its own work, and the drawing it left the canvas to finish.
401
+
402
+ It warns of text under 12 pixels or of low contrast, a picture that never
403
+ changes through the eight seconds of input, a game paused at the end, and
404
+ analytics events the manifest declares that no run sent. Text a canvas draws
405
+ can't be read, so a person looks at the pictures.
406
+
407
+ **What it writes**, into `.hopple/smoke/` beside the config (`--out` for
408
+ elsewhere): `sheet.png`, every shape's key moments side by side, for a person
409
+ to look over in one go; each moment's picture; and `report.json`, with the
410
+ problems and warnings and, for each run, what the game sent as analytics,
411
+ saved, scored and unlocked, and how long its frames took, for a test to check.
412
+ `--cover` also plays it at 1200 × 630 and writes the last picture, or the one
413
+ a script's `{"shot": "cover"}` takes, where the manifest's `cover` names, or as
414
+ `cover.png` beside the config. Every upload needs a cover: `check`, `upload`
415
+ and `publish` refuse a game whose manifest names none, and say to make one
416
+ this way.
417
+
418
+ A game may also have a clip, which Explore plays in place of its cover: the
419
+ manifest's `"clip": { "video": "clip.mp4", "poster": "clip.jpg" }`, the
420
+ poster being the clip's first frame. `smoke` does not make one yet. `check`,
421
+ `upload` and `publish` say everything wrong with one before sending anything:
422
+ it must be an H.264 MP4 with no sound track, 2 to 15 seconds long, no larger
423
+ than 1280 × 720 either way up, saved with fast start (ffmpeg's
424
+ `-movflags +faststart`), and at most 4 MB; its poster a PNG, JPEG or WebP of
425
+ at most 512 KB.
426
+
427
+ It makes no sound: Chrome is muted and the host tells the game it is muted.
428
+ `--sound` turns it on, unless `$HOPPLE_NO_AUDIO=1`. It exits with 1 when
429
+ anything failed.
430
+
431
+ ### `hopple upload` and `hopple publish`
165
432
 
166
433
  ```bash
167
- npx hopple publish # this project's game, built
434
+ npx hopple upload # this project's game, built: uploaded, not published
435
+ npx hopple publish @3 # publish build 3, the one the upload printed
436
+ npx hopple publish # build, upload, and publish in one go
437
+ npx hopple publish --beta # the same, as the beta
168
438
  npx hopple publish path/to/project
169
439
  ```
170
440
 
441
+ `upload`:
442
+
171
443
  1. Makes every check `hopple check` makes, so mistakes are caught before
172
444
  anything is uploaded.
173
- 2. Uploads the manifest and the page, and publishes them as
174
- `<owner>/<manifest id>`, as a new version. The owner is the manifest's
175
- `owner`, or you when it names none; only the owner and the game's
176
- collaborators may publish it. The game is listed with
445
+ 2. Says which account it uploads as, or that it uploads anonymously, before
446
+ it sends anything. An anonymous session is refused a project an account
447
+ published to that server from here before, or whose manifest names an
448
+ `owner`: its upload would be a separate anonymous copy of the game, and
449
+ the account's would keep its old build. It says to sign in as that
450
+ account; `--anonymous` uploads the copy anyway. Who published a project is
451
+ kept beside its config, in `.hopple/published.json`, by server, after
452
+ every upload from an account.
453
+ 3. Uploads the manifest and the page as `<owner>/<manifest id>`, naming the
454
+ installed `@hopple/sdk`'s version: the server refuses a version built
455
+ against an SDK newer than the runtime its label has out, until that
456
+ runtime is released. The owner is
457
+ the manifest's `owner`, or you when it names none; only the owner and the
458
+ game's collaborators may upload it. The game's title and description are
177
459
  the manifest's `title` and `description`: to change them, change the
178
460
  manifest.
179
- 3. Prints the version's address, whether it is live, and a link that opens that
180
- exact version.
461
+ 4. Prints the version, as the manifest's `version` and the build the server
462
+ numbered it (`owner/name 1.5.2 (build 3)`), a link that opens that exact
463
+ version, and how to publish it (`hopple publish @3`).
464
+
465
+ The version is not published: nobody browsing the site finds it, and only
466
+ people given the link can play it. Until an admin approves it, it plays
467
+ without scores, saves or achievements. Files and a manifest the game already
468
+ has are that version again, not a new one: uploading files already uploaded
469
+ prints the build they are. So are files the game already has with only the
470
+ manifest's `version` raised: it prints that build, under the `version` it was
471
+ uploaded with, and says no new version was made.
472
+
473
+ `publish` uploads the same way, then asks for **`latest`** to point at the
474
+ version: `latest` is what the game's address opens, and what the feed shows
475
+ while the game is listed. With `--beta` it asks for **`beta`**: a newer
476
+ version that players who opted in get, while it is newer than `latest`, with
477
+ its own boards and achievements. A beta no newer than `latest` is refused, and
478
+ publishing `latest` at the beta or past it ends the beta. With
479
+ `@<build>` it builds and uploads nothing, and asks for that build, already
480
+ uploaded. A `publish` after an `upload` of the same files asks for the
481
+ uploaded version, since the upload is that version again; as does a `publish`
482
+ of the same files with only `version` raised.
483
+
484
+ A published version names one build: a version whose manifest `version` is
485
+ already a published build's is refused, and its `upload` warns about it. Raise
486
+ `version` and upload again.
487
+
488
+ - **Once a tag moves to the version**, `publish` loads it once, headless,
489
+ from its own address with the runtime that address serves, as `hopple
490
+ smoke` does, and says whether it starts and throws nothing. It exits with 1
491
+ when it does not, so whoever published it hears about it, and roll it back
492
+ with `hopple rollback`. With no Chrome here it says nothing; `--no-live-check`
493
+ skips it.
494
+ - **A trusted user's or an admin's request** moves the tag at once, whoever
495
+ owns the game, and so does a request for a version already approved: that
496
+ is a rollback (`hopple publish @2`).
497
+ - **Anybody else's waits** for an admin to approve the version, while the tag
498
+ stays where it was. Approving it moves the tag. A game has one request
499
+ waiting per tag: a new one replaces it, and the version it named stays,
500
+ uploaded. You can have at most 5 waiting, across games.
501
+
502
+ It prints whether the tag moved or the request waits for review, and a link
503
+ to the version. `hopple withdraw` takes back a request still waiting.
504
+
505
+ Publishing needs an account. Without `hopple login`, `publish` uploads as
506
+ `upload` does, asking for nothing, and says to sign in, then `hopple publish
507
+ @<build>`; `publish @<build>` uploads nothing, says to sign in and fails.
508
+ `upload` uploads, says it was anonymous, and says to sign in before
509
+ publishing. Sign in before or after: the games uploaded anonymously from this
510
+ machine move into your account.
511
+
512
+ ### `hopple versions`, `withdraw`, `untag`, `unpublish`, `rollback`, `listing`
181
513
 
182
- If you are a trusted user or an admin, the version goes live immediately,
183
- whoever owns the game.
184
- Otherwise it waits for an admin to review it, and the previous live version
185
- (if any) stays in the feed meanwhile.
514
+ ```bash
515
+ npx hopple versions # every version: its review, its tags, what waits
516
+ npx hopple withdraw # take back the request waiting for latest
517
+ npx hopple withdraw --beta # or for beta
518
+ npx hopple untag beta # end the beta
519
+ npx hopple unpublish # take the game down: no latest, no beta, nothing waiting
520
+ npx hopple rollback # latest back to the approved version before it
521
+ npx hopple listing unlisted # out of the feed and search; listed puts it back
522
+ ```
186
523
 
187
- Nothing is published for an anonymous account. Without `hopple login`, the
188
- upload is kept and its link works, but it stays out of the feed, and `publish`
189
- prints a warning saying so. Sign in before or after: either way the game ends
190
- up in your account.
524
+ They work on the game `publish` would upload to, for its owner, its
525
+ collaborators and admins.
526
+
527
+ - `versions` lists every version, newest first: whether it is approved,
528
+ turned down (with the admin's note) or not reviewed, the tags pointing at
529
+ it, the tag it waits for, who uploaded it and when, and its link. It says
530
+ whether the game is listed.
531
+ - `withdraw` closes the request waiting for `latest`, or with `--beta` for
532
+ `beta`. The version stays, and its link still opens it.
533
+ - `untag beta` ends the beta: its players get `latest`.
534
+ - `unpublish` takes the game down: it removes `latest` and `beta` and
535
+ withdraws what waits for review, so nothing brings it back until somebody
536
+ publishes it again. Its versions stay, and their links still open them.
537
+ - `rollback` points `latest` at the newest approved version before the one it
538
+ points at; run again, it goes further back. After an `unpublish` it points
539
+ `latest` back at the version it had. With nothing to go back to, it fails.
540
+ - `listing` says whether the game is listed: in the feed and search while it
541
+ has a `latest`. `listed` or `unlisted` sets it, which only the owner may do.
542
+ An unlisted game keeps its tags, its scores and its links.
191
543
 
192
544
  ### `hopple login`, `logout`, `whoami`, `list`
193
545
 
@@ -198,22 +550,42 @@ up in your account.
198
550
  site (or sign in there, any way the site offers), check that the page shows
199
551
  the same code, and approve. Nothing is typed in the terminal, and the link
200
552
  can be opened on another machine. It is good for ten minutes.
201
- Anything you published anonymously from this machine moves into your account.
553
+ Anything you uploaded anonymously from this machine moves into your account.
554
+ A sign-in lasts 90 days from when it was last used. Once one ends (expired,
555
+ or gone from the server), commands stop with an error until you run
556
+ `hopple login` again; they do not quietly carry on anonymously.
202
557
  - `hopple whoami` shows who you are on that server and how you signed in.
203
558
  - `hopple logout` ends the session and forgets it.
204
- - `hopple list` shows each game you own or collaborate on, its live version, its
205
- newest version if different (and whether it is waiting for review), and a
206
- link to each.
559
+ - `hopple list` shows each game you own or collaborate on, whether it is
560
+ listed, the versions its tags point at, those waiting for review, its newest
561
+ version, and a link to each.
207
562
 
208
563
  Sessions are stored per server in `~/.config/hopple/sessions.json` (or under
209
564
  `$XDG_CONFIG_HOME`, or `$HOPPLE_CONFIG_DIR` if set), readable only by you.
210
565
  The file contains your session tokens, so treat it like a password.
211
566
 
212
567
  Every request names the CLI and its version (`User-Agent: hopple-cli/<version>`).
213
- The server uses that to count games published and terminals signed in from
214
- the CLI, under your Hopple player in our usage analytics. Nothing else is
215
- collected, and nothing is collected on your machine. Set `DO_NOT_TRACK=1` to
216
- leave your publishes and sign-ins out of those counts.
568
+ A server refuses a CLI older than it accepts, saying to update it.
569
+
570
+ ### `hopple usage`
571
+
572
+ ```bash
573
+ npx hopple usage # whether this machine shares usage data
574
+ npx hopple usage on # share it
575
+ npx hopple usage off # don't
576
+ ```
577
+
578
+ The CLI shares no usage data until you say so. In a terminal, the first of
579
+ `create`, `dev`, `check`, `smoke`, `upload`, `publish` or `login` you run asks
580
+ once; run by an agent, nothing asks, and the skill has the agent ask you and run
581
+ `hopple usage on` or `off` with your answer. The answer is kept in
582
+ `usage.json` beside the sessions.
583
+
584
+ Shared, it says which of those commands you ran and whether they worked, and
585
+ lets the server count games you upload and publish and terminals signed in,
586
+ under your Hopple player in our usage analytics. Never your code, files, names
587
+ or paths. Until then, and whenever `DO_NOT_TRACK=1` is set whatever you said,
588
+ every request asks the server to leave this machine out of its counts.
217
589
 
218
590
  ### `hopple collaborators`
219
591
 
@@ -223,14 +595,59 @@ npx hopple collaborators add ada # let ada publish it too
223
595
  npx hopple collaborators remove ada
224
596
  ```
225
597
 
226
- A collaborator may publish new versions of the game. Nothing else: deleting
227
- it and choosing who publishes it stay with its owner. The game is the one
598
+ A collaborator may upload new versions of the game, ask for its tags, withdraw
599
+ its requests and end its beta. Nothing else: listing it, deleting it and
600
+ choosing who publishes it stay with its owner. The game is the one
228
601
  `publish` would upload to, `<owner>/<manifest id>`. Only accounts can be added,
229
602
  and each is told in their inbox.
230
603
 
231
604
  To publish a game you collaborate on, set the manifest's `owner` to the
232
- owner's handle. Without it, `publish` makes a game of your own instead. Its
233
- versions go live or wait for review by your own trust, not the owner's.
605
+ owner's handle. Without it, `publish` makes a game of your own instead. Your
606
+ requests move its tags or wait for review by your own trust, not the owner's.
607
+
608
+ ### `hopple bugs`
609
+
610
+ ```bash
611
+ npx hopple bugs # every bug report players sent, newest first
612
+ npx hopple bugs download <id> # one, into bugs/<id>/
613
+ npx hopple bugs download all --out reports
614
+ ```
615
+
616
+ Players report a bug from the game's About tab: what went wrong, in their
617
+ words, and a screenshot if they choose one. Their save of the game and the
618
+ build they were playing go with it on their own, as does the browser they
619
+ played in. `bugs` lists the reports with each one's id; `bugs download` saves
620
+ one, or all of them, each into a folder of its own:
621
+
622
+ | File | What it is |
623
+ |---|---|
624
+ | `report.json` | What the player wrote, when, the build and the browser. |
625
+ | `save.json` | The save they were playing on, exactly as the game wrote it. |
626
+ | `save-state.json`, `.txt` or `.bin` | That save's state alone, to load in the game. |
627
+ | `screenshot.png`, `.jpg` or `.webp` | The picture they sent. |
628
+
629
+ Each of the last three is there only where the report has one. For the game's
630
+ owner, collaborators and admins; nothing in a report says who sent it.
631
+
632
+ ### `hopple share`
633
+
634
+ ```bash
635
+ npx hopple share 'https://hopple.app/ada/pocket?share=…' # the record behind a link
636
+ npx hopple share <link> --data > state.txt # the game's data alone, byte for byte
637
+ npx hopple share <link> --json
638
+ ```
639
+
640
+ The record behind a link a player shared: the game's `data` and `meta`, when
641
+ it was made and on which build of the game, where it was made and how it
642
+ left the page, and how many people opened it. It takes the link as the player
643
+ sent it, or its id. To get debug data from a player, have the game put it in a
644
+ link (`hopple.share.offer({ data, meta })`) and ask them to send you the link.
645
+ Data a game handed over as bytes (a `Uint8Array`) is written by `--data` as
646
+ those bytes, and shown in base64 otherwise.
647
+
648
+ For the game's owner, collaborators and admins. Reading a record does not
649
+ count as opening the link. Links made in the dev shell are kept in its browser,
650
+ not on a server, and are read in its log.
234
651
 
235
652
  ## The dev shell
236
653
 
@@ -248,10 +665,10 @@ handle or the corner button) has:
248
665
  - **Manifest**: what the game declares.
249
666
  - **The log**: every analytics event, every refusal, every save read, write and
250
667
  clear (with sizes), every share link, and every error the game threw, with
251
- its stack. An error also shows over the game until it is read, and is
252
- printed in the terminal `hopple dev` runs in: once with its stack, then again
253
- only when it has been thrown 10, 100, 1000… times, and whole again after a
254
- restart.
668
+ its stack. A new error is also said over the game in a notice that goes
669
+ away on its own, and is printed in the terminal `hopple dev` runs in: once
670
+ with its stack, then again only when it has been thrown 10, 100, 1000…
671
+ times, and whole again after a restart.
255
672
 
256
673
  Switches that make the host misbehave on purpose, so you can see your game
257
674
  cope:
@@ -273,7 +690,7 @@ What each feature does in the shell:
273
690
  | Achievements | Kept in memory for one player. *Reset* clears them **without** restarting the game (the running game keeps what it was told, just as in a real client). |
274
691
  | Share | Every link (the game's, or the rail's Share button) gets a record kept in the browser's `localStorage`: where it came from, and the game's `data` and `meta`. The record is written to the log, the link is copied to the clipboard, and the game is told `copied`. Opening the link in the same browser restarts the game with that data. *Open without the link* drops it. |
275
692
  | Panel | The same panel as a real host's, with the game's pages in it. The game can ask for one; opening the panel yourself, on the game's pages or on others, shows how the game reacts to a panel it didn't ask for. |
276
- | Input | The key-binding page, and a switch for which input device the player is using. |
693
+ | Input | The key-binding page, a switch for which input device the player is using, and a virtual pad to play the game with. |
277
694
  | Sound | Mute, master volume and a slider per declared channel, in the panel, on the game's page. The log says whether the game answered with the mix it was asked for. |
278
695
  | Pause | A button in the corner, shown only when the game says it can pause. |
279
696