@hopple/sdk 0.1.0-rc.2 → 1.0.0-next.1

package/config.schema.json

@@ -21,13 +21,13 @@
         },
         "page": {
           "type": "string",
-          "description": "The built page, relative to the config: the one file that is published, so it has to hold the whole game.",
-          "markdownDescription": "The built page, relative to the config: the one file that is published,\nso it has to hold the whole game.",
+          "description": "The built page, relative to the config. The directory it is in is published, with the page as its `index.html`; a page beside its config is published alone, so it has to hold the whole game.",
+          "markdownDescription": "The built page, relative to the config. The directory it is in is\npublished, with the page as its `index.html`; a page beside its config is\npublished alone, so it has to hold the whole game.",
           "pattern": "\\.[Hh][Tt][Mm][Ll]?$",
           "errorMessage": "must be the built .html file, like \"dist/index.html\""
         },
         "manifest": {
-          "$ref": "#/definitions/GameManifest",
+          "$ref": "#/definitions/ProjectManifest",
           "description": "What the game is. Uploaded beside the page, and read by every host before the game runs.",
           "markdownDescription": "What the game is. Uploaded beside the page, and read by every host before the game runs."
         }
@@ -37,15 +37,15 @@
         "manifest"
       ],
       "additionalProperties": false,
-      "description": "A game project's hopple config: `hopple.config.ts`, `hopple.config.js` or `hopple.config.json`, beside the project's `package.json`.\n\nEverything the `hopple` command line needs to know about a project, in one place: how to build the game, which built file is the game, and the manifest that says what the game is. Only the manifest leaves the machine, uploaded beside the page as `game.manifest.json`. A TypeScript or JavaScript config default-exports one of these; a JSON config is one.\n\n```ts import type { HoppleConfig } from '@hopple/sdk';\n\nexport default {   build: 'npm run build',   page: 'dist/index.html',   manifest: { schema: 1, id: 'my-game', version: '0.1.0', title: 'My Game', orientation: 'portrait', sdk: '^0.1.0', audio: null }, } satisfies HoppleConfig; ```",
-      "markdownDescription": "A game project's hopple config: `hopple.config.ts`, `hopple.config.js` or\n`hopple.config.json`, beside the project's `package.json`.\n\nEverything the `hopple` command line needs to know about a project, in one\nplace: how to build the game, which built file is the game, and the manifest\nthat says what the game is. Only the manifest leaves the machine, uploaded\nbeside the page as `game.manifest.json`. A TypeScript or JavaScript config\ndefault-exports one of these; a JSON config is one.\n\n```ts\nimport type { HoppleConfig } from '@hopple/sdk';\n\nexport default {\n  build: 'npm run build',\n  page: 'dist/index.html',\n  manifest: { schema: 1, id: 'my-game', version: '0.1.0', title: 'My Game', orientation: 'portrait', sdk: '^0.1.0', audio: null },\n} satisfies HoppleConfig;\n```"
+      "description": "A game project's hopple config: `hopple.config.ts`, `hopple.config.js` or `hopple.config.json`, beside the project's `package.json`.\n\nEverything the `hopple` command line needs to know about a project, in one place: how to build the game, which built file is the game, and the manifest that says what the game is. Only the manifest leaves the machine, uploaded beside the page as `game.manifest.json`. A TypeScript or JavaScript config default-exports one of these; a JSON config is one.\n\n```ts import type { HoppleConfig } from '@hopple/sdk';\n\nexport default {   build: 'npm run build',   page: 'dist/index.html',   manifest: { id: 'my-game', version: '0.1.0', title: 'My Game', orientation: 'portrait', audio: null }, } satisfies HoppleConfig; ```",
+      "markdownDescription": "A game project's hopple config: `hopple.config.ts`, `hopple.config.js` or\n`hopple.config.json`, beside the project's `package.json`.\n\nEverything the `hopple` command line needs to know about a project, in one\nplace: how to build the game, which built file is the game, and the manifest\nthat says what the game is. Only the manifest leaves the machine, uploaded\nbeside the page as `game.manifest.json`. A TypeScript or JavaScript config\ndefault-exports one of these; a JSON config is one.\n\n```ts\nimport type { HoppleConfig } from '@hopple/sdk';\n\nexport default {\n  build: 'npm run build',\n  page: 'dist/index.html',\n  manifest: { id: 'my-game', version: '0.1.0', title: 'My Game', orientation: 'portrait', audio: null },\n} satisfies HoppleConfig;\n```"
     },
