@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/game-economy-tutorial.md

@@ -0,0 +1,326 @@
+# Building a shop, step by step
+
+This builds a working shop: a currency, an item, a purchase, and the screen a player buys from. It
+is the safe version — the one where the server does the arithmetic — and it is written to be
+followed in order.
+
+Read [`inventory-and-catalogs.md`](inventory-and-catalogs.md) first for the concepts; this is the
+recipe.
+
+**Before you start**, you need two things this document assumes:
+
+- **The `gemctl` command-line tool.** It is not on npm — `npm install gemctl` finds nothing. Ask
+  the platform team where to get it. If you do not have it, steps 1 and 2 cannot be done; get it
+  first.
+- **A developer account with your game registered.** Uploading config needs developer permission on
+  the game. A `403` means the account lacks it, and signing in again will not fix it.
+
+Everything here targets the **`dev` channel** — the one only your team sees. The last step says why
+you must not change that.
+
+## The budget, so you know when you have it right
+
+A shop screen costs **three requests to render, one when the player selects a row, and one to
+execute the purchase.** If you find yourself calling the server once per shop row, you have taken a
+wrong turn — go back to step 4. The three-to-render are: load the config, read the player's
+inventory snapshot, and read recipe usage for cooldowns. Everything a row shows — its price,
+whether the player can afford it, its cooldown, uses remaining, base odds — comes from those,
+computed on the client.
+
+## 1. Author the config
+
+Your currency, item and shop are config, not code. This is a minimal illustrative shape — run
+`gemctl config schema` for the authoritative field list, and do not copy a field list out of any
+document, because the schema is versioned and a copied list goes stale.
+
+```yaml
+currencies:
+  - id: coins
+    display_name: Coins
+    min_balance: 0
+    max_balance: 999999
+
+items:
+  - id: healing-potion
+    display_name: Healing Potion
+    fungible: true
+
+catalogs:
+  - id: general-store
+    recipes:
+      - id: buy-potion
+        recipe_type: purchase
+        costs:
+          - currency_id: coins
+            amount: 25
+        grants:
+          - item_definition_id: healing-potion
+            quantity: 1
+```
+
+A **purchase recipe** is the whole point: it names what it costs and what it grants, and the server
+enforces both. You will run it by name; you will never send the price yourself.
+
+**`recipe_type` is one of five values: `purchase`, `exchange`, `claim`, `craft` or `loot_box`.** It
+defaults to `purchase`, so a shop recipe can leave it out. Any other value — `standard`, for one —
+is refused at upload, naming the five.
+
+## 2. Upload and promote to the dev channel
+
+```bash
+gemctl config schema                          # the authoritative field list
+gemctl config upload --wait                    # registers a version; validation is ASYNC
+gemctl config promote <version> --channel dev  # THIS is what makes it live
+```
+
+**Uploading is not shipping.** Until `gemctl config promote` puts the version on the channel your
+game runs, the shop does not exist for that channel and every read of it comes back empty. This is
+the same rule save slots follow; see
+[`saving-player-progress.md`](saving-player-progress.md#1-declare-the-slot-in-your-game-config).
+
+## 3. Load the config and the snapshot, once
+
+In the game, at shop-open, read the three things the whole screen is built from:
+
+```js
+const config = await gem.gameConfig.load(); // the shop's definitions
+const snap = await gem.me.inventory.snapshot(); // what the player holds
+const usage = await gem.me.mutations.recipeUsageAll(); // cooldowns, one read for every recipe
+```
+
+**`config` can be `null`.** That means this channel has no config yet — the version was not
+promoted, or the game is running on a different channel than the one you promoted to. Render an
+"shop unavailable" state; it is a real condition, not an error to swallow.
+
+## 4. Render the shop from what you already have — no per-row call
+
+Walk the catalog's recipes and render each from the config and the snapshot. **Do not call the
+server inside this loop.** The price is on the recipe; affordability is the player's balance
+against it; the cooldown is in the usage you already read.
+
+One shape gotcha before the code: the config document is the raw published data,
+so its fields are **snake_case** — `display_name`, `currency_id`,
+`item_definition_id`. The player-side reads (`recipeUsage`, `gem.me.currencies`,
+`recipeAvailability`) are the SDK's own shapes and are camelCase. Do not mix
+them.
+
+```js
+const store = config.catalogs.find((c) => c.id === 'general-store');
+const balance = (await gem.me.currencies.get('coins')).total; // from the snapshot, not a fourth request
+// `null` means no record — decide at the render what that shows, never `?? 0` at the read.
+
+for (const recipe of store.recipes) {
+  const cost =
+    recipe.costs?.find((c) => 'currency_id' in c && c.currency_id === 'coins')?.amount ?? 0;
+  const affordable = balance !== null && balance >= cost; // null is "no record", and null >= 0 is true in JS
+  const used = usage.usages.find((u) => u.recipeId === recipe.id); // camelCase: SDK shape
+  const onCooldown = used?.isOnCooldown ?? false;
+
+  const grant = recipe.grants?.[0];
+  const name =
+    grant && 'item_definition_id' in grant
+      ? config.item(grant.item_definition_id)?.display_name
+      : recipe.id;
+
+  const row = document.createElement('button');
+  row.textContent = `${name} — ${cost}`; // textContent, never innerHTML
+  row.disabled = !affordable || onCooldown;
+  row.onclick = () => onBuy(recipe); // remember which recipe this row is — steps 5-6 need it
+  shopEl.append(row);
+}
+```
+
+**Render with `textContent`, never `innerHTML`.** A display name or an item's freeform properties
+is text you did not author — an item can arrive from another player by trade — so building markup
+from it is a cross-player script-injection sink. The same goes for any `img.src` or `a.href` you
+might set from a config or item string: don't. See
+[`inventory-and-catalogs.md`](inventory-and-catalogs.md#8-items).
+
+## 5. When the player picks a row, check that one recipe
+
+The `onBuy(recipe)` the row wired up above runs the rest. Now — and only now, for the one recipe
+the player chose — ask the server whether it can run. This is the single per-selection call, and it
+carries the cooldown so you need nothing else:
+
+```js
+async function onBuy(recipe) {
+  const av = await gem.me.mutations.recipeAvailability('general-store', recipe.id);
+  if (!av.canExecute) {
+    showReason(av.reasons, av.cooldownExpiresAt); // e.g. "on cooldown until …"
+    return;
+  }
+  // ... step 6 continues here
+}
+```
+
+A 20-row shop that called this per row would be 20 requests for a screen that needs none until a
+click. Check availability on selection, not on render.
+
+## 6. Execute the recipe — the server does the arithmetic
+
+Still inside `onBuy`, with the same `recipe`: run it by name. You send no price, no balance, no
+total — the server charges the cost and grants the item, and a modified client cannot change what
+it charges:
+
+`executeRecipe` resolves with a typed result — the order id, the status, what it
+granted, what it consumed (the cost side), and any loot rolls:
+
+```js
+try {
+  const result = await gem.me.mutations.executeRecipe('general-store', recipe.id);
+  // result.orderId, result.status, result.granted, result.consumed, result.lootResults
+  await confirmPurchase(result.orderId); // step 7
+} catch (err) {
+  handlePurchaseError(err);
+}
+```
+
+For a loot box, `result.lootResults` is what makes a "you got …" screen possible — it names which
+entry dropped and at what rarity, which the inventory snapshot alone does not.
+
+Three failures to handle, and getting them right is the difference between a shop and a
+data-corruption bug:
+
+- **A `412` and a timeout are opposite.** You are not sending `ifMatch` here — a purchase is a delta
+  the server bounds, so it needs no condition — so a `412` should not arise. But the general rule
+  matters the moment you do send one elsewhere: a `412` proves the write did _not_ happen; a
+  **timeout proves nothing** and the purchase may have applied. **Never resend a timed-out
+  purchase.** Read the order back (step 7) to find out.
+- **Retry only what `err.retryable` says is retryable.** `rate_limited` and `unavailable` are; wait
+  `err.retryAfterSeconds` when the refusal carries one, and your own backoff when it does not —
+  absence means the platform gave no estimate, not "stop". `insufficient_funds`,
+  `precondition_failed`, `invalid` and `too_large` are never retryable. Retrying blind is how one
+  slow moment becomes a storm.
+- **A `402` means the player cannot afford it.** Re-read the balance, re-render, and do not resend.
+
+## 7. Confirm it landed
+
+The answer to "did my purchase go through" is the order, read back by its id:
+
+```js
+const order = await gem.me.orders.get(result.orderId);
+// order.status tells you what happened; the grant is in the player's next snapshot
+```
+
+This is also the answer after a timeout: you got no result back, so list recent orders and look for
+the one you attempted, rather than resending the purchase.
+
+## Selling a cosmetic for Tickets
+
+Your shop can also sell for the arcade's own currencies, and the platform draws one line through
+them: **Tickets buy cosmetics, Gems buy anything.** Each platform currency has a spend scope — Tickets'
+is `cosmetic_only`, Gems' is `any`. Mark a cosmetic in the
+config, and price it in `ARCADE_TICKETS`:
+
+```yaml
+items:
+  - id: wizard-hat
+    display_name: Wizard Hat
+    category: cosmetic # it changes how the player looks, never what they can do
+    platform_prices:
+      - currency: ARCADE_TICKETS # Tickets
+        price: 40
+  - id: dragon-skin
+    display_name: Dragon Skin
+    category: cosmetic # no price of its own: it is sold through the recipe below
+```
+
+`category` defaults to `progression`, so an item is a cosmetic only when you say so. The upload
+refuses a price in a `cosmetic_only` currency on anything that is not: an item that is not
+`category: cosmetic`, a recipe that grants a currency, a progression, a loot-table roll or a
+non-cosmetic item. The refusal names the currency's scope and the item or the grant, so the fix is in
+the message. Progression — an extra life, an upgrade —
+is priced in `GEMS`.
+
+To make a cosmetic wait for progress — "reach level 10 to unlock the dragon skin" — sell it through a
+recipe, because an item's own price cannot carry a prerequisite. Give the item no price of its own,
+or it can be bought directly and the lock means nothing:
+
+```yaml
+catalogs:
+  - id: cosmetics
+    recipes:
+      - id: buy-dragon-skin
+        prerequisites:
+          - prerequisite_type: progression_level
+            reference_id: '…' # your `mastery` progression's id
+            reference_value: 10
+        grants:
+          - item_definition_id: dragon-skin
+            quantity: 1
+        platform_prices:
+          - currency: ARCADE_TICKETS
+            price: 120
+```
+
+In the shop, ask about that row the way step 5 does, and show the lock rather than a button:
+
+```js
+const av = await gem.me.mutations.recipeAvailability('cosmetics', 'buy-dragon-skin');
+if (av.locked) {
+  const [lock] = av.lockReasons; // { prerequisiteType: 'progression_level', required: 10, current: 7, … }
+  row.textContent = `Reach level ${lock.required} to unlock`;
+  row.disabled = true;
+}
+```
+
+The platform checks the prerequisite **before** it takes any Tickets: a locked player who buys
+anyway is refused `recipe_locked` and charged nothing. See
+[`inventory-and-catalogs.md`](inventory-and-catalogs.md#16-selling-for-a-platform-currency) for the
+two purchase paths and the full rule.
+
+### Buying it, and reading a refusal
+
+With the arcade's purchase sheet, the platform confirms and charges; your game asks and reads the
+outcome. A refusal carries a `reason` that says why:
+
+```js
+const res = await gem.purchases.request({
+  kind: 'recipe',
+  catalogId: 'cosmetics',
+  targetId: 'buy-dragon-skin', // the recipe's id, never its slug
+  currencySlug: 'ARCADE_TICKETS',
+});
+if (res.outcome === 'ok' || res.outcome === 'unavailable') {
+  gem.me.inventory.refresh(); // `unavailable` means no answer arrived, not that nothing happened
+} else if (res.reason === 'recipe_locked' || res.reason === 'insufficient_funds') {
+  updateShopRow(res.reason); // your shop's own words: "Locked", "Not enough Tickets"
+} else if (res.reason !== 'cancelled' && res.reason !== 'busy') {
+  console.warn('purchase declined:', res.reason); // unknown_currency, no_price_in_currency … are yours to fix
+}
+```
+
+With your own purchase screen (`gem.me.mutations.purchase`), the same strings arrive as `err.code`
+— see [`inventory-and-catalogs.md`](inventory-and-catalogs.md#why-a-purchase-was-refused).
+
+**Never draw a top-up or payment screen of your own** — no "get more Tickets", no checkout, nothing
+shaped like the arcade's purchase sheet. A player short of Tickets earns more by playing; your shop
+says "Not enough Tickets" and stops there.
+
+## Rewarding a player — still a recipe
+
+When your game _gives_ a player something — "you earned 100 coins," a quest reward — reach for a
+recipe too, not a direct grant. A reward flow is the same client-authored economy as a shop under a
+friendlier name, and the same rule applies: if the value matters, the server has to be the one that
+awards it. Author a reward recipe in your config and execute it exactly as above.
+
+## The one thing you must not do next
+
+Everything here is on the **`dev` channel** on purpose. This shop is not safe to put in front of
+real players as-is, and the reason is not a bug you can fix by promoting it:
+
+> Within your own game's scope there is **no client-side integrity boundary**. Any balance, item or
+> progression a browser client can author, a modified browser client can author differently.
+> Recipes move the arithmetic to the server and are the only thing that does. Do not attach anything
+> of value — a leaderboard, a tournament, a payout, a cross-player market — to a number a client
+> authored.
+
+Recipes are what make this shop honest: the server charges the cost. But a shop is only as safe as
+the flows around it, and promoting a config to the channel every player sees is a decision to make
+deliberately, not a step in a tutorial. Keep this on `dev` until you have decided the whole economy
+around it holds up.
+
+## What to read next
+
+- [`inventory-and-catalogs.md`](inventory-and-catalogs.md) — the full concept reference for everything used here.
+- [`trading-and-gifting.md`](trading-and-gifting.md) — moving items and currency between players.