@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/dist/sdk.d.ts

@@ -205,6 +205,7 @@ type GameConfigSnapshot = {
     "async_opponent_types"?: SnapshotAsyncOpponentType[];
     "catalogs": SnapshotCatalog[];
     "currencies": SnapshotCurrency[];
+    "friend_challenge_templates"?: SnapshotFriendChallengeTemplate[];
     "game_room_templates": SnapshotGameRoomTemplate[];
     "hash": string;
     "items": SnapshotItem[];
@@ -212,6 +213,7 @@ type GameConfigSnapshot = {
     "leaderboards"?: SnapshotLeaderboard[];
     "loot_tables": SnapshotLootTable[];
     "progressions": SnapshotProgression[];
+    "rewarded_placements"?: SnapshotRewardedPlacement[];
     "run_types"?: SnapshotRunType[];
     "version": number;
 };
@@ -419,6 +421,21 @@ type SnapshotCurrency = {
     "min_balance": number;
     "slug"?: string | null;
 };
+type SnapshotFriendChallengeParam = {
+    "key": string;
+    "localized"?: Record<string, unknown> | null;
+    "max"?: unknown;
+    "min"?: unknown;
+    "pattern"?: string | null;
+    "type": string;
+    "values"?: Record<string, unknown> | null;
+};
+type SnapshotFriendChallengeTemplate = {
+    "key": string;
+    "localized"?: Record<string, unknown>;
+    "params"?: SnapshotFriendChallengeParam[];
+    "text": string;
+};
 type SnapshotGameRoomTemplate = {
     "allow_host_transfer": boolean;
     "allow_join_in_progress"?: boolean;
@@ -526,6 +543,25 @@ type SnapshotRecipe = {
     "slug"?: string | null;
     "sort_order": number;
 };
+type SnapshotRewardGrant = {
+    "item_definition_id": string;
+    "quantity": number;
+    "type": "item_grant";
+} | {
+    "amount": number;
+    "currency_id": string;
+    "type": "currency_grant";
+};
+type SnapshotRewardedPlacement = {
+    "allowance_currency_id"?: string | null;
+    "cooldown_seconds": number;
+    "grants": SnapshotRewardGrant[];
+    "max_held"?: number | null;
+    "max_per_day": number;
+    "placement": string;
+    "reward_class": string;
+    "without_ads": string;
+};
 type SnapshotRunType = {
     "bucket_1_allowed_values"?: string[] | null;
     "bucket_1_name"?: string | null;
@@ -1211,10 +1247,35 @@ interface ListFriendsOptions {
     readonly cursor?: string;
     readonly signal?: AbortSignal;
 }
+interface FriendChallengeRequest {
+    readonly playerId: string;
+    readonly template: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+}
+type FriendChallengeOutcomeKind = "accepted" | "cancelled" | "refused" | "unavailable";
+interface FriendChallengeOutcome {
+    readonly outcome: FriendChallengeOutcomeKind;
+}
+type FriendChallengeErrorCode = "unknown_template" | "template_not_on_channel" | "param_invalid" | "param_undeclared" | "recipient_invalid" | (string & {});
+declare class FriendChallengeError extends GemApiError {
+    readonly code?: FriendChallengeErrorCode;
+    readonly param?: string;
+    readonly channel?: string;
+    readonly configVersion?: number;
+    constructor(source: GemApiError, extra?: {
+        readonly param?: string;
+        readonly channel?: string;
+        readonly configVersion?: number;
+    });
+}
+interface FriendsApiDependencies {
+    readonly challenge?: (request: FriendChallengeRequest) => Promise<FriendChallengeOutcome>;
+}
 declare class FriendsApi {
     #private;
-    constructor(api: GameApi$1);
+    constructor(api: GameApi$1, dependencies?: FriendsApiDependencies);
     list(options?: ListFriendsOptions): Promise<FriendsPage>;
+    challenge(request: FriendChallengeRequest): Promise<FriendChallengeOutcome>;
 }
 type PlatformCurrencyAccess = "read" | "spend";
 interface PlatformCurrency {
@@ -1231,9 +1292,35 @@ declare class PlatformCurrenciesApi {
     constructor(api: GameApi$1);
     get(options?: PlatformCurrencyReadOptions): Promise<readonly PlatformCurrency[]>;
 }
+type EarnAllowancePeriod = "day" | "window";
+interface EarnAllowance {
+    readonly currencySlug: string;
+    readonly currencyId: string;
+    readonly limit: number;
+    readonly earned: number;
+    readonly remaining: number;
+    readonly period: EarnAllowancePeriod;
+    readonly periodDays: number;
+    readonly resetsAt?: number;
+}
+interface EarnAllowanceReadOptions {
+    readonly signal?: AbortSignal;
+}
+interface EarnAllowanceSignal {
+    on(listener: () => void): () => void;
+    emit(): void;
+}
+type EarnAllowanceEvent = "changed";
+declare class PlatformEarnAllowanceApi {
+    #private;
+    constructor(api: GameApi$1, signal?: EarnAllowanceSignal, log?: ((line: string) => void) | null);
+    get(options?: EarnAllowanceReadOptions): Promise<readonly EarnAllowance[]>;
+    on(event: EarnAllowanceEvent, listener: () => void): () => void;
+}
 declare class PlatformApi {
     readonly currencies: PlatformCurrenciesApi;
-    constructor(api: GameApi$1);
+    readonly earnAllowance: PlatformEarnAllowanceApi;
+    constructor(api: GameApi$1, earnAllowanceSignal?: EarnAllowanceSignal, log?: ((line: string) => void) | null);
 }
 interface ProfileShowcaseEntry$1 {
     readonly key: string;
@@ -1856,6 +1943,12 @@ interface GemViewport$1 {
         bottom: number;
         left: number;
     };
+    readonly reserved?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }[];
 }
 interface GemDeviceSettings {
     readonly gem: typeof PROTOCOL;
@@ -1977,6 +2070,18 @@ interface GemSignInResult {
     readonly requestId: string;
     readonly outcome: "signed_in" | "declined" | "unavailable";
 }
+interface GemFriendChallengeResult {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.friendChallengeResult";
+    readonly requestId: string;
+    readonly outcome: "accepted" | "cancelled" | "refused" | "unavailable" | "rate_limited" | "invalid";
+    readonly code?: string;
+    readonly param?: string;
+    readonly channel?: string;
+    readonly configVersion?: number;
+    readonly retryAfterMs?: number;
+    readonly detail?: string;
+}
 interface ConnectOptions {
     readonly clusterTargetId?: ClusterTargetLike;
     readonly retry?: StartMatchRetryOptions;
@@ -3967,25 +4072,6 @@ interface SignInOutcome {
 interface AccountApi {
     requestSignIn(): Promise<SignInOutcome>;
 }
-type AdFormat = "interstitial" | "rewarded";
-interface AdRequest {
-    placement: string;
-    format: AdFormat;
-}
-type AdOutcomeKind = "shown" | "no_ad" | "unavailable";
-interface AdOutcome {
-    readonly outcome: AdOutcomeKind;
-}
-interface AdsApi {
-    requestAd(req: AdRequest): Promise<AdOutcome>;
-}
-type DeviceSettings = Readonly<Record<string, unknown>>;
-type DeviceSettingsPutOutcome = "stored" | "too_large" | "unavailable";
-interface DeviceSettingsApi {
-    readonly current: DeviceSettings | null;
-    wait(timeoutMs?: number): Promise<DeviceSettings | null>;
-    put(settings: DeviceSettings): Promise<DeviceSettingsPutOutcome>;
-}
 interface PlayerBoostMultiplier {
     readonly currencyId: string;
     readonly currencySlug: string;
@@ -4016,6 +4102,7 @@ interface FrameCallbacks {
     onPause?(msg: GemPause): void;
     onPrefs?(msg: GemPrefs$1): void;
     onCohorts?(msg: GemCohorts$1): void;
+    onEarnAllowanceChanged?(): void;
     onViewport?(msg: GemViewport$1): void;
     onWillTerminate?(msg: GemWillTerminate): void;
     onDevtools?(action: "open" | "close" | "toggle"): void;
@@ -4041,6 +4128,7 @@ interface FrameCallbacks {
     onDeviceSettingsResult?(msg: GemDeviceSettingsResult): void;
     onAdResult?(msg: GemAdResult): void;
     onSignInResult?(msg: GemSignInResult): void;
+    onFriendChallengeResult?(msg: GemFriendChallengeResult): void;
     onError?(code: GemErrorCode, message?: string): void;
     onDropped?(code: GemErrorCode, message?: string): void;
     onStateChange?(state: FrameState): void;
@@ -4082,6 +4170,13 @@ declare class GemFrame {
     requestFullscreen(enabled: boolean): void;
     reportMuted(muted: boolean): boolean;
     cueReward(cue: RewardCue): boolean;
+    setWalletVisible(visible: boolean, options?: {
+        only?: readonly string[];
+    }): boolean;
+    requestShare(params: ReadonlyArray<{
+        readonly key: string;
+        readonly value: string;
+    }>): boolean;
     reportFrameStats(stats: {
         fps: number;
         frameTimeP95Ms: number;
@@ -4094,6 +4189,7 @@ declare class GemFrame {
     putDeviceSettings(requestId: string, settings: Readonly<Record<string, unknown>>): boolean;
     requestAd(requestId: string, placement: string, format: "interstitial" | "rewarded"): boolean;
     requestSignIn(requestId: string): boolean;
+    requestFriendChallenge(requestId: string, playerId: string, template: string, params?: Readonly<Record<string, string | number>>): boolean;
     close(): void;
     private transition;
     private refuseMalformed;
@@ -4105,6 +4201,32 @@ declare class GemFrame {
     private dispatchInbound;
     private screenshotDenied;
 }
+interface ShareRequest {
+    readonly params?: Readonly<Record<string, string>>;
+}
+interface ShareApi {
+    readonly available: boolean;
+    request(request?: ShareRequest): void;
+}
+type AdFormat = "interstitial" | "rewarded";
+interface AdRequest {
+    placement: string;
+    format: AdFormat;
+}
+type AdOutcomeKind = "shown" | "no_ad" | "unavailable";
+interface AdOutcome {
+    readonly outcome: AdOutcomeKind;
+}
+interface AdsApi {
+    requestAd(req: AdRequest): Promise<AdOutcome>;
+}
+type DeviceSettings = Readonly<Record<string, unknown>>;
+type DeviceSettingsPutOutcome = "stored" | "too_large" | "unavailable";
+interface DeviceSettingsApi {
+    readonly current: DeviceSettings | null;
+    wait(timeoutMs?: number): Promise<DeviceSettings | null>;
+    put(settings: DeviceSettings): Promise<DeviceSettingsPutOutcome>;
+}
 declare const DEVICE_SETTINGS_MAX_BYTES = 16384;
 declare const ARCADE_EMBEDDERS: readonly string[];
 interface GemOptions {
@@ -4165,6 +4287,16 @@ interface GemInsets {
 }
 interface GemViewport {
     readonly insets: GemInsets;
+    readonly reserved: readonly GemReservedArea[];
+}
+interface GemReservedArea {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface WalletVisibleOptions {
+    readonly only?: readonly string[];
 }
 interface GemTerminationNotice {
     readonly reason: GemWillTerminate["reason"];
@@ -4189,6 +4321,7 @@ interface Gem {
     readonly deviceSettings: DeviceSettingsApi;
     readonly ads: AdsApi;
     readonly account: AccountApi;
+    readonly share: ShareApi;
     readonly analytics: AnalyticsApi;
     readonly leaderboards: LeaderboardsApi;
     readonly challenges: ChallengesApi;
@@ -4204,6 +4337,7 @@ interface Gem {
     awaitCohorts(timeoutMs?: number): Promise<GemCohorts | null>;
     reportMuted(muted: boolean): void;
     cueReward(cue: RewardCue): boolean;
+    setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean;
     exit(reason?: string): Promise<void>;
     readonly boot: BootTimeline;
     readonly frame: GemFrame;
@@ -4229,4 +4363,4 @@ interface ExitAnalytics {
 }
 declare function leaveAndExit(rooms: ExitRooms, bridge: ExitBridge | null, reason?: string, analytics?: ExitAnalytics): Promise<void>;
 declare function createGem(options?: GemOptions): Gem;
-export { ARCADE_EMBEDDERS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameConfig, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemIdentity, type GemInsets, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, LeaderboardsApi, type ListChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };
+export { ARCADE_EMBEDDERS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameConfig, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemIdentity, type GemInsets, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, LeaderboardsApi, type ListChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type WalletVisibleOptions, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };

package/docs/achievements.md

@@ -0,0 +1,232 @@
+# Achievements
+
+An **achievement** is a platform-wide recognition a player earns in your game: a name, a
+description and some **achievement points**. The arcade lists your achievements on your store page, shows each player what they have unlocked, and
+adds their points to their **Achievement Score**, a total that spans every game they play (§5).
+
+There is no achievements API to call. An achievement sits on a **progression threshold your game
+already has**, and it unlocks when your server, or a serverless function the player called, moves
+that progression past it. Everything here is
+built from things [inventory-and-catalogs.md](inventory-and-catalogs.md) §13 already covers — read
+that first.
+
+## 1. Declaring one
+
+An achievement is a kind of `platform_grants` entry, on either of the two thresholds a progression
+has: its `completion_threshold`, or one level of a track. The full schema and its validation rules
+are in the gemctl `game-config` skill; the shape is:
+
+```yaml
+progressions:
+  - slug: boards_cleared
+    display_name: Boards cleared
+    config:
+      tracks:
+        - track_id: main
+          levels:
+            - level: 1
+              threshold: 10
+              platform_grants:
+                - achievement:
+                    id: 91ac… # its own id, stable forever
+                    points: 20
+                    display_name: Getting the Hang of It
+                    description: Clear 10 boards.
+            - level: 2
+              threshold: 100
+              platform_grants:
+                - achievement:
+                    id: c47d…
+                    points: 150
+                    visibility: hidden
+                    hidden_hint: See it through.
+                    display_name: Every Door Opened
+                    description: Clear all 100 boards.
+```
+
+One counter with a level per tier is the usual shape: "clear 10, 50, 100 boards" is three levels on
+one progression, not three progressions.
+
+What the upload enforces, so you are not surprised by it:
+
+- **A budget.** Your game's achievements may be worth at most **1,000 points** in total, and your
+  game may have at most **200 achievements** over its life — both counting ones you have since
+  removed, so retiring an achievement never frees room for another. Points are identity, not
+  currency — a player cannot spend them, and a game cannot mint them freely.
+- **Nothing in your config may put value into its progression.** An achievement that awards
+  points or rewards may not sit on a progression that a recipe's cost or grant, a loot-table
+  entry, another progression's `rewards_on_complete` or a track level's `rewards` can raise — a
+  `progression_add` of a positive amount, or a `progression_set`. Unlocking counts the stored value
+  (§2), so any such write decides what your server's next write unlocks: a recipe priced in Gems
+  that adds 100 to `boards_cleared` would sell "Clear all 100 boards" to anyone with the Gems. A
+  reset or a spend (a negative add) is fine — it cannot buy an unlock that happens once. The
+  refusal is anchored at the achievement and names the operation that writes it:
+
+  ```text
+  progressions[0] (boards_cleared): platform_grants[0]: source is written by an operation in this
+  config — catalogs[0] (shop) recipes[0] (board_pack) grants[0]. An achievement that awards points
+  or rewards is earned only by the game server's own progression_add or progression_max, …
+  ```
+
+  Keep the counter your server advances separate from anything a player can buy, open or claim.
+  A display-only achievement (`points: 0`, no rewards) may sit on such a progression.
+
+- **Released achievements are fixed.** Once a release carries an achievement, its `points`,
+  `rewards`, `visibility` and _where it sits_ — which progression, which level, and that threshold —
+  cannot change. Its copy can. Removing it retires it: players who hold it keep it, and its points
+  still count against your budget.
+- **The text is screened.** Copy that impersonates the platform or its staff is refused, and the
+  refusal names the rule it broke.
+
+## 2. Who unlocks it
+
+An achievement unlocks when an **eligible order** leaves the progression's value at or above the
+threshold it sits on. Eligible means:
+
+- written by **your game's server**, running as a platform-allocated server with its game-server
+  credential, **or by your serverless function, for the player who called it**. A browser write
+  never unlocks one, and neither does a server you started yourself with a developer credential —
+  its receipt says `suppressed`, with the reason `principal=developer-minted server token`;
+- when a function wrote it, **on a progression that opts in** with `function_may_grant: true`
+  (otherwise `suppressed`, `functions_not_opted_in`), **for the player who called the function**,
+  and not for a guest (`function_invoker_is_guest`). A function a player called cannot write any
+  other player at all (`403 function_foreign_entity_write`), and a character never unlocks one.
+  A function your dedicated server called acts for your game, like the server. Every receipt a
+  function's order produces carries `principal: "function"`
+  ([serverless-functions.md](serverless-functions.md#paying-the-player-who-called));
+- on the **`release` channel**. Writes on `dev` and `test` do cross the threshold, and the receipt
+  says so as `suppressed` with the channel as the reason, but nothing unlocks: an unlock is
+  permanent, so testing must not spend one.
+
+**The platform checks which credential wrote the progression. It cannot check why.** Your server's
+or your function's own logic is the whole defence, and a function is the easier one to lean on: a
+player can call it with any input they like, as often as their per-minute budget allows. Advance a progression that carries achievements only from what your
+server observed or simulated itself — a match it ran, a board it scored — never from a player's
+claim ("I cleared board 50"), and never through a handler that passes a client's request straight
+through to a progression write. Apply the same plausibility and rate checks you would apply before
+paying currency.
+
+It unlocks **once per player, ever**. Resetting the progression and crossing the threshold again
+does nothing, and neither the completion flag nor claiming a level's rewards plays any part. A player
+whose value was already past the threshold before your release unlocks it on your server's **next
+write** to that progression.
+
+⚠️ **That catch-up counts the stored value, whoever wrote it.** That is why nothing in your config
+may write the progression (§1), and why an achievement that pays points or rewards belongs on a
+progression the browser has never been able to write. If a progression used to be
+`client_writable`, or used to be written by a recipe, a loot table or a reward, its players' values
+may not be your server's; make a new progression for the achievement rather than removing the other
+writer from the old one. A release uploaded before this rule that still has such a writer unlocks
+nothing there: the receipt says `suppressed`, with the reason `written_by_config`, until you upload
+a config without it.
+
+A progression the browser may write (`client_writable: true`) can carry only **display-only**
+achievements: `points: 0` and no rewards. They never unlock on the platform — no record, no
+receipt, nothing on the arcade — so a game that lists one works out its state itself, from
+`currentValue >= threshold`.
+
+The platform can switch achievements off for your game. When it has, the receipt says
+`suppressed` with the reason `achievements_disabled` — read that before suspecting your config. It
+can also switch off only what serverless functions pay and unlock; a function's unlock then reads
+`suppressed` with `functions_disabled`.
+
+## 3. On your server: what the order unlocked
+
+Your server writes the progression as it always has, and the order it gets back carries a receipt for
+each achievement threshold the write crossed, plus any achievement it unlocked by catching up. The
+server entry's `achievementReceipts` reads them off; the package itself is installed as
+[getting-started.md](getting-started.md) describes.
+
+```js
+import { achievementReceipts } from '@indiegems/gem-web-sdk/server';
+
+const order = await gem.api.addEntityProgression('players', playerId, 'boards_cleared', {
+  amount: 1,
+});
+for (const r of achievementReceipts(order)) {
+  if (r.outcome === 'unlocked') log(`${playerId} unlocked ${r.achievementId} (+${r.points})`);
+  if (r.outcome === 'suppressed') log(`${r.achievementId} not unlocked: ${r.reason}`);
+}
+```
+
+| `outcome`          | Means                                                                            |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `unlocked`         | This order unlocked it, and `points` is what it credited                         |
+| `already_unlocked` | The write crossed it again — after a reset — and the player already holds it     |
+| `suppressed`       | It was not unlocked, and `reason` says why — for your logs, never for the player |
+
+The list is empty when the write crossed no threshold, which is almost every write. For a batch,
+read each entry of the result's `orders`. For a "best score" progression, use the `progression_max`
+operation on `gem.api.createEntityOrder`; its result reads the same way.
+
+**A receipt is a report, not a trigger.** A retried or replayed order reports nothing — the
+threshold is already behind it — so a game-side reward keyed off `unlocked` is lost whenever the
+first response never arrived. Put a game reward in the same threshold's `rewards`, which the
+platform pays on the crossing itself, and read the player's standing from the progression. Those
+rewards pay again if the progression resets and is crossed again; the achievement does not.
+
+## 4. In the game: showing the player's standing
+
+The progression reads your client already makes carry each achievement on the progression and
+whether this player has it:
+
+```js
+const p = await gem.me.progressions.get('boards_cleared');
+for (const a of p?.achievements ?? []) {
+  const state = a.revoked ? 'removed' : a.unlockedAt !== undefined ? 'unlocked' : 'locked';
+  // a.id, a.threshold, a.points, a.hidden
+}
+if (p?.achievementsUnavailable) {
+  // The list is right, but whether each is unlocked could not be read just now. Show no
+  // "locked" state from this read. A later get() asks the backend again rather than the cache.
+}
+```
+
+The standing comes from the platform's unlock record, not from the progression's value — so after a
+reset, `isCompleted` is `false` and `currentValue` is back at zero, and the achievement still reads
+as unlocked. `revoked` means the platform removed an unlock; it cannot be earned again. `points` is
+what the achievement awards while locked, and what the unlock credited once held.
+
+`achievements` is absent on a progression with none, and on a character's progressions: an
+achievement belongs to the player. A player who has never written the progression has no record of
+it, so `get` returns `null` and there is no list to read — to show locked achievements before the
+first write, list them from your own game config.
+
+The client caches what it reads, and an unlock happens on your server, so the client does not see
+it by itself. When your server tells the game a player unlocked something, call
+`gem.me.inventory.refresh()` before reading the progression again.
+
+**This read is for display.** Never send it to your server as proof that a player holds something;
+a modified client can report anything. Your server reads the standing itself.
+
+**`hidden` is a presentation rule, not a secret.** Your game already knows a hidden achievement's
+threshold — it is in your config. The arcade hides its name and description from players until they
+unlock it; if your game shows its own achievement list, do the same.
+
+## 5. Points are prestige: the Achievement Score
+
+Achievement points are a player's permanent standing on the arcade. They are **never spent,
+bought, boosted, decayed or expired**, and they are **removed only for fraud or moderation**.
+
+- **Never bought.** There is no achievement write API, and nothing a player pays for may write an
+  achievement's progression (§1) — so no price, pack or recipe reaches a point.
+- **Never boosted.** A Boost multiplies what some platform-currency grants pay. It never touches
+  achievement points: an unlock credits exactly the points your release registered for that
+  achievement, for every player, boosted or not.
+- **Never spent, decayed or expired.** Nothing consumes points, and resetting the progression,
+  retiring the achievement in a later release or a player's time away never takes them back.
+- **Removed only for fraud or moderation.** The platform can revoke an unlock — a player who
+  cheated, or a game whose server was compromised — and that removes its points. A revoked
+  achievement cannot be earned again. This is the platform's decision, never a game's.
+
+The **Achievement Score** is the one number the arcade shows for them: every point a player holds
+from every game's achievements, plus the points of the platform's own achievements. Your game never
+computes it, and should not restate it as a currency of its own: it moves only when an unlock
+credits points or a revocation removes them.
+
+## What to read next
+
+- [`inventory-and-catalogs.md`](inventory-and-catalogs.md) §13 — progressions and platform grants,
+  which this page builds on.
+- [`server-bundles.md`](server-bundles.md) — how your server gets the credential that makes a write
+  eligible.