hopple 0.1.0-rc.3 → 0.1.0-rc.6

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,13 @@ 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 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.
12
15
  - `hopple collaborators` chooses who else may publish a game.
13
16
 
14
17
  It is a dev dependency of the game (`npm install --save-dev hopple`, which
@@ -20,7 +23,8 @@ whatever tool the game uses.
20
23
 
21
24
  ## The project's config
22
25
 
23
- `dev`, `check`, `publish` and `collaborators` work on a **project**: a directory with a hopple
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
24
28
  config in it. They find it in the current directory, or the nearest one above
25
29
  it (like `tsconfig.json`). The config says everything they need to know:
26
30
 
@@ -32,12 +36,10 @@ export default {
32
36
  build: 'npm run build',
33
37
  page: 'dist/index.html',
34
38
  manifest: {
35
- schema: 1,
36
39
  id: 'my-game',
37
40
  version: '0.1.0',
38
41
  title: 'My Game',
39
42
  orientation: 'portrait',
40
- sdk: '^0.1.0',
41
43
  audio: null,
42
44
  },
43
45
  } satisfies HoppleConfig;
@@ -51,7 +53,19 @@ export default {
51
53
  published whole. A page beside the config has no output directory, and is
52
54
  published alone.
53
55
  - **`manifest`** is what the game is: its id, title, description, and what it
54
- declares. See [the manifest's reference](https://docs.hopple.app/manifest.md).
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.
55
69
 
56
70
  Only the page and the manifest are uploaded; `build` and `page` never leave
57
71
  your machine.
@@ -71,7 +85,14 @@ and errors in an editor, the manifest's included.
71
85
  hopple create <dir>
72
86
  hopple dev [project] [--port <n>] [--server <url>] [--no-build]
73
87
  hopple check [project] [--no-build]
74
- hopple publish [project] [--server <url>] [--no-build]
88
+ hopple upload [project] [--server <url>] [--no-build]
89
+ hopple publish [project] [@<version>] [--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>]
75
96
  hopple list [--server <url>]
76
97
  hopple collaborators [add <handle> | remove <handle>] [project] [--server <url>]
77
98
  hopple login [--server <url>]
@@ -90,10 +111,11 @@ The server is taken from `--server`, then `$HOPPLE_SERVER`, then
90
111
  ### `hopple create`
91
112
 
92
113
  ```bash
93
- npx hopple create my-game
114
+ npx hopple create my-game # or --next, for @hopple/sdk@next
94
115
  cd my-game && npm install
95
116
  npx hopple dev # build, then play it in the dev shell
96
117
  npm run watch # in another terminal: rebuild on every change, then reload the shell
118
+ npx hopple upload # build, check, then upload: a link to try it
97
119
  npx hopple publish # build, check, then publish
98
120
  ```
99
121
 
@@ -101,10 +123,17 @@ Writes a new project into `<dir>`, which must be new or empty. The directory's
101
123
  name becomes the game's id (lowercase letters, digits and hyphens). It is the
102
124
  recommended setup, not a requirement:
103
125
 
126
+ - **`@hopple/sdk`** is the one npm's `latest` names now (`^1.6.0`), or with
127
+ `--next` the one `next` names, exactly (`2.0.0-next.3`): `next` is the
128
+ API's next release, which breaks whenever it needs to, so the game stays on
129
+ it until it is moved on by hand. Only accounts an admin allows may publish
130
+ on `next`. `create` asks the registry `npm_config_registry` names, npm's own
131
+ otherwise.
132
+
104
133
  - **Vite** builds it into `dist/`, with `base: './'` so every address in it
105
134
  is relative, and `dist/index.html` as its page.
106
135
  - **`index.html` loads the runtime as its first script**,
107
- `<script src="_rt/1/hopple.js"></script>`. The runtime is the SDK, served
136
+ `<script src="_rt/hopple.js"></script>`. The runtime is the SDK, served
108
137
  beside the game by whatever runs it; the `@hopple/sdk` package the game
109
138
  imports is its types and a stub that forwards to it. So a fix to the SDK
110
139
  reaches the game without a rebuild. Keep the tag first.
@@ -132,11 +161,15 @@ The dev server serves:
132
161
  - `/game/`: the config's `page`, and `/game/…` the other files in its
133
162
  directory, with caching disabled. Nothing outside that directory is
134
163
  served.
135
- - `/game/_rt/1/hopple.js`: the runtime, beside the game as it is beside every
136
- published version. It is the release the server's players get, fetched
137
- from the server (`--server`, as for the other commands) when `hopple dev`
138
- starts, or the copy this CLI carries when the server can't be reached; the
139
- terminal says which.
164
+ - `/game/_rt/hopple.js`: the runtime, beside the game as it is beside every
165
+ published version. It is the release of the game's label (the track, the
166
+ major its manifest's `api` names or `next`, then each preview it declares
167
+ at its revision, `next+network.1`) the server's players get, fetched from
168
+ the server (`--server`, as for the other commands) when `hopple dev`
169
+ starts, or this CLI's own build of that label when the server can't be
170
+ reached or answers with another; the terminal says which. A server's
171
+ release can be newer than this CLI's shell understands, and the shell then
172
+ says to update `hopple`.
140
173
 
141
174
  A valid manifest is shown in the shell. An invalid or missing one is reported
142
175
  in the terminal and on the page, naming the bad fields, and the game still
@@ -148,11 +181,53 @@ stylesheet, images), but says in the terminal that it can't be published like
148
181
  that.
149
182
 
150
183
  **With no project to be found**, the shell starts empty and waits for a URL
151
- like `/?server=<server url>&game=<owner>/<name>@<version>`. The admin pages'
152
- "Dev shell" button opens exactly that, so you can run any uploaded game (yours
153
- or someone else's) in the dev shell. The shell downloads the game and its
184
+ like `/?server=<server url>&game=<owner>/<name>@<version>` (or `@beta`). The dev shell link
185
+ `hopple-admin review` prints for each waiting version is exactly that, and so
186
+ can a link you write for any uploaded game (yours or someone else's). The shell downloads the game and its
154
187
  manifest from that server's feed and runs it exactly as it would a local build.
155
188
 
189
+ #### Playing with others
190
+
191
+ `hopple dev` runs Hopple's own relay, at `/net` on its port, so a game
192
+ declaring the network preview gets parties and matches on the same rules as
193
+ on the site, with no server and no account. The sheet has the site's
194
+ **Party** tab.
195
+
196
+ A networked game opens on **two players tiled in one window**, each a whole
197
+ dev shell in a frame of its own, already in one party:
198
+
199
+ - **Tiling** works as in an IDE. Drag a player's title bar onto the edge of
200
+ another to split that pane there, or onto its middle to swap the two; drag
201
+ a divider to resize; double-click a title bar (or ⤢) to play that player
202
+ full size. The bar above has side by side, stacked and grid, and **add a
203
+ player**, up to 8. The layout is kept for the game.
204
+ - **The focused player** (the one clicked last, outlined) is the only one
205
+ heard and the one the keyboard reaches. A real pad goes to its player:
206
+ the first pad to Player 1, the second to Player 2.
207
+ - **Each player keeps their own** id, save and connection, as a separate
208
+ device would. A pane's × takes that player out of the party and the match.
209
+ - **`/?player=N`** opens one player alone, at full size. A party's or a
210
+ match's link opens one shell as a guest, which is how a phone on the same
211
+ network joins.
212
+
213
+ The Dev tab's **Network** part, for each player:
214
+
215
+ - **Network**: `none`, `lan`, `wired`, `wifi`, `mobile`, `weak` or `far`,
216
+ the delays, jitter, loss, stalls and bandwidth of `@hopple/netlab`'s
217
+ profiles, put between the player and the relay.
218
+ - **Faults**: drop the connection (it comes back on its own), stall it for
219
+ 3 s, take it offline for 35 s (past the 30 s the relay holds for a player
220
+ coming back), switch away for 5 s, or reload.
221
+ - **Match**: its code, seats, lock, kept messages, and its people with who
222
+ hosts it and who is away or gone.
223
+ - **Traffic**: what the game sent and heard, against the relay's limits (a
224
+ message at most 4096 bytes, 60 a second in bursts of 120), with a warning
225
+ when it comes near them and every refusal counted, and the latest messages
226
+ each way.
227
+
228
+ The shell a server hosts as plain files, with no `hopple dev` behind it, has
229
+ no relay and offers no matches.
230
+
156
231
  ### `hopple check`
157
232
 
158
233
  ```bash
@@ -173,9 +248,8 @@ Everything `publish` checks before it uploads, without uploading:
173
248
  whole game. The runtime, `_rt/`, is not the game's: it is served beside
174
249
  every game, and the directory may hold nothing there.
175
250
  3. The page loads the runtime as its first script,
176
- `<script src="_rt/1/hopple.js"></script>`, as it is, and no page or
177
- script carries a copy of the SDK. Games published before the runtime keep
178
- the SDK they bundled, but a new upload built that way is refused.
251
+ `<script src="_rt/hopple.js"></script>`, as it is, and no page or
252
+ script carries a copy of the SDK.
179
253
  4. Nothing is addressed from the root (`/assets/x.png` names the root of
180
254
  whatever serves the game, not the game), no page has a `<base>`, and every
181
255
  page is UTF-8.
@@ -189,33 +263,93 @@ It exits with 1 and says what is wrong, or prints the game's id, version and
189
263
  size. Over 2 MB compressed it warns that a player on a phone waits for the
190
264
  game, and over 10 MB `publish` refuses it.
191
265
 
192
- ### `hopple publish`
266
+ ### `hopple upload` and `hopple publish`
193
267
 
194
268
  ```bash
195
- npx hopple publish # this project's game, built
269
+ npx hopple upload # this project's game, built: uploaded, not published
270
+ npx hopple publish @3 # publish version 3, the one the upload printed
271
+ npx hopple publish # build, upload, and publish in one go
272
+ npx hopple publish --beta # the same, as the beta
196
273
  npx hopple publish path/to/project
197
274
  ```
198
275
 
276
+ `upload`:
277
+
199
278
  1. Makes every check `hopple check` makes, so mistakes are caught before
200
279
  anything is uploaded.
201
- 2. Uploads the manifest and the page, and publishes them as
202
- `<owner>/<manifest id>`, as a new version. The owner is the manifest's
203
- `owner`, or you when it names none; only the owner and the game's
204
- collaborators may publish it. The game is listed with
280
+ 2. Uploads the manifest and the page as `<owner>/<manifest id>`. The owner is
281
+ the manifest's `owner`, or you when it names none; only the owner and the
282
+ game's collaborators may upload it. The game's title and description are
205
283
  the manifest's `title` and `description`: to change them, change the
206
284
  manifest.
207
- 3. Prints the version's address, whether it is live, and a link that opens that
208
- exact version.
285
+ 3. Prints the version's address, a link that opens that exact version, and
286
+ how to publish it (`hopple publish @3`).
287
+
288
+ The version is not published: nobody browsing the site finds it, and only
289
+ people given the link can play it. Until an admin approves it, it plays
290
+ without scores, saves or achievements. Files and a manifest the game already
291
+ has are that version again, not a new one: uploading a build already
292
+ uploaded prints the version it is.
293
+
294
+ `publish` uploads the same way, then asks for **`latest`** to point at the
295
+ version: `latest` is what the game's address opens, and what the feed shows
296
+ while the game is listed. With `--beta` it asks for **`beta`**: a newer
297
+ version that players who opted in get, while it is newer than `latest`, with
298
+ its own boards and achievements. A beta no newer than `latest` is refused, and
299
+ publishing `latest` at the beta or past it ends the beta. With
300
+ `@<version>` it builds and uploads nothing, and asks for that version, already
301
+ uploaded. A `publish` after an `upload` of the same build asks for the
302
+ uploaded version, since the upload is that version again.
303
+
304
+ - **A trusted user's or an admin's request** moves the tag at once, whoever
305
+ owns the game, and so does a request for a version already approved: that
306
+ is a rollback (`hopple publish @2`).
307
+ - **Anybody else's waits** for an admin to approve the version, while the tag
308
+ stays where it was. Approving it moves the tag. A game has one request
309
+ waiting per tag: a new one replaces it, and the version it named stays,
310
+ uploaded. You can have at most 5 waiting, across games.
311
+
312
+ It prints whether the tag moved or the request waits for review, and a link
313
+ to the version. `hopple withdraw` takes back a request still waiting.
314
+
315
+ Publishing needs an account. Without `hopple login`, `publish` uploads as
316
+ `upload` does, asking for nothing, and says to sign in, then `hopple publish
317
+ @<version>`; `publish @<version>` uploads nothing, says to sign in and fails.
318
+ `upload` uploads, says it was anonymous, and says to sign in before
319
+ publishing. Sign in before or after: the games uploaded anonymously from this
320
+ machine move into your account.
321
+
322
+ ### `hopple versions`, `withdraw`, `untag`, `unpublish`, `rollback`, `listing`
209
323
 
210
- If you are a trusted user or an admin, the version goes live immediately,
211
- whoever owns the game.
212
- Otherwise it waits for an admin to review it, and the previous live version
213
- (if any) stays in the feed meanwhile.
324
+ ```bash
325
+ npx hopple versions # every version: its review, its tags, what waits
326
+ npx hopple withdraw # take back the request waiting for latest
327
+ npx hopple withdraw --beta # or for beta
328
+ npx hopple untag beta # end the beta
329
+ npx hopple unpublish # take the game down: no latest, no beta, nothing waiting
330
+ npx hopple rollback # latest back to the approved version before it
331
+ npx hopple listing unlisted # out of the feed and search; listed puts it back
332
+ ```
214
333
 
215
- Nothing is published for an anonymous account. Without `hopple login`, the
216
- upload is kept and its link works, but it stays out of the feed, and `publish`
217
- prints a warning saying so. Sign in before or after: either way the game ends
218
- up in your account.
334
+ They work on the game `publish` would upload to, for its owner, its
335
+ collaborators and admins.
336
+
337
+ - `versions` lists every version, newest first: whether it is approved,
338
+ turned down (with the admin's note) or not reviewed, the tags pointing at
339
+ it, the tag it waits for, who uploaded it and when, and its link. It says
340
+ whether the game is listed.
341
+ - `withdraw` closes the request waiting for `latest`, or with `--beta` for
342
+ `beta`. The version stays, and its link still opens it.
343
+ - `untag beta` ends the beta: its players get `latest`.
344
+ - `unpublish` takes the game down: it removes `latest` and `beta` and
345
+ withdraws what waits for review, so nothing brings it back until somebody
346
+ publishes it again. Its versions stay, and their links still open them.
347
+ - `rollback` points `latest` at the newest approved version before the one it
348
+ points at; run again, it goes further back. After an `unpublish` it points
349
+ `latest` back at the version it had. With nothing to go back to, it fails.
350
+ - `listing` says whether the game is listed: in the feed and search while it
351
+ has a `latest`. `listed` or `unlisted` sets it, which only the owner may do.
352
+ An unlisted game keeps its tags, its scores and its links.
219
353
 
220
354
  ### `hopple login`, `logout`, `whoami`, `list`
221
355
 
@@ -226,19 +360,23 @@ up in your account.
226
360
  site (or sign in there, any way the site offers), check that the page shows
227
361
  the same code, and approve. Nothing is typed in the terminal, and the link
228
362
  can be opened on another machine. It is good for ten minutes.
229
- Anything you published anonymously from this machine moves into your account.
363
+ Anything you uploaded anonymously from this machine moves into your account.
364
+ A sign-in lasts 90 days from when it was last used. Once one ends (expired,
365
+ or gone from the server), commands stop with an error until you run
366
+ `hopple login` again; they do not quietly carry on anonymously.
230
367
  - `hopple whoami` shows who you are on that server and how you signed in.
231
368
  - `hopple logout` ends the session and forgets it.
232
- - `hopple list` shows each game you own or collaborate on, its live version, its
233
- newest version if different (and whether it is waiting for review), and a
234
- link to each.
369
+ - `hopple list` shows each game you own or collaborate on, whether it is
370
+ listed, the versions its tags point at, those waiting for review, its newest
371
+ version, and a link to each.
235
372
 
236
373
  Sessions are stored per server in `~/.config/hopple/sessions.json` (or under
237
374
  `$XDG_CONFIG_HOME`, or `$HOPPLE_CONFIG_DIR` if set), readable only by you.
238
375
  The file contains your session tokens, so treat it like a password.
239
376
 
240
377
  Every request names the CLI and its version (`User-Agent: hopple-cli/<version>`).
241
- The server uses that to count games published and terminals signed in from
378
+ A server refuses a CLI older than it accepts, saying to update it. It also
379
+ uses the version to count games published and terminals signed in from
242
380
  the CLI, under your Hopple player in our usage analytics. Nothing else is
243
381
  collected, and nothing is collected on your machine. Set `DO_NOT_TRACK=1` to
244
382
  leave your publishes and sign-ins out of those counts.
@@ -251,14 +389,15 @@ npx hopple collaborators add ada # let ada publish it too
251
389
  npx hopple collaborators remove ada
252
390
  ```
253
391
 
254
- A collaborator may publish new versions of the game. Nothing else: deleting
255
- it and choosing who publishes it stay with its owner. The game is the one
392
+ A collaborator may upload new versions of the game, ask for its tags, withdraw
393
+ its requests and end its beta. Nothing else: listing it, deleting it and
394
+ choosing who publishes it stay with its owner. The game is the one
256
395
  `publish` would upload to, `<owner>/<manifest id>`. Only accounts can be added,
257
396
  and each is told in their inbox.
258
397
 
259
398
  To publish a game you collaborate on, set the manifest's `owner` to the
260
- owner's handle. Without it, `publish` makes a game of your own instead. Its
261
- versions go live or wait for review by your own trust, not the owner's.
399
+ owner's handle. Without it, `publish` makes a game of your own instead. Your
400
+ requests move its tags or wait for review by your own trust, not the owner's.
262
401
 
263
402
  ## The dev shell
264
403
 
@@ -276,10 +415,10 @@ handle or the corner button) has:
276
415
  - **Manifest**: what the game declares.
277
416
  - **The log**: every analytics event, every refusal, every save read, write and
278
417
  clear (with sizes), every share link, and every error the game threw, with
279
- its stack. An error also shows over the game until it is read, and is
280
- printed in the terminal `hopple dev` runs in: once with its stack, then again
281
- only when it has been thrown 10, 100, 1000… times, and whole again after a
282
- restart.
418
+ its stack. A new error is also said over the game in a notice that goes
419
+ away on its own, and is printed in the terminal `hopple dev` runs in: once
420
+ with its stack, then again only when it has been thrown 10, 100, 1000…
421
+ times, and whole again after a restart.
283
422
 
284
423
  Switches that make the host misbehave on purpose, so you can see your game
285
424
  cope:
@@ -301,7 +440,7 @@ What each feature does in the shell:
301
440
  | 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). |
302
441
  | 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. |
303
442
  | 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. |
304
- | Input | The key-binding page, and a switch for which input device the player is using. |
443
+ | Input | The key-binding page, a switch for which input device the player is using, and a virtual pad to play the game with. |
305
444
  | 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. |
306
445
  | Pause | A button in the corner, shown only when the game says it can pause. |
307
446
 
@@ -162,3 +162,28 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
162
162
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
163
163
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
164
164
  SOFTWARE.
165
+
166
+ --------------------------------------------------------------------------------
167
+
168
+ ws 8.21.1 (MIT)
169
+
170
+ Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
171
+ Copyright (c) 2013 Arnout Kazemier and contributors
172
+ Copyright (c) 2016 Luigi Pinca and contributors
173
+
174
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
175
+ this software and associated documentation files (the "Software"), to deal in
176
+ the Software without restriction, including without limitation the rights to
177
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
178
+ the Software, and to permit persons to whom the Software is furnished to do so,
179
+ subject to the following conditions:
180
+
181
+ The above copyright notice and this permission notice shall be included in all
182
+ copies or substantial portions of the Software.
183
+
184
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
185
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
186
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
187
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
188
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
189
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.