@indiegems/gem-web-sdk 13.3.3 → 13.4.0

package/docs/rewarded-ads.md

@@ -6,7 +6,8 @@ for 3 dice rolls". Pressing it is the player's choice to watch, so the Arcade st
 straight away, labelled as an ad, with no prompt of its own first. The platform then decides
 whether the player is rewarded, and writes the reward into **your game's own inventory** for that
 player. Your game never grants the reward, and never learns from the answer whether one was
-granted. It reads its inventory.
+granted. It reads its inventory. The Arcade shows no result once the ad closes, either: it hands
+straight back, and **your game shows the reward** (§3).
 
 ```js
 watchAdButton.addEventListener('click', async () => {
@@ -210,19 +211,35 @@ after a press:
 
 | what happened                                                                             | was the reward granted?                                                                                                                             |
 | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| the ad played for its full length                                                         | yes, before the answer                                                                                                                              |
+| the ad played for its full length                                                         | yes, and usually before the answer; a provider's confirmation can land after it (below)                                                             |
 | the player closed the ad early                                                            | no: closing early is a skip, and a skip pays nothing                                                                                                |
 | an ad source serves, but no ad was available for this press, or it failed to play         | your `without_ads` decides: `grant` grants within your caps, with no ad; `nothing` grants nothing, and the Arcade shows "No ad available right now" |
 | no ad source serves the channel (§8)                                                      | your `without_ads` decides, with no ad                                                                                                              |
 | a cap, a cooldown, `max_held`, the platform's spacing (§6), or something about the player | no                                                                                                                                                  |
 
-In some cases the platform also grants with no ad for reasons your game is not told. So **branch on
-your inventory, never on the outcome.** Re-read it once the ask settles, whatever it settled as.
+The answer is `shown` whenever the Arcade put its ad stage up, however the ad then ended: watched
+to the end, closed early, or no ad could play and `without_ads` decided. It is `no_ad` when no
+stage went up. In some cases the platform also grants with no ad for reasons your game is not
+told. So **branch on your inventory, never on the outcome.** Re-read it once the ask settles,
+whatever it settled as.
+
+**The Arcade shows no result: your game shows the reward.** When the ad closes, the Arcade hands
+straight back to your game, for a test ad and a real one alike. It draws no "you received" line and
+no Continue button of its own. While the ad plays it is labelled "Ad", or **TEST AD** for a test
+ad, and after it the only thing the Arcade ever draws is "No ad available right now", when no ad
+could play and nothing was granted. Telling the player what they got is yours: re-read the
+inventory, then show the new token your own way, such as "+1 revive", or use it at once as §5's
+revive does. When the ad played to the end and the grant landed at once, it is already in the
+inventory when the answer arrives.
 
 **A reward can also arrive after that re-read.** Some ad providers confirm a finished ad from their
-own server, a little after the player closes it, so the reward can land after the ask has
-answered. So also re-read when the screen that spends the reward opens, and spend a token the
-player already holds before asking for another (§5's code does both).
+own server, a little after the player closes it. The Arcade waits a few seconds for that
+confirmation before it hands back, so the reward has usually landed by the time the ask answers,
+but it can land after. So pick the reward up whenever a later read finds it, not only on the
+re-read right after the ask: re-read when the screen that spends the reward opens, show the reward
+then if it is new, and spend a token the player already holds before asking for another (§5's code
+does both). Your game hears of no grant on its own: the SDK's change event fires only for your own
+writes, so a later read is how you find it.
 [`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the general rule.
 
 A granted reward shows in your order history like any other change, as an order the platform made
@@ -413,32 +430,35 @@ The caps are **yours to declare and the platform's to enforce.** The reward is y
 economy, so you choose its limits, and the platform holds them on its side, where a modified client
 cannot reach them. They apply the same with an ad and without one.
 
