@hopple/sdk 1.0.0-next.1 → 1.0.0-next.12

package/index.js

@@ -1,4 +1,4 @@
-/*! @hopple/sdk 1.0.0-next.1 | Copyright (c) 2026 The Hopple authors | MIT License */
+/*! @hopple/sdk | Copyright (c) 2026 The Hopple authors | MIT License */
 // The SDK runs from the runtime the page loads as its first script, which
 // defines the global `Hopple`; this forwards each export to it.
 const runtime = globalThis.Hopple;

package/manifest.d.ts

@@ -1,4 +1,4 @@
-//#region ../../../../../../../tmp/hopple-sdk-types-SLrqDf/manifest/src/manifest.d.ts
+//#region ../../../../../../../tmp/hopple-sdk-types-hbSZtA/manifest/src/manifest.d.ts
 /**
  * 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.
@@ -217,6 +217,26 @@ type ScoreBoard = {
   direction: ScoreDirection;
   /** See `ScoreFormat`. Absent means `integer`. */
   format?: ScoreFormat;
+  /**
+   * Which board, of the ones this id has named. Absent is `1`.
+   *
+   * **Raising it starts the board again from nobody.** The runs under the
+   * version before are kept and no longer counted, shown or ranked, so a board
+   * whose scores stopped being comparable — new levels, a new rule — begins
+   * again under the id the game already submits to.
+   *
+   * **Only a change to what a stored score means needs it.** The title changes
+   * freely, and so does the format between `integer` and `decimal`. Once the
+   * board holds scores, turning it around (`direction`) or writing it in
+   * another unit (to or from `duration-ms`) is refused at the same version.
+   * Going back to a version declared before brings its runs back, so it is
+   * held to what that version was.
+   *
+   * @asType integer
+   * @minimum 1
+   * @maximum 1000
+   */
+  version?: number;
 };
 /**
  * The boards this game keeps a score on.
@@ -380,6 +400,28 @@ type Achievement = {
   secret?: boolean;
   /** Present makes this measured rather than flagged. See `AchievementProgress`. */
   progress?: AchievementProgress;
+  /**
+   * Which achievement, of the ones this id has named. Absent is `1`.
+   *
+   * **Raising it starts the achievement again for everybody.** What players
+   * reported and unlocked under the version before is kept and no longer
+   * counted, so it is earned afresh under the id the game already reports to.
+   *
+   * **Only a change to what a stored value means needs it.** The words change
+   * freely — title, detail, icon, secret — and so does the target, and a tier
+   * added after the last one: progress is kept as the number reported, which
+   * stays true when the goal moves, and a player who unlocked it keeps it. At
+   * the same version, a published achievement may not turn from a flag into a
+   * measure or back, turn its direction around, write its value in another
+   * unit (to or from `duration-ms`), or move or drop a tier it already has.
+   * Going back to a version declared before brings back what was earned under
+   * it, so it is held to what that version was.
+   *
+   * @asType integer
+   * @minimum 1
+   * @maximum 1000
+   */
+  version?: number;
 };
 /**
  * The achievements this game keeps for a player.
@@ -445,7 +487,7 @@ type InputDeviceSet = InputDevice[];
  * doubled. A thumbstick is not one of these; see `InputStick`.
  *
  * @group Input
- * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|pointer\.(?:primary|secondary)|mouse\.(?:left|middle|right)|touch\.tap|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))$
+ * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|pointer\.(?:primary|secondary)|mouse\.(?:left|middle|right|wheelup|wheeldown)|touch\.tap|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 is not a binding this SDK knows (a thumbstick is read rather than bound, and Escape is the host's key)
  */
 type InputBinding = string;
@@ -521,7 +563,7 @@ type PlayerBinding = string;
  * mouse button.
  *
  * @group Input
- * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\.(?:left|middle|right))$
+ * @pattern ^(?:key\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\.(?:left|middle|right|wheelup|wheeldown))$
  * @errorMessage must be a key or a mouse button (and Escape is the host's key)
  */
 type KeyboardBinding = string;
@@ -671,6 +713,20 @@ type ControlSlot = {
   as?: InputStick | Record<string, InputBinding>;
   /** `thumbstick` only. See `ControlAxis`. Absent, the stick moves both ways. */
   axis?: ControlAxis;
+  /**
+   * How big this control is next to the layout's others: `1.25` for a jump
+   * button a thumb lands on without looking, `0.8` for one pressed now and then.
+   * Absent, 1.
+   *
+   * A size in the layout rather than in the game's stylesheet, because whether
+   * the layout fits on a small screen is worked out from it before the
+   * controls are drawn. A game's stylesheet changes how they look, never how
+   * much of the screen they answer in.
+   *
+   * @minimum 0.75
+   * @maximum 1.5
+   */
+  scale?: number;
 };
 /**
  * The one direction an on-screen thumbstick moves in: `x` across, `y` up and
@@ -821,6 +877,23 @@ type PreviewsDeclaration = {
    */
   network?: PreviewRevision;
 };
