@indiegems/gem-web-sdk 13.0.0 → 13.1.0

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

@@ -708,46 +708,54 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 The Arcade keeps **one control of its own over every game**, on every device — a phone's full-bleed
 game, a framed or full-window game on a desktop, a tablet or a TV in native fullscreen:
 
-- **The Gem button**, the Gem Arcade's gem, in the **top-left corner**, always there (a touch target, about
-  50px across). It opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems,
-  Tickets and achievement score, mute, the player's Arcade-wide settings and the rest. Not your
-  settings: those are [your own button](#game-settings).
+- **The Gem button**, the Gem Arcade's gem, always there (a touch target, about 50px across), in
+  the **top-left corner** unless your game [asks for another](#moving-the-gem-gemsetgemcorner). It
+  opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems, Tickets and
+  achievement score, mute, the player's Arcade-wide settings and the rest. Not your settings: those
+  are [your own button](#game-settings).
 - **Nothing else.** The player's wallets (Gems, Tickets, their achievement score) are **not** drawn
   over your game: the player opens the Gem menu to see them, and every platform-currency payout
   flies into the Gem button ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you)).
   When the player switches the frame-rate readout on, it sits beside the gem and is reserved the
   same way.
 
-**The top of the screen has one layout, in every game:**
+### The top of the screen
 
-| Where                                | Whose        | What goes there                                                                                                                                                                                         |
-| ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Top-left corner**                  | the Arcade's | Its Gem button. Nothing of yours under it.                                                                                                                                                              |
-| **Top-left, right of the Gem**       | yours        | Your **Home / Back** buttons, drawn when a screen needs them, level with the Gem and just to its right. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
-| **Centre of the top row**            | yours        | Your **information**: score, moves, a timer, a level name.                                                                                                                                              |
-| **Top-right**                        | yours        | Your **settings** button ([Game settings](#game-settings)).                                                                                                                                             |
+**The top of the screen has one layout, in every game, wherever the Gem sits.** A player learns
+where "back" and "settings" are once, across every game:
 
-Keep the spot beside the Gem for Home / Back even on a screen that has neither today: a player
-learns where "back" is once, across every game, and information that sits there on one screen
-teaches them the wrong thing on the next.
+| Where                     | Whose        | What goes there                                                                                                                                                                                                        |
+| ------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **The Gem's corner**      | the Arcade's | Its Gem button — top-left unless you [ask for another corner](#moving-the-gem-gemsetgemcorner). Nothing of yours under it.                                                                                             |
+| **Top-right**             | yours        | Your **settings** button ([Game settings](#game-settings)) at the end of the row, and your **Back / Home** button just to its left, level with it and about 16px apart, so a fingertip lands on one and not the other. |
+| **Centre of the top row** | yours        | Your **information**: a title, score, moves, a timer, a level name.                                                                                                                                                    |
 
-**Your settings button goes top-right**, clear of any Arcade control: under the Gem Arcade there is
-none in that corner, but another embedder may keep one there. [Game settings](#game-settings) shows
-how to place it.
+- **Back / Home is drawn when a screen needs it, always in that spot.** It moves around _inside_
+  your game — back to your level select or title screen — and never leaves it: leaving is the
+  Arcade's menu, so a player always knows which control does which.
+- **Whichever of your controls shares the Gem's corner sits level with the Gem, on the side toward
+  the centre.** With the Gem top-left, nothing of yours does. With the Gem top-right, your Back and
+  settings sit just left of it.
+- **Your settings button is there on every screen.** It goes top-right even where no Arcade control
+  is: another embedder may keep one in that corner, so place it from the reserved areas below and it
+  moves aside for whatever is there.
 
-Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
-them. **Never hard-code their size or position.** They differ by phone, and in native fullscreen the
-gem may rise into the camera band — read them, as below.
+The parts of your frame under the Gem and any other Arcade control are **reserved**: keep
+essential UI and every touch target out of them. **Never hard-code their size or position.** They
+differ by phone, orientation and mode. The Gem sits at the edge of the safe area and never rises
+into the camera band, but that edge is somewhere else on every device — read them, as below.
 
 An inset cannot say that — as a left or top inset, a button a few dozen pixels wide would take a whole
 strip of your screen. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your
 frame, measured from its top-left corner — one for the Gem button, and one for the frame-rate
-readout while the player shows it:
+readout while the player shows it. Each is grown out to the frame edges it sits nearest, because the
+sliver between the Gem and the edge is no place for a button either. On a notched phone in portrait,
+with the Gem top-left:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [{ "x": 8, "y": 55, "width": 52, "height": 52 }]
+  "reserved": [{ "x": 0, "y": 0, "width": 60, "height": 99 }]
 }
 ```
 
@@ -755,35 +763,37 @@ readout while the player shows it:
 `--gem-safe-*` before anything else hears the push: `--gem-reserved-tl-width` and
 `--gem-reserved-tl-height`, and the same pair for `tr`, `bl` and `br` — how far that corner's
 reserved rectangles reach in from its two edges. A rectangle belongs to the corner its centre lies
-nearest to. Under the Gem Arcade the Gem button is a top-left rectangle, so:
+nearest to. Lay the top row out between the two top corners, and it is right wherever the Gem is:
 
 ```css
-/* ONE Home or Back button, level with the Gem, just to its right */
-#back {
+/* The top row: clear of whatever the Arcade reserves in either top corner */
+#top-row {
+  position: absolute;
   top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
   left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
+  right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
+  display: flex;
+  align-items: center;
+  gap: 16px;
 }
-/* your information — score, moves, a timer — clear of every top corner the arcade reserves */
-#info {
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
-  right: var(--gem-safe-right, 0px);
+/* your information takes the middle; Back, then settings, at the right end */
+#top-row .info {
+  flex: 1;
+  text-align: center;
 }
 ```
 
 The per-corner properties say how far a corner's rectangles reach, not how much room is left beside
-them. To know whether a row of your own buttons fits beside the Gem, read the rectangles from
-script: the room to the right of the top-left ones is the frame's width less the furthest right
-edge among them.
+them. To know whether your top row fits between the Arcade's controls, read the rectangles from
+script: the room is what lies between the top rectangles on the left and those on the right.
 
 ```js
-const reserved = gem.viewport?.reserved ?? [];
-const topLeft = reserved.filter((r) => r.x + r.width / 2 < window.innerWidth / 2);
-const from = topLeft.length ? Math.max(...topLeft.map((r) => r.x + r.width)) : 0;
-nav.classList.toggle('below-arcade-row', window.innerWidth - from < nav.offsetWidth + 8);
+const w = window.innerWidth;
+const top = (gem.viewport?.reserved ?? []).filter((r) => r.y === 0);
+const isLeft = (r) => r.x + r.width / 2 < w / 2;
+const from = Math.max(0, ...top.filter(isLeft).map((r) => r.x + r.width));
+const to = Math.min(w, ...top.filter((r) => !isLeft(r)).map((r) => r.x));
+row.classList.toggle('below-arcade-row', to - from < row.scrollWidth + 8);
 ```
 
 All eight properties are written on every push, `0px` for a clear corner, so a rotation never leaves
@@ -791,8 +801,39 @@ a stale value; they are never set under an embedder that sends no viewport, whic
 fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
 
 **Lay out against it whenever it changes.** The Gem button's rectangle is there for the whole
-session, and it moves with a rotation, a resize or the frame-rate readout. Read every corner, not
-only the one this page names today: a layout that honours all four is right under any embedder.
+session, and it moves with a rotation, a resize, the frame-rate readout and a change of corner. Read
+every corner, not only the one you asked for: a layout that honours all four is right under any
+embedder.
+
+### Moving the Gem: `gem.setGemCorner`
+
+**Leave the Gem top-left unless your own HUD needs that corner.** If it does, ask for another:
+
+```js
+// This game's minimap needs the top-left, so the Gem goes bottom-left.
+gem.setGemCorner('bottom-left'); // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+```
+
+- **One corner per game**, at most one per orientation (one in portrait, another in landscape).
+  Call it once at boot, and again on a rotation if the two differ. A Gem that moves from screen to
+  screen is a way out the player has to look for.
+- **In landscape the bottom corners are where a player's thumbs hold the sticks.** Ask for one only
+  if your controls do not live there.
+- **Lay out around the reserved rectangles you receive, never around the corner you asked for.**
+  The Arcade moves the Gem on its own terms: not while the player is using it or its menu is open,
+  no more often than every few seconds, and a corner the player chooses for themselves, should the
+  Arcade ever offer that, wins over yours. The rectangles — and the `--gem-reserved-*` properties —
+  say where the Gem is now; a game that reads them is right whatever the Arcade decided, and a game
+  that assumed its corner is not.
+- **The top row does not change.** Back and settings stay top-right and information top-centre,
+  wherever the Gem goes ([the top of the screen](#the-top-of-the-screen)).
+- **It is screen state, not a toggle**: each call is the whole answer, held before the Arcade
+  connects and sent again after any reconnect. A value that is not one of the four corners is
+  ignored, with a warning on the console.
+
+`gem.setGemCorner` returns `true` when the Arcade was told, and `false` before it connects and
+under an embedder that cannot move its Gem. On `false` the Gem stays where the embedder puts it,
+and the rectangles say where that is: there is nothing else to do.
 
 **Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
 read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
@@ -900,8 +941,8 @@ This is the whole model, and every other page that mentions settings links here:
   them from `gem.prefs.recommended` (and `muted` and `reducedMotion` from `gem.prefs`) and applies
   them again on `onPrefs`. The Arcade never asks your game anything about them, and never shows
   anything your game says.
-- **Every game draws its own settings button, top-right, and its own settings screen.** The
-  Arcade's menu never opens it.
+- **Every game draws its own settings button, top-right ([the top of the
+  screen](#the-top-of-the-screen)), and its own settings screen.** The Arcade's menu never opens it.
 - **A setting starts from `recommended` until the player changes it in your game, and then the
   player's choice in your game wins.** Save only what the player chose, never a recommended value.
 - **Where a choice is kept.** Device configuration — volume, graphics quality, look sensitivity, a
@@ -914,17 +955,15 @@ This is the whole model, and every other page that mentions settings links here:
   while `gem.vibration.available` ([vibration](vibration.md)).
 
 **The button goes in the top-right corner**, the same corner in every game, so a player never has
-to look for it. Place it with the reserved-area properties so it never sits under an Arcade
-control, whatever the Arcade keeps in that corner on this device:
+to look for it, with your Back button just to its left when a screen has one. Place it with the
+reserved-area properties so it never sits under an Arcade control: if the Gem is in that corner, the
+button sits level with it, just inside it.
 
 ```css
 #settings-button {
   position: absolute;
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  right: var(--gem-safe-right, 0px);
+  top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
+  right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
 }
 ```
 
@@ -1143,7 +1182,8 @@ What it does, so you know what to expect:
 
 ## The Arcade's menu
 
-The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is
+The Arcade keeps one button over every game, on every device: the Gem, top-left unless your game
+[asks for another corner](#moving-the-gem-gemsetgemcorner). Its menu is
 how a player leaves (**Return to the Arcade**), sees their Gems, Tickets and achievement score, mutes,
 goes fullscreen, reports a problem and changes their Arcade-wide settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
 four entries of your own:
@@ -1175,9 +1215,9 @@ gem.setMenu({
 settings button is there either way; what such a game also needs is a way out of its own, a control
 that calls `gem.exit()`.
 
-Your own **back or home** button — the one that moves around inside your game — goes **top-left**,
-which the Arcade [leaves clear](#the-arcades-own-controls-reserved-areas). It never leaves the game:
-leaving is the Arcade's menu, so a player always knows which control does which.
+Your own **back or home** button — the one that moves around inside your game — goes **top-right,
+just left of your settings button** ([the top of the screen](#the-top-of-the-screen)). It never
+leaves the game: leaving is the Arcade's menu, so a player always knows which control does which.
 
 ## Sound: your own mute control, and the Arcade's
 
@@ -1267,8 +1307,8 @@ belong to the Arcade. **Your game never draws one**, and never shows a pending s
 Arcade takes every figure from the platform and shows them itself.
 
 **The Gem Arcade draws no wallet over your game** (since 2026-10-11). Nothing of it sits in your top
-row, at rest or when a balance moves. The player opens the Gem menu — the Gem button at the
-top-left — to see their Gems, Tickets and achievement score, and every payout
+row, at rest or when a balance moves. The player opens the Gem menu — the Gem button, in whichever
+corner it sits — to see their Gems, Tickets and achievement score, and every payout
 [`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
 flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
 the ones the player earns on screen and the flight starts where they are looking.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -40,7 +40,8 @@
       "import": "./dist/gem-web-sdk.quality.js"
     },
     "./schema": "./schema/bridge.v1.json",
-    "./brand/*": "./brand/*"
+    "./brand/*": "./brand/*",
+    "./rigs/*": "./rigs/*"
   },
   "files": [
     "bin",
@@ -50,6 +51,7 @@
     "schema/bridge.v1.json",
     "schema/capabilities.public.json",
     "brand/*.png",
+    "rigs/*.glb",
     "docs/*.md",
     "docs/manifest.json",
     "docs/api/*.md",

package/schema/bridge.v1.json

@@ -684,9 +684,9 @@
           "optional": true,
           "$comment": [
             "Every 3D character the player WEARS, one per RIG FAMILY (gem-api",
-            "`avatars_3d`). A family is a rig contract —",
-            "`small_human` is the first — and a player wears at most one character",
-            "per family, so a game that accepts several families reads the one it",
+            "`avatars_3d`). A family is a rig contract — `small_human` and",
+            "`adult_human` today — and a player wears at most one character per",
+            "family, so a game that accepts several families reads the one it",
             "draws by `family`.",
             "",
             "THE FLAT FIELDS STAY, AND THEY ARE ONE OF THESE. `avatar3dId`,",
@@ -720,7 +720,7 @@
               "family": {
                 "kind": "string",
                 "maxLength": 32,
-                "$comment": "The rig family (gem-api `family`), e.g. `small_human`. A lowercase code, checked by the frame rather than by a format here, so one family name this frame does not recognise costs the entry and never the message."
+                "$comment": "The rig family (gem-api `family`), e.g. `small_human` or `adult_human`. A lowercase code, checked by the frame rather than by a format here, so one family name this frame does not recognise costs the entry and never the message."
               },
               "id": {
                 "kind": "string",
@@ -2681,8 +2681,8 @@
         "moved (or is about to move) a progression mapped onto a platform currency,",
         "and the game would like the arcade to show it landing: the currency flying",
         "from `origin` into the arcade's chrome — in the Gem Arcade, into its Gem",
-        "button at the frame's top-left — and the total moving when the platform",
-        "confirms the grant.",
+        "button, in whichever corner of the frame it sits — and the total moving",
+        "when the platform confirms the grant.",
         "",
         "A PRESENTATION CUE, NOT A CLAIM. Nothing here is trusted as a number. The",
         "amount that lands and the player's new total reach the parent from gem-api",
@@ -3008,6 +3008,53 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.gemCorner",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The corner of the frame the game would like the arcade's own control",
+        "over it to sit in - in the Gem Arcade, the Gem button that opens its",
+        "menu. With no message at all it sits top-left, which is also the",
+        "recommendation: a game asks for another corner only when its own HUD",
+        "needs that one.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.menu`. Each message is the whole",
+        "answer and the latest one wins. The SDK holds it from before the bridge",
+        "is up and re-sends it after every handshake, so a parent that reconnects",
+        "puts the control where the game had asked.",
+        "",
+        "A REQUEST, APPLIED ON THE PARENT'S TERMS. The parent holds a move while",
+        "the player is using the control or one of its surfaces is open, keeps a",
+        "minimum dwell between moves and applies only the latest request after",
+        "one, and puts a player's own choice of corner, should it ever offer one,",
+        "above the game's. So a game never lays out around the corner it asked",
+        "for: it lays out around the rectangles `gem.viewport` sends in",
+        "`reserved`, which say where the control actually is.",
+        "",
+        "ONE ENUM, AND IT ONLY GROWS. A later anchor is a new value behind a",
+        "capability of its own, sent only to a parent that advertised that",
+        "capability, so `v` does not move; a parent that advertised only",
+        "`gemCorner` is only ever sent these four.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. The game",
+        "picks one of four places the parent defines, never a coordinate, a size,",
+        "a visibility or a look; the parent's dwell and holds, not this rate",
+        "limit, are what keep a game from making the control run away.",
+        "",
+        "Gated by `gemCorner`: sent only to a parent that advertised it. To any",
+        "other, `gem.setGemCorner` returns false."
+      ],
+      "fields": {
+        "corner": {
+          "kind": "enum",
+          "values": ["top-left", "top-right", "bottom-left", "bottom-right"],
+          "$comment": "Physical, not logical: `left` is the frame's left edge in every language, so a right-to-left locale never mirrors a game's choice."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.requestShare",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -236,6 +236,12 @@
       "gates": [
         "gem.controlsDeclare"
       ]
+    },
+    "gemCorner": {
+      "implemented": true,
+      "gates": [
+        "gem.gemCorner"
+      ]
     }
   }
 }