-    "GameManifest": {
+    "ProjectManifest": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
-        "schema": {
-          "type": "number",
-          "const": 1
+        "api": {
+          "$ref": "#/definitions/ApiVersion"
         },
         "id": {
           "type": "string",
@@ -95,13 +95,6 @@
         "orientation": {
           "$ref": "#/definitions/Orientation"
         },
-        "sdk": {
-          "type": "string",
-          "description": "The `@hopple/sdk` version the game was built against, optionally prefixed with `^` or `~`.\n\nRecorded rather than enforced: what the host and the game actually have to agree on is the protocol version, which the handshake settles. This is for diagnostics — \"every game that broke was built against 2.3\" is a question worth being able to ask. Deliberately far narrower than everything npm accepts: a grammar we can read in one line is a grammar three packages can agree on.",
-          "markdownDescription": "The `@hopple/sdk` version the game was built against, optionally prefixed\nwith `^` or `~`.\n\nRecorded rather than enforced: what the host and the game actually have to\nagree on is the protocol version, which the handshake settles. This is for\ndiagnostics — \"every game that broke was built against 2.3\" is a question\nworth being able to ask. Deliberately far narrower than everything npm\naccepts: a grammar we can read in one line is a grammar three packages can\nagree on.",
-          "pattern": "^[\\^~]?\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
-          "errorMessage": "must be a version like 1.0.0, ^1.0.0 or ~1.0.0"
-        },
         "layout": {
           "$ref": "#/definitions/LayoutDeclaration",
           "description": "How the game wants the host's furniture handled. See `InsetMode`.",
@@ -132,6 +125,11 @@
           "description": "How this game is played, and what it draws to be played with. See `InputDeclaration`.",
           "markdownDescription": "How this game is played, and what it draws to be played with. See `InputDeclaration`."
         },
+        "players": {
+          "$ref": "#/definitions/PlayersDeclaration",
+          "description": "How many play on one device. See `PlayersDeclaration`.",
+          "markdownDescription": "How many play on one device. See `PlayersDeclaration`."
+        },
         "audio": {
           "anyOf": [
             {
@@ -143,20 +141,29 @@
           ],
           "description": "What this game makes noise with, one channel at a time, or `null` for a game that makes none. See `AudioDeclaration`.",
           "markdownDescription": "What this game makes noise with, one channel at a time, or `null` for a\ngame that makes none. See `AudioDeclaration`."
+        },
+        "previews": {
+          "$ref": "#/definitions/PreviewsDeclaration",
+          "description": "The previews this game is written against, each at its revision. See `PreviewsDeclaration`.",
+          "markdownDescription": "The previews this game is written against, each at its revision. See\n`PreviewsDeclaration`."
         }
       },
       "required": [
-        "schema",
+        "audio",
         "id",
-        "version",
-        "title",
         "orientation",
-        "sdk",
-        "audio"
+        "title",
+        "version"
       ],
-      "additionalProperties": {},
-      "description": "The index signature is the additive-only rule applied to this file: a game built against a newer SDK declares keys an older host has never heard of, and must still run there. It costs a typo in a manifest literal going unnoticed by the compiler, which the validator catches instead.",
-      "markdownDescription": "The index signature is the additive-only rule applied to this file: a game\nbuilt against a newer SDK declares keys an older host has never heard of, and\nmust still run there. It costs a typo in a manifest literal going unnoticed\nby the compiler, which the validator catches instead."
+      "description": "The manifest as a project's config holds it: `api` may be left out, for the CLI to fill from the installed `@hopple/sdk`.",
+      "markdownDescription": "The manifest as a project's config holds it: `api` may be left out, for the\nCLI to fill from the installed `@hopple/sdk`."
+    },
+    "ApiVersion": {
+      "type": "string",
+      "description": "The API a game is written against: `M.m`, a major and the least minor it needs, or `next`, the pre-releases of the next stable release.",
+      "markdownDescription": "The API a game is written against: `M.m`, a major and the least minor it\nneeds, or `next`, the pre-releases of the next stable release.",
+      "pattern": "^(?:(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)|next)$",
+      "errorMessage": "must be the API the game is written against, like \"1.0\", or \"next\""
     },
     "Orientation": {
       "type": "string",
@@ -178,7 +185,7 @@
       "required": [
         "insets"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "What a game declares about layout. Absent means every default.",
       "markdownDescription": "What a game declares about layout. Absent means every default."
     },
@@ -215,7 +222,7 @@
       "required": [
         "events"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "The custom events a game sends, and what each one carries.\n\n**The first key here whose reader is not the host.** `layout.insets` is declared because a frame has to be sized before there is a game to ask; nothing about analytics has to be answered before the bundle runs. What earns this its place is cardinality: names and columns invented at runtime make a pipe nobody can build a table for, and the party that has to build that table — the publish CLI, the server, a creator dashboard — is exactly the party that already reads the manifest and never talks to a game.\n\n**Every prop is optional and nothing is required**, which is what keeps the declaration cheap enough to be worth asking for: forgetting one costs a column rather than the event. The additive rule carries over unchanged — add events, add props, never retype one — and that is the whole of what a per-event table needs to survive the game's next version.",
       "markdownDescription": "The custom events a game sends, and what each one carries.\n\n**The first key here whose reader is not the host.** `layout.insets` is\ndeclared because a frame has to be sized before there is a game to ask;\nnothing about analytics has to be answered before the bundle runs. What earns\nthis its place is cardinality: names and columns invented at runtime make a\npipe nobody can build a table for, and the party that has to build that table\n— the publish CLI, the server, a creator dashboard — is exactly the party that\nalready reads the manifest and never talks to a game.\n\n**Every prop is optional and nothing is required**, which is what keeps the\ndeclaration cheap enough to be worth asking for: forgetting one costs a column\nrather than the event. The additive rule carries over unchanged — add events,\nadd props, never retype one — and that is the whole of what a per-event table\nneeds to survive the game's next version."
     },
@@ -257,7 +264,7 @@
       "required": [
         "bytes"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "What a game expects to keep, in bytes.\n\n**The manifest's own test is whether the host must know before the bundle runs**, and here it must: a host that prefetches a save from a server has to know which games have one before there is a game to ask, and a publish pipeline that provisions storage has to know before a player exists.\n\nThe budget the game expects, not a grant. A host answers with its own cap at the handshake, and a game with no key here may still call the API — it just gets nothing prefetched, which is the honest reading of not having said so.",
       "markdownDescription": "What a game expects to keep, in bytes.\n\n**The manifest's own test is whether the host must know before the bundle\nruns**, and here it must: a host that prefetches a save from a server has to\nknow which games have one before there is a game to ask, and a publish\npipeline that provisions storage has to know before a player exists.\n\nThe budget the game expects, not a grant. A host answers with its own cap at\nthe handshake, and a game with no key here may still call the API — it just\ngets nothing prefetched, which is the honest reading of not having said so."
     },
@@ -283,7 +290,7 @@
       "required": [
         "boards"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "The boards this game keeps a score on.\n\n**A map from the first version, even for a game that wants one board.** The board id travels in `score.submit`, which is frozen game-side code, and a single-board key would have to *change meaning* to grow a second one — the one thing the additive rule forbids. A map costs a game with one board the few characters of naming it, and costs a game with four nothing at all.\n\n**Read by the host and by the server**, which is what earns it a key rather than a runtime call: a client draws a game's board in a sheet over a feed without ever having run that game, and the server has to know how a board sorts before it can answer a query about one.",
       "markdownDescription": "The boards this game keeps a score on.\n\n**A map from the first version, even for a game that wants one board.** The\nboard id travels in `score.submit`, which is frozen game-side code, and a\nsingle-board key would have to *change meaning* to grow a second one — the\none thing the additive rule forbids. A map costs a game with one board the\nfew characters of naming it, and costs a game with four nothing at all.\n\n**Read by the host and by the server**, which is what earns it a key rather\nthan a runtime call: a client draws a game's board in a sheet over a feed\nwithout ever having run that game, and the server has to know how a board\nsorts before it can answer a query about one."
     },
@@ -311,7 +318,7 @@
         "title",
         "direction"
       ],
-      "additionalProperties": {}
+      "additionalProperties": false
     },
     "ScoreDirection": {
       "type": "string",
@@ -354,7 +361,7 @@
       "required": [
         "list"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "The achievements this game keeps for a player.\n\n**A map, for the reason `score.boards` is one**: the id travels in `achievement.unlock`, which is frozen game-side code, so the shape has to hold a second entry without anything changing meaning.\n\n**Read by the host, by the client and by the server, and by none of them from the game.** The site draws this panel for a game sitting in the feed that has never been run; the server refuses an id no publisher declared. That is what earns a manifest key rather than a runtime call — the same test `score` passed.",
       "markdownDescription": "The achievements this game keeps for a player.\n\n**A map, for the reason `score.boards` is one**: the id travels in\n`achievement.unlock`, which is frozen game-side code, so the shape has to\nhold a second entry without anything changing meaning.\n\n**Read by the host, by the client and by the server, and by none of them from\nthe game.** The site draws this panel for a game sitting in the feed that has\nnever been run; the server refuses an id no publisher declared. That is what\nearns a manifest key rather than a runtime call — the same test `score`\npassed."
     },
@@ -399,7 +406,7 @@
       "required": [
         "title"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "One thing a player can be shown to have done.\n\n**Two kinds, told apart by one key.** Without `progress` this is a flag: it happens once, and saying so twice is the same fact twice. With `progress` it is measured — a count, a distance, a best time — reported as the game goes and unlocked when the value reaches the target.\n\n**`secret` withholds the words, never the row.** A secret achievement is listed while it is locked, so a player can see there is one left, with its title and detail held back until it is theirs. Hiding the row itself would make the list's length change under the player, which reads as a bug rather than as a surprise. It is a courtesy of the panel and not a secret kept from the machine: the manifest ships beside the bundle and is public, so anybody who wants the words already has them.",
       "markdownDescription": "One thing a player can be shown to have done.\n\n**Two kinds, told apart by one key.** Without `progress` this is a flag: it\nhappens once, and saying so twice is the same fact twice. With `progress` it\nis measured — a count, a distance, a best time — reported as the game goes\nand unlocked when the value reaches the target.\n\n**`secret` withholds the words, never the row.** A secret achievement is\nlisted while it is locked, so a player can see there is one left, with its\ntitle and detail held back until it is theirs. Hiding the row itself would\nmake the list's length change under the player, which reads as a bug rather\nthan as a surprise. It is a courtesy of the panel and not a secret kept from\nthe machine: the manifest ships beside the bundle and is public, so anybody\nwho wants the words already has them."
     },
@@ -436,7 +443,7 @@
       "required": [
         "target"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "What makes an achievement measured rather than flagged.\n\n**`direction` is the one thing that cannot be guessed**, exactly as it cannot be guessed for a board. `desc` — the default, and what most achievements are — counts up to the target: *break 100 blocks*. `asc` counts down to it:\n*finish under two minutes*, where the value kept is the player's best time and a smaller one beats a larger. A panel that assumed bigger-is-better would draw a stopwatch achievement as though every slow run were progress.\n\n**`format` is how to draw the number**, for the reason a board needs one: whoever renders this has never run the game and cannot ask it what `112400` means.\n\nBoth are `ScoreDirection` and `ScoreFormat` rather than types of their own. \"Which way is better\" and \"how is this number written\" are the same two questions wherever they are asked, and a second spelling of each is two vocabularies to keep in step and one bug when they drift.",
       "markdownDescription": "What makes an achievement measured rather than flagged.\n\n**`direction` is the one thing that cannot be guessed**, exactly as it cannot\nbe guessed for a board. `desc` — the default, and what most achievements are\n— counts up to the target: *break 100 blocks*. `asc` counts down to it:\n*finish under two minutes*, where the value kept is the player's best time\nand a smaller one beats a larger. A panel that assumed bigger-is-better would\ndraw a stopwatch achievement as though every slow run were progress.\n\n**`format` is how to draw the number**, for the reason a board needs one:\nwhoever renders this has never run the game and cannot ask it what `112400`\nmeans.\n\nBoth are `ScoreDirection` and `ScoreFormat` rather than types of their own.\n\"Which way is better\" and \"how is this number written\" are the same two\nquestions wherever they are asked, and a second spelling of each is two\nvocabularies to keep in step and one bug when they drift."
     },
@@ -471,7 +478,7 @@
         "at",
         "title"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "One named step on the way to a measured achievement's target.\n\n**A tier is a label, never a second achievement.** The achievement is unlocked at its `target` and nowhere else; a tier is what a panel calls the player between here and there — *Silver, 50 of 100*. Modelling each tier as its own id would be three rows in every board that draws them and three unlocks a game has to remember to send, where this is one number reported once and read three ways.",
       "markdownDescription": "One named step on the way to a measured achievement's target.\n\n**A tier is a label, never a second achievement.** The achievement is\nunlocked at its `target` and nowhere else; a tier is what a panel calls the\nplayer between here and there — *Silver, 50 of 100*. Modelling each tier as\nits own id would be three rows in every board that draws them and three\nunlocks a game has to remember to send, where this is one number reported\nonce and read three ways."
     },
@@ -515,9 +522,14 @@
             "maxLength": 48,
             "errorMessage": "must be a layout name of lowercase letters, digits, dots, hyphens and underscores"
           }