+/**
+ * What kind of game this is, as one word from a list every game shares.
+ *
+ * A closed list, because a client files games under these and has to name each
+ * one in front of a player: left to free text, one kind of game becomes three
+ * spellings of it with a game each. The list only grows, since a published
+ * manifest has to stay valid. Whoever reads one may be older than the game, and
+ * ignores a word it does not know.
+ *
+ * `local-multiplayer` and `online-multiplayer` say how a game is played rather
+ * than what it is, and only count where the manifest bears them out: see
+ * `declaredGenres`.
+ *
+ * @group Manifest
+ * @category Useful
+ */
+type GameGenre = 'racing' | 'shooter' | 'platformer' | 'puzzle' | 'arcade' | 'physics' | 'roguelike' | 'strategy' | 'building' | 'idle' | 'sports' | 'horror' | 'stealth' | 'fighting' | 'casual' | 'simulation' | 'adventure' | 'rhythm' | 'rpg' | 'local-multiplayer' | 'online-multiplayer';
 /**
  * Publishing refuses a key the manifest's API does not know; a host reading a
  * published one ignores it (see `validateManifest`).
@@ -860,8 +933,19 @@ type GameManifest = {
    * @errorMessage must be a handle: lowercase letters, digits and hyphens
    */
   owner?: string;
+  /**
+   * `false` for a game that is never to be uploaded: an example, a test, a
+   * game kept to one machine. `hopple dev` and `hopple check` still run it;
+   * `hopple upload` and `hopple publish` refuse it, and so does a server it
+   * is sent to another way. Absent, it may be published.
+   *
+   * @category Useful
+   */
+  publishable?: boolean;
   /**
    * The game's own version, `MAJOR.MINOR.PATCH`. Ours to read, never to parse for meaning.
+   * People see it beside the build the server numbers each upload with, and
+   * each published version needs one no other published version of the game has.
    *
    * @category Important
    * @pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
@@ -884,6 +968,18 @@ type GameManifest = {
    * @errorMessage must not be blank
    */
   description?: string;
+  /**
+   * What kind of game it is, the main one first. Read by whoever files it in a
+   * catalogue, which never runs it. At most `GENRE_MAX`, not counting
+   * `local-multiplayer` and `online-multiplayer`: a game that is every kind
+   * tells a player nothing. The publisher's claim, taken at its word, except
+   * for those two. See `GameGenre`.
+   *
+   * @category Useful
+   * @minItems 1
+   * @maxItems 5
+   */
+  genres?: GameGenre[];
   /**
    * A picture of the game, shown wherever a link to it is pasted — a chat, a
    * post, a message.

package/manifest.js

@@ -1,4 +1,4 @@
-/*! @hopple/sdk 1.0.0-next.1 | Copyright (c) 2026 The Hopple authors | MIT License */
+/*! @hopple/sdk 1.0.0-next.12 | Copyright (c) 2026 The Hopple authors | MIT License */
 //#region ../manifest/src/manifest.schema.ts
 const GameManifest = {
 	"type": "object",
@@ -16,6 +16,7 @@ const GameManifest = {
 			"maxLength": 64,
 			"errorMessage": "must be a handle: lowercase letters, digits and hyphens"
 		},
+		"publishable": { "type": "boolean" },
 		"version": {
 			"type": "string",
 			"pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
@@ -33,6 +34,12 @@ const GameManifest = {
 			"maxLength": 500,
 			"errorMessage": "must not be blank"
 		},
+		"genres": {
+			"type": "array",
+			"items": { "$ref": "#/definitions/GameGenre" },
+			"minItems": 1,
+			"maxItems": 5
+		},
 		"cover": {
 			"type": "string",
 			"pattern": "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+\\.(?:png|jpe?g|webp)$",
@@ -65,6 +72,32 @@ const ApiVersion = {
 	"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\""
 };
+const GameGenre = {
+	"type": "string",
+	"enum": [
+		"racing",
+		"shooter",
+		"platformer",
+		"puzzle",
+		"arcade",
+		"physics",
+		"roguelike",
+		"strategy",
+		"building",
+		"idle",
+		"sports",
+		"horror",
+		"stealth",
+		"fighting",
+		"casual",
+		"simulation",
+		"adventure",
+		"rhythm",
+		"rpg",
+		"local-multiplayer",
+		"online-multiplayer"
+	]
+};
 const Orientation = {
 	"type": "string",
 	"enum": [
@@ -153,7 +186,12 @@ const ScoreBoard = {
 			"errorMessage": "must not be blank"
 		},
 		"direction": { "$ref": "#/definitions/ScoreDirection" },
-		"format": { "$ref": "#/definitions/ScoreFormat" }
+		"format": { "$ref": "#/definitions/ScoreFormat" },
+		"version": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 1e3
+		}
 	},
 	"required": ["title", "direction"],
 	"additionalProperties": false
@@ -208,7 +246,12 @@ const Achievement = {
 			"errorMessage": "must not be blank"
 		},
 		"secret": { "type": "boolean" },
-		"progress": { "$ref": "#/definitions/AchievementProgress" }
+		"progress": { "$ref": "#/definitions/AchievementProgress" },
+		"version": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 1e3
+		}
 	},
 	"required": ["title"],
 	"additionalProperties": false
@@ -332,7 +375,7 @@ const InputBindings = {
 };
 const InputBinding = {
 	"type": "string",
-	"pattern": "^(?:key\\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|pointer\\.(?:primary|secondary)|mouse\\.(?:left|middle|right)|touch\\.tap|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))$",
+	"pattern": "^(?:key\\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|pointer\\.(?:primary|secondary)|mouse\\.(?:left|middle|right|wheelup|wheeldown)|touch\\.tap|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": "is not a binding this SDK knows (a thumbstick is read rather than bound, and Escape is the host's key)"
 };
 const ControlLayout = {
@@ -372,7 +415,12 @@ const ControlSlot = {
 			"type": "object",
 			"additionalProperties": { "$ref": "#/definitions/InputBinding" }
 		}] },
