@indiegems/gem-web-sdk 10.3.1 → 10.4.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.3.1"
+    "version": "10.4.0"
   },
   "entries": [
     {
@@ -8702,7 +8702,7 @@
           "group": "player",
           "signature": "readonly recommended: GemRecommendedSettings | null",
           "documented": true,
-          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, and the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) — or `null` when the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
+          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) and a starting graphics quality — or `null`\nwhen the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8876,6 +8876,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemRecommendedSettings.graphicsQuality",
+          "name": "graphicsQuality",
+          "anchor": "gemrecommendedsettings-graphicsquality",
+          "group": "player",
+          "signature": "readonly graphicsQuality: GemGraphicsQuality",
+          "documented": true,
+          "summary": "The graphics quality to START at on this device: `'low'`, `'medium'` or\n`'high'`. The Arcade picks it per device — the tier it detected, or the\nplayer's own Graphics choice — so a game opens at a quality that suits the\ndevice instead of guessing. A starting point, not a cap: while\n`graphicsQualityAuto` is true your game may adapt from here as it runs,\nand `createQualityGovernor` from `@indiegems/gem-web-sdk/quality` does\nthat for you. When the Arcade did not say, `'low'` with `batterySaver`\non and `'medium'` otherwise.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.graphicsQualityAuto",
+          "name": "graphicsQualityAuto",
+          "anchor": "gemrecommendedsettings-graphicsqualityauto",
+          "group": "player",
+          "signature": "readonly graphicsQualityAuto: boolean",
+          "documented": true,
+          "summary": "Whether the Arcade chose `graphicsQuality` for this device (`true`, the\nplayer left Graphics on Auto) or the player picked it by hand (`false`).\nWhile it is `false`, hold that quality: never step it down or up on your\nown. `true` when the Arcade did not say.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemCohort",
           "name": "GemCohort",
@@ -9949,6 +9981,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.paused",
+          "name": "paused",
+          "anchor": "gem-paused",
+          "group": "start",
+          "signature": "readonly paused: boolean",
+          "documented": true,
+          "summary": "Whether the arcade has your game paused right now: `true` from an\n`onPause(true)` until the `onPause(false)` that follows it, `false` before\nany. The same pause `onPause` tells you about, readable at any moment —\nfor code that was not around when the edge arrived, such as a frame-time\nmonitor deciding whether a slow frame counts.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.cohorts",
           "name": "cohorts",
@@ -12778,6 +12826,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemGraphicsQuality",
+          "name": "GemGraphicsQuality",
+          "anchor": "gemgraphicsquality",
+          "group": "player",
+          "signature": "type GemGraphicsQuality = \"low\" | \"medium\" | \"high\"",
+          "documented": true,
+          "summary": "A graphics quality tier: `'low'`, `'medium'` or `'high'`. What\n`gem.prefs.recommended.graphicsQuality` holds.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ServerTokenGrant",
           "name": "ServerTokenGrant",

package/docs/changelog.md

@@ -16,6 +16,20 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 10.4.0
+
+Upgrading from 10.3.1. Impact: required.
+
+### Rebuild
+
+- The recommended preferences type gained optional graphics quality and automatic fields, and the host method that sends preferences accepts the same two fields. Existing code keeps working; recompile your game against the new types. Host or test-harness code that sends preferences can now also pass the graphics quality tier and the automatic flag.
+
+### New capability
+
+- The recommended settings now carry a graphics quality tier and an automatic flag. The Arcade picks a starting tier per device (low, medium or high) and a game can start from it. An unknown tier is read as medium, a missing tier follows the battery saver setting (low when it is on, otherwise medium), and a missing automatic flag is read as true, so both values are always present in the game. When the automatic flag is false the player picked the tier by hand, and the game should keep it rather than adapt it.
+- The new paused value holds the latest state of the pause signal. Code that starts after the pause signal has already arrived, such as a frame-time monitor created mid-game, can read it to learn whether the game is currently paused.
+- A new optional quality entry point lets a game adapt its graphics level to frame time. It starts at the Arcade's tier mapped onto the game's own levels. It steps down one level after about two seconds of slow frames and up one level after about ten seconds of comfortably fast frames, never going above one level over its start. It ignores paused and hidden time, holds steady when the player chose the tier by hand, and restarts when a new recommendation arrives. It can run on animation frames or be fed frame times manually. A game that does not import it pays nothing in size.
+
 ## 10.3.1
 
 Upgrading from 10.3.0. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "10.3.1"
