@indiegems/gem-web-sdk 7.4.0 → 7.4.2

package/docs/brand-art.md

@@ -0,0 +1,334 @@
+# The Gems, Tickets and trophy art
+
+The SDK ships the platform's own art for its two currencies, **Gems** and **Tickets**, and for
+**trophies**. You need it only if your game draws Gems, Tickets or a trophy on its own screens. Read
+§1 before you pick a file: each currency has two kinds of art, and which one you use depends on what
+the screen is for.
+
+**Currency display belongs to the arcade.** The arcade draws the player's Gems and Tickets totals in
+its own chrome while your game runs, and it animates every payout of either into its total. Your game
+draws Gems or Tickets only in the three places §5 allows — an amount on offer or just paid, a reward
+screen, and how much more your game can still pay (the earn allowance) — and never a balance of its
+own. §5 is the creator's ruling and is not optional.
+
+> **The Tickets art is generated art, open to a designer pass.** It was generated on 2026-09-28
+> (gemforge asset `e540c7ac-850c-4ef0-9b9c-f11227098ce6`): a solid tangerine ticket with a vertical
+> gradient, so it never reads as the rainbow gem or the gold trophy. It replaced the first art of
+> 2026-09-27, a ticket cut from the gem's rainbow glass. If a designer redraws it, the new art
+> replaces these files **under the same names** in a later SDK release, so a game that imports them
+> picks it up on its next SDK update. Lay your screens out from the sizes on this page, not from the
+> drawing.
+
+## 1. Two kinds of currency art: pick by the ROLE of the screen
+
+| You are drawing | Use | Drawn at |
+| --------------- | --- | -------- |
+| Gems **inline**, beside a number: a price, a "+15" reward label, a small chip | the **icon**, `gem-icon-20-*` or `gem-icon-32-*` | 16–40 CSS px |
+| Gems as **the subject of a reward presentation**: a victory or reward screen where the gem is what the player looks at, such as a victory overlay with a sunburst behind the reward | the **hero**, `gem-hero-*` | 64–256 CSS px |
+| Tickets **inline**, beside a number | the **icon**, `ticket-icon-20-*` or `ticket-icon-32-*` | 16–40 CSS px |
+| Tickets as **the subject of a reward presentation** | the **hero**, `ticket-hero-*` | 64–256 CSS px |
+
+The role decides first and the size follows from it. A price tag is inline even if you make it
+large; a reward screen is a presentation even on a small phone.
+
+- **Never use the hero at icon sizes.** It is one render drawn to be seen large; shrunk to 20 px its
+  outline goes under a pixel, its facet lines vanish and the gem smudges into the background.
+- **Never use the icon at hero sizes.** Each icon file is a separate render drawn for one small box,
+  with a heavier outline and fewer details than a large gem needs. Stretched, it is visibly coarse.
+- **Nothing ships for 40–64 CSS px.** If a design lands there, it is undecided between the two roles:
+  make the inline element smaller or the presentation bigger.
+
+The **trophy** comes only as a hero (§3). There is no trophy icon.
+
+The Gems and Tickets marks differ in **shape** — a faceted gem, and a ticket with a notch in each
+end — as well as colour, so a player can tell the two apart without seeing colour. Keep the currency's
+name beside or behind every amount (in words, or for a screen reader) all the same.
+
+## 2. The Gems icon
+
+The same icon the arcade draws in its own wallet, rendered from the 3D model of the Gems gem **once
+per display size**, not scaled from one image. Each size is its own render with its own outline
+weight and detail, and each device-pixel ratio of it is rendered on its own pixel grid.
+
+| Rendition | For a CSS box of | File | Pixels |
+| --------- | ---------------- | ---- | ------ |
+| 20 | up to about 24 px | `gem-icon-20-1x.png` | 20 × 20 |
+| | | `gem-icon-20-1.5x.png` | 30 × 30 |
+| | | `gem-icon-20-2x.png` | 40 × 40 |
+| | | `gem-icon-20-3x.png` | 60 × 60 |
+| 32 | above 24, up to about 40 px | `gem-icon-32-1x.png` | 32 × 32 |
+| | | `gem-icon-32-1.5x.png` | 48 × 48 |
+| | | `gem-icon-32-2x.png` | 64 × 64 |
+| | | `gem-icon-32-3x.png` | 96 × 96 |
+
+Each file is square, 8-bit RGBA, with a transparent background. **The gem fills the width of its
+box** — its widest points touch the left and right edges, with clear rows above and below — because
+at 20 px a margin is gem the player loses. Size the box to the gem, and leave any spacing to your
+layout.
+
+The names use `-1.5x`, not `@1.5x`: a Gem web bundle refuses any file name with a character outside
+`A–Z a–z 0–9 . _ -`, and your bundler keeps the name when it copies the file into your build.
+
+### Where the icon comes from
+
+These are the Arcade's own icon renders — the files its wallet draws — with the same pixels, byte
+for byte, apart from stripping the colour-space and resolution tags every browser already assumes. They are the gem
+of the arcade's Gems flight — a 3D model rendered in Blender, a round cut with the icon's six facet
+colours — at rest and without its motion blur, so the gem a player sees in your price is the gem
+that flies into their wallet. Each size has its own recipe, in CSS px, so it carries the same visual
+weight on every screen:
+
+| Size | Outline | Girdle line | Facet lines | Sparkle |
+| ---- | ------- | ----------- | ----------- | ------- |
+| 20 px | 1.5 px | 0.75 px | none | 3 px arms |
+| 32 px | 2 px | 0.8 px | none | 5 px arms |
+
+Both take the render's gleam at a third of its strength and colour the crown's pale centre facet
+light cyan and light yellow. They are PNG rather than WebP because the renderer's WebP is lossy at
+every quality setting and moved a 20 px icon's facet colours visibly. The renders are deterministic
+and the pipeline lives with the platform's art sources; if the gem changes, the platform re-renders
+both sizes and a new SDK release ships them. Never edit the files by hand.
+
+### The Tickets icon
+
+The same two renditions and four ratios, under the same rules: the ticket spans the full width of its
+box, with clear rows above and below it (more of them than the gem, because a ticket is wider than it
+is tall), and each size is drawn on its own grid with its own outline weight — 1.5 px at 20, 2 px at
+32.
+
+| Rendition | For a CSS box of | File | Pixels |
+| --------- | ---------------- | ---- | ------ |
+| 20 | up to about 24 px | `ticket-icon-20-1x.png` | 20 × 20 |
+| | | `ticket-icon-20-1.5x.png` | 30 × 30 |
+| | | `ticket-icon-20-2x.png` | 40 × 40 |
+| | | `ticket-icon-20-3x.png` | 60 × 60 |
+| 32 | above 24, up to about 40 px | `ticket-icon-32-1x.png` | 32 × 32 |
+| | | `ticket-icon-32-1.5x.png` | 48 × 48 |
+| | | `ticket-icon-32-2x.png` | 64 × 64 |
+| | | `ticket-icon-32-3x.png` | 96 × 96 |
+
+It is the hero's ticket — solid tangerine, a notch in each end and a perforated stub (see the note at
+the top of this page) — downscaled onto each file's own pixel grid, inside the gem icon's violet
+outline. The arcade's wallet draws the same ticket from the same master, and a simplified vector
+version of it at 16–20 px.
+
+## 3. The hero art
+
+Three marks — the gem, the ticket and the trophy — each at five sizes. Every file is a square PNG with a
+transparent background, no outline, and the mark centred with a small margin, so the files swap for
+one another at any size without moving your layout.
+
+| File | Pixels |
+| ---- | ------ |
+| `gem-hero-128.png`, `ticket-hero-128.png`, `trophy-hero-128.png` | 128 × 128 |
+| `gem-hero-256.png`, `ticket-hero-256.png`, `trophy-hero-256.png` | 256 × 256 |
+| `gem-hero-384.png`, `ticket-hero-384.png`, `trophy-hero-384.png` | 384 × 384 |
+| `gem-hero-512.png`, `ticket-hero-512.png`, `trophy-hero-512.png` | 512 × 512 |
+| `gem-hero-768.png`, `ticket-hero-768.png`, `trophy-hero-768.png` | 768 × 768 |
+
+The hero is drawn to be displayed at **64 to 256 CSS pixels**. Pick the smallest file at or above the
+size you draw it multiplied by the screen's `devicePixelRatio`:
+
+| Drawn at | 1× screen | 2× screen | 3× screen |
+| -------- | --------- | --------- | --------- |
+| 64 px | 128 | 128 | 256 |
+| 128 px | 128 | 256 | 384 |
+| 256 px | 256 | 512 | 768 |
+
+**Do not draw it larger than 256 CSS pixels.** On a 3× screen that needs more than the largest file,
+and the art softens as it is stretched. Below 64 px, use the icon (§2).
+
+## 4. Loading and drawing the art
+
+All of it is in the package you already install, under `brand/`, and published beside it on the CDN —
+the same bytes either way, for the version you are on.
+
+### In a game with a bundler
+
+Import the file by its path in the package. Your bundler copies it into your build and hands you its
+URL, so it loads from your game's own origin like the rest of your art, and only the files you import
+reach a player:
+
+```js
+import g20x1 from '@indiegems/gem-web-sdk/brand/gem-icon-20-1x.png';
+import g20x15 from '@indiegems/gem-web-sdk/brand/gem-icon-20-1.5x.png';
+import g20x2 from '@indiegems/gem-web-sdk/brand/gem-icon-20-2x.png';
+import g20x3 from '@indiegems/gem-web-sdk/brand/gem-icon-20-3x.png';
+```
+
+The package is the one [getting-started.md](getting-started.md) installs; there is nothing else to
+add. **In TypeScript, the type of a `.png` import comes from your bundler, not from this package**:
+with Vite, that is `vite/client` in your `tsconfig.json` `types`. Vite inlines a file under 4 KB as a
+`data:` URL rather than copying it, which several of the small icon files are; that works, and
+`build.assetsInlineLimit` changes it if you want every file as its own request.
+
+### The icon in an `<img>`
+
+Offer all four files in **width descriptors** and set `sizes` to the CSS box you draw it in, so the
+browser picks the file for that box on this screen:
+
+```js
+const gem = document.createElement('img');
+gem.src = g20x1;
+gem.srcset = `${g20x1} 20w, ${g20x15} 30w, ${g20x2} 40w, ${g20x3} 60w`;
+gem.sizes = '20px'; // the CSS box: the same value as the width and height below
+gem.width = 20;
+gem.height = 20;
+gem.alt = ''; // decorative: the amount beside it says "Gems" in words or to a screen reader
+priceRow.append(gem, document.createTextNode(' 250'));
+```
+
+For the 32 rendition, the widths are `32w, 48w, 64w, 96w`. If your box is in `rem`, set `sizes` in
+the same `rem` — `sizes` is how the browser knows the box, and a wrong value picks a blurry file.
+
+### The icon as a CSS background
+
+`image-set()` picks by device-pixel ratio. Keep a plain `background-image` first for a browser that
+lacks it:
+
+```js
+const chip = document.querySelector('.gems-chip-icon');
+chip.style.backgroundImage = `url("${g20x2}")`;
+chip.style.backgroundImage = `image-set(url("${g20x1}") 1x, url("${g20x15}") 1.5x, url("${g20x2}") 2x, url("${g20x3}") 3x)`;
+```
+
+```css
+.gems-chip-icon {
+  width: 20px;
+  height: 20px;
+  background: center / contain no-repeat;
+}
+```
+
+### The icon on a canvas, or as a Pixi or three.js texture
+
+A canvas has no `srcset`. **Load the 3x file of the rendition your box calls for, and scale it
+down** — never up:
+
+```js
+// 2D canvas: a 20 CSS px icon at (x, y) in CSS px, on a canvas scaled for devicePixelRatio.
+const img = new Image();
+img.src = g20x3; // 60 px: enough for any screen up to 3x
+await img.decode();
+ctx.imageSmoothingQuality = 'high';
+ctx.drawImage(img, x, y, 20, 20);
+```
+
+```js
+// PixiJS
+const texture = await PIXI.Assets.load(g20x3);
+const gem = new PIXI.Sprite(texture);
+gem.width = gem.height = 20;
+```
+
+```js
+// three.js: an icon on a HUD sprite
+const map = new THREE.TextureLoader().load(g32x3);
+map.colorSpace = THREE.SRGBColorSpace;
+const gem = new THREE.Sprite(new THREE.SpriteMaterial({ map, transparent: true }));
+```
+
+Keep mipmapping on (three.js does by default) so the scaled-down icon stays crisp rather than
+shimmering.
+
+### The hero
+
+The same import, and a `srcset` in density descriptors, picked per §3:
+
+```js
+import gem256 from '@indiegems/gem-web-sdk/brand/gem-hero-256.png';
+import gem512 from '@indiegems/gem-web-sdk/brand/gem-hero-512.png';
+
+const art = document.createElement('img');
+art.src = gem256;
+art.srcset = `${gem256} 1x, ${gem512} 2x`;
+art.alt = ''; // decorative: say "Gems" in the text beside it
+```
+
+The same URL works as a texture — `new THREE.TextureLoader().load(gem512)` — because it is your own
+origin.
+
+### Without a bundler, or from another engine
+
+Every file is also published at a permanent URL, under the version you install:
+
+```text
+https://downloads.gemarcade.com/sdk/v<version>/brand/gem-icon-20-2x.png
+https://downloads.gemarcade.com/sdk/v<version>/brand/gem-hero-256.png
+```
+
+The CDN lets any origin read these files, so a canvas or a WebGL texture can use one — set
+`crossOrigin = 'anonymous'` on the image before its `src`, or the texture is refused as tainted. A
+path never changes once published, so a URL you ship keeps working, and `artifact-manifest.json` in
+the same version folder lists each file's `sha384` hash under `brand`.
+
+**Prefer copying the file into your build over loading it by URL at play time.** A load at play time
+is one more request that can be slow or fail, and your screen then shows a gap where the art should
+be. If you do load it live, lay the screen out so it reads correctly without the image.
+
+### The platform currency's `icon_url`
+
+gem-api's public platform currency catalogue, `GET /v1/inventory/currencies`, returns each platform
+currency with an `icon_url`. For Gems that is one rendered icon image, being set now. It exists for
+an engine or a tool that cannot bundle files and needs to ask the platform what Gems look like.
+**A bundled game should prefer the renditions in this package**: they come in two sizes and four
+densities, and they cost no request at play time.
+
+## 5. The rules: Gems and Tickets display belongs to the arcade
+
+The creator's ruling (2026-09-24): **"Gems display belongs to the arcade."** Tickets, the platform's
+second currency, is held to the same ruling: read every rule below about Gems as a rule about Tickets
+too, with the ticket in place of the gem. Amended 2026-09-30 for the earn allowance (the platform's
+decision of that date); the ruling's other rules are unchanged. In rules:
+
+- **Keep no Gems counter.** Your game shows no Gems balance, running total or wallet of its own, on
+  any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown.
+- **Draw no Gems flight or celebration of your own.** No particles flying to a corner, no counting-up
+  number, no burst of gems. `gem.cueReward` is the animation, and the arcade draws it.
+- **Show no Gems amount at all when you are not connected to the arcade.** Without the arcade there is
+  nothing to pay from and nothing to accrue to, so a price or a reward in Gems means nothing. Hide
+  every Gems element unless `gem.awaitBridge()` settled `connected` (and `onStateChange` has not
+  since reported otherwise).
+- **At a payout, cue the arcade from your gem:**
+
+  ```js
+  const { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem element itself
+  gem.cueReward({
+    currencySlug: 'GEMS',
+    expected: 15,
+    origin: { x: x + width / 2, y: y + height / 2 },
+  });
+  ```
+
+  `origin` is the **centre of the Gems icon (or hero) on screen**, in CSS px of your game's own
+  viewport. Measure that gem element's own box — not the row, the chip or the panel around it — so
+  the flight leaves from the gem the player is looking at. On a canvas, convert from canvas pixels
+  with the canvas's `getBoundingClientRect()`.
+
+  A Tickets payout is cued the same way, from the ticket, with `currencySlug: 'ARCADE_TICKETS'`. The
+  arcade's wallet shows Gems and Tickets side by side and flies each payout into the total of the
+  currency the cue names, so the slug is what decides where your ticket lands.
+- **If `cueReward` returns `false`, do nothing.** There is no fallback celebration. `false` means the
+  arcade will not show the payout here — the bridge is not up, or the embedder has no wallet — and
+  your game does not replace it with one of its own. Your reward screen still says what was earned;
+  it just does not animate Gems anywhere.
+- **Draw the art as it is.** Scale it and place it freely; do not recolour it, tint it, greyscale it
+  for a disabled state, crop it, add an outline or a drop shadow, or redraw it. A player learns these
+  marks on the arcade, and a variant reads as a different thing.
+- **The gem means Gems, the platform's currency** — never your own currency. Next to a number it
+  states an amount of Gems, so show only amounts the platform pays, charges or reports: the reward
+  your mapping grants, the price the platform charges, and the remaining earn allowance read from
+  `gem.platform.earnAllowance.get()` ("40 Gems left to earn today"). The icon may sit beside that
+  figure. It is still not a balance, a counter or a running total, and it is never a number your game
+  computes. Your server's order response is the receipt, not your screen.
+- **The ticket means Tickets, the platform's cosmetics currency** — never your own currency, and
+  never a raffle, an entry or a pass. The gem rule above applies to it word for word.
+- **The trophy means an achievement**: use it where your game shows what a player has earned.
+  Whether the trophy also becomes the mark of the player's Achievement Score — the sum of their
+  achievement points, which the arcade now shows — is an open design question; until it is answered,
+  use the trophy for achievements.
+- **Never inside a panel dressed as the arcade's own screens.** A player must always be able to tell
+  your game from the platform, most of all where money or an account is involved.
+
+How a payout reaches the wallet, and what the arcade does with the cue:
+[inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet).

