@hopple/sdk 1.0.0-next.4 → 1.0.0-next.5

package/manifest.js

@@ -1,4 +1,4 @@
-/*! @hopple/sdk 1.0.0-next.4 | Copyright (c) 2026 The Hopple authors | MIT License */
+/*! @hopple/sdk 1.0.0-next.5 | Copyright (c) 2026 The Hopple authors | MIT License */
 //#region ../manifest/src/manifest.schema.ts
 const GameManifest = {
 	"type": "object",
@@ -186,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
@@ -241,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

package/manifest.md

@@ -55,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
@@ -142,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.
@@ -180,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.
 
@@ -354,17 +360,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,6 +1,6 @@
 {
   "name": "@hopple/sdk",
-  "version": "1.0.0-next.4",
+  "version": "1.0.0-next.5",
   "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",
@@ -29,7 +29,6 @@
       "types": "./manifest.d.ts",
       "default": "./manifest.js"
     },
-    "./config.schema.json": "./config.schema.json",
     "./package.json": "./package.json"
   },
   "main": "./index.js",