+        },
+        "player": {
+          "$ref": "#/definitions/PlayerInputDeclaration",
+          "description": "What each local player does, beside `actions`, which are everybody's. See `PlayerInputDeclaration`.",
+          "markdownDescription": "What each local player does, beside `actions`, which are everybody's. See\n`PlayerInputDeclaration`."
         }
       },
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "What a game says about how it is played.\n\n**It passes the manifest's test twice.** The host must know before the bundle runs — whether on-screen controls apply at all, and what a remapping screen offers, are settled before there is a game to ask — and it is read by parties that never run the game: a feed deciding whether to show a keyboard-only game to somebody holding a phone, and a remapping screen opened from outside a run.\n\nAction, control and layout ids follow the grammar the wire does, and a test keeps the two in step.",
       "markdownDescription": "What a game says about how it is played.\n\n**It passes the manifest's test twice.** The host must know before the bundle\nruns — whether on-screen controls apply at all, and what a remapping screen\noffers, are settled before there is a game to ask — and it is read by parties\nthat never run the game: a feed deciding whether to show a keyboard-only game\nto somebody holding a phone, and a remapping screen opened from outside a run.\n\nAction, control and layout ids follow the grammar the wire does, and a test\nkeeps the two in step."
     },
@@ -570,7 +582,7 @@
       "required": [
         "bind"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "One thing a player does, named by the game and bound to whatever produces it.\n\n**An action is a button and never an axis.** A key, a face button on a pad, a pointer button and an on-screen button all press the same action, because from the game's side they are the same event. A thumbstick is not one of those and is read through its own API — folding the two together would put a range on every binding that mostly does not have one, and would leave a game unable to say whether it meant the press or the lean.\n\n**An object rather than a bare list of bindings**, from the first version, because two strings are wanted the moment anybody draws this: a `title` for the remapping screen, which shows actions to a player and cannot show `move.left`, and a `label` for the face of an on-screen button. Growing a list into an object later would change what an action's value *is*, which is the one move the additive rule forbids. Only the object is accepted, even for an action that needs neither string: one way to write an action is one way to read it.",
       "markdownDescription": "One thing a player does, named by the game and bound to whatever produces it.\n\n**An action is a button and never an axis.** A key, a face button on a pad, a\npointer button and an on-screen button all press the same action, because\nfrom the game's side they are the same event. A thumbstick is not one of\nthose and is read through its own API — folding the two together would put a\nrange on every binding that mostly does not have one, and would leave a game\nunable to say whether it meant the press or the lean.\n\n**An object rather than a bare list of bindings**, from the first version,\nbecause two strings are wanted the moment anybody draws this: a `title` for\nthe remapping screen, which shows actions to a player and cannot show\n`move.left`, and a `label` for the face of an on-screen button. Growing a\nlist into an object later would change what an action's value *is*, which is\nthe one move the additive rule forbids. Only the object is accepted, even for\nan action that needs neither string: one way to write an action is one way to\nread it."
     },
