hopple 0.1.0-rc.3 → 0.1.0-rc.5
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 +145 -48
- package/hopple.js +392 -85
- package/package.json +1 -1
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
|
|
9
|
-
uploads it to a Hopple server
|
|
10
|
-
|
|
11
|
-
|
|
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
|
|
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
|
|
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/
|
|
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/
|
|
136
|
-
published version. It is the release the
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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,9 +181,9 @@ 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
|
|
152
|
-
|
|
153
|
-
or someone else's)
|
|
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
|
|
|
156
189
|
### `hopple check`
|
|
@@ -173,9 +206,8 @@ Everything `publish` checks before it uploads, without uploading:
|
|
|
173
206
|
whole game. The runtime, `_rt/`, is not the game's: it is served beside
|
|
174
207
|
every game, and the directory may hold nothing there.
|
|
175
208
|
3. The page loads the runtime as its first script,
|
|
176
|
-
`<script src="_rt/
|
|
177
|
-
script carries a copy of the SDK.
|
|
178
|
-
the SDK they bundled, but a new upload built that way is refused.
|
|
209
|
+
`<script src="_rt/hopple.js"></script>`, as it is, and no page or
|
|
210
|
+
script carries a copy of the SDK.
|
|
179
211
|
4. Nothing is addressed from the root (`/assets/x.png` names the root of
|
|
180
212
|
whatever serves the game, not the game), no page has a `<base>`, and every
|
|
181
213
|
page is UTF-8.
|
|
@@ -189,33 +221,93 @@ It exits with 1 and says what is wrong, or prints the game's id, version and
|
|
|
189
221
|
size. Over 2 MB compressed it warns that a player on a phone waits for the
|
|
190
222
|
game, and over 10 MB `publish` refuses it.
|
|
191
223
|
|
|
192
|
-
### `hopple publish`
|
|
224
|
+
### `hopple upload` and `hopple publish`
|
|
193
225
|
|
|
194
226
|
```bash
|
|
195
|
-
npx hopple
|
|
227
|
+
npx hopple upload # this project's game, built: uploaded, not published
|
|
228
|
+
npx hopple publish @3 # publish version 3, the one the upload printed
|
|
229
|
+
npx hopple publish # build, upload, and publish in one go
|
|
230
|
+
npx hopple publish --beta # the same, as the beta
|
|
196
231
|
npx hopple publish path/to/project
|
|
197
232
|
```
|
|
198
233
|
|
|
234
|
+
`upload`:
|
|
235
|
+
|
|
199
236
|
1. Makes every check `hopple check` makes, so mistakes are caught before
|
|
200
237
|
anything is uploaded.
|
|
201
|
-
2. Uploads the manifest and the page
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
collaborators may publish it. The game is listed with
|
|
238
|
+
2. Uploads the manifest and the page as `<owner>/<manifest id>`. The owner is
|
|
239
|
+
the manifest's `owner`, or you when it names none; only the owner and the
|
|
240
|
+
game's collaborators may upload it. The game's title and description are
|
|
205
241
|
the manifest's `title` and `description`: to change them, change the
|
|
206
242
|
manifest.
|
|
207
|
-
3. Prints the version's address,
|
|
208
|
-
|
|
243
|
+
3. Prints the version's address, a link that opens that exact version, and
|
|
244
|
+
how to publish it (`hopple publish @3`).
|
|
245
|
+
|
|
246
|
+
The version is not published: nobody browsing the site finds it, and only
|
|
247
|
+
people given the link can play it. Until an admin approves it, it plays
|
|
248
|
+
without scores, saves or achievements. Files and a manifest the game already
|
|
249
|
+
has are that version again, not a new one: uploading a build already
|
|
250
|
+
uploaded prints the version it is.
|
|
251
|
+
|
|
252
|
+
`publish` uploads the same way, then asks for **`latest`** to point at the
|
|
253
|
+
version: `latest` is what the game's address opens, and what the feed shows
|
|
254
|
+
while the game is listed. With `--beta` it asks for **`beta`**: a newer
|
|
255
|
+
version that players who opted in get, while it is newer than `latest`, with
|
|
256
|
+
its own boards and achievements. A beta no newer than `latest` is refused, and
|
|
257
|
+
publishing `latest` at the beta or past it ends the beta. With
|
|
258
|
+
`@<version>` it builds and uploads nothing, and asks for that version, already
|
|
259
|
+
uploaded. A `publish` after an `upload` of the same build asks for the
|
|
260
|
+
uploaded version, since the upload is that version again.
|
|
261
|
+
|
|
262
|
+
- **A trusted user's or an admin's request** moves the tag at once, whoever
|
|
263
|
+
owns the game, and so does a request for a version already approved: that
|
|
264
|
+
is a rollback (`hopple publish @2`).
|
|
265
|
+
- **Anybody else's waits** for an admin to approve the version, while the tag
|
|
266
|
+
stays where it was. Approving it moves the tag. A game has one request
|
|
267
|
+
waiting per tag: a new one replaces it, and the version it named stays,
|
|
268
|
+
uploaded. You can have at most 5 waiting, across games.
|
|
269
|
+
|
|
270
|
+
It prints whether the tag moved or the request waits for review, and a link
|
|
271
|
+
to the version. `hopple withdraw` takes back a request still waiting.
|
|
272
|
+
|
|
273
|
+
Publishing needs an account. Without `hopple login`, `publish` uploads as
|
|
274
|
+
`upload` does, asking for nothing, and says to sign in, then `hopple publish
|
|
275
|
+
@<version>`; `publish @<version>` uploads nothing, says to sign in and fails.
|
|
276
|
+
`upload` uploads, says it was anonymous, and says to sign in before
|
|
277
|
+
publishing. Sign in before or after: the games uploaded anonymously from this
|
|
278
|
+
machine move into your account.
|
|
279
|
+
|
|
280
|
+
### `hopple versions`, `withdraw`, `untag`, `unpublish`, `rollback`, `listing`
|
|
209
281
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
282
|
+
```bash
|
|
283
|
+
npx hopple versions # every version: its review, its tags, what waits
|
|
284
|
+
npx hopple withdraw # take back the request waiting for latest
|
|
285
|
+
npx hopple withdraw --beta # or for beta
|
|
286
|
+
npx hopple untag beta # end the beta
|
|
287
|
+
npx hopple unpublish # take the game down: no latest, no beta, nothing waiting
|
|
288
|
+
npx hopple rollback # latest back to the approved version before it
|
|
289
|
+
npx hopple listing unlisted # out of the feed and search; listed puts it back
|
|
290
|
+
```
|
|
214
291
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
292
|
+
They work on the game `publish` would upload to, for its owner, its
|
|
293
|
+
collaborators and admins.
|
|
294
|
+
|
|
295
|
+
- `versions` lists every version, newest first: whether it is approved,
|
|
296
|
+
turned down (with the admin's note) or not reviewed, the tags pointing at
|
|
297
|
+
it, the tag it waits for, who uploaded it and when, and its link. It says
|
|
298
|
+
whether the game is listed.
|
|
299
|
+
- `withdraw` closes the request waiting for `latest`, or with `--beta` for
|
|
300
|
+
`beta`. The version stays, and its link still opens it.
|
|
301
|
+
- `untag beta` ends the beta: its players get `latest`.
|
|
302
|
+
- `unpublish` takes the game down: it removes `latest` and `beta` and
|
|
303
|
+
withdraws what waits for review, so nothing brings it back until somebody
|
|
304
|
+
publishes it again. Its versions stay, and their links still open them.
|
|
305
|
+
- `rollback` points `latest` at the newest approved version before the one it
|
|
306
|
+
points at; run again, it goes further back. After an `unpublish` it points
|
|
307
|
+
`latest` back at the version it had. With nothing to go back to, it fails.
|
|
308
|
+
- `listing` says whether the game is listed: in the feed and search while it
|
|
309
|
+
has a `latest`. `listed` or `unlisted` sets it, which only the owner may do.
|
|
310
|
+
An unlisted game keeps its tags, its scores and its links.
|
|
219
311
|
|
|
220
312
|
### `hopple login`, `logout`, `whoami`, `list`
|
|
221
313
|
|
|
@@ -226,19 +318,23 @@ up in your account.
|
|
|
226
318
|
site (or sign in there, any way the site offers), check that the page shows
|
|
227
319
|
the same code, and approve. Nothing is typed in the terminal, and the link
|
|
228
320
|
can be opened on another machine. It is good for ten minutes.
|
|
229
|
-
Anything you
|
|
321
|
+
Anything you uploaded anonymously from this machine moves into your account.
|
|
322
|
+
A sign-in lasts 90 days from when it was last used. Once one ends (expired,
|
|
323
|
+
or gone from the server), commands stop with an error until you run
|
|
324
|
+
`hopple login` again; they do not quietly carry on anonymously.
|
|
230
325
|
- `hopple whoami` shows who you are on that server and how you signed in.
|
|
231
326
|
- `hopple logout` ends the session and forgets it.
|
|
232
|
-
- `hopple list` shows each game you own or collaborate on,
|
|
233
|
-
|
|
234
|
-
link to each.
|
|
327
|
+
- `hopple list` shows each game you own or collaborate on, whether it is
|
|
328
|
+
listed, the versions its tags point at, those waiting for review, its newest
|
|
329
|
+
version, and a link to each.
|
|
235
330
|
|
|
236
331
|
Sessions are stored per server in `~/.config/hopple/sessions.json` (or under
|
|
237
332
|
`$XDG_CONFIG_HOME`, or `$HOPPLE_CONFIG_DIR` if set), readable only by you.
|
|
238
333
|
The file contains your session tokens, so treat it like a password.
|
|
239
334
|
|
|
240
335
|
Every request names the CLI and its version (`User-Agent: hopple-cli/<version>`).
|
|
241
|
-
|
|
336
|
+
A server refuses a CLI older than it accepts, saying to update it. It also
|
|
337
|
+
uses the version to count games published and terminals signed in from
|
|
242
338
|
the CLI, under your Hopple player in our usage analytics. Nothing else is
|
|
243
339
|
collected, and nothing is collected on your machine. Set `DO_NOT_TRACK=1` to
|
|
244
340
|
leave your publishes and sign-ins out of those counts.
|
|
@@ -251,14 +347,15 @@ npx hopple collaborators add ada # let ada publish it too
|
|
|
251
347
|
npx hopple collaborators remove ada
|
|
252
348
|
```
|
|
253
349
|
|
|
254
|
-
A collaborator may
|
|
255
|
-
|
|
350
|
+
A collaborator may upload new versions of the game, ask for its tags, withdraw
|
|
351
|
+
its requests and end its beta. Nothing else: listing it, deleting it and
|
|
352
|
+
choosing who publishes it stay with its owner. The game is the one
|
|
256
353
|
`publish` would upload to, `<owner>/<manifest id>`. Only accounts can be added,
|
|
257
354
|
and each is told in their inbox.
|
|
258
355
|
|
|
259
356
|
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.
|
|
261
|
-
|
|
357
|
+
owner's handle. Without it, `publish` makes a game of your own instead. Your
|
|
358
|
+
requests move its tags or wait for review by your own trust, not the owner's.
|
|
262
359
|
|
|
263
360
|
## The dev shell
|
|
264
361
|
|
|
@@ -301,7 +398,7 @@ What each feature does in the shell:
|
|
|
301
398
|
| 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
399
|
| 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
400
|
| 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,
|
|
401
|
+
| 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
402
|
| 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
403
|
| Pause | A button in the corner, shown only when the game says it can pause. |
|
|
307
404
|
|