-| limit                                                                                    | declared by           | enforced by   |
-| ---------------------------------------------------------------------------------------- | --------------------- | ------------- |
-| `max_per_day` — grants per player per UTC day                                            | you, optionally       | the platform  |
-| `cooldown_seconds` — the time between two grants                                         | you                   | the platform  |
-| `max_held` — no grant while the player holds this many                                   | you, for item rewards | the platform  |
-| `min_watch_secs` — how long a test ad plays before it pays                               | you, optionally       | the platform  |
-| at least 15 seconds between two rewarded offers to one player in one game                | the platform          | the platform  |
-| at least 15 seconds between two rewards granted with no ad, in any of the player's games | the platform          | the platform  |
-| once per run, only on the death screen, never in ranked                                  | you                   | **your game** |
-
-- **The second spacing reaches across games.** If another game granted this player a reward with
-  no ad a few seconds ago, an ask in yours that would also grant with no ad (§8) answers `no_ad`
-  with nothing granted, even though your game has offered nothing.
+| limit                                                                                          | declared by           | enforced by   |
+| ---------------------------------------------------------------------------------------------- | --------------------- | ------------- |
+| `max_per_day` — grants per player per UTC day                                                  | you, optionally       | the platform  |
+| `cooldown_seconds` — the time between two grants                                               | you                   | the platform  |
+| `max_held` — no grant while the player holds this many                                         | you, for item rewards | the platform  |
+| `min_watch_secs` — how long a test ad plays before it pays                                     | you, optionally       | the platform  |
+| a gap between two rewards granted with no ad, only where the platform turns one on (off today) | the platform          | the platform  |
+| once per run, only on the death screen, never in ranked                                        | you                   | **your game** |
+
+- **The platform makes no player wait between rewarded ads.** A player who has just watched one
+  to the end and presses again is offered the next at once. Your placement's own limits are the
+  only spacing there is.
+- **A no-ad gap applies only where the platform turns one on, and it is off today.** Set, it
+  spaces two rewards granted with no ad (§8) to one player, across all of their games: an ask in
+  yours that would grant with no ad inside it answers `no_ad` with nothing granted, even though
+  your game has offered nothing. It never touches an ask that plays an ad.
 - **What counts toward a cap** is a grant, after an ad or with none, and an ad that is still
   playing. A grant `without_ads: grant` makes because no ad could play counts the same as any
   other. An ad the player closed early, and a press that paid nothing, do not count, so a skip
-  costs the player nothing against your caps. Every press does start the first spacing, though:
-  a player who closes the ad early and presses again within 15 seconds gets `no_ad` and nothing.
+  costs the player nothing against your caps, and a player who closes the ad early can press
+  again at once.
 - **The platform may hold a daily cap lower than the one you declared, never higher.** It sets no
   daily limit of its own unless one is configured, and a configured one applies to every placement
   from the next ask, with no upload from you.
 - ⚠️ **Nothing protects your economy by default but your own caps.** A placement with no
-  `max_per_day` and no `cooldown_seconds` can pay once every 15 seconds. That holds with an ad,
-  and under `without_ads: grant` without one, wherever no ad plays. `max_held: 1` stops a player
-  banking a second token; it does not stop them spending one and earning the next. Declare the
-  daily cap and cooldown your economy needs.
+  `max_per_day` and no `cooldown_seconds` pays after every ad watched to the end, as fast as the
+  player can watch them, and under `without_ads: grant` on every press, wherever no ad plays.
+  `max_held: 1` stops a player banking a second token; it does not stop them spending one and
+  earning the next. Declare the daily cap and cooldown your economy needs.
 - **`without_ads: grant` means the reward is fine to give free, within its caps.** Every press
   that finds no ad pays under it, so the caps are all that limit it. Leave the field out, which is
   `nothing`, for a reward that should only ever follow an ad.
@@ -455,11 +475,11 @@ platform sets them all. A rewarded reward is your economy, so the caps are yours
 - **A rewarded ad does not replace the break's platform moment.** Signal the moment from the press
   that leaves the break as usual ([`platform-moments.md`](platform-moments.md)); whether the Arcade
   shows anything then is its decision.
-- **Rewarded has its own spacing:** your placement's `cooldown_seconds`, and the platform's 15
-  seconds (§6). An ask inside any of them answers `no_ad` with nothing granted, so do not re-ask on
-  a timer. Never ask on a timer at all: the ad would start with no press. The SDK refuses a timer's
-  ask only when no input came in the last few seconds (§3), so do not count on it. A player who
-  presses again later gets a fresh ask.
+- **Rewarded has its own spacing:** your placement's `cooldown_seconds` and `max_per_day` (§6),
+  and nothing of the platform's. An ask inside a cooldown, or past the daily cap, answers `no_ad`
+  with nothing granted, so do not re-ask on a timer. Never ask on a timer at all: the ad would
+  start with no press. The SDK refuses a timer's ask only when no input came in the last few
+  seconds (§3), so do not count on it. A player who presses again later gets a fresh ask.
 - A grant made with no ad holds nothing off, because nothing was shown.
 
 ## 8. Where an ad plays, and where it does not