+  "@indiegems/gem-web-sdk": "10.4.0"
 }
 ```
 

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "25047a1c8498f92990b4d50768cf49d1cd4acd2a27dd42db595ca322aa56a2a9",
-      "updated": "2026-10-11T19:08:27Z"
+      "sha256": "fd69a4c08141e0646d695adedce0d313de2295cfd6bc656433ce33dd02ec731a",
+      "updated": "2026-10-11T19:38:28Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "327be77c7b742f7ecfb3ca8f4869480e72942ea9f7293e25634c47c056a38eae",
-      "updated": "2026-10-11T19:08:27Z"
+      "sha256": "f2c13478823888b777058bbdc4de41216dd8b48d7e7efab3a31334f980d647ec",
+      "updated": "2026-10-11T19:38:28Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "c6bf3689c928b6cb24d86faa380e6ed4bece1f3dd6e8dfc71c1ff9de1ed0dd42",
-      "updated": "2026-10-11T19:08:27Z"
+      "sha256": "04bb5fb5f631a52c7962728a74602ce7eec6ee6a1a3efa6197542ce5aa4cce95",
+      "updated": "2026-10-11T19:38:28Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "c5797bd913fbd8c62fb3fbe83b6c8c6cb22f5aec984c0d56f3f0198c917fee7d",
-      "updated": "2026-10-11T18:48:12Z"
+      "sha256": "ce2abba4b32ee1c0dd69eabaaac1f33e2534ac5b58e9a45c4f8a7b3bd3e11f27",
+      "updated": "2026-10-11T19:25:48Z"
     }
   ]
 }

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.3.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.3.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.4.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v10.4.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -924,12 +924,18 @@ same push as `muted` and `reducedMotion`, and again whenever the player changes
 | `gamepadLookSensitivity` | `20` to `400` | Look speed for a gamepad stick, as a percentage: `100` is 1×.                                                |
 | `invertLookY`    | `true` / `false`      | Up/down look inverted: pushing up or dragging up looks down. Pitch only, never yaw.                          |
 | `touchMovement`  | `'floating'` / `'fixed'` | On a touch screen, a movement stick that appears where the thumb lands, or one fixed in place.            |
+| `graphicsQuality` | `'low'` / `'medium'` / `'high'` | The graphics quality to start at on this device.                                                  |
+| `graphicsQualityAuto` | `true` / `false` | `true`: the Arcade picked that tier for this device, so you may adapt from it. `false`: the player picked it, so hold it. |
 
-The last four are the camera and controls settings: see
+`lookSensitivity` to `touchMovement` are the camera and controls settings: see
 [camera and look controls](#camera-and-look-controls) for telling the Arcade which of them your game
 uses, and for `gem.controls.look()`, which applies the two sensitivities and the invert for you. An
 older Arcade sends `recommended` without them; the SDK then fills each with its default (`100`,
-`100`, `false`, `'floating'`), so whenever `recommended` is not `null` all nine fields are there.
+`100`, `false`, `'floating'`). The last two are the starting graphics quality: see
+[graphics quality](#graphics-quality-the-arcade-picks-the-start-your-game-adapts). An older Arcade
+sends neither; the SDK then fills `graphicsQuality` from `batterySaver` (`'low'` when it is on,
+`'medium'` otherwise) and `graphicsQualityAuto` with `true`, and reads a tier it does not know as
+`'medium'`. So whenever `recommended` is not `null`, all eleven fields are there.
 
 **They are recommendations, and the player's own choice in your game always wins:**
 
@@ -949,6 +955,7 @@ older Arcade sends `recommended` without them; the SDK then fills each with its
 const DEFAULTS = {
   volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true,
   lookSensitivity: 100, gamepadLookSensitivity: 100, invertLookY: false, touchMovement: 'floating',
+  graphicsQuality: 'medium',
 };
 let chosen = {}; // ONLY what the player picked in your settings screen
 
@@ -1067,6 +1074,66 @@ function frame(dt) {
   `touchMovement: 'game'` if your game only has one kind.
 - **No camera, no call.** A game with no camera to turn declares nothing and never calls `look`.
 
+## Graphics quality: the Arcade picks the start, your game adapts
+
+Players open a lot of games they have never played. Each one should open at a quality that suits
+the device instead of guessing and stuttering for the first minute. The work is split three ways:
+
+- **The Arcade picks the starting tier, per device**, and sends it as
+  `gem.prefs.recommended.graphicsQuality`: `'low'`, `'medium'` or `'high'`. On Auto, the player's
+  default, it is the tier the Arcade measured for this browser on this device. Otherwise it is the
+  player's own choice in the Arcade's Settings: Battery saver (`'low'`, and cap your frame rate and
+  cut effects too), Balanced (`'medium'`) or Best looking (`'high'`).
+- **Your game adapts from there while it runs**: one level down when frames stay slow, one level up
+  when there is plenty of room. `createQualityGovernor` does this for you, so you do not write a
+  frame-time monitor of your own.
+- **A choice the player made by hand is held.** `graphicsQualityAuto` is `false` when the player
+  picked the tier, and then you render at exactly that tier and never move it yourself. Your own
+  quality option, if your settings screen has one, still wins over the Arcade's, as every
+  [recommended setting](#start-from-the-players-arcade-wide-defaults-gemprefsrecommended) does.
+
+The governor is a separate import, so a game that does not use it carries none of it:
+
+```js
+import { createQualityGovernor } from '@indiegems/gem-web-sdk/quality';
+
+// Your own levels, lowest first. Names, or a count: `levels: 4` means levels 0 to 3.
+const governor = createQualityGovernor({
+  gem,
+  levels: ['low', 'medium', 'high'],
+  onChange: (level) => applyQuality(level), // shadows, resolution scale, particles…
+});
+applyQuality(governor.level); // where it starts; onChange is not called for that
+```
+
+What it does, so you know what to expect:
+
+- **It starts at the Arcade's tier.** A tier whose name is one of your levels starts there;
+  otherwise `'low'` is your lowest level, `'high'` your highest and `'medium'` your middle one. With
+  no Arcade (`gem.prefs` is `null`, or no `gem`), it starts in the middle.
+- **It measures your frames itself**, with `requestAnimationFrame`. If your loop already knows its
+  frame time, pass `manual: true` and call `governor.frame(dtMs)` once a frame instead; the first
+  `frame` call switches it to your numbers anyway, so frames are never counted twice.
+- **Down fast, up slow.** One level down after about 2 seconds of slow frames (the 90th-percentile
+  frame over 1.25 times your frame budget), one level up after about 10 seconds with room to spare
+  (under 0.7 times the budget), and never more than one level above where it started. A single
+  hitch is not slow frames. After every change it ignores 2 seconds of frames, and a level it
+  already had to leave takes twice as long to climb back into.
+- **Your budget is `1000 / targetFps`**, and `targetFps` is 60 unless you say. A game that caps
+  itself at 30 frames a second on battery saver passes `targetFps: 30`, or every frame reads as
+  slow.
+- **It never counts a paused game**: not while the Arcade has you paused (`gem.paused`), and not
+  while the tab is hidden. It also ignores the first 2 seconds, which are your game loading.
+- **It holds a hand-picked tier.** While `graphicsQualityAuto` is `false` it stays at the start and
+  never calls `onChange` on its own. Pass `auto: false` to hold whatever the Arcade says, or
+  `start: 'high'` to start from a level the player chose in your own settings.
+- **A new recommendation starts it over.** When the player changes Graphics in the Arcade's
+  Settings, the governor goes back to the new start and calls `onChange(level, 'reset')`. It reads
+  `gem.prefs` live, so you do not have to tell it.
+- **`governor.stats`** has what it measured (`fps`, `p90Ms` and `budgetMs`, the level's index,
+  whether it is holding or paused), for your own debug overlay. Call `governor.dispose()` when your
+  game stops rendering for good.
+
 ## The Arcade's menu
 
 The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "10.3.1",
+  "version": "10.4.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -35,6 +35,10 @@
       "types": "./dist/function.d.ts",
       "import": "./dist/gem-web-sdk.function.js"
     },
+    "./quality": {
+      "types": "./dist/quality.d.ts",
+      "import": "./dist/gem-web-sdk.quality.js"
+    },
     "./schema": "./schema/bridge.v1.json",
     "./brand/*": "./brand/*"
   },

package/schema/bridge.v1.json

@@ -804,7 +804,8 @@
           "$comment": [
             "The player's ARCADE-WIDE DEFAULTS for this device, which the Arcade",
             "keeps in its own Settings: a starting volume, battery saver, a keyboard",
-            "layout, the gamepad's confirm button, and vibration. RECOMMENDATIONS",
+            "layout, the gamepad's confirm button, vibration, the camera and",
+            "controls settings and a starting graphics quality. RECOMMENDATIONS",
             "ONLY. The game's own saved settings win: a game starts a setting from",
             "here only while the player has made no choice of their own in that",
             "game, and never overwrites one the player made because this changed.",
@@ -824,6 +825,16 @@
             "the game side all four are present whenever the object is. A game says",
             "which of them it leaves to the player with `gem.controlsDeclare`.",
             "",
+            "THE GRAPHICS TWO ARE OPTIONAL INSIDE IT TOO (owner decision",
+            "2026-10-11): `graphicsQuality` and `graphicsQualityAuto`, the quality",
+            "a game STARTS at on this device. The Arcade picks the start (the",
+            "player's Graphics setting, or the tier it detected for this device on",
+            "Auto); the game adapts from there while it runs, and holds the start",
+            "when the player picked it by hand. A parent built against an older SDK",
+            "omits them, and the SDK fills `graphicsQuality` from `batterySaver`",
+            "(`low` when it is on, `medium` otherwise) and `graphicsQualityAuto`",
+            "with true, so on the game side both are present whenever the object is.",
+            "",
             "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
             "the top of this message, and keep their meaning: they are the Arcade's",
             "own state the frame acts on, not a recommendation. The Arcade starts",
@@ -900,6 +911,31 @@
                 "only `floating` or `fixed` today, and the SDK maps any other value to",
                 "the default, `floating`, so a game only ever sees those two."
               ]
+            },
+            "graphicsQuality": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": [
+                "The graphics quality a game should START at on this device: `low`,",
+                "`medium` or `high`. The player's Graphics setting decides it --",
+                "Battery saver sends `low`, Balanced `medium`, Best looking `high`,",
+                "and Auto (the default) sends the tier the Arcade detected for this",
+                "device. A starting point, not a cap: a game adapts from here while it",
+                "runs unless `graphicsQualityAuto` is false.",
+                "",
+                "A CODE, NOT AN ENUM, so the vocabulary can grow without costing an",
+                "older frame the whole message (see WIDENING above): a parent sends",
+                "only `low`, `medium` or `high` today, and the SDK maps any other",
+                "value to `medium`, so a game only ever sees those three. When it is",
+                "absent the SDK fills `low` if `batterySaver` is true, else `medium`."
+              ]
+            },
+            "graphicsQualityAuto": {
+              "kind": "boolean",
+              "optional": true,
+              "$comment": "True when the Arcade detected `graphicsQuality` for this device (the player left Graphics on Auto), so the game may step its quality up or down from there as it measures frames; false when the player picked it by hand, so the game holds it and changes it only when the player does (in the Arcade or in the game's own settings). Default true when absent."
             }
           }
         }