@hopple/sdk 0.0.0-stage → 0.1.0-rc.2

package/manifest.md

@@ -0,0 +1,281 @@
+# The game manifest
+
+Every game has a manifest. It says what the game is and declares anything a
+host needs to know **before** the game runs: its score boards, achievements,
+analytics events, input actions, audio channels and so on.
+
+The manifest is written in the game's project, as the `manifest` in its hopple
+config (see [the CLI](https://docs.hopple.app/cli.md#the-projects-config)), and uploaded
+beside the game's HTML file as `game.manifest.json`.
+
+The host reads the manifest itself. The game never sends it over the bridge,
+and the host never asks the game what it is allowed to do.
+
+## A minimal manifest
+
+```json
+{
+  "schema": 1,
+  "id": "ping",
+  "version": "1.0.0",
+  "title": "Ping",
+  "orientation": "portrait",
+  "sdk": "^0.1.0",
+  "audio": null
+}
+```
+
+These seven keys are required. Everything else is optional.
+
+| Key | Rules | Meaning |
+|---|---|---|
+| `schema` | `1` | The manifest format version. |
+| `id` | lowercase letters, digits and single hyphens; at most 64 characters | The game's name. On the server, a game is `<owner>/<id>`. |
+| `version` | `MAJOR.MINOR.PATCH`, optional `-prerelease` | The game's own version. Shown to the game as `sdk.info.game.version`. |
+| `title` | at most 60 characters | What players see. |
+| `description` | optional; at most 500 characters | A sentence or two shown beside the title. |
+| `orientation` | `portrait`, `landscape` or `any` | The shape the game is designed for. Hosts lay the game out to match. |
+| `sdk` | a version, optionally with `^` or `~` | The SDK the game was built against. Recorded, not enforced; the protocol handshake is what checks compatibility. |
+| `audio` | `null`, or an object | Whether the game makes sound, and its volume channels. See [`audio`](#audio). |
+
+## Validating
+
+`hopple check` validates the manifest and names every problem with its field.
+The CLI, the dev shell, the server and the clients all use the same function,
+so they always agree on whether a manifest is valid.
+
+- **Unknown keys are allowed.** A game built with a newer SDK may declare
+  things an older host doesn't know about, and must still run there.
+- **Known keys are checked strictly.** A misspelt value (such as
+  `"draw_under"`) is an error, not silently ignored.
+
+### In an editor
+
+`@hopple/sdk` ships the hopple config's JSON Schema, the manifest's included,
+as `config.schema.json`, for completion, hover docs and errors as you type. A
+JSON config can point at it:
+
+```json
+{ "$schema": "./node_modules/@hopple/sdk/config.schema.json", "page": "dist/index.html", "manifest": { ... } }
+```
+
+A TypeScript config gets the same checks from its type, `HoppleConfig`.
+
+A few rules relate one part of a manifest to another, which JSON Schema can't
+express: buttons must name declared actions, a control's `as` must name its
+own buttons, and tiers must be in order and short of the target. An editor
+won't flag them, but `hopple check` will.
+
+**Tip:** write the config in TypeScript, as `hopple create` sets up. Then a
+mistake in the manifest is a type error, and your code and manifest can share
+constants.
+
+## Optional keys
+
+Each SDK feature that needs the host to know something in advance has its own
+top-level key. The sections below show each one; see
+[the SDK's guide](https://docs.hopple.app/sdk.md) for how to use the feature from code.
+
+### layout
+
+```json
+"layout": { "insets": "draw-under" }
+```
+
+| `insets` | Meaning |
+|---|---|
+| `reserve` (default) | The host shrinks the game's frame so none of the host's own buttons, or the device's notch, cover it. |
+| `draw-under` | The frame fills the whole screen. The game reads `sdk.layout` and keeps its own important content clear of what covers it. |
+
+This has to be in the manifest because the host sizes the frame before the
+game has started.
+
+### analytics
+
+```json
+"analytics": {
+  "events": {
+    "level.complete": { "level": "number", "seconds": "number" },
+    "shop.open": {}
+  }
+}
+```
+
+Declares every event name the game may send, and the type of each property:
+`string`, `number` or `boolean`.
+
+- An event whose name isn't declared is refused (and the game is told).
+- A property of the wrong type is dropped; the event is kept.
+- Every property is optional.
+- Names use lowercase letters, digits, `.`, `_` and `-`. Names starting with
+  `hopple.` are reserved for the host's own records.
+- Limits: 64 events, 8 properties per event, names up to 48 characters,
+  property names up to 24.
+
+### save
+
+```json
+"save": { "bytes": 2048 }
+```
+
+Says the game keeps a save and roughly how big it will be (at most 1 MiB).
+Hosts that load saves from a server use this to know which games to prefetch.
+A game without this key can still use `sdk.save`.
+
+### score
+
+```json
+"score": {
+  "boards": {
+    "points": { "title": "High score", "direction": "desc" },
+    "speed":  { "title": "Best time",  "direction": "asc", "format": "duration-ms" }
+  }
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `title` | yes | What players see. At most 40 characters. |
+| `direction` | yes | `desc`: higher is better. `asc`: lower is better (times, strokes). |
+| `format` | no | `integer` (default), `decimal`, or `duration-ms` (so `224310` shows as `3:44.31`). |
+
+`boards` is a map even for one board, so a game can add a second one later
+without changing the meaning of the first. At most 16 boards.
+
+### achievements
+
+```json
+"achievements": {
+  "list": {
+    "first-ping": { "title": "Hello there", "detail": "Press unlock, once", "icon": "👋" },
+    "centurion": {
+      "title": "Centurion",
+      "progress": {
+        "target": 100,
+        "tiers": [{ "at": 10, "title": "Bronze" }, { "at": 50, "title": "Silver" }]
+      }
+    },
+    "speedrun": {
+      "title": "Under two minutes",
+      "progress": { "target": 120000, "direction": "asc", "format": "duration-ms" }
+    },
+    "the-ending": { "title": "You found it", "secret": true }
+  }
+}
+```
+
+There are two kinds:
+
+- **Flags** (no `progress`): earned once, by `sdk.achievements.unlock(id)`.
+- **Measured** (with `progress`): the game reports a value and the achievement
+  is earned when it reaches `target`. `direction` is `desc` (more is better,
+  the default) or `asc` (less is better). `format` works as for score boards.
+  `tiers` are named milestones on the way to the target; they are labels, not
+  separate achievements.
+
+`secret: true` hides the title and detail from players until it is earned.
+The manifest is public, so this only stops spoilers.
+
+Limits: 128 achievements, titles up to 40 characters, details up to 120, icons
+up to 8 characters, 8 tiers.
+
+### input
+
+```json
+"input": {
+  "supported": [["touch"], ["gamepad"], ["keyboard", "mouse"]],
+  "actions": {
+    "shoot":   { "bind": ["key.KeyZ", "pad.south"], "title": "Shoot", "label": "A" },
+    "special": { "bind": ["key.KeyC"], "title": "Special", "label": "C" },
+    "pause":   { "bind": ["key.KeyP", "pad.start"], "title": "Pause" }
+  },
+  "controls": {
+    "play": {
+      "left":  { "move": { "type": "thumbstick", "as": "pad.left.stick" } },
+      "right": { "acts": { "type": "buttons", "shape": "column", "buttons": ["shoot", "special"] } }
+    }
+  }
+}
+```
+
+- **`supported`**: which input devices the game can be played with. Each entry
+  is one set of devices that together are enough. The example means: touch
+  alone, or a gamepad alone, or keyboard and mouse together. Devices are
+  `keyboard`, `mouse`, `touch` and `gamepad`. This is the author's claim and
+  is not checked against the bindings (a game may read input directly). A
+  host can use it, through `playableWith`, to decide whether to offer a game
+  to a player at all.
+- **`actions`**: named buttons the game reacts to, and their default bindings.
+  `title` is shown on the host's key-binding screen; `label` is printed on the
+  on-screen button, and is what `sdk.input.mapping` calls the action on a touch
+  screen. Both are optional; `bind` is not.
+- **`controls`**: named layouts of on-screen controls for touch screens. Each
+  layout places controls in zones (`left`, `right`, `full`). A control is
+  either a `thumbstick` (with `as` naming which stick it acts as, and an
+  optional `axis` of `x` or `y` holding it to one direction) or a set of
+  `buttons` (naming actions) arranged as a `row`, `column`, `diamond` or
+  `cluster`. An unknown shape is drawn as a column. A stick held to an axis is
+  drawn as a track and always reads 0 on the other axis; a real pad's stick
+  still reports both.
+
+Binding names:
+
+| Binding | Means |
+|---|---|
+| `key.KeyZ` | A physical key, by `KeyboardEvent.code`. `KeyA` is the same physical key on every keyboard layout. |
+| `pointer.primary` | A left click or a tap. (`pointer.secondary`: a right click.) |
+| `mouse.left` | A left click only, not a tap. Also `mouse.middle`, `mouse.right`. |
+| `touch.tap` | A tap only, not a click. |
+| `pad.south` | The bottom face button of either cluster, on any gamepad or on-screen pad. |
+| `pad.right.south` | The bottom right face button (A on Xbox, cross on PlayStation). |
+| `pad.left.south` | D-pad down. |
+| `pad.left.bumper`, `pad.right.trigger` | Shoulder buttons. |
+| `pad.start`, `pad.select` | The menu buttons. |
+| `pad.left.stick` | The left thumbstick. Sticks are read with `sdk.input.onStick`, not bound to actions. |
+| `controls.<name>` | An on-screen control with no physical equivalent. |
+
+Positions use compass words (`north`, `south`, `east`, `west`) and clusters are
+`left` and `right`, because controller brands disagree about which button is
+"A". `Escape` can't be bound: hosts use it to leave fullscreen and pointer
+lock. The controller's home button can't either, and holding `pad.start` opens
+the host's sheet; a tap of Start is still the game's.
+
+Limits: 64 actions, 8 bindings per action, 8 control layouts.
+
+### audio
+
+```json
+"audio": {
+  "channels": {
+    "music":   { "title": "Music" },
+    "effects": { "title": "Effects" }
+  }
+}
+```
+
+`audio` is required. Set it to `null` for a game that makes no sound, and to an
+object for one that does. `channels` is optional and may be empty: a game with
+sound but no channels (`"audio": {}`) gets a mute button and a master volume,
+and must still respect them.
+
+Each channel gets its own labelled volume slider in the host's sound controls.
+`title` is required: it is the slider's label. `master` is reserved, since
+every host already has a master volume. At most 8 channels.
+
+## Changing the manifest in a new version
+
+The server refuses a new version whose manifest would corrupt data players
+already have:
+
+- **A score board that has scores can't be removed or change direction.**
+  Removing it would orphan the scores (and renaming a board looks like removing
+  it); flipping `direction` would turn the whole board upside down. An admin
+  can clear the board first if that is really what you want.
+- **A published achievement can't be changed.** Its title, detail, icon, secret
+  flag, kind, target, direction, format and tiers are fixed, because players already
+  hold it. You can add new achievements, and you can stop declaring old ones
+  (what players earned is kept).
+
+Input action ids and audio channel ids may change freely. A player's remapped
+keys or volume settings for an id that no longer exists are simply dropped.
+

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@hopple/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.2",
+  "description": "The Hopple SDK: what a game imports to talk to the host that runs it.",
+  "license": "MIT",
+  "homepage": "https://hopple.app",
+  "keywords": [
+    "hopple",
+    "game",
+    "games",
+    "sdk",
+    "html5"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./hopple-sdk.min.js": "./hopple-sdk.min.js",
+    "./config.schema.json": "./config.schema.json",
+    "./package.json": "./package.json"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "unpkg": "./hopple-sdk.min.js",
+  "jsdelivr": "./hopple-sdk.min.js"
+}