@@ -553,7 +573,8 @@ Play your game on its `dev` or `test` channel. `dev` is open to your team and `t
 testers. Pressing the button starts a test ad at once, marked **TEST AD**, which counts down the
 placement's `min_watch_secs` (5 seconds unless you set it). Watch it to the end and the reward
 lands in that channel's inventory. Close it before then and that is a skip, which pays nothing.
-Your game is paused while it plays, and the ask answers when it closes.
+Your game is paused while it plays, and the ask answers when it closes, with no result shown by
+the Arcade: your game's re-read finds the reward and shows it.
 
 To pick a behaviour before you press, add `gem_test_ads=<mode>` to the play page's address:
 

package/docs/rooms-and-matches.md

@@ -983,6 +983,53 @@ template either way.
 This is still quick-join: the player is in a room at once, possibly alone. For "any of these modes,
 but never start short", name the same slugs on `queueForMatch()` instead.
 
+## 5e. Landing in a friend's room: play-with
+
+The Arcade can open your game **to play with someone**: when the player presses Join on a friend
+who is playing it, or answers the prompt the Arcade shows a party member when their leader starts
+it. Your game makes no call for this. The Arcade adds a
+launch key of its own, `gemPlayWith`: an opaque ticket the platform issued for this player, which
+names nobody your game can recognise. The SDK reads it once as `createGem` runs, and every
+`quickJoin()` of the session passes it on: the platform tries the room of the person the ticket
+stands for first, and otherwise quick-joins exactly as it always does.
+
+```js
+const room = await gem.rooms.quickJoin({ templateSlug: 'hub' });
+if (gem.rooms.playWith === 'joined') showToast('You joined your friend');
+```
+
+- **Their room is tried first, when the player may play with them** — an accepted friend whose
+  presence shows the player that they are in your game, or a member of the same party. The room
+  must be a public one of a template the quick-join named, on the channel being played, that
+  admits a join now (open, or a running match whose template admits late joiners), with a free
+  seat. When it is not, the quick-join goes on as usual: a fuller room, or a new one.
+- **`gem.rooms.playWith` says which.** `'joined'` — seated in that player's room; `'unavailable'`
+  — their room could not be joined, or the ticket was no longer good, so the quick-join went on as
+  usual; `null` — this quick-join did not ask, because the Arcade did not open the game to play
+  with anyone. It never says why, and it is read-only: there is no option for naming a player
+  yourself. A game that could name one could ask the platform, one friend at a time, where each of
+  them is.
+- **Who it was stays with the platform.** Neither the launch key, the answer nor anything else of
+  this mechanism names the person: your game learns that it was opened to play with somebody, and
+  whether the quick-join seated the player with them. When it was `'joined'`, the people in the room are its members, as they
+  always are.
+- **The two share a `groupId`.** A member who came to play with someone carries the same
+  `RoomMember.groupId` as them, as a party's members do, so a roster grouped by it already shows
+  them together. It is not a party: either of them leaves alone.
+- **No `seated` fires for it.** `seated` reports a seat your game did not make; this one your own
+  `quickJoin()` made, and its answer is the room.
+- **Only quick-join takes part.** `create()`, `join()`, `joinByCode()` and `queueForMatch()`
+  never try a friend's room, and a party leader's quick-join brings the party into a room of its
+  own rather than joining anyone else's.
+- **Never read `gemPlayWith` from the URL yourself, and never define a key of that name.** It is
+  the platform's, like `gemChallenge`
+  ([`getting-started.md`](getting-started.md#linking-to-your-game)).
+
+A game that quick-joins as it starts — a hub, a drop-in lobby — gets all of this with no change.
+One that shows a mode picker first keeps it: the friend's room is tried for the modes the player
+picks, and a friend playing another mode reads `'unavailable'`. Naming several modes in one
+quick-join (§5d) tries the friend's room for any of them.
+
 ## 6. Scope
 
 **In:** rooms, membership, host, ready state, the match lifecycle, and the dedicated-server connect
@@ -997,7 +1044,8 @@ skill rating, and inventing one is not a small addition to this.
 **Elsewhere:** P2P _connection_ and parties. Both are
 [`p2p-and-parties.md`](p2p-and-parties.md). Three things surface here:
 
-- **A member's group, not their party.** `RoomMember.groupId` says who arrived together, as an opaque
+- **A member's group, not their party.** `RoomMember.groupId` says who arrived together — as a
+  party, or one coming to play with the other (§5e) — as an opaque
   label that is stable for the life of this room and unrelated to the label the same people carry in
   any other room. It is gem-api's, read off the wire; it replaced a pass-through of the real
   `party_id`, which is account-level and cross-game and therefore a social-graph key rather than a

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.3.3/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v13.3.3/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v13.4.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v13.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

@@ -729,7 +729,7 @@ 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, always there (a touch target, about 50px across), in
+- **The Gem button**, the Gem Arcade's gem, always there (a 44px square touch target), 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
@@ -756,7 +756,8 @@ where "back" and "settings" are once, across every game:
   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.
+  settings sit just left of it. "Level" means centred on the Gem button's own middle, which the
+  SDK gives you as `--gem-reserved-tl-center-y` (below), never on the middle of its reserved area.
 - **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.
@@ -769,32 +770,72 @@ into the camera band, but that edge is somewhere else on every device — read t
 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. 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:
+readout while the player shows it.
+
+**Each rectangle is a keep-out area, not the control.** It 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. So its
+middle is not the button's middle, and nothing should be lined up with it. Beside it, `control`
+is the control's own box, as drawn and not grown: that is what you line up with. On a notched phone
+in portrait, with the Gem top-left, the Gem sits 8px in from the left and at the foot of the
+47px inset:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [{ "x": 0, "y": 0, "width": 60, "height": 99 }]
+  "reserved": [
+    {
+      "x": 0,
+      "y": 0,
+      "width": 52,
+      "height": 91,
+      "control": { "x": 8, "y": 47, "width": 44, "height": 44 }
+    }
+  ]
 }
 ```
 
