@indiegems/gem-web-sdk 13.2.2 → 13.3.1

package/docs/manifest.json

@@ -23,8 +23,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "9058c26bc11266f235dfa3c72c80a3fc962aa9f204ef491006e6d34545f5eeeb",
-      "updated": "2026-10-09T00:24:00Z"
+      "sha256": "338dcdfe4aaa90241f7132677a0135d0ec8e32336f4302413dc0f11391b37623",
+      "updated": "2026-10-15T23:20:43Z"
     },
     {
       "file": "async-opponents.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "1b3fc8bb0464ca818298376b96cb20f1eb611059d2b9b9f2f8c538b57b19a559",
-      "updated": "2026-10-15T19:06:19Z"
+      "sha256": "1f95ccc1c4e84075e6f8a7a7d36403593196c3d7bc271f5cd3a992c77becf3de",
+      "updated": "2026-10-15T23:30:59Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "b152abdec73f8b72c39f896bf64faccf3a1924a1cf2b42bae566ff41752a836a",
-      "updated": "2026-10-15T19:06:19Z"
+      "sha256": "d131f187f5a3146a6ec13289d889606c4de770378921dc3b56b7c1b678b5f162",
+      "updated": "2026-10-15T23:30:59Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "55c841c525b7a765baa6749f30602291a884f05819d2afbb4f32138d215dd2a8",
-      "updated": "2026-10-15T19:06:19Z"
+      "sha256": "f6654b2865d04cbcb8ed1bb1e157107e27d96348d74e8bf1be040a747991b743",
+      "updated": "2026-10-15T23:30:59Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "439683ca206b2230e48ab46d5eb9a945964fb6f2e308ffcc8ec1e1b9423fc5e8",
-      "updated": "2026-10-15T13:34:34Z"
+      "sha256": "e97ca7a5b01a40d57900eb1116e961768f62bccfd412afd02bca245cdb7beeab",
+      "updated": "2026-10-15T20:36:02Z"
     }
   ]
 }

package/docs/player-text-fields.json

@@ -0,0 +1,219 @@
+{
+  "$comment": [
+    "The published fields whose value is PlayerText (player-authored text), and the",
+    "first release from which each has been PlayerText in that entry. String(), a",
+    "template literal or JSON.stringify on one shows \"[gem: use gem.text.toPlain()]\";",
+    "convert it with text.toPlain(). `entry` is the package export (`sdk` is",
+    "@indiegems/gem-web-sdk/sdk), `field` is <Type>.<property>, and `since` is null",
+    "for a field no release has shipped yet. Written by",
+    "`node scripts/player-text-fields.mjs`."
+  ],
+  "schema_version": 1,
+  "fields": [
+    {
+      "entry": "function",
+      "field": "Friend.displayName",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "Friend.displayTag",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "LeaderboardEntry.displayName",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "LeaderboardEntry.displayTag",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "PlayerIdentity.displayName",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "PlayerIdentity.displayTag",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "PlayerProfile.displayName",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "PlayerProfile.displayTag",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "ShowcaseFriendEntry.displayName",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "ShowcaseFriendEntry.displayTag",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "function",
+      "field": "Transfer.message",
+      "since": "7.6.0"
+    },
+    {
+      "entry": "game",
+      "field": "Friend.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "Friend.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "GemPlayer.displayHandle",
+      "since": "1.2.0"
+    },
+    {
+      "entry": "game",
+      "field": "GemPlayer.displayName",
+      "since": "1.2.0"
+    },
+    {
+      "entry": "game",
+      "field": "GemPlayer.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "LeaderboardEntry.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "LeaderboardEntry.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "PlayerIdentity.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "PlayerIdentity.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "PlayerProfile.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "PlayerProfile.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "ShowcaseFriendEntry.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "game",
+      "field": "ShowcaseFriendEntry.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "Friend.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "Friend.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GemPlayer.displayHandle",
+      "since": "3.2.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GemPlayer.displayName",
+      "since": "3.2.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GemPlayer.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GemServerProfile.displayName",
+      "since": "3.2.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GemServerProfile.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "LeaderboardEntry.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "LeaderboardEntry.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "PlayerIdentity.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "PlayerIdentity.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "PlayerProfile.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "PlayerProfile.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "ShowcaseFriendEntry.displayName",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "ShowcaseFriendEntry.displayTag",
+      "since": "5.11.0"
+    },
+    {
+      "entry": "server",
+      "field": "GemServerProfile.displayName",
+      "since": "2.2.0"
+    },
+    {
+      "entry": "server",
+      "field": "GemServerProfile.displayTag",
+      "since": "5.11.0"
+    }
+  ]
+}

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/v13.2.2/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v13.2.2/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v13.3.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v13.3.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -1189,6 +1189,10 @@ What it does, so you know what to expect:
 - **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.