@@ -604,9 +616,9 @@
           "$ref": "#/definitions/ControlZoneSlots"
         }
       },
-      "additionalProperties": {},
-      "description": "One named arrangement of on-screen controls.\n\nA game may declare several and switch between them — a menu wants different controls from play, and a driving section different ones again — which is why they are named rather than there being one. A zone nobody knows is a layout from a newer SDK, which the additive rule says must still load, so whoever draws it simply has nowhere to put it.",
-      "markdownDescription": "One named arrangement of on-screen controls.\n\nA game may declare several and switch between them — a menu wants different\ncontrols from play, and a driving section different ones again — which is why\nthey are named rather than there being one. A zone nobody knows is a layout\nfrom a newer SDK, which the additive rule says must still load, so whoever\ndraws it simply has nowhere to put it."
+      "additionalProperties": false,
+      "description": "One named arrangement of on-screen controls.\n\nA game may declare several and switch between them — a menu wants different controls from play, and a driving section different ones again — which is why they are named rather than there being one. A zone nobody knows is a layout from a newer minor, which a host reads leniently, so whoever draws it simply has nowhere to put it.",
+      "markdownDescription": "One named arrangement of on-screen controls.\n\nA game may declare several and switch between them — a menu wants different\ncontrols from play, and a driving section different ones again — which is why\nthey are named rather than there being one. A zone nobody knows is a layout\nfrom a newer minor, which a host reads leniently, so whoever draws it simply\nhas nowhere to put it."
     },
     "ControlZoneSlots": {
       "type": "object",
@@ -671,7 +683,7 @@
       "required": [
         "type"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "One on-screen control: a group of buttons, or a thumbstick.\n\n**A button slot names an action; a stick slot names a stick.** The asymmetry is the hardware's. On-screen buttons have no fixed count or position — three across, five down, four in a diamond — so there is no standard control to unify them with, and the action is the only stable name they have. Thumbsticks come in twos and everybody agrees which is which, so a virtual one says which it stands for and a game reads the physical stick and this one through one id.\n\nThere is no d-pad here. A d-pad is four buttons wherever it exists — four entries on the wire from a real pad, four keys on a keyboard — so a layout that wants one declares four buttons and binds them like anything else.",
       "markdownDescription": "One on-screen control: a group of buttons, or a thumbstick.\n\n**A button slot names an action; a stick slot names a stick.** The asymmetry\nis the hardware's. On-screen buttons have no fixed count or position — three\nacross, five down, four in a diamond — so there is no standard control to\nunify them with, and the action is the only stable name they have. Thumbsticks\ncome in twos and everybody agrees which is which, so a virtual one says which\nit stands for and a game reads the physical stick and this one through one id.\n\nThere is no d-pad here. A d-pad is four buttons wherever it exists — four\nentries on the wire from a real pad, four keys on a keyboard — so a layout\nthat wants one declares four buttons and binds them like anything else.",
       "if": {
@@ -736,6 +748,145 @@
       "description": "The one direction an on-screen thumbstick moves in: `x` across, `y` up and down.\n\nFor a game that steers along one line — a runner sliding left and right, a paddle — where a stick that also leans up and down is a thumb wandering off the line it means. The drawn stick becomes a track along that axis and always reports the other one as 0. **Only the drawn stick:** a real pad's stick still reports both, so a game reads the axis it wants from either.\n\nWhoever draws the controls may be older than the game, and draw a stick that moves both ways. The SDK zeroes the other axis whatever the renderer reports, so the game hears one axis either way.",
       "markdownDescription": "The one direction an on-screen thumbstick moves in: `x` across, `y` up and\ndown.\n\nFor a game that steers along one line — a runner sliding left and right, a\npaddle — where a stick that also leans up and down is a thumb wandering off\nthe line it means. The drawn stick becomes a track along that axis and always\nreports the other one as 0. **Only the drawn stick:** a real pad's stick still\nreports both, so a game reads the axis it wants from either.\n\nWhoever draws the controls may be older than the game, and draw a stick that\nmoves both ways. The SDK zeroes the other axis whatever the renderer reports,\nso the game hears one axis either way."
     },
+    "PlayerInputDeclaration": {
+      "type": "object",
+      "properties": {
+        "actions": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/PlayerInputAction"
+          },
+          "description": "The actions each player has, by id: never an id `actions` declares too.",
+          "markdownDescription": "The actions each player has, by id: never an id `actions` declares too.",
+          "maxProperties": 32,
+          "propertyNames": {
+            "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$",
+            "maxLength": 48,
+            "errorMessage": "must be lowercase letters, digits, dots, hyphens and underscores"
+          }
+        },
+        "keyboard": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/KeyboardSet"
+          },
+          "description": "The parts of the keyboard players play with, one player each, in the order they are offered. A player alone hears every one of them. Left out, the keyboard presses no player's action.",
+          "markdownDescription": "The parts of the keyboard players play with, one player each, in the\norder they are offered. A player alone hears every one of them. Left out,\nthe keyboard presses no player's action.",
+          "minItems": 1,
+          "maxItems": 4
+        }
+      },
+      "required": [
+        "actions"
+      ],
+      "additionalProperties": false,
+      "description": "What each local player does, and how they share the keyboard.\n\n**One set of actions for every player.** Each local player has their own copy, pressed by the pad they hold, the part of the keyboard they play with, or the on-screen controls. A pad's buttons are the same for every pad, so any number of pads just works; the keyboard is split into sets, one player each, so the number of sets is how many can share it.",
+      "markdownDescription": "What each local player does, and how they share the keyboard.\n\n**One set of actions for every player.** Each local player has their own\ncopy, pressed by the pad they hold, the part of the keyboard they play with,\nor the on-screen controls. A pad's buttons are the same for every pad, so any\nnumber of pads just works; the keyboard is split into sets, one player each,\nso the number of sets is how many can share it."
+    },
+    "PlayerInputAction": {
+      "type": "object",
+      "properties": {
+        "bind": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PlayerBinding"
+          },
+          "description": "What presses it on a pad, the same for every pad, and on the screen. Leave it out for an action pressed only on the keyboard.",
+          "markdownDescription": "What presses it on a pad, the same for every pad, and on the screen.\nLeave it out for an action pressed only on the keyboard.",
+          "minItems": 1,
+          "maxItems": 8
+        },
+        "title": {
+          "type": "string",
+          "description": "What to call it in front of a player, in a remapping screen.",
+          "markdownDescription": "What to call it in front of a player, in a remapping screen.",
+          "pattern": "\\S",
+          "maxLength": 40,
+          "errorMessage": "must not be blank"
+        },
+        "label": {
+          "type": "string",
+          "description": "What to draw on an on-screen button: a glyph, or a letter.",
+          "markdownDescription": "What to draw on an on-screen button: a glyph, or a letter.",
+          "pattern": "\\S",
+          "maxLength": 8,
+          "errorMessage": "must not be blank"
+        },
+        "join": {
+          "type": "boolean",
+          "description": "Whether pressing it on a pad or a part of the keyboard nobody plays with makes a new player, while the game is taking players. Left out on every action, any of them does.",
+          "markdownDescription": "Whether pressing it on a pad or a part of the keyboard nobody plays with\nmakes a new player, while the game is taking players. Left out on every\naction, any of them does."
+        }
+      },
+      "additionalProperties": false,
+      "description": "One thing each player does: the same action for every local player, pressed by their own pad, their own part of the keyboard, or the on-screen controls.",
+      "markdownDescription": "One thing each player does: the same action for every local player, pressed\nby their own pad, their own part of the keyboard, or the on-screen controls."
+    },
+    "PlayerBinding": {
+      "type": "string",
+      "description": "What presses a player's action on a pad or on the screen: a pad button, or an on-screen control. Keys and mouse buttons are a keyboard set's, in `PlayerInputDeclaration.keyboard`.",
+      "markdownDescription": "What presses a player's action on a pad or on the screen: a pad button, or\nan on-screen control. Keys and mouse buttons are a keyboard set's, in\n`PlayerInputDeclaration.keyboard`.",
+      "pattern": "^(?:controls\\.(?=.{1,48}$)[a-z0-9]+(?:[_-][a-z0-9]+)*|pad\\.(?:north|south|east|west|start|select)|pad\\.(?:left|right)\\.(?:north|south|east|west|bumper|trigger))$",
+      "errorMessage": "must be a pad button or an on-screen control: a player's keys and mouse buttons go in input.player.keyboard"
+    },
+    "KeyboardSet": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "What the players call it: *Left keys*, *Arrows*.",
+          "markdownDescription": "What the players call it: *Left keys*, *Arrows*.",
+          "pattern": "\\S",
+          "maxLength": 40,
+          "errorMessage": "must not be blank"
+        },
+        "bind": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/KeyboardBinding"
+            }
+          },
+          "description": "The keys and mouse buttons of each player action, by its id.",
+          "markdownDescription": "The keys and mouse buttons of each player action, by its id.",
+          "maxProperties": 64,
+          "propertyNames": {
+            "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$",
+            "maxLength": 48,
+            "errorMessage": "must be a player action id"
+          }
+        }
+      },
+      "required": [
+        "bind"
+      ],
+      "additionalProperties": false,
+      "description": "One part of the keyboard one player plays with: the keys and mouse buttons that press each of the player actions there.",
+      "markdownDescription": "One part of the keyboard one player plays with: the keys and mouse buttons\nthat press each of the player actions there."
+    },
+    "KeyboardBinding": {
+      "type": "string",
+      "description": "What presses a player's action on their part of the keyboard: a key, or a mouse button.",
+      "markdownDescription": "What presses a player's action on their part of the keyboard: a key, or a\nmouse button.",
+      "pattern": "^(?:key\\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\\.(?:left|middle|right))$",
+      "errorMessage": "must be a key or a mouse button (and Escape is the host's key)"
+    },
+    "PlayersDeclaration": {
+      "type": "object",
+      "properties": {
+        "local": {
+          "type": "integer",
+          "description": "The most players on one device, each with their own copy of `input.player`'s actions. 1 when left out.",
+          "markdownDescription": "The most players on one device, each with their own copy of\n`input.player`'s actions. 1 when left out.",
+          "minimum": 1,
+          "maximum": 8
+        }
+      },
+      "additionalProperties": false,
+      "description": "How many people play a game on one device.\n\nRead by hosts before the game runs: a listing says *1–4 on one device*, and the input panel offers a row for each player.",
+      "markdownDescription": "How many people play a game on one device.\n\nRead by hosts before the game runs: a listing says *1–4 on one device*, and\nthe input panel offers a row for each player."
+    },
     "AudioDeclaration": {
       "type": "object",
       "properties": {
@@ -757,7 +908,7 @@
           }
         }
       },
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "What this game makes noise with, so a host can offer a fader for each.\n\n**A map from the first version, even for a game with one channel.** The channel id travels in `audio.set`, which is frozen game-side code, and a single-channel key would have to *change meaning* to grow a second one — the one move the additive rule forbids.\n\n**The manifest's test is whether the host must know before the bundle runs**, and here it must twice over. The panel is drawn where the game's title is, which a host draws for games in a feed that nobody has opened; and the opening volumes ride in the handshake, so the host has to know which channels it is stating a volume for before there is a game to ask.\n\n**The key is required, and `null` is how a silent game says so.** Leaving it out would read the same as forgetting it, and a game that makes noise but never said so is one whose player cannot turn it down. An object with no channels is a game with sound and no tracks worth a fader of their own: it gets a master fader and a mute button and no more. What is never optional is obeying what the host then says: see `AudioState`.",
       "markdownDescription": "What this game makes noise with, so a host can offer a fader for each.\n\n**A map from the first version, even for a game with one channel.** The\nchannel id travels in `audio.set`, which is frozen game-side code, and a\nsingle-channel key would have to *change meaning* to grow a second one — the\none move the additive rule forbids.\n\n**The manifest's test is whether the host must know before the bundle runs**,\nand here it must twice over. The panel is drawn where the game's title is,\nwhich a host draws for games in a feed that nobody has opened; and the\nopening volumes ride in the handshake, so the host has to know which channels\nit is stating a volume for before there is a game to ask.\n\n**The key is required, and `null` is how a silent game says so.** Leaving it\nout would read the same as forgetting it, and a game that makes noise but\nnever said so is one whose player cannot turn it down. An object with no\nchannels is a game with sound and no tracks worth a fader of their own: it\ngets a master fader and a mute button and no more. What is never optional is\nobeying what the host then says: see `AudioState`."
     },