package/docs/cross-promotion.md

@@ -0,0 +1,137 @@
+# Cross-promotion
+
+The Arcade can show a **full-screen panel about another game** at a break in yours. Your game asks
+for one; the Arcade decides whether to show anything, draws it in its own chrome over your paused
+game, and tells you when it is done.
+
+```js
+const { outcome } = await gem.ads.requestAd({
+  placement: 'level-complete',
+  format: 'interstitial',
+});
+// Nothing to handle. Carry on.
+startNextLevel();
+```
+
+That is the whole surface. The rest of this page is the four things a game gets wrong when nobody
+tells it.
+
+## 1. The answer is usually no, and no is ordinary
+
+`outcome` is one of exactly three values:
+
+| outcome | what happened | what your game does |
+|---|---|---|
+| `no_ad` | nothing was shown | carry on exactly as if you had not asked |
+| `shown` | a panel was painted and has closed | carry on — and grant nothing |
+| `unavailable` | the Arcade could not draw one just now | carry on; read it identically to `no_ad` |
+
+**`no_ad` is the common answer**, not an edge case. There may be nothing suitable, the player may
+be somebody the Arcade will not interrupt, or the break may simply be too soon after the last one.
+You are not told which, and there is nothing to infer.
+
+So write the `no_ad` path as your ordinary path:
+
+- Do **not** render a placeholder, a spinner, or a "nothing to show right now" message. Empty means
+  nothing appears.
+- Do **not** hold up your own flow waiting for a fill. Ask, and continue when the promise settles.
+- Do **not** retry on a no. A second ask at the same break gets the same answer and spends a slot.
+
+## 2. Nothing rejects
+
+`requestAd` always resolves. There is no error branch and no `try`/`catch` to write. Even a refusal
+of your own arguments — a `placement` outside the grammar below, a `format` outside the two —
+resolves `no_ad`, so your game keeps exactly one branch. (The mistake is still reported to your
+`onError` handler, so you find out in development.)
+
+## 3. ⚠️ `shown` grants nothing
+
+`shown` says a panel was painted and has closed. It is **not** a receipt, **not** an entitlement,
+and **not** permission to hand anything out.
+
+`format: 'rewarded'` exists in the vocabulary and is answered `no_ad` today. Even when that
+changes, a reward will be granted by the platform against its own record of what was shown — never
+by your game reading an outcome. An outcome travels over the same channel as everything else your
+frame receives, and a game that unlocks a level or grants a currency on the strength of one has an
+unlock that any page embedding your game can forge.
+
+Treat a break as a break. If your game wants to give the player something for reaching the end of a
+level, give it to them for reaching the end of the level.
+
+**Where a rewarded grant will arrive, so you can write the code now.** On your game's own inventory
+for this player, written by the platform — never by your game — and read through
+`gem.me.inventory`, the same place a purchase lands, read the same way. (That is the game-scoped
+inventory `gem.me` shows you, not the player's platform wallet.) There will be **no fourth outcome
+and no extra field** on the answer. `outcome` is pinned at three values because a new value would
+break every game bundle already in the field: its validator refuses the whole message. A new field
+would not break anything — validators ignore fields they do not know — but it is not coming either:
+anything on that answer can be forged by the page embedding your game, so a reward carried there
+would be a reward anyone could hand out. If you serve `rewarded`, re-read your snapshot once the ask
+settles, whatever it settled as:
+
+```js
+await gem.ads.requestAd({ placement: 'run-banked', format: 'rewarded' });
+gem.me.inventory.refresh(); // drop what is cached
+const snap = await gem.me.inventory.snapshot(); // the grant, if there was one, is here
+```
+
+Today that re-read finds nothing new, because nothing is served. It costs one request at a break
+your player is already sitting in, and it is the whole of what changes on the day one is — no
+rebuild. [`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the
+general form of this.
+
+## 4. The Arcade pauses your game for you
+
+While a panel is up, your game is paused the same way it is paused when a player switches tabs —
+the Arcade sends the pause your game already handles, and lifts it when the panel closes. You do
+not need to pause anything yourself, and you should not resume on a timer: resume when the promise
+settles.
+
+If you have not wired the pause at all yet, that is the thing to fix first;
+[`what-a-game-must-do.md`](what-a-game-must-do.md) covers it.
+
+## Where to put the call
+
+At a break **the player already expects**: a level ending, a round finishing, a run being banked, a
+return to a menu. Never mid-input, never during a timed sequence, and never on a screen the player
+reached by accident.
+
+`placement` is your own name for that break — `level-complete`, `run-banked`, `back-to-menu`. The
+platform matches it against nothing today, never shows it to a player, and does not vary its
+decision on it. It exists so your own analytics can tell two break points apart, so name it for
+yourself.
+
+**It has a grammar, and it is narrow on purpose: 1 to 32 characters of `a-z`, `0-9`, `-` and `_`.**
+Lowercase, no spaces, no accents — `'Boss Fight'` is not a placement, `'boss-fight'` is. Anything
+else resolves `no_ad` and is reported to your `onError` handler, so you meet it while you are
+building rather than later. The reason it is enforced now, while nothing depends on it, is that
+this is the field a promotion is eventually **keyed by**: the Arcade will forward it unchanged, and
+a name that does not fit the platform's grammar would be a name that stopped working after your
+game had shipped. The bound is the platform's, not the SDK's, and the two agree.
+
+```js
+async function onLevelComplete() {
+  showResultsScreen();
+  await gem.ads.requestAd({ placement: 'level-complete', format: 'interstitial' });
+  // Settled either way. The results screen is still up; the player taps Next.
+  enableNextButton();
+}
+```
+
+## What never crosses
+
+Your game never learns what was shown — no title, no image, no id, nothing about the other game.
+You receive an outcome and nothing else.
+
+You are also never told *why* the answer was no. That is deliberate and permanent: a reason would
+tell your game something about the player that game code is not told, and there will not be a
+fourth outcome value naming one. The Arcade also settles every `no_ad` and `unavailable` on a
+schedule that does not depend on which branch produced it, so there is nothing in the timing to
+read either. (`shown` is not held back — how long that one takes is how long your player spent
+looking at a panel.)
+
+## If you do nothing
+
+Nothing happens. A game that never calls `gem.ads.requestAd` is never interrupted, and the call is
+not on the list of things a game must do to ship. This page exists for games that want a break to
+be worth something.