+- **Capping your frame rate? Report your draws, or the Arcade's FPS overlay still reads 60.** The
+  overlay counts the frames the browser offers your page, not the frames you draw. Call
+  `gem.reportFrame()` each time you draw and it counts your draws instead, so a player can see
+  Battery saver working. See [The Arcade's FPS overlay](#the-arcades-fps-overlay).
 - **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
@@ -1371,15 +1375,31 @@ Arcade, which draws a small readout in its own chrome. **Your game draws nothing
   is sent until `showFrameStats` arrives `true`; the counter stops when it goes `false`, while the
   Arcade has your game paused (`onPause`), and when the bridge closes. A game whose player never
   presses the toggle never runs any of it.
-- **What the number measures.** The `requestAnimationFrame` ticks the browser delivers to your
-  game's document. That is exactly your render rate if you render on that callback — three.js,
-  Phaser and Babylon.js do, and so does any engine's web export — and it is measured inside your
-  frame on purpose:
-  the Arcade page cannot count your frames from outside, because a cross-origin iframe renders on
-  its own schedule, and a page-side counter would read a steady 60 over a game hitching at 25.
-- **If you render in a worker.** A game that draws through an `OffscreenCanvas` in a worker is
-  timed on its main thread here, which is not its renderer. There is no hook yet for such a game to
-  report its own figure; if you need one, ask.
+- **What the number measures, by default: the frames your page is offered, not the frames you
+  draw.** It counts the `requestAnimationFrame` ticks the browser delivers to your game's
+  document. That is your render rate only if you draw on every one of them — three.js, Phaser and
+  Babylon.js do unless you cap them — and it is measured inside your frame on purpose: the Arcade
+  page cannot count your frames from outside, because a cross-origin iframe renders on its own
+  schedule, and a page-side counter would read a steady 60 over a game hitching at 25.
+- **If you skip frames, report your draws.** A game that caps itself on Battery saver by drawing
+  every other tick still receives 60 ticks a second, so the default figure reads about 60 and
+  nobody can see the cap working. The same goes for a game that draws through an `OffscreenCanvas`
+  in a worker, which the SDK can only time on its main thread. Call `gem.reportFrame()` each time
+  your game draws a frame, and the overlay counts your draws instead, labelled as the game's own
+  figure:
+
+  ```js
+  function render() {
+    renderer.render(scene, camera);
+    gem.reportFrame(); // once per frame you actually draw
+  }
+  ```
+
+  Call it on **every** frame you draw, from your first: the first call switches the overlay to your
+  draws for the rest of the session, so a screen that draws without it reads as dropped frames, and
+  a second call for one frame counts it twice. It is free while the overlay is off — a flag check,
+  nothing sent — so leave it in your loop. A worker renderer posts to the main thread when it draws
+  and calls it there.
 - **Do not draw an FPS counter of your own over the Arcade's.** Two readouts that disagree — and
   they will, since they count different things — teach a player that one of them is lying. A debug
   overlay in your own builds is fine; keep it off in an Arcade build, or at least off by default.
@@ -1390,6 +1410,10 @@ Arcade, which draws a small readout in its own chrome. **Your game draws nothing
 `showFrameStats` is also on `gem.prefs` for you to read, held like the rest, but the only reason to
 read it is to know the Arcade is already showing one.
 
+The browser offers no way to count the frames it actually put on screen for your page, which is
+why your draws come from you: without `gem.reportFrame()` the SDK cannot tell a frame you drew from
+one you skipped.
+
 ## The player's language: prefer what the page sends, detect the rest
 
 **`gem.prefs.locale` is the language the Arcade page is RENDERING in.** That is the one fact a frame
@@ -1492,6 +1516,103 @@ and showcase rows used to be plain strings and are now `PlayerText`, as they alr
 members. `gem.player.displayHandle` and `gem.player.avatarUrl` still work, and are
 [deprecated](deprecation-policy.md) in favour of `displayTag` and `avatarIconUrl`.
 
+### A name turned into a string: what catches it
+
+`PlayerText` is not a string, so TypeScript refuses `el.innerHTML = who.displayName`, a `string`
+variable or parameter, and string methods such as `.length` and `.toUpperCase()`. **Four uses
+still compile**, because each accepts any value, and each puts `[gem: use gem.text.toPlain()]` on
+screen where the name should be:
+
+```js
+String(who.displayName); // and who.displayName.toString()
+`Hi ${who.displayName}`;
+'Hi ' + who.displayName;
+JSON.stringify({ name: who.displayName });
+```
+
+A game that moved to a release where a field became `PlayerText` and kept a line like these
+compiles, builds and uploads cleanly, and shows players the placeholder. Three things catch it
+first:
+
+- **The console, while you develop.** On a page served from your own machine (your bundler's dev
+  or preview server, `gemctl serve`, with or without `--dev`), the first time each field is turned
+  into a string the SDK logs one `console.warn` naming the field and the fix, with a stack trace
+  that points at your line. A published game logs nothing, and the placeholder is the same.
+- **A lint rule.** If your ESLint runs typescript-eslint with type information, its
+  `restrict-template-expressions` and `restrict-plus-operands` rules already flag the template and
+  the `+`. This rule flags all four; paste it into `eslint.config.js`:
+
+  ```js
+  // Flags String(x), x.toString(), `${x}`, '…' + x and JSON.stringify(x) on PlayerText.
+  const noPlayerTextString = {
+    meta: {
+      type: 'problem',
+      schema: [],
+      messages: {
+        stringified:
+          'This is PlayerText: as a string it shows "[gem: use gem.text.toPlain()]". Convert it with text.toPlain().',
+      },
+    },
+    create(context) {
+      const services = context.sourceCode.parserServices;
+      const checker = services.program.getTypeChecker();
+      const isPlayerText = (type) =>
+        (type.isUnion() ? type.types : [type]).some((t) => t.getSymbol()?.getName() === 'PlayerText');
+      const typeOf = (node) => checker.getTypeAtLocation(services.esTreeNodeToTSNodeMap.get(node));
+      const check = (node) => {
+        if (node && isPlayerText(typeOf(node))) context.report({ node, messageId: 'stringified' });
+      };
+      // JSON.stringify also looks one level into an object: { name: who.displayName }.
+      const checkJson = (node) => {
+        if (!node) return;
+        const type = typeOf(node);
+        const tsNode = services.esTreeNodeToTSNodeMap.get(node);
+        const inside = checker
+          .getPropertiesOfType(type)
+          .some((p) => isPlayerText(checker.getTypeOfSymbolAtLocation(p, tsNode)));
+        if (isPlayerText(type) || inside) context.report({ node, messageId: 'stringified' });
+      };
+      return {
+        CallExpression(node) {
+          const { callee } = node;
+          if (callee.type === 'Identifier' && callee.name === 'String') check(node.arguments[0]);
+          if (callee.type !== 'MemberExpression' || callee.computed) return;
+          const isJson = callee.object.type === 'Identifier' && callee.object.name === 'JSON';
+          if (isJson && callee.property.name === 'stringify') checkJson(node.arguments[0]);
+          if (callee.property.name === 'toString') check(callee.object);
+        },
+        TemplateLiteral(node) {
+          // A tagged template is the tag's to handle, and an html`` tag escapes.
+          if (node.parent.type !== 'TaggedTemplateExpression') node.expressions.forEach(check);
+        },
+        BinaryExpression(node) {
+          if (node.operator === '+') [node.left, node.right].forEach(check);
+        },
+        AssignmentExpression(node) {
+          if (node.operator === '+=') check(node.right);
+        },
+      };
+    },
+  };
+
+  export default [
+    // …your existing config, with type information on (parserOptions.projectService: true)
+    {
+      files: ['**/*.ts', '**/*.tsx', '**/*.mts'],
+      plugins: { gem: { rules: { 'no-player-text-string': noPlayerTextString } } },
+      rules: { 'gem/no-player-text-string': 'error' },
+    },
+  ];
+  ```
+
+  It needs type information, so it lints TypeScript only. In plain JavaScript, rely on the console
+  warning.
+- **The field list.** The package carries `docs/player-text-fields.json`: every field that holds
+  `PlayerText`, by entry (`sdk` is `@indiegems/gem-web-sdk/sdk`), each with the first release in
+  which that entry shipped it as `PlayerText`. Search your code for every field it lists, not only
+  the ones that are new since your last pin: a field that has been `PlayerText` for years
+  stringifies to the placeholder just the same.
+
 ### The signed-in player's Boost: show it, never gate on it
 
 `gem.player` also carries **`boost`** — the player's Boost, which the Arcade sells for real money.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "13.2.2",
+  "version": "13.3.1",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -58,6 +58,7 @@
     "docs/manifest.json",
     "docs/api/*.md",
     "docs/api/reference.json",
+    "docs/player-text-fields.json",
     "CHANGELOG.md"
   ]
 }

