@indiegems/gem-web-sdk 13.0.0 → 13.2.0

package/docs/platform-moments.md

@@ -0,0 +1,266 @@
+# Platform moments
+
+At every natural break in play — a level ending, a run over, a match's results, a return to the
+menu — your game signals a **platform moment**. The Arcade then decides, on its own servers,
+whether to show one of **its own** offers over your paused game: a break video, the Arcade app, a
+platform store offer, a subscription, another game. Usually it shows nothing.
+
+```js
+// From the press that LEAVES the break — Next, Retry, Back to menu.
+async function onNextPressed() {
+  startLevelTransition(); // your fade or loading beat, in parallel
+  const { shown } = await gem.moments.signal({ kind: 'level_end' });
+  startNextLevel(); // settled either way; never grant anything on `shown`
+}
+```
+
+**Every game signals a moment at every break**, whether or not it has a shop of its own. The
+release checklist requires it (§11). That is the whole surface; the rest of this page is where to
+put the call, where never to, and the few things a game gets wrong when nobody tells it.
+
+- [1. A platform moment is not your own offer](#1-a-platform-moment-is-not-your-own-offer)
+- [2. The five kinds](#2-the-five-kinds)
+- [3. Where to call it, and where never to](#3-where-to-call-it-and-where-never-to)
+- [4. The answer is usually `false`, and false is ordinary](#4-the-answer-is-usually-false-and-false-is-ordinary)
+- [5. Nothing rejects](#5-nothing-rejects)
+- [6. `shown` grants nothing](#6-shown-grants-nothing)
+- [7. The Arcade pauses your game for you](#7-the-arcade-pauses-your-game-for-you)
+- [8. Multiplayer](#8-multiplayer)
+- [9. What never crosses](#9-what-never-crosses)
+- [10. Testing it in the dev host](#10-testing-it-in-the-dev-host)
+- [11. The release requirement](#11-the-release-requirement)
+- [12. Moving off `format: 'interstitial'`](#12-moving-off-format-interstitial)
+
+## 1. A platform moment is not your own offer
+
+Two kinds of upsell can happen in a game, and they never mix.
+
+|                     | **Platform moment** (this page)                                                                                 | **Your game's own offer**                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Who decides         | the Arcade, on its servers                                                                                      | your game                                                     |
+| What it shows       | platform things only: break videos, the Arcade app, platform store offers, subscriptions, other games          | your own items, currencies and rewarded buttons               |
+| When                | only at a moment your game signals, paced by the platform                                                       | whenever your game likes, on its own cadence                  |
+| Drawn by            | the Arcade's own chrome, over your paused game                                                                  | your game's own UI                                            |
+| What your game learns | `shown: true` or `false`, nothing else                                                                        | everything — it is yours                                      |
+
+Three rules follow from it:
+
+- **A platform moment never shows your game's own items, and your game never routes its own offer
+  through one.** Your shop, your special offers and your rewarded buttons
+  ([`rewarded-ads.md`](rewarded-ads.md)) stay yours, in your UI, on your schedule.
+- **Signal every natural break, whether or not your game has a shop of its own.** The moment is
+  about the break, not about what your game sells.
+- **No stacking.** When a moment settles `shown: true`, do not also pop your own offer at that
+  break. Your normal results screen and its shop button are fine; a second popup in the same breath
+  is not.
+
+## 2. The five kinds
+
+`kind` is required, and it is one of five. The set is closed and will not grow: a game written
+today never meets a sixth.
+
+| `kind`        | the break                                                                                     | for example                                                              |
+| ------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `level_end`   | a level, stage, wave or puzzle finished, won or lost                                          | a platformer's stage clear, a puzzle solved, a tower-defence wave beaten |
+| `run_end`     | game over, death, or a run banked                                                             | an endless runner's crash, a roguelike death, an arcade game's last life |
+| `match_end`   | a multiplayer round or match finished, and the player is leaving its results                  | a battle royale's results, a card game's round, a race's podium          |
+| `menu_return` | the player chose to go back to the title, a main menu or level select — a return, never the first arrival | Back to menu on a results screen, Quit to menu from the pause menu       |
+| `other_break` | any other natural stop                                                                        | the end of a story chapter, a between-waves shop                         |
+
+`kind` is a **label**. The Arcade uses it for its own analytics, the dev host prints it (§10), and
+the release checklist reads it (§11). It never changes what the Arcade decides for your game, so
+there is nothing to gain by choosing one kind over another: pick the one that describes the break.
+
+`placement` is optional: your own name for the screen the player is leaving — `world-1-3`,
+`results`, `pause_quit`. It has the grammar every name you hand the SDK has, **1 to 32 characters of
+`a-z`, `0-9`, `-` and `_`**, and it appears in exactly one place: the dev host's log, so a reviewer
+can map each moment to a screen. It is never sent to the platform, never stored, never shown to a
+player and never sent to an ad network.
+
+```js
+await gem.moments.signal({ kind: 'run_end', placement: 'desert-run' });
+```
+
+## 3. Where to call it, and where never to
+
+**From the player's press that leaves the break** — Next, Retry, Continue, Back to menu. The
+results screen stays fully interactive until then: the player reads their score, looks at the
+leaderboard, opens your shop. When they press to leave, your game starts its own transition (a fade,
+a loading beat) and signals at the same moment, in parallel, and starts play when the promise
+settles. Usually nothing was shown and the answer arrives inside your transition, so the player
+never sees a wait.
+
+Once per break. A break with three ways out signals from whichever press the player made, not from
+all three.
+
+**Never:**
+
+- mid-input, or during a timed sequence — a jump, a countdown, a combo;
+- on a timer, or on a schedule of your own;
+- on boot, or on the first arrival at the title screen — a `menu_return` is a **return**;
+- from a pause menu the player opened, just because it opened — choosing **Quit to menu** from it
+  **is** a `menu_return`, signalled from that press;
+- more than once at one break.
+
+No press is required by the SDK: the rule is about when a break really is one, not about user
+activation.
+
+## 4. The answer is usually `false`, and false is ordinary
+
+The promise resolves `{ shown }`, one boolean:
+
+| `shown` | what happened                                                    | what your game does                       |
+| ------- | ---------------------------------------------------------------- | ----------------------------------------- |
+| `false` | nothing was shown                                                | carry on exactly as if you had not asked  |
+| `true`  | the Arcade showed something of its own, and it has closed        | carry on — and grant nothing (§6)         |
+
+**`false` is the common answer**, not an edge case. The Arcade paces what it shows, gives a new
+player time before it shows anything, and has nothing suitable more often than not. You are not told
+which, and there is nothing to infer.
+
+- Do **not** render a placeholder, a spinner or a "nothing right now" message.
+- Do **not** hold your game's flow on a fill. Start your transition, signal, and continue when the
+  promise settles.
+- Do **not** retry on a `false`. A second signal at the same break is refused (§5).
+
+## 5. Nothing rejects
+
+`gem.moments.signal` always resolves. There is no error branch and no `try`/`catch` to write. When
+the SDK refuses a signal itself, it resolves `{ shown: false }` without asking the Arcade, and calls
+your `onError` handler with code `'internal'` and a message that **begins with a stable token**, so
+you find the mistake while you build:
+
+| token                       | when                                                                                               |
+| --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `moments_unsupported`       | the page your game runs in does not do platform moments. Keep the call; it costs nothing. Said once a session |
+| `moments_invalid_argument`  | a `kind` outside the five, or a `placement` outside the grammar                                    |
+| `moments_before_ready`      | a signal before `gem.frame.ready()` — play has not started, so there is no break                   |
+| `moments_in_flight`         | a second signal while the first is still waiting for its answer                                    |
+| `moments_called_repeatedly` | a signal within 10 seconds of the last moment's answer — one break signalled twice, or a timer     |
+| `moments_timeout`           | no answer within three minutes                                                                     |
+
+The 10 seconds count from the last **answer**, not the last call, so a long panel does not eat into
+the next level. A refused signal does not restart the count.
+
+Match on the token, not the rest of the message:
+
+```js
+const gem = createGem({
+  onError: (code, message) => {
+    if (message?.startsWith('moments_') && !message.startsWith('moments_unsupported')) {
+      reportBug('platform moment refused', message); // your own telemetry
+    }
+  },
+});
+```
+
+## 6. `shown` grants nothing
+
+`shown: true` says the Arcade showed something of its own and it has closed. It is **not** a
+receipt, **not** an entitlement, and **not** permission to hand anything out. Nothing on this call
+pays the player, and a game that unlocks a level or grants a currency on the strength of it has an
+unlock any page embedding your game can forge.
+
+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.
+
+## 7. The Arcade pauses your game for you
+
+While the Arcade shows something, your game is paused the same way it is when a player switches
+tabs — the Arcade sends the pause your game already handles, and lifts it when the panel closes.
+You do not pause anything yourself, and you never resume on a timer: resume when the promise
+settles. If you have not wired the pause yet, that is the thing to fix first;
+[`what-a-game-must-do.md`](what-a-game-must-do.md) covers it.
+
+## 8. Multiplayer
+
+Signal `match_end` as the player leaves a match's results, exactly as a single-player game signals
+`level_end`. What the Arcade may show to a player who is still in a live room or a party about to
+start is the Arcade's decision, made from its own knowledge of the room — never from the `kind`
+your game sent — so there is nothing extra for your game to do, and nothing to hold back. The
+Arcade does not keep a player who is about to play waiting on an offer.
+
+## 9. What never crosses
+
+Your game never learns what was shown — no title, no image, no offer, no id. It receives one
+boolean.
+
+You are also never told **why** nothing was shown. That is deliberate and permanent: the reasons
+include pacing, a new player's grace, the player's account, age and consent, and a reason would
+tell your game something about the player that game code is not told. There will not be a second
+field naming one. The Arcade also settles every `false` on a schedule that does not depend on why,
+so there is nothing in the timing to read either. (`true` is not held back — how long that one
+takes is how long your player spent with a panel.)
+
+## 10. Testing it in the dev host
+
+`gemctl serve` and the Gem Editor's dev host answer moments the way the Arcade does, with a TEST
+panel in place of a real offer. (Both dev hosts gain this in their own releases after the SDK that
+ships `gem.moments`. Until yours has it, a moment there answers `false`, and your `onError`
+handler hears `moments_unsupported` once.)
+
+> **Platform moment · level_end · world-1-3**
+> In the Gem Arcade, an offer of the Arcade's own may appear here. Usually nothing does. Your game
+> is paused until this closes.
+> **[Close]**
+
+Add `?moments=` to the dev host's page to choose what it does:
+
+| mode      | what the dev host does                                                                    |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `none`    | shows nothing, and answers `false` after the same short wait the Arcade holds             |
+| `panel`   | shows the TEST panel at every moment                                                      |
+| `paced`   | shows the panel at most once every three minutes, so you see the real frequency          |
+| `video`   | the longest path: a ten-second break video, then its result                               |
+| `delayed` | paints the panel late, to test a player who presses Continue before it arrives            |
+
+Each moment writes **one log line**, in the same form on every dev host:
+
+```text
+moment kind=level_end placement=world-1-3 since_ready_ms=84210 since_prev_ms=61005 answer=not_shown
+```
+
+`since_ready_ms` is how long after `gem.frame.ready()` the moment arrived, `since_prev_ms` how long
+after the previous one (`-` for the first), and `answer` is `shown` or `not_shown`. A
+`placement` you did not give is `-`, and a deprecated interstitial ask is logged on the same line as
+`kind=legacy`. The grammar of the line is published with the SDK, as
+`@indiegems/gem-web-sdk/schema/moment-log-line.json`.
+
+Play through every break in your game once and read the log: every results, game-over and
+back-to-menu screen should have produced a line, with the `kind` you meant, and none should appear
+on boot, mid-level or seconds apart. That log is what the release checklist reads (§11).
+
+## 11. The release requirement
+
+The release checklist requires platform moments, as a platform requirement every game meets:
+
+- **MOM-01 — every natural break signals a platform moment.** The checklist inventories your
+  breaks from your code and from a play-through under `gemctl serve`, and expects a log line for
+  each. A game with no moments at all does not pass; a break with no signal is a finding to fix.
+- **MOM-02 — never at the wrong time.** No signal right after `ready()`, none on a regular
+  interval, none twice at one break, none mid-input and none from opening a pause menu. The log
+  line is how the first three are checked.
+- **MOM-03 — no stacking** (advisory): no popup of your own at a break that settled
+  `shown: true`.
+
+**The platform itself does not enforce any of this.** Publishing never refuses a game for missing
+moments, the Arcade never refuses to run one, and `gemctl`'s doctor warns rather than fails. The
+checklist is where it is required, and it is required there at every important break.
+
+## 12. Moving off `format: 'interstitial'`
+
+`gem.ads.requestAd({ placement, format: 'interstitial' })` is **deprecated**. It still works, and
+the Arcade treats it as a platform moment, but `14.0.0` is the earliest release that may remove it
+([`deprecation-policy.md`](deprecation-policy.md)). Replace it at the same break, and move the call
+to the press that leaves the break if it was made as the results screen opened:
+
+```js
+// Before
+await gem.ads.requestAd({ placement: 'level-complete', format: 'interstitial' });
+
+// After — from the Next press
+await gem.moments.signal({ kind: 'level_end', placement: 'level-complete' });
+```
+
+`format: 'rewarded'` is not deprecated and does not change: a button the player presses for a
+reward is your game's own offer, and [`rewarded-ads.md`](rewarded-ads.md) is its page.

package/docs/rewarded-ads.md

@@ -204,10 +204,11 @@ cannot tell which input caused the ask: a browser counts any tap in your game fo
 and the SDK counts any controller input for one, so an ask from your jump button's handler, or
 from a death a second after a tap, goes through.
 Making the ask only from the button is yours to get right.
-[`cross-promotion.md`](cross-promotion.md#where-to-put-the-call) has the handler.
 
-The answer is one of the same three outcomes every `requestAd` gets — `shown`, `no_ad` or
-`unavailable` — and for `rewarded` none of them says whether a reward was granted. What can happen
+The answer is one of three outcomes — `shown`, `no_ad` or `unavailable`, the last two read
+identically — and it never rejects: even a `placement` outside the grammar resolves `no_ad`, and
+the mistake goes to your `onError` handler. For `rewarded` none of the three says whether a reward
+was granted. What can happen
 after a press:
 
 | what happened                                                                             | was the reward granted?                                                                                                                             |
@@ -230,7 +231,7 @@ player already holds before asking for another (§5's code does both).
 A granted reward shows in your order history like any other change, as an order the platform made
 with `source` `reward`.
 
-**While the ad plays, your game is paused,** the same way it is for an interstitial: the Arcade
+**While the ad plays, your game is paused,** the same way it is at a [platform moment](platform-moments.md): the Arcade
 sends the pause your game already handles and lifts it when the ad closes. Resume when the promise
 settles, not on a timer. A second `requestAd` while one is still in flight resolves `no_ad` at once,
 so disable the button between the press and the answer.
@@ -301,13 +302,28 @@ a cap is spent, a cooldown runs, the player holds `max_held`, or rewarded is off
 drawing on it never offers a press that is certain to pay nothing. Hide or grey the button out
 otherwise, and say when it is back from `nextEligibleAt` or `resetsAt`. `grantable` is not a
 promise: a press can still pay nothing for reasons the read never reports. The status reserves
-nothing, and it never rejects. See [cross-promotion.md](cross-promotion.md):
+nothing, and it never rejects:
 
 ```js
 const status = await gem.ads.rewardedStatus('classic_revive');
 watchAdButton.hidden = !status.grantable;
 ```
 
+| field              | what it says                                                               |
+| ------------------ | -------------------------------------------------------------------------- |
+| `declared`         | the config promoted to the channel being played names this placement       |
+| `grantable`        | pressing the button could pay right now — **not** that an ad will play     |
+| `remainingToday`   | grants left today under the daily cap; absent when the placement has none  |
+| `nextEligibleAt`   | when a running cooldown ends, in epoch milliseconds; absent when none runs |
+| `heldLimitReached` | the player already holds the placement's `max_held` — spend one first      |
+| `resetsAt`         | when today's count resets, the next 00:00 UTC, in epoch milliseconds       |
+
+Without a play token, when the read fails or takes longer than ten seconds, or for a placement
+outside the grammar, it answers not declared and not grantable with no `resetsAt`, and the reason
+goes to your `onError` handler. It is a read of the platform, so call it when you draw the button
+— on a results or death screen — not every frame, and draw the rest of the screen first rather than
+holding it on the answer.
+
 For a revive, the screen reads what it needs **when it opens**, so the press itself can ask at
 once:
 
@@ -437,10 +453,11 @@ platform sets them all. A rewarded reward is your economy, so the caps are yours
 
 ## 7. Pacing
 
-- **A rewarded ask is never held back by an interstitial.** A player who presses your button is not
-  refused because a promotion played a minute ago, in your game or another.
-- **An ad that starts holds off the next interstitial.** Do not follow a rewarded ad with an
-  interstitial at the same break; that ask answers `no_ad`.
+- **A rewarded ask is never held back by a platform moment.** A player who presses your button is
+  not refused because the Arcade showed something a minute ago, in your game or another.
+- **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

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

package/docs/serverless-functions-js.md

@@ -1,5 +1,16 @@
 # Serverless functions in JavaScript
 
+⚠️ **JavaScript functions are disabled for now, due to performance issues. Write a new function in
+Rust.** A JavaScript function runs many times slower on the platform than the same function built
+from Rust as a WebAssembly component, too slow to fit a call's CPU limit, so uploading a new
+JavaScript function is refused with `400 js_functions_disabled`: "New JavaScript functions are not
+accepted: build the function as a WebAssembly component from Rust (the gem:functions world, target
+wasm32-unknown-unknown) and finalize it with kind `component`. Versions already published as
+JavaScript keep running." [serverless-functions.md](serverless-functions.md#3-writing-one) shows how
+to write one in Rust. A JavaScript function you have already published keeps running: it is still
+listed, you can still promote it to a channel or roll back to it, and players' calls still reach
+it. This page stays for those functions, and for when JavaScript functions come back.
+
 A serverless function can be written in JavaScript or TypeScript instead of Rust: the language your
 game is already written in, so the verification code in your browser game moves into a function
 with no change beyond bundling. You upload one bundled ES module, and the platform runs it on a
@@ -218,7 +229,9 @@ gemctl function check functions/score-check/dist/function.js
 ```
 
 `check` runs the platform's publish-time validation for JavaScript on your machine, and an upload
-runs it first and answers `400 source_invalid` with the same `details.reason`:
+runs it first and answers `400 source_invalid` with the same `details.reason`. While JavaScript
+functions are disabled (the notice at the top of this page), an upload is refused with
+`400 js_functions_disabled` before any of these checks run.
 
 | Reason             | What it usually is                                                                          | What to change                                    |
 | ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
@@ -234,6 +247,9 @@ JavaScript; it does not accept TypeScript, so upload what your build wrote.
 
 ## 5. Publishing
 
+While JavaScript functions are disabled, a new JavaScript version cannot be uploaded; promoting a
+version you already published, and rolling back to one, work as before.
+
 Uploading, promoting, rolling back and channels are the same as for a component
 (serverless-functions.md sections 4 and 5). On the website, the **Functions** tab of your game's
 **Builds** page promotes a version to a channel, rolls back by promoting an earlier one, and shows

package/docs/serverless-functions.md

@@ -55,10 +55,15 @@ possible.
 
 ## 2. What a function is
 
-A function is one WebAssembly **component** or one JavaScript module per game per channel. A
-JavaScript module is written against the SDK instead, and
-[serverless-functions-js.md](serverless-functions-js.md) covers what differs for one. A component
-is built against the platform's `gem:functions` world, and exports exactly one function:
+A function is one WebAssembly **component** per game per channel, built from Rust.
+
+⚠️ **JavaScript functions are disabled for now, due to performance issues. Write your function in
+Rust.** Uploading a new JavaScript function is refused with `400 js_functions_disabled`. A
+JavaScript function you have already published keeps running, and
+[serverless-functions-js.md](serverless-functions-js.md) still covers it.
+
+A component is built against the platform's `gem:functions` world, and exports exactly one
+function:
 
 ```wit
 export handle: func(input: list<u8>) -> result<list<u8>, string>;
@@ -467,9 +472,9 @@ decision point, such as the end of a run or a claim, and never on a timer or onc
 
 ## 3. Writing one
 
-The reference toolchain for a component is Rust; to write a function in JavaScript or TypeScript,
-see [serverless-functions-js.md](serverless-functions-js.md). gemctl writes the starter crate and
-wraps what your build produces, and the build in between is yours:
+A function is written in Rust and built into a component; JavaScript functions are disabled for
+now, due to performance issues (section 2). gemctl writes the starter crate and wraps what your
+build produces, and the build in between is yours:
 
 ```bash
 gemctl function init functions/score-check
@@ -844,6 +849,7 @@ Publishing has its own refusals, and nothing is stored when one happens:
 | What you get                     | What happened                                                                                                                                        | What to do                                               |
 | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | `400 component_invalid`          | The backend's check refused the component. `details.reason` is one of the five in section 3, or `sha256_mismatch`, `size_mismatch` or `not_uploaded` | The five: fix and rebuild. The other three: upload again |
+| `400 js_functions_disabled`      | You uploaded a JavaScript function. JavaScript functions are disabled for now, due to performance issues; versions already published as JavaScript keep running | Write it in Rust and upload the component (section 3) |
 | `409 function_version_exists`    | That version string is taken, perhaps by a deleted version not yet purged                                                                            | Choose another version                                   |
 | `409 function_version_in_use`    | You tried to delete a version a channel still serves                                                                                                 | Promote another version there, or unassign it first      |
 | `404 function_version_not_found` | No such version, or it has been deleted                                                                                                              | `gemctl function list --all --include-deleted`           |