-**The SDK turns them into one pair of custom properties per corner**, written beside
-`--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. Lay the top row out between the two top corners, and it is right wherever the Gem is:
+Here the area's middle is about 46px down and the button's is 69px down, some 23px apart: a top bar
+centred on the area would have its middle level with the top of the Gem. The numbers change with the phone, the
+orientation, a letterboxed game and a television, so read them rather than copying these.
+`control` is absent under an arcade or embedder that does not send it yet; then you have the
+keep-out area alone.
+
+**The SDK turns them into custom properties per corner**, written beside `--gem-safe-*` before
+anything else hears the push. A rectangle belongs to the corner its centre lies nearest to.
+
+| Property (and the same for `tr`, `bl`, `br`) | What it is                                                                                                    |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `--gem-reserved-tl-width`                    | How far that corner's keep-out areas reach in from the side edge. Keep your controls outside it.              |
+| `--gem-reserved-tl-height`                   | How far they reach down from the top edge (up from the bottom edge, for `bl` and `br`).                       |
+| `--gem-reserved-tl-center-y`                 | The vertical middle of that corner's controls themselves, from your frame's top edge. Line things up on it.   |
+| `--gem-reserved-tl-control-height`           | Those controls' height: the Gem button's, or the Gem and the frame-rate readout together when both are there. |
+
+To line a top bar up with the Gem, give it the Gem's height and centre it on the Gem's middle. Put
+the bar between the two top corners' keep-out areas, and it is right wherever the Gem is:
 
 ```css
-/* The top row: clear of whatever the Arcade reserves in either top corner */
+/* The Gem's middle and height, from whichever top corner holds it. The fallback is the Arcade's
+   own placement on a full-bleed game, for an embedder that does not send the control's box.
+   On :root, where the SDK writes its properties, so every element below can use them. */
+:root {
+  --gem-mid: var(
+    --gem-reserved-tl-center-y,
+    var(
+      --gem-reserved-tr-center-y,
+      calc(max(8px, var(--gem-safe-top, env(safe-area-inset-top, 0px))) + 22px)
+    )
+  );
+  --gem-size: var(--gem-reserved-tl-control-height, var(--gem-reserved-tr-control-height, 44px));
+}
+/* The top row: level with the Gem, 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));
+  top: calc(var(--gem-mid) - var(--gem-size) / 2);
+  height: var(--gem-size);
   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;
+  align-items: center; /* anything taller than the Gem still centres on its middle */
   gap: 16px;
 }
 /* your information takes the middle; Back, then settings, at the right end */
