@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/docs/arcade-economy.md

@@ -0,0 +1,263 @@
+# Gems, Tickets and Achievement Points
+
+The arcade runs three things across every game, and a player should be able to tell them apart at
+a glance:
+
+> **Gems = progress. Tickets = cosmetics. Achievement Points = prestige.**
+
+You do not have to use any of them. A game with no platform currency and no achievements is a
+complete game, and the currencies your core loop runs on — gold, XP, energy, materials, cards — are
+yours to design however you like ([inventory-and-catalogs.md](inventory-and-catalogs.md)). Read this
+page before you design a reward a player carries out of your game, a price they pay with something
+earned elsewhere, or an achievement. The rules below decide which of the three a reward can be, and
+most of them are enforced at upload, so a design that ignores them is refused rather than shipped.
+
+## 1. The three, side by side
+
+|                    | **Gems** (`GEMS`)                                      | **Tickets** (`ARCADE_TICKETS`)                  | **Achievement Points**                                    |
+| ------------------ | ------------------------------------------------------ | ----------------------------------------------- | --------------------------------------------------------- |
+| What it is         | the arcade's progression currency                      | the arcade's cosmetics currency                 | permanent prestige: the **Achievement Score**             |
+| Which games pay it | any game with a server or a serverless function        | any game with a server or a serverless function | an achievement, from any game with a server or a function |
+| What it buys       | anything a game prices in it                           | cosmetic items only                             | nothing — it is never spent                               |
+| Sold for money     | never                                                  | never                                           | never                                                     |
+| A Boost raises it  | yes — the grants and the caps                          | yes — the grants and the caps                   | never                                                     |
+
+A player earns Gems across the arcade's games and spends them on progress anywhere: upgrades, unlocks,
+extra attempts, resources, characters, cards. A player earns Tickets by playing almost anything and
+spends them on how they look: skins, outfits, visual effects, decorations, emotes, profile
+cosmetics. Achievement points are what a player has done, summed across every game into the
+Achievement Score; they are never bought, boosted or spent, and nothing takes them away except the
+platform, for fraud or moderation.
+
+## 2. What your game keeps for itself
+
+The arcade does not replace your economy. The currencies and resources your core loop runs on —
+gold, XP, wood, energy, lives, cards — stay your game's own: defined in your game config, minted and
+priced by you, invisible to every other game. Nothing on this page applies to them.
+
+What you map onto the three is the layer above that loop — the part that would otherwise become a
+platform-wide currency of your own:
+
+| If your design has…                                                                       | Use                                                       |
+| ----------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| a premium or meta currency that speeds up or unlocks progress                             | **Gems**: price that progress in `GEMS`                   |
+| a cosmetics currency, or a shop of skins                                                  | **Tickets**: price the cosmetics in `ARCADE_TICKETS`      |
+| a trophy count, a mastery rank or a completion percentage that says "this player is good" | **achievements**, whose points join the Achievement Score |
+
+⚠️ **Do not build a second Gems or a second Tickets.** A game-local premium or cosmetic
+meta-currency — "Crystals" that buy your upgrades, "Shards" that buy your skins, earned and hoarded
+the way a player would earn and hoard the arcade's — competes with the arcade's own, splits the
+player between two wallets that mean the same thing, and sidesteps every rule on this page: the Gem
+Source approval, the cosmetics-only line and the platform's caps. The release review checks for one.
+A currency that is part of play is fine: coins picked up in a level and spent in that run's shop,
+energy that paces a session, materials a crafting tree consumes.
+
+## 3. Which kind of game is yours
+
+There are four shapes:
+
+| Shape          | Grants Gems | Prices in Gems | For example                                                                             |
+| -------------- | ----------- | -------------- | --------------------------------------------------------------------------------------- |
+| **Gem Source** | yes         | no             | a game with a controlled daily activity that feeds progress to the arcade               |
+| **Balanced**   | yes         | yes            | a Gem Source whose own progression also spends Gems                                     |
+| **Gem Sink**   | no          | yes            | a progression-heavy game: upgrades, characters, cards bought with Gems earned elsewhere |
+| **No-Gem**     | no          | no             | a game that stays out of Gems entirely                                                  |
+
+The shapes describe what a game does, not what it may do: a Gem Source that starts pricing its own
+progress in Gems is Balanced. Every shape may pay Tickets, price its cosmetics in Tickets and carry
+achievements. **Gems can be your game's soft currency** — award them for play and price your
+progression in them.
+
+Which platform currencies **your** game may grant or price is the platform's answer, and it can
+change: `gemctl platform config --game <id>` lists them under `platform_grants` and
+`platform_prices`, each with a note on what the arcade wants it used for. A mapping onto a currency
+the platform will not let your game pay is refused at upload, and the refusal names the ones it
+will.
+
+## 4. Earning needs server authority
+
+A platform currency or an achievement is paid only on the say-so of code a player cannot modify.
+Your game never grants one directly. A progression in your game config carries a `platform_grants`
+mapping, and when that progression moves, the platform pays under its own authority
+([inventory-and-catalogs.md](inventory-and-catalogs.md#platform-grants-awarding-a-platform-wide-currency)).
+What may move it:
+
+- **Your game server** — a platform-allocated dedicated server, through the progression add and max
+  routes.
+- **Your serverless function**, called by the player it pays, on a progression that sets
+  `function_may_grant: true`. It may pay Gems and Tickets and unlock achievements for **that player
+  only**, and never for a guest. A function a player calls may also change only that player's own
+  state — any write it aims at another player is refused. Opting in makes the function's own checks
+  the only thing deciding a reward was earned, so read
+  [serverless-functions.md](serverless-functions.md) before you set it.
+- **Never the browser.** A mapped progression cannot be `client_writable`, and nothing else in your
+  config — a recipe, a loot-table entry, another progression's reward — may write it.
+
+So a browser-only game with neither a server nor a function pays nothing platform-wide. That is the
+rule read strictly, not a gap: a browser credential is public, and anything it could pay, a modified
+client could pay itself.
+
+**Achievements hold the same line, harder.** An achievement that awards points may not sit on a
+progression anything in your config writes: a recipe priced in Gems that adds to it would sell the
+achievement. Points are never bought, boosted, spent, decayed or expired, and the platform removes
+them only for fraud or moderation ([achievements.md](achievements.md)).
+
+## 5. Spending: price each item in the currency it deserves
+
+Any game may sell an item or a recipe for a platform currency, with no server and no approval: the
+item or recipe carries `platform_prices`, and the player pays through the arcade's purchase sheet or
+your own purchase screen
+([inventory-and-catalogs.md](inventory-and-catalogs.md#16-selling-for-a-platform-currency)). What a
+currency may price is a platform setting on that currency, its **spend scope**:
+
+- **Gems — `any`.** Price progress in `GEMS`: an extra life, an upgrade, a character, a pack of
+  cards, another attempt.
+- **Tickets — `cosmetic_only`.** A Tickets price is accepted only on an item your config declares
+  `category: cosmetic`, or on a recipe that grants cosmetic items and nothing else. A Tickets price
+  on anything that grants a currency, moves a progression, grants a non-cosmetic item, opens into
+  other items (a bundle or a loot box) or rolls a loot table is refused at upload — a loot table
+  even when every entry in it is cosmetic.
+
+So a Tickets price on an item is always the pair `currency: ARCADE_TICKETS` and
+`category: cosmetic`; on a recipe, every item it grants declares `category: cosmetic`.
+
+**`category` defaults to `progression`**, so an item is a cosmetic only because you said so. The
+platform takes that at your word and the release review checks it: an item that changes what a
+player can do, labelled `cosmetic` so it can sell for Tickets, breaks platform policy.
+
+**A cosmetic can still wait for progress.** "Reach level 10 to unlock the dragon skin" is a recipe
+with a prerequisite and a Tickets price, and the platform refuses a locked player with
+`recipe_locked` before it takes anything ([game-economy-tutorial.md](game-economy-tutorial.md)).
+
+**Take the scope from the refusal, not from this page.** The platform owns each currency's scope and
+can change it. A refusal names the scope that applied, and `gemctl platform config` lists which
+currencies your game may price in at all. A scope changed after you published stops the prices it
+no longer admits: the purchase is refused and the price leaves the catalog, with nothing charged.
+
+**The arcade sells cosmetics of its own for Tickets, and never sells prestige.** Besides your game's
+shop, the arcade has a Tickets shop of its own profile cosmetics. Every arcade item is either a
+**shop** item — a cosmetic priced in Tickets — or **earned**: a default, a free claim, an achievement
+or Achievement Score reward. An earned item can never be given a price, in Tickets, Gems or anything
+else, so what a player shows off for what they did cannot be bought.
+
+## 6. Every number is the platform's, and it moves
+
+Each platform currency carries settings the arcade holds per currency and can change at any time,
+without a release of this SDK or of your game:
+
+- which games may grant it;
+- how much one grant may pay, how much one game may pay one player per window, and how much all
+  games together may pay one player per day — the **daily maximum**;
+- the most a player may hold — the **holdings cap**;
+- whether games may price in it, and what it may price;
+- whether a Boost raises it;
+- whether the arcade shows it in its header and wallet.
+
+**Author against `gemctl platform config`, never against a number you remember.** For your game it
+lists every currency a `platform_grants` mapping may target, with its current ceilings, every
+currency a price may name, and a note on when to reach for each. A currency it does not list for a
+site cannot be used there.
+
+Your game declares no cap of its own. You choose only what each firing pays; the ceilings bound it,
+and the order's `platform_grant` entry — `fired`, `clamped` or `suppressed` — is the receipt for what
+landed:
+
+- **A ceiling trims; it does not refuse.** For every platform currency, a firing that would cross
+  the per-firing cap, the per-game cap or the daily maximum pays what is left of it and reads
+  `clamped`; once the day is spent it pays 0. When the player reaches the daily maximum, the arcade
+  tells them in its own chrome, and that notice is never relayed into your game
+  ([daily-challenges.md](daily-challenges.md)), though it can read how much more it may pay
+  ([the earn allowance](inventory-and-catalogs.md#showing-how-much-more-a-player-can-earn)).
+- **The holdings cap is all or nothing.** A grant that would take the player's balance past it pays
+  nothing and reads `clamped` with `clamped_by: holdings_cap`. Nothing a player already holds is
+  ever taken away.
+
+Your reward screen may say what the mapping pays; the receipt, never your screen, says what the
+player got.
+
+## 7. Boosts: the one thing a player buys with money
+
+Nothing in the arcade sells Gems or Tickets, alone or in a bundle, and nothing sells achievement
+points. The one real-money product is a **Boost**, which a player buys from the arcade, never from
+your game:
+
+- **It multiplies what Gems and Tickets grants pay, and the ceilings with them.** A player on a 2×
+  Boost earns twice as much per grant, may earn twice as much per window and per day, and may hold
+  more. When it ends, what they earned stays theirs.
+- **It never touches achievement points.** An unlock credits the same points for every player.
+- **Your game does nothing to apply it.** The platform multiplies your mapping's payout itself.
+  Keep `amount` at the unboosted figure; the receipt reports what landed.
+- **None is on sale yet.** The first Boost, `booster_x2_30d`, is inactive until the arcade launches
+  it, so today every player earns at the unboosted rate. Design for both.
+
+⚠️ **Show a Boost; never gate on one.** Your game may tell a player they are boosted — "2× Tickets"
+beside a reward, from `gem.player.boost`
+([what-a-game-must-do.md](what-a-game-must-do.md#the-signed-in-players-boost-show-it-never-gate-on-it))
+— and must never make content, difficulty, power, access, prices, matchmaking or odds depend on
+whether they are. A Boost buys a faster stream of the arcade's currencies and nothing else. A level,
+a character or an advantage behind it is paying to win, and the release review refuses it: the full
+rule is [platform-rules.md](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate).
+
+## 8. The arcade owns the display of every platform currency
+
+The arcade draws the player's platform currencies in its own chrome while your game runs, and
+animates every payout into the right total. Gems and Tickets follow the same rules:
+
+- **No counter.** Keep no balance, running total or wallet of a platform currency on any screen of
+  yours. Read `gem.platform.currencies.get()` to decide whether a price is affordable, never to draw
+  a number.
+- **No celebration of your own.** At a payout, cue the arcade's wallet with `gem.cueReward`, naming
+  the currency that paid — `currencySlug: 'GEMS'` from the gem on your reward screen,
+  `'ARCADE_TICKETS'` from the ticket. If it returns `false`, do nothing
+  ([inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet)).
+- **No "daily max" of your own making.** Your game cannot see what every other game paid the player,
+  and must not compute a maximum. To show how much more your game can pay, read
+  `gem.platform.earnAllowance.get()` (one consolidated figure, display only); the arcade still tells
+  the player when they reach the maximum.
+- **No top-up or payment screen of your own.** Never draw a "get more Gems" or "buy Tickets" offer,
+  a checkout, a wallet top-up, or anything shaped like the arcade's purchase sheet: a game screen
+  that looks like platform payment chrome is an imitation of it, and players cannot tell the two
+  apart. Your shop's own Buy button is yours. When a purchase is refused for
+  `insufficient_funds`, say so in your shop's own words ("Not enough Tickets") and stop there.
+- **No amount at all when you are not connected to the arcade.** Hide every platform price and
+  reward unless `gem.awaitBridge()` settled `connected`.
+- **Draw a currency with the art the SDK ships**: the icon beside an amount, the hero only on a
+  reward presentation ([brand-art.md](brand-art.md)).
+
+**The Achievement Score is the arcade's to total, too.** Your game shows its own achievements and
+never computes the score, restates it, or turns it into a currency of its own.
+
+## 9. What the arcade does not have
+
+- **No Stars, Coins, Tokens or Supporter Seals.** All four are retired. None of them can be
+  granted, priced in or bought: a config naming one is refused at upload, and a mapping onto one
+  that is still live reads `suppressed`. The Achievement Score is the arcade's measure of prestige.
+- **No Gems or Tickets for money**, alone or in a bundle, and no achievement points or earned
+  items for anything a player pays for.
+- **No content behind a Boost.** A Boost is shown, never checked.
+
+## 10. When an upload or a grant is refused
+
+| What you get                                               | What happened                                                   | What to do                                                                                   |
+| ---------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| a mapping refused, naming the currencies your game may pay | the platform does not let your game grant that currency         | target one it lists — `gemctl platform config` has the current set                           |
+| a receipt `suppressed`, reason `not_allowlisted…`          | the platform stopped letting your game grant that currency      | target a currency `gemctl platform config` lists; paid balances stay                         |
+| a price refused, naming the spend scope `cosmetic_only`    | a Tickets price on something that is not a cosmetic             | price it in `GEMS`, or mark the item `category: cosmetic` if it changes only looks           |
+| a receipt `suppressed`, reason `functions_not_opted_in`    | your function wrote a paying progression that has not opted in  | read [serverless-functions.md](serverless-functions.md), then set `function_may_grant: true` |
+| a receipt `suppressed`, reason `function_gems_not_enabled` | an older receipt, from before functions could pay Gems          | nothing — a function pays Gems now, so its next firing pays                                  |
+| `403 function_foreign_entity_write`                        | a function a player called wrote another player                 | take the player from the call's context, never its input                                     |
+| a receipt `clamped`                                        | a ceiling trimmed the payout, or the day was already spent      | nothing — show what landed; `gemctl platform config` has the ceilings                        |
+| a receipt `clamped`, `clamped_by: holdings_cap`            | the player already holds as much as they may                    | nothing — the player spends before they earn more                                            |
+
+## What to read next
+
+- [`inventory-and-catalogs.md`](inventory-and-catalogs.md) — platform grants (§13) and selling for a
+  platform currency (§16), in full.
+- [`game-economy-tutorial.md`](game-economy-tutorial.md) — a shop, step by step, including a
+  cosmetic sold for Tickets.
+- [`daily-challenges.md`](daily-challenges.md) — the commonest thing that pays a platform currency.
+- [`achievements.md`](achievements.md) — achievements, their points and the Achievement Score.
+- [`serverless-functions.md`](serverless-functions.md) — paying a player from a game with no
+  dedicated server, and what a function a player calls may change.
+- [`platform-rules.md`](platform-rules.md) — the Boost rule, among the rest.
+- [`brand-art.md`](brand-art.md) — the art for every platform currency, and the rules for drawing it.