Changelog and versioning policy
How the SDK is versioned, what counts as a breaking change, how long an old major version stays supported, and what changed when. The current values below are generated from the code.
| What | Current value | Where it lives |
|---|---|---|
SDK contract (the v field of every message) | 1 | SDK_VERSION in @gameportal/sdk-types |
| Platform rules | 4 | PLATFORM_RULES_VERSION in @gameportal/sdk-types/platform-rules; every validator report records it |
Manifest sdkVersion | 1 | gameManifestSchema in @gameportal/sdk-types |
Versioning policy #
The SDK has one version that matters to a game: the contract version, the major number in the v field of every message and in the manifest sdkVersion (today 1). A game announces the versions it speaks in hello.sdkVersions; a portal that supports none of them answers with unsupported_version, the bridge goes to the unsupported mode and the portal shows its own error screen.
Additive changes stay inside v1. They never need a change in a game that exists today:
A new optional field in a message the portal sends to the game. Games ignore fields they do not know, and the schemas the bridge validates with are tolerant of them.
A new optional field in
manifest.json.A new message type the game does not have to handle, or a new bridge option with a default.
A new platform rule that is a warning, or a clarification of an existing rule.
Breaking changes need a new major version (v: 2).
Removing or renaming a field, a message type or an error code.
Changing what a field means, or a limit in a way that fails messages that used to pass.
Making an optional manifest field required, or a new manifest requirement for existing games.
A new message a game must answer.
Support window. When a new major version is released, the previous one keeps working for at least 6 months, announced here with a date before it ends. During the window a portal speaks both: the game's hello.sdkVersions decides. This is the programme's proposal and is confirmed with the first external games.
Platform rules have their own version (PLATFORM_RULES_VERSION), raised whenever a rule is added, removed or changes meaning. Reports record the version they ran with. Adding a blocker, removing one or lowering one is decided by the owner, because it changes what live games must satisfy; a new blocker is first run against the live games and the result is written down. Rule ids are never reused.
Packages. The SDK packages are private workspace packages in the GamePortal repository today (version 0.0.0); the contract version is the number that counts. When they are published for external developers (V2) they get semver release numbers, with the contract version in the changelog of each release.
These docs describe SDK v1 and the current platform rules. The tables are generated from the code, and tests fail when they are stale or when a code sample stops compiling.
Changelog #
Newest first. "Additive" means no game needs to change.
| Date | Change | Kind |
|---|---|---|
| 2026-10-19 | P pauses too. Inside the portal the bridge sends pauseRequest for P as well as Esc (P without modifiers, not repeated, not in a text field; isPauseKey is the test). A game that needs P for play opts out with the bridge option pauseOnKeyP: false. | Additive (a new bridge option with a default) |
| 2026-10-19 | Platform rules, version 2 (publishing security, T-27): R-SEC-06 no cryptocurrency mining and R-SEC-07 reviewable, non-obfuscated code (both warnings), WebRTC peer connections and STUN/TURN addresses under R-NET-02. Games from outside developers are served with the target Content-Security-Policy enforced, a Permissions-Policy, and only inside the portal frame; games-host refuses service worker scripts and answers 410 for a taken-down version. | Additive for games that already follow the rules |
| 2026-10-18 | Developer docs (docs/developers, the portal page /developers), generated reference tables, sample type-checks. | Docs |
| 2026-10-18 | Starter and tools. templates/game-starter, pnpm create:game, the dev console with a fake portal, validate and check for every game (@gameportal/game-tools). | Additive |
| 2026-10-18 | Leaderboard eligibility. A score mode gets a public leaderboard only with a finite max and a maxPerSecond of at most 1000; the top-10 badge needs at least 20 players. Scores of other modes still count and drive challenges. | Additive (affects which modes have boards) |
| 2026-10-18 | Platform rules, version 1, and the rules runner (@gameportal/rules): static validators and the fake-portal scenarios. | Additive |
| 2026-10-18 | Score plausibility. Manifest scores.<mode>.integer and max, and challenge.maxPerSecond; the portal clamps a challenge's daily progress to the active play time it measured. | Additive (optional manifest fields) |
| 2026-10-18 | Save format versions. saveVersion in ready, save, init.save and ack.conflict; upgradeSave and upgradeSaveData in the bridge; the outdated save status; an older build can no longer overwrite a save from a newer format; refused saves are kept in the save history for seven days. | Additive in v1 (made before external games) |
| 2026-10-17 | SDK contract v1. hello, init, ready, save, score, event, session, pause, resume, lang, day, ack; the MessageChannel handshake; limits and error codes; @gameportal/sdk-types and @gameportal/game-bridge. | Initial release |
Deprecations #
None. A deprecation is announced here, with the date it ends, at least 6 months before it takes effect.