hopple 0.0.0 → 0.1.0-rc.10

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/LICENSE ADDED
@@ -0,0 +1,40 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The Hopple authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ --------------------------------------------------------------------------------
24
+
25
+ The files `hopple create` writes into a new project are not under the license
26
+ above. They are under the BSD Zero Clause License (0BSD), so a game made from
27
+ them owes nothing to anyone:
28
+
29
+ Copyright (c) 2026 The Hopple authors
30
+
31
+ Permission to use, copy, modify, and/or distribute this software for any
32
+ purpose with or without fee is hereby granted.
33
+
34
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
35
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
36
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
37
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
38
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
39
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
40
+ PERFORMANCE OF THIS SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,481 @@
1
+ # hopple: the command line
2
+
3
+ The command-line tool for game developers:
4
+
5
+ - `hopple create` starts a new game with the recommended setup (optional).
6
+ - `hopple dev` runs a built game in the **dev shell**, a host made for
7
+ testing, which runs it with the same code as the real clients.
8
+ - `hopple check` says whether a game can be published. `hopple upload`
9
+ uploads it to a Hopple server, for a link to try it, and `hopple publish`
10
+ uploads it and asks for it to be published.
11
+ - `hopple versions`, `withdraw`, `untag`, `unpublish`, `rollback` and
12
+ `listing` say and change where a game's versions stand.
13
+ - `hopple list`, `login`, `logout` and `whoami` manage what you've uploaded
14
+ and who you upload as.
15
+ - `hopple collaborators` chooses who else may publish a game.
16
+
17
+ It is a dev dependency of the game (`npm install --save-dev hopple`, which
18
+ `hopple create` sets up), run with `npx hopple`. It is one compiled file with
19
+ no dependencies, and needs Node 22.18 or later.
20
+
21
+ `hopple` is not a bundler. It takes a game that is already built, by
22
+ whatever tool the game uses.
23
+
24
+ ## The project's config
25
+
26
+ The commands about a game (`dev`, `check`, `upload`, `publish`, `versions`,
27
+ `withdraw`, `untag`, `unpublish`, `rollback`, `listing`, `collaborators`) work on a **project**: a directory with a hopple
28
+ config in it. They find it in the current directory, or the nearest one above
29
+ it (like `tsconfig.json`). The config says everything they need to know:
30
+
31
+ ```ts
32
+ // hopple.config.ts
33
+ import type { HoppleConfig } from '@hopple/sdk';
34
+
35
+ export default {
36
+ build: 'npm run build',
37
+ page: 'dist/index.html',
38
+ manifest: {
39
+ id: 'my-game',
40
+ version: '0.1.0',
41
+ title: 'My Game',
42
+ orientation: 'portrait',
43
+ audio: null,
44
+ },
45
+ } satisfies HoppleConfig;
46
+ ```
47
+
48
+ - **`build`** (optional) is the command that builds the game. It runs first, in
49
+ the config's directory, and a failed build stops the command. So
50
+ `npx hopple publish` can't upload a stale build. `--no-build` skips it.
51
+ - **`page`** is the built HTML file, relative to the config: the `index.html`
52
+ of the build's output directory, which is played in the dev shell and
53
+ published whole. A page beside the config has no output directory, and is
54
+ published alone.
55
+ - **`manifest`** is what the game is: its id, title, description, and what it
56
+ declares. See [the manifest's reference](https://docs.hopple.app/manifest.md). Its `api`
57
+ may be left out: every command fills it from the installed `@hopple/sdk`
58
+ (`1.6.2` is `"1.6"`, a pre-release is `"next"`), and refuses a manifest
59
+ whose `api` differs from it. The manifest is checked with the validator the
60
+ installed `@hopple/sdk` carries, which is of that API, so a CLI newer or
61
+ older than the SDK judges it the same; with no SDK installed, with the
62
+ CLI's own. Likewise **`previews.network`**: a project depending on
63
+ `@hopple/sdk-preview-network` (its `package.json` lists it) declares the network
64
+ preview at the installed revision (`0.1.4` is `1`) without saying so, and
65
+ a manifest naming another revision than the one installed, or naming one
66
+ with none installed, is refused. A `@hopple/sdk-preview-network` merely found above the
67
+ project, as another game in a workspace installs it, is checked against
68
+ but declares nothing.
69
+
70
+ Only the page and the manifest are uploaded; `build` and `page` never leave
71
+ your machine.
72
+
73
+ The config can be `hopple.config.ts`, `hopple.config.js` (both default-export
74
+ it) or `hopple.config.json` (which is it). A TypeScript config needs no build
75
+ of its own: Node runs it. Any other key is an error, so a misspelt `build`
76
+ can't be silently skipped, and two configs in one directory are an error too.
77
+
78
+ A JSON config can start with
79
+ `"$schema": "./node_modules/@hopple/sdk/config.schema.json"` for completion
80
+ and errors in an editor, the manifest's included.
81
+
82
+ ## Commands
83
+
84
+ ```
85
+ hopple create <dir>
86
+ hopple dev [project] [--port <n>] [--server <url>] [--no-build]
87
+ hopple check [project] [--no-build]
88
+ hopple upload [project] [--server <url>] [--no-build]
89
+ hopple publish [project] [@<build>] [--beta] [--server <url>] [--no-build]
90
+ hopple versions [project] [--server <url>]
91
+ hopple withdraw [project] [--beta] [--server <url>]
92
+ hopple untag beta [project] [--server <url>]
93
+ hopple unpublish [project] [--server <url>]
94
+ hopple rollback [project] [--server <url>]
95
+ hopple listing [project] [listed | unlisted] [--server <url>]
96
+ hopple list [--server <url>]
97
+ hopple collaborators [add <handle> | remove <handle>] [project] [--server <url>]
98
+ hopple login [--server <url>]
99
+ hopple logout [--server <url>]
100
+ hopple whoami [--server <url>]
101
+ hopple --version
102
+ ```
103
+
104
+ `[project]` is a project's directory (or a directory inside it), or its config
105
+ file. Left out, it is the current directory.
106
+
107
+ The server is taken from `--server`, then `$HOPPLE_SERVER`, then
108
+ `https://hopple.app`. It is named by its site; the CLI finds the API under
109
+ `/api` on it.
110
+
111
+ ### Out of date
112
+
113
+ `create`, `dev`, `check`, `upload` and `publish` end by saying when what the
114
+ agent works from is out of date:
115
+
116
+ - **The Hopple skill.** Each copy of the `hopple-game` skill in an agent's
117
+ skills (`~/.agents/skills`, `~/.claude/skills`, `$CLAUDE_CONFIG_DIR/skills`,
118
+ and `.agents/skills` and `.claude/skills` in the project and the
119
+ directories above it) whose `Skill version:` is older than the one
120
+ `https://docs.hopple.app/skill.md` serves is named, with the command that
121
+ updates it: `npx skills update hopple-game -g -y` for one the skills
122
+ installer put there for the user (`npx skills add https://docs.hopple.app
123
+ -g`), `-p -y` in the project for one it put in a project, and for a copy
124
+ made by hand, to install or read the current one.
125
+ - **This CLI.** `create`, `dev` and `check` ask the server whether it would
126
+ refuse this CLI, which it does below the version it supports, and say what
127
+ to update; `upload` and `publish` are told by the server itself.
128
+
129
+ It never fails or slows a command: it runs beside it, each request gives up
130
+ after 1.5 seconds, and what it learns is kept in `updates.json` beside the
131
+ sessions file (the site's skill version for 6 hours, a server's answer for an
132
+ hour). With no skill installed it asks the site nothing, and offline it says
133
+ nothing. `HOPPLE_NO_UPDATE_CHECK=1` turns it off; `$HOPPLE_DOCS` points it at
134
+ another documentation site.
135
+
136
+ ### `hopple create`
137
+
138
+ ```bash
139
+ npx hopple create my-game # or --next, for @hopple/sdk@next
140
+ cd my-game && npm install
141
+ npx hopple dev # build, then play it in the dev shell
142
+ npm run watch # in another terminal: rebuild on every change, then reload the shell
143
+ npx hopple upload # build, check, then upload: a link to try it
144
+ npx hopple publish # build, check, then publish
145
+ ```
146
+
147
+ Writes a new project into `<dir>`, which must be new or empty. The directory's
148
+ name becomes the game's id (lowercase letters, digits and hyphens). It is the
149
+ recommended setup, not a requirement:
150
+
151
+ - **`@hopple/sdk`** is the one npm's `latest` names now (`^1.6.0`), or with
152
+ `--next` the one `next` names, exactly (`2.0.0-next.3`): `next` is the
153
+ API's next release, which breaks whenever it needs to, so the game stays on
154
+ it until it is moved on by hand. Only accounts an admin allows may publish
155
+ on `next`. `create` asks the registry `npm_config_registry` names, npm's own
156
+ otherwise.
157
+
158
+ - **Vite** builds it into `dist/`, with `base: './'` so every address in it
159
+ is relative, and `dist/index.html` as its page.
160
+ - **`index.html` loads the runtime as its first script**,
161
+ `<script src="_rt/hopple.js"></script>`. The runtime is the SDK, served
162
+ beside the game by whatever runs it; the `@hopple/sdk` package the game
163
+ imports is its types and a stub that forwards to it. So a fix to the SDK
164
+ reaches the game without a rebuild. Keep the tag first.
165
+ - **`hopple.config.ts`** builds with `npm run build` (typecheck with `tsc`,
166
+ then bundle), names `dist/index.html` as the page, and holds the manifest.
167
+ Being TypeScript, a mistake in the manifest is a type error.
168
+ - **There is no `publish` script**: `npm publish` would run it, then upload the
169
+ project to the npm registry. The project is also `"private": true`.
170
+ - `src/game.ts` is a small working game (a ball you keep in the air) that uses
171
+ the SDK the way every game should: `init`, the loop, layout, input and pause.
172
+
173
+ A game built any other way (another bundler, or a hand-written HTML file) is
174
+ played and published with the same commands, once it has a config.
175
+
176
+ ### `hopple dev`
177
+
178
+ ```bash
179
+ npx hopple dev # this project's game, built: http://localhost:5173
180
+ npx hopple dev path/to/project --port 8080
181
+ ```
182
+
183
+ The dev server serves:
184
+
185
+ - `/`: the dev shell.
186
+ - `/game/`: the config's `page`, and `/game/…` the other files in its
187
+ directory, with caching disabled. Nothing outside that directory is
188
+ served.
189
+ - `/game/_rt/hopple.js`: the runtime, beside the game as it is beside every
190
+ published version. It is the release of the game's label (the track, the
191
+ major its manifest's `api` names or `next`, then each preview it declares
192
+ at its revision, `next+network.1`) the server's players get, fetched from
193
+ the server (`--server`, as for the other commands) when `hopple dev`
194
+ starts, or this CLI's own build of that label when the server can't be
195
+ reached or answers with another; the terminal says which. A server's
196
+ release can be newer than this CLI's shell understands, and the shell then
197
+ says to update `hopple`.
198
+
199
+ A valid manifest is shown in the shell. An invalid or missing one is reported
200
+ in the terminal and on the page, naming the bad fields, and the game still
201
+ runs. The config is read again every time the shell page loads, so **an edited
202
+ manifest shows up on reload**, with no restart. So does a rebuilt game.
203
+
204
+ It plays a build that loads files from beside its page (a separate script, a
205
+ stylesheet, images), but says in the terminal that it can't be published like
206
+ that.
207
+
208
+ **With no project to be found**, the shell starts empty and waits for a URL
209
+ like `/?server=<server url>&game=<owner>/<name>@<build>` (or `@beta`). The dev shell link
210
+ `hopple-admin review` prints for each waiting version is exactly that, and so
211
+ can a link you write for any uploaded game (yours or someone else's). The shell downloads the game and its
212
+ manifest from that server's feed and runs it exactly as it would a local build.
213
+
214
+ #### Playing with others
215
+
216
+ `hopple dev` runs Hopple's own relay, at `/net` on its port, so a game
217
+ declaring the network preview gets parties and matches on the same rules as
218
+ on the site, with no server and no account. The sheet has the site's
219
+ **Party** tab.
220
+
221
+ A networked game opens on **two players tiled in one window**, each a whole
222
+ dev shell in a frame of its own, already in one party:
223
+
224
+ - **Tiling** works as in an IDE. Drag a player's title bar onto the edge of
225
+ another to split that pane there, or onto its middle to swap the two; drag
226
+ a divider to resize; double-click a title bar (or ⤢) to play that player
227
+ full size. The bar above has side by side, stacked and grid, and **add a
228
+ player**, up to 8. The layout is kept for the game.
229
+ - **The focused player** (the one clicked last, outlined) is the only one
230
+ heard and the one the keyboard reaches. A real pad goes to its player:
231
+ the first pad to Player 1, the second to Player 2.
232
+ - **Each player keeps their own** id, save and connection, as a separate
233
+ device would. A pane's × takes that player out of the party and the match.
234
+ - **`/?player=N`** opens one player alone, at full size. A party's or a
235
+ match's link opens one shell as a guest, which is how a phone on the same
236
+ network joins.
237
+
238
+ The Dev tab's **Network** part, for each player:
239
+
240
+ - **Network**: `none`, `lan`, `wired`, `wifi`, `mobile`, `weak` or `far`,
241
+ the delays, jitter, loss, stalls and bandwidth of `@hopple/netlab`'s
242
+ profiles, put between the player and the relay.
243
+ - **Faults**: drop the connection (it comes back on its own), stall it for
244
+ 3 s, take it offline for 35 s (past the 30 s the relay holds for a player
245
+ coming back), switch away for 5 s, or reload.
246
+ - **Match**: its code, seats, lock, kept messages, and its people with who
247
+ hosts it and who is away or gone.
248
+ - **Traffic**: what the game sent and heard, against the relay's limits (a
249
+ message at most 4096 bytes, 60 a second in bursts of 120), with a warning
250
+ when it comes near them and every refusal counted, and the latest messages
251
+ each way.
252
+
253
+ The shell a server hosts as plain files, with no `hopple dev` behind it, has
254
+ no relay and offers no matches.
255
+
256
+ ### `hopple check`
257
+
258
+ ```bash
259
+ npx hopple check # this project's game, built
260
+ npx hopple check --no-build # as it was last built
261
+ ```
262
+
263
+ Everything `publish` checks before it uploads, without uploading:
264
+
265
+ 1. The manifest validates.
266
+ 2. The **page** exists and is its output directory's `index.html`, and loads
267
+ nothing the directory doesn't hold: every `<script src>`, stylesheet
268
+ `<link>`, `<img>` and CSS `url()` is a `data:` URL or a file in the
269
+ directory, referred to relatively. That directory is what is published, at
270
+ the root of the version's own address, and a game reaches nothing else.
271
+ (Files the game's code fetches can't be seen this way; they fail the same
272
+ way.) A page beside its config is published alone, so it must contain the
273
+ whole game. The runtime, `_rt/`, is not the game's: it is served beside
274
+ every game, and the directory may hold nothing there.
275
+ 3. The page loads the runtime as its first script,
276
+ `<script src="_rt/hopple.js"></script>`, as it is, and no page or
277
+ script carries a copy of the SDK.
278
+ 4. Nothing is addressed from the root (`/assets/x.png` names the root of
279
+ whatever serves the game, not the game), no page has a `<base>`, and every
280
+ page is UTF-8.
281
+ 5. No script uses `localStorage`, `sessionStorage`, IndexedDB, Cache
282
+ Storage or `document.cookie`: a game's origin keeps nothing past a reload,
283
+ and the runtime makes them throw. Use `save` instead.
284
+
285
+ The server checks the same, in the same words.
286
+
287
+ It exits with 1 and says what is wrong, or prints the game's id, version and
288
+ size. Over 2 MB compressed it warns that a player on a phone waits for the
289
+ game, and over 10 MB `publish` refuses it.
290
+
291
+ ### `hopple upload` and `hopple publish`
292
+
293
+ ```bash
294
+ npx hopple upload # this project's game, built: uploaded, not published
295
+ npx hopple publish @3 # publish build 3, the one the upload printed
296
+ npx hopple publish # build, upload, and publish in one go
297
+ npx hopple publish --beta # the same, as the beta
298
+ npx hopple publish path/to/project
299
+ ```
300
+
301
+ `upload`:
302
+
303
+ 1. Makes every check `hopple check` makes, so mistakes are caught before
304
+ anything is uploaded.
305
+ 2. Uploads the manifest and the page as `<owner>/<manifest id>`. The owner is
306
+ the manifest's `owner`, or you when it names none; only the owner and the
307
+ game's collaborators may upload it. The game's title and description are
308
+ the manifest's `title` and `description`: to change them, change the
309
+ manifest.
310
+ 3. Prints the version, as the manifest's `version` and the build the server
311
+ numbered it (`owner/name 1.5.2 (build 3)`), a link that opens that exact
312
+ version, and how to publish it (`hopple publish @3`).
313
+
314
+ The version is not published: nobody browsing the site finds it, and only
315
+ people given the link can play it. Until an admin approves it, it plays
316
+ without scores, saves or achievements. Files and a manifest the game already
317
+ has are that version again, not a new one: uploading files already uploaded
318
+ prints the build they are.
319
+
320
+ `publish` uploads the same way, then asks for **`latest`** to point at the
321
+ version: `latest` is what the game's address opens, and what the feed shows
322
+ while the game is listed. With `--beta` it asks for **`beta`**: a newer
323
+ version that players who opted in get, while it is newer than `latest`, with
324
+ its own boards and achievements. A beta no newer than `latest` is refused, and
325
+ publishing `latest` at the beta or past it ends the beta. With
326
+ `@<build>` it builds and uploads nothing, and asks for that build, already
327
+ uploaded. A `publish` after an `upload` of the same files asks for the
328
+ uploaded version, since the upload is that version again.
329
+
330
+ A published version names one build: a version whose manifest `version` is
331
+ already a published build's is refused, and its `upload` warns about it. Raise
332
+ `version` and upload again.
333
+
334
+ - **A trusted user's or an admin's request** moves the tag at once, whoever
335
+ owns the game, and so does a request for a version already approved: that
336
+ is a rollback (`hopple publish @2`).
337
+ - **Anybody else's waits** for an admin to approve the version, while the tag
338
+ stays where it was. Approving it moves the tag. A game has one request
339
+ waiting per tag: a new one replaces it, and the version it named stays,
340
+ uploaded. You can have at most 5 waiting, across games.
341
+
342
+ It prints whether the tag moved or the request waits for review, and a link
343
+ to the version. `hopple withdraw` takes back a request still waiting.
344
+
345
+ Publishing needs an account. Without `hopple login`, `publish` uploads as
346
+ `upload` does, asking for nothing, and says to sign in, then `hopple publish
347
+ @<build>`; `publish @<build>` uploads nothing, says to sign in and fails.
348
+ `upload` uploads, says it was anonymous, and says to sign in before
349
+ publishing. Sign in before or after: the games uploaded anonymously from this
350
+ machine move into your account.
351
+
352
+ ### `hopple versions`, `withdraw`, `untag`, `unpublish`, `rollback`, `listing`
353
+
354
+ ```bash
355
+ npx hopple versions # every version: its review, its tags, what waits
356
+ npx hopple withdraw # take back the request waiting for latest
357
+ npx hopple withdraw --beta # or for beta
358
+ npx hopple untag beta # end the beta
359
+ npx hopple unpublish # take the game down: no latest, no beta, nothing waiting
360
+ npx hopple rollback # latest back to the approved version before it
361
+ npx hopple listing unlisted # out of the feed and search; listed puts it back
362
+ ```
363
+
364
+ They work on the game `publish` would upload to, for its owner, its
365
+ collaborators and admins.
366
+
367
+ - `versions` lists every version, newest first: whether it is approved,
368
+ turned down (with the admin's note) or not reviewed, the tags pointing at
369
+ it, the tag it waits for, who uploaded it and when, and its link. It says
370
+ whether the game is listed.
371
+ - `withdraw` closes the request waiting for `latest`, or with `--beta` for
372
+ `beta`. The version stays, and its link still opens it.
373
+ - `untag beta` ends the beta: its players get `latest`.
374
+ - `unpublish` takes the game down: it removes `latest` and `beta` and
375
+ withdraws what waits for review, so nothing brings it back until somebody
376
+ publishes it again. Its versions stay, and their links still open them.
377
+ - `rollback` points `latest` at the newest approved version before the one it
378
+ points at; run again, it goes further back. After an `unpublish` it points
379
+ `latest` back at the version it had. With nothing to go back to, it fails.
380
+ - `listing` says whether the game is listed: in the feed and search while it
381
+ has a `latest`. `listed` or `unlisted` sets it, which only the owner may do.
382
+ An unlisted game keeps its tags, its scores and its links.
383
+
384
+ ### `hopple login`, `logout`, `whoami`, `list`
385
+
386
+ - The first command that talks to a server starts an **anonymous session**,
387
+ named `anon-` and three words, so you can upload without an account.
388
+ - `hopple login` signs that same session in. It prints a link and a short
389
+ code, and waits: open the link in a browser where you are signed in to the
390
+ site (or sign in there, any way the site offers), check that the page shows
391
+ the same code, and approve. Nothing is typed in the terminal, and the link
392
+ can be opened on another machine. It is good for ten minutes.
393
+ Anything you uploaded anonymously from this machine moves into your account.
394
+ A sign-in lasts 90 days from when it was last used. Once one ends (expired,
395
+ or gone from the server), commands stop with an error until you run
396
+ `hopple login` again; they do not quietly carry on anonymously.
397
+ - `hopple whoami` shows who you are on that server and how you signed in.
398
+ - `hopple logout` ends the session and forgets it.
399
+ - `hopple list` shows each game you own or collaborate on, whether it is
400
+ listed, the versions its tags point at, those waiting for review, its newest
401
+ version, and a link to each.
402
+
403
+ Sessions are stored per server in `~/.config/hopple/sessions.json` (or under
404
+ `$XDG_CONFIG_HOME`, or `$HOPPLE_CONFIG_DIR` if set), readable only by you.
405
+ The file contains your session tokens, so treat it like a password.
406
+
407
+ Every request names the CLI and its version (`User-Agent: hopple-cli/<version>`).
408
+ A server refuses a CLI older than it accepts, saying to update it. It also
409
+ uses the version to count games published and terminals signed in from
410
+ the CLI, under your Hopple player in our usage analytics. Nothing else is
411
+ collected, and nothing is collected on your machine. Set `DO_NOT_TRACK=1` to
412
+ leave your publishes and sign-ins out of those counts.
413
+
414
+ ### `hopple collaborators`
415
+
416
+ ```bash
417
+ npx hopple collaborators # who else may publish this project's game
418
+ npx hopple collaborators add ada # let ada publish it too
419
+ npx hopple collaborators remove ada
420
+ ```
421
+
422
+ A collaborator may upload new versions of the game, ask for its tags, withdraw
423
+ its requests and end its beta. Nothing else: listing it, deleting it and
424
+ choosing who publishes it stay with its owner. The game is the one
425
+ `publish` would upload to, `<owner>/<manifest id>`. Only accounts can be added,
426
+ and each is told in their inbox.
427
+
428
+ To publish a game you collaborate on, set the manifest's `owner` to the
429
+ owner's handle. Without it, `publish` makes a game of your own instead. Your
430
+ requests move its tags or wait for review by your own trust, not the owner's.
431
+
432
+ ## The dev shell
433
+
434
+ The dev shell runs the game the way real hosts do (same sandbox, same bridge),
435
+ but surrounds it with controls for testing. Its panel (opened from the rail's
436
+ handle or the corner button) has:
437
+
438
+ - **Device**: the frame's shape (portrait phone, landscape phone, or the whole
439
+ browser window), where the host's buttons go, and a fake notch.
440
+ - **Lifecycle**: switch the game between `active`, `passive` and `hidden`; the
441
+ log shows the orders each one sends (sound, loop, resources). Ping it.
442
+ - **Info**: device tier, locale, whether the player is returning, and "be a new
443
+ player". Each of these **restarts the game**, because info is only sent once,
444
+ at the start.
445
+ - **Manifest**: what the game declares.
446
+ - **The log**: every analytics event, every refusal, every save read, write and
447
+ clear (with sizes), every share link, and every error the game threw, with
448
+ its stack. A new error is also said over the game in a notice that goes
449
+ away on its own, and is printed in the terminal `hopple dev` runs in: once
450
+ with its stack, then again only when it has been thrown 10, 100, 1000…
451
+ times, and whole again after a restart.
452
+
453
+ Switches that make the host misbehave on purpose, so you can see your game
454
+ cope:
455
+
456
+ - Reserve the host's buttons even though the game said `draw-under`.
457
+ - A host with no save store, a full one, or one that takes 2 seconds to reply.
458
+ - A host with no scores, no achievements, no panel, no input settings, no
459
+ audio settings, or that never asks the game to pause. These restart the game,
460
+ since what a host offers is settled at the start.
461
+ - Analytics rate limits like a real host's: 10 events a second, 15 in 15
462
+ seconds, 30 a minute.
463
+
464
+ What each feature does in the shell:
465
+
466
+ | Feature | In the dev shell |
467
+ |---|---|
468
+ | Save | Stored in the browser's `localStorage`. The panel shows what is stored, its size and age, and can delete it. |
469
+ | Score | A made-up leaderboard, so you can see how a rank looks before any real players exist. You can set the range. Your submitted scores join it. Reloading generates a new one. |
470
+ | 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). |
471
+ | 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. |
472
+ | 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. |
473
+ | Input | The key-binding page, a switch for which input device the player is using, and a virtual pad to play the game with. |
474
+ | 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. |
475
+ | Pause | A button in the corner, shown only when the game says it can pause. |
476
+
477
+ ## License
478
+
479
+ MIT; see `LICENSE`. The files `hopple create` writes into a new
480
+ project are under 0BSD instead, so a game made from them owes nothing to
481
+ anyone. The license covers the code, not the Hopple name or logo.