@@ -804,6 +845,18 @@ nearest to. Lay the top row out between the two top corners, and it is right whe
 }
 ```
 
+With the Gem in a bottom corner, neither top corner has a control, and the fallback puts the row
+where the Gem would sit at the top. From script, read the box itself:
+
+```js
+// The Gem's own box: the tallest control on the top edge (the frame-rate readout is smaller)
+const boxes = (gem.viewport?.reserved ?? []).filter((r) => r.y === 0 && r.control);
+const gemBox = boxes.map((r) => r.control).sort((a, b) => b.height - a.height)[0];
+const middle = gemBox
+  ? gemBox.y + gemBox.height / 2
+  : Math.max(8, gem.viewport?.insets.top ?? 0) + 22;
+```
+
 The per-corner properties say how far a corner's rectangles reach, not how much room is left beside
 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.
@@ -817,9 +870,12 @@ 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
-a stale value; they are never set under an embedder that sends no viewport, which is what the `0px`
-fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
+The eight width and height properties are written on every push, `0px` for a clear corner, so a
+rotation never leaves a stale value; they are never set under an embedder that sends no viewport,
+which is what the `0px` fallback is for. The centre and control height are different: a corner with
+no control in it, or one whose embedder sends no control box, has them **removed** rather than set to
+`0px` (a middle of 0 would put your bar half off the screen), so your `var()` fallback stands.
+`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, the frame-rate readout and a change of corner. Read
@@ -978,12 +1034,14 @@ This is the whole model, and every other page that mentions settings links here:
 **The button goes in the top-right corner**, the same corner in every game, so a player never has
 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.