-		"axis": { "$ref": "#/definitions/ControlAxis" }
+		"axis": { "$ref": "#/definitions/ControlAxis" },
+		"scale": {
+			"type": "number",
+			"minimum": .75,
+			"maximum": 1.5
+		}
 	},
 	"required": ["type"],
 	"additionalProperties": false,
@@ -412,6 +460,7 @@ const InputStick = {
 const definitions = {
 	GameManifest,
 	ApiVersion,
+	GameGenre,
 	Orientation,
 	LayoutDeclaration,
 	InsetMode,
@@ -523,7 +572,7 @@ const definitions = {
 	},
 	KeyboardBinding: {
 		"type": "string",
-		"pattern": "^(?:key\\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\\.(?:left|middle|right))$",
+		"pattern": "^(?:key\\.(?!Escape$)(?=.{1,48}$)[A-Za-z][A-Za-z0-9]*|mouse\\.(?:left|middle|right|wheelup|wheeldown))$",
 		"errorMessage": "must be a key or a mouse button (and Escape is the host's key)"
 	},
 	PlayersDeclaration: {
@@ -573,6 +622,7 @@ const definitions = {
 };
 AchievementProgress.properties.target.maximum;
 GameManifest.required;
+GameGenre.enum;
 /**
 * The zones a layout places controls in, in the order they are drawn.
 *
@@ -750,6 +800,9 @@ function walkObject(node, value, path, fail, lenient) {
 	}
 }
 function checkReferences(manifest, fail) {
+	const genres = manifest.genres ?? [];
+	for (const genre of new Set(genres.filter((one, index) => genres.indexOf(one) !== index))) fail("genres", `names "${genre}" twice`);
+	if (genres.filter((genre) => !MULTIPLAYER_GENRES.includes(genre)).length > 3) fail("genres", `must hold at most 3 genres, beside local-multiplayer and online-multiplayer`);
 	const players = manifest.input?.player;
 	const own = new Set(Object.keys(players?.actions ?? {}));
 	const actions = /* @__PURE__ */ new Set([...Object.keys(manifest.input?.actions ?? {}), ...own]);
@@ -787,6 +840,8 @@ function checkReferences(manifest, fail) {
 		}
 	}
 }
+/** The genres that say how a game is played together rather than what it is. */
+const MULTIPLAYER_GENRES = ["local-multiplayer", "online-multiplayer"];
 /**
 * Whether `a` beats `b` on a board sorted this way. Ties are not improvements.
 *

package/manifest.md

@@ -35,6 +35,7 @@ leave `api` and `previews` out: the CLI fills `api` from the installed
 | `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. |
+| `genres` | optional; see [`genres`](#genres) | What kind of game it is, the main one first. |
 | `orientation` | `portrait`, `landscape` or `any` | The shape the game is designed for. Hosts lay the game out to match. |
 | `audio` | `null`, or an object | Whether the game makes sound, and its volume channels. See [`audio`](#audio). |
 
@@ -54,15 +55,17 @@ same function, so they agree on whether a manifest is valid.
 
 ### 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:
+The `hopple` CLI 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 in a project with `hopple` installed can point at it:
 
 ```json
-{ "$schema": "./node_modules/@hopple/sdk/config.schema.json", "page": "dist/index.html", "manifest": { ... } }
+{ "$schema": "./node_modules/hopple/config.schema.json", "page": "dist/index.html", "manifest": { ... } }
 ```
 
-A TypeScript config gets the same checks from its type, `HoppleConfig`.
+A TypeScript config gets the same checks from its type,
+`import type { HoppleConfig } from 'hopple'`, whose manifest is the type of
+the installed `@hopple/sdk`.
 
 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
@@ -141,6 +144,7 @@ A game without this key can still use `sdk.save`.
 | `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`). |
+| `version` | no | 1 by default. Raising it starts the board again; see [Changing the manifest in a new version](#changing-the-manifest-in-a-new-version). |
 
 `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.
@@ -179,6 +183,9 @@ There are two kinds:
 `secret: true` hides the title and detail from players until it is earned.
 The manifest is public, so this only stops spoilers.
 
+`version` is 1 by default. Raising it starts the achievement again for
+everybody; see [Changing the manifest in a new version](#changing-the-manifest-in-a-new-version).
+
 Limits: 128 achievements, titles up to 40 characters, details up to 120, icons
 up to 8 characters, 8 tiers.
 
@@ -219,7 +226,8 @@ up to 8 characters, 8 tiers.
   `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.
+  still reports both. Any control may have a `scale` from 0.75 to 1.5, its
+  size next to the layout's others (1 when left out).
 
 Binding names:
 
@@ -228,6 +236,7 @@ Binding names:
 | `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`. |
+| `mouse.wheelup`, `mouse.wheeldown` | A step of the mouse wheel: a press and a release for each notch, and for every stretch of a trackpad swipe. |
 | `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). |
@@ -295,6 +304,31 @@ 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.
 
+### genres
+
+```json
+"genres": ["puzzle", "shooter", "online-multiplayer"]
+```
+
+What kind of game this is, the main one first: at least one, and at most 3
+beside the two multiplayer words, none twice. A game with none declared is
+filed by what its title and description say, and most often less well.
+
+The words are `racing`, `shooter`, `platformer`, `puzzle`, `arcade`, `physics`,
+`roguelike`, `strategy`, `building`, `idle`, `sports`, `horror`, `stealth`,
+`fighting`, `casual`, `simulation`, `adventure`, `rhythm` and `rpg`, and two
+that say how it is played together:
+
+- **`local-multiplayer`**: several people on one device. Needs `players.local`
+  above 1.
+- **`online-multiplayer`**: over the network. Needs `previews.network`.
+
+Either of those without what it needs is not refused: the game is published,
+that word is ignored, and `hopple check`, `hopple upload` and `hopple publish`
+warn about it. They warn the other way round too, for a game that declares
+`genres` and leaves out a way of playing together its manifest shows, since it
+then is not listed as one. Clients group the two under one shelf.
+
 ### previews
 
 ```json
@@ -327,17 +361,27 @@ approval and links, and an upload declaring it is refused.
 
 ## 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).
+Every board and every achievement has a `version`, 1 when left out. The
+server refuses a new version of the game whose manifest would change what data
+players already have means, and the way out is always to raise that board's or
+achievement's `version`: it starts again from nobody under the same id, and
+what was stored under the version before is kept but no longer counted.
+
+- **Boards and achievements can be added and dropped freely.** What players
+  stored under one that is dropped is kept, and comes back if it is declared
+  again.
+- **A board's title can change, and so can its format between `integer` and
+  `decimal`.** Once it has scores, flipping its `direction` or moving its
+  format to or from `duration-ms` needs a new `version`.
+- **An achievement's title, detail, icon and secret flag can change, and so can
+  its target; tiers can be added after the last one.** Progress is kept as the
+  number reported, so a player at 12 of 12 is at 12 of 25 when the target is
+  raised, and keeps the unlock; when it is lowered past them, they have it.
+  Turning a flag into a measured achievement or back, flipping `direction`,
+  moving its format to or from `duration-ms`, or moving or dropping a tier it
+  already has needs a new `version`, whether or not anybody holds it yet.
+- **A version declared again is held to what it was**, since what was stored
+  under it comes back.
 
 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,9 +1,13 @@
 {
   "name": "@hopple/sdk",
-  "version": "1.0.0-next.1",
+  "version": "1.0.0-next.12",
   "description": "The Hopple SDK: what a game imports to talk to the host that runs it, forwarded to the runtime its page loads.",
   "license": "MIT",
   "homepage": "https://hopple.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pamarit/hopple.git"
+  },
   "keywords": [
     "hopple",
     "game",
@@ -25,7 +29,6 @@
       "types": "./manifest.d.ts",
       "default": "./manifest.js"
     },
-    "./config.schema.json": "./config.schema.json",
     "./package.json": "./package.json"
   },
   "main": "./index.js",