@@ -776,9 +927,28 @@
       "required": [
         "title"
       ],
-      "additionalProperties": {},
+      "additionalProperties": false,
       "description": "One thing a game makes noise with, as the player is offered it.\n\nThe title is the whole of it, and required: this exists to be a label on a fader in a host's own panel, and a fader labelled `sfx2` is a control nobody can use. What a channel *is* — a bus, a set of samples, one oscillator — is the game's business and is never described here.",
       "markdownDescription": "One thing a game makes noise with, as the player is offered it.\n\nThe title is the whole of it, and required: this exists to be a label on a\nfader in a host's own panel, and a fader labelled `sfx2` is a control nobody\ncan use. What a channel *is* — a bus, a set of samples, one oscillator — is\nthe game's business and is never described here."
+    },
+    "PreviewsDeclaration": {
+      "type": "object",
+      "properties": {
+        "network": {
+          "$ref": "#/definitions/PreviewRevision",
+          "description": "That this game plays over the network, in matches, at this revision of `@hopple/sdk-preview-network`: `sdk.match`.\n\nThe permission a reviewer grants, and what lets a host offer *Play with friends* before the game has loaded. Nothing else about networking is declared: the way a match is played, and its size, are chosen by the game when it makes one. Absent, a game is never told about a match, and never reaches one.",
+          "markdownDescription": "That this game plays over the network, in matches, at this revision of\n`@hopple/sdk-preview-network`: `sdk.match`.\n\nThe permission a reviewer grants, and what lets a host offer *Play with\nfriends* before the game has loaded. Nothing else about networking is\ndeclared: the way a match is played, and its size, are chosen by the game\nwhen it makes one. Absent, a game is never told about a match, and never\nreaches one."
+        }
+      },
+      "additionalProperties": false,
+      "description": "The previews a game is written against, each at the revision it needs.\n\nA preview is a part of the SDK that is not stable yet: its own `0.x` package, versioned apart from `api`, and served only to the games that declare it, at the revision they declare. A change to a preview reaches the games written against it and nobody else.",
+      "markdownDescription": "The previews a game is written against, each at the revision it needs.\n\nA preview is a part of the SDK that is not stable yet: its own `0.x`\npackage, versioned apart from `api`, and served only to the games that\ndeclare it, at the revision they declare. A change to a preview reaches the\ngames written against it and nobody else."
+    },
+    "PreviewRevision": {
+      "type": "integer",
+      "description": "A preview's revision: a whole number from 1, the `R` of its package's `0.R.p`. A breaking change to the preview is a new revision.",
+      "markdownDescription": "A preview's revision: a whole number from 1, the `R` of its package's\n`0.R.p`. A breaking change to the preview is a new revision.",
+      "minimum": 1
     }
   }
 }