+button sits level with it, just inside it. Inside [the top row](#the-top-of-the-screen) it is
+level already; placed on its own, centre it on the same middle:
 
 ```css
 #settings-button {
   position: absolute;
-  top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
+  top: var(--gem-mid); /* defined on :root, as for the top row */
+  transform: translateY(-50%);
   right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
 }
 ```
@@ -994,19 +1052,19 @@ The player sets their defaults once, in the Arcade's Settings, separately for ea
 and a television can say different things. They reach your game as `gem.prefs.recommended`, in the
 same push as `muted` and `reducedMotion`, and again whenever the player changes one:
 
-| Field            | Values                | What it suggests                                                                                             |
-| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `volume`         | `0` to `100`          | Your master volume's starting level, as a percentage — divide by 100 for a gain. A level, never a mute.     |
-| `batterySaver`   | `true` / `false`      | Spend less power: a lower frame rate, fewer effects, a lower resolution.                                     |
-| `keyboardLayout` | `'wasd'` / `'arrows'` | Which keys move by default.                                                                                  |
-| `gamepadConfirm` | `'south'` / `'east'`  | Which face button confirms, by position: the bottom one (A on an Xbox controller) or the right one (B). The other one goes back. |
-| `vibration`      | `true` / `false`      | Your vibration toggle's starting state ([if your game vibrates](#if-your-game-vibrates)).                    |
-| `lookSensitivity` | `20` to `400`        | Look speed for touch, mouse and pen, as a percentage of the base speeds: `100` is 1×.                        |
-| `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. |
+| Field                    | Values                          | What it suggests                                                                                                                 |
+| ------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `volume`                 | `0` to `100`                    | Your master volume's starting level, as a percentage — divide by 100 for a gain. A level, never a mute.                          |
+| `batterySaver`           | `true` / `false`                | Spend less power: a lower frame rate, fewer effects, a lower resolution.                                                         |
+| `keyboardLayout`         | `'wasd'` / `'arrows'`           | Which keys move by default.                                                                                                      |
+| `gamepadConfirm`         | `'south'` / `'east'`            | Which face button confirms, by position: the bottom one (A on an Xbox controller) or the right one (B). The other one goes back. |
+| `vibration`              | `true` / `false`                | Your vibration toggle's starting state ([if your game vibrates](#if-your-game-vibrates)).                                        |
+| `lookSensitivity`        | `20` to `400`                   | Look speed for touch, mouse and pen, as a percentage of the base speeds: `100` is 1×.                                            |
+| `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.        |
 
 `lookSensitivity` to `touchMovement` are the camera and controls settings: see
 [camera and look controls](#camera-and-look-controls) for `gem.controls.look()`, which applies the
@@ -1034,8 +1092,15 @@ sends neither; the SDK then fills `graphicsQuality` from `batterySaver` (`'low'`
 
 ```js
 const DEFAULTS = {
-  volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true,
-  lookSensitivity: 100, gamepadLookSensitivity: 100, invertLookY: false, touchMovement: 'floating',
+  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
@@ -1106,11 +1171,16 @@ function turn({ yaw: dYaw, pitch: dPitch }) {
 
 // Touch and pen: the change since the last event. A mouse: movementX/Y under pointer lock.
 let last = null;
-canvas.addEventListener('pointerdown', (e) => { last = { x: e.clientX, y: e.clientY }; });
-canvas.addEventListener('pointerup', () => { last = null; });
+canvas.addEventListener('pointerdown', (e) => {
+  last = { x: e.clientX, y: e.clientY };
+});
+canvas.addEventListener('pointerup', () => {
+  last = null;
+});
 canvas.addEventListener('pointermove', (e) => {
   if (e.pointerType === 'mouse') {
-    if (document.pointerLockElement === canvas) turn(look.fromPointer(e.movementX, e.movementY, 'mouse'));
+    if (document.pointerLockElement === canvas)
+      turn(look.fromPointer(e.movementX, e.movementY, 'mouse'));
     return;
   }
   if (!last) return;
@@ -1400,6 +1470,7 @@ Arcade, which draws a small readout in its own chrome. **Your game draws nothing
   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.
@@ -1557,7 +1628,9 @@ first:
       const services = context.sourceCode.parserServices;
       const checker = services.program.getTypeChecker();
       const isPlayerText = (type) =>
-        (type.isUnion() ? type.types : [type]).some((t) => t.getSymbol()?.getName() === 'PlayerText');
+        (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' });
@@ -1607,6 +1680,7 @@ first:
 
   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
@@ -1651,9 +1725,9 @@ accepts, uploading and selling your own, the purchase flow and loading the model
 has **two tabs**, and they are **two separate worn choices** — wearing one never changes the
 other:
 
-| Tab | What the player wears | On `gem.player` and every room member |
-|---|---|---|
-| **2D** | a portrait — a picture | `avatarIconId`, `avatarIconUrl` (`avatar_icon_id`, `avatar_icon_url` on the wire) |
+| Tab    | What the player wears           | On `gem.player` and every room member                                                                             |
+| ------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **2D** | a portrait — a picture          | `avatarIconId`, `avatarIconUrl` (`avatar_icon_id`, `avatar_icon_url` on the wire)                                 |
 | **3D** | a 3D character — a rigged model | `avatar3dId`, `avatar3dModelUrl`, `avatar3dIconUrl` (`avatar_3d_id`, `avatar_3d_model_url`, `avatar_3d_icon_url`) |
 
 - **`avatar3dId`** is the worn 3D character's item id. Absent means none is worn — draw your

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "13.3.3",
+  "version": "13.4.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -1250,7 +1250,28 @@
               "x": { "kind": "int", "min": 0, "max": 16384 },
               "y": { "kind": "int", "min": 0, "max": 16384 },
               "width": { "kind": "int", "min": 0, "max": 16384 },
-              "height": { "kind": "int", "min": 0, "max": 16384 }
+              "height": { "kind": "int", "min": 0, "max": 16384 },
+              "control": {
+                "kind": "object",
+                "optional": true,
+                "$comment": [
+                  "The box of the control this area protects, as drawn: NOT grown to",
+                  "the frame's edges, clipped to the frame, in the same space and",
+                  "rounded outward like the area. The area is a keep-out zone, grown",
+                  "to the nearest edges so nothing lands in the sliver between the",
+                  "control and the edge; its middle is not the control's middle. This",
+                  "is what a game lines its own controls up with, such as a top bar",
+                  "centred on the Gem button. Additive: absent from an older parent,",
+                  "which leaves the game knowing only the keep-out area, and ignored",
+                  "by an older SDK, which never reads it."
+                ],
+                "fields": {
+                  "x": { "kind": "int", "min": 0, "max": 16384 },
+                  "y": { "kind": "int", "min": 0, "max": 16384 },
+                  "width": { "kind": "int", "min": 0, "max": 16384 },
+                  "height": { "kind": "int", "min": 0, "max": 16384 }
+                }
+              }
             }
           }
         }