package/schema/bridge.v1.json

@@ -3302,9 +3302,17 @@
         "WHAT IT COUNTS. The frame document's own requestAnimationFrame delivery,",
         "which is exact for an engine that renders on that callback (three.js,",
         "Phaser, Babylon.js, any engine's web export) and is what the SDK measures",
-        "with no code from the game. A game that renders in a worker through OffscreenCanvas is",
-        "measured on its main thread here, not at its renderer; reporting its own",
-        "figure is a hook this version does not carry.",
+        "with no code from the game. It is NOT the frames the game draws: a game",
+        "honouring Battery saver by drawing every other tick still reads about 60,",
+        "and a game rendering in a worker through OffscreenCanvas is timed on its",
+        "main thread, not at its renderer.",
+        "",
+        "OR WHAT THE GAME SAYS IT DREW. A game that calls `gem.reportFrame()` each",
+        "time it draws is counted by its draws instead, from its first call for",
+        "the rest of the session, and `counts` says which figure this is, so the",
+        "Arcade labels it rather than calling draws page frames or the reverse.",
+        "No web API reports the compositor's presented frames to a document, so",
+        "the game's report is the only figure that counts draws.",
         "",
         "SENT ONLY WHILE ASKED. Nothing is counted and nothing is sent until",
         "`gem.prefs.showFrameStats` arrives true, and the counter stops on false",
@@ -3326,7 +3334,20 @@
       ],
       "fields": {
         "fps": { "kind": "int", "min": 0, "max": 1000 },
-        "frameTimeP95Ms": { "kind": "int", "min": 0, "max": 100000 }
+        "frameTimeP95Ms": { "kind": "int", "min": 0, "max": 100000 },
+        "counts": {
+          "kind": "enum",
+          "values": ["pageFrames", "gameDraws"],
+          "optional": true,
+          "$comment": [
+            "Which figure `fps` and `frameTimeP95Ms` are. `pageFrames`: the",
+            "requestAnimationFrame ticks delivered to the game's document, measured",
+            "by the SDK. `gameDraws`: the frames the game reported drawing through",
+            "`gem.reportFrame()`. ABSENT from an SDK before this field, which always",
+            "measured page frames, so a receiver reads absent as `pageFrames`.",
+            "Additive: a parent that ignores it draws the numbers as before."
+          ]
+        }
       },
       "rateLimit": { "perMinute": 120 }
     },