@origingame/engine 0.0.0-stage → 0.1.1

package/knowledge/wiki/platform.md

@@ -0,0 +1,857 @@
+<!-- Generated from crates/og-api/api.ogt by `og api gen`. Do not edit: `og api check` fails on any difference; change api.ogt and regenerate. -->
+
+# The `platform` module
+
+Platform services as host capabilities (docs/design.md §2.8): cloud store, leaderboards, telemetry, Origin Point and AI marks. Game code names a method and its arguments, never a credential, a URL or a cookie: the host owns them. On the web the shell forwards each call to the Player through origin-checked postMessage (Player protocol 2, docs/web-export.md); natively the host answers from a local JSON store (`og run --platform-store`, default `<project>/.og/platform.json`).
+
+Calls are asynchronous: each returns a request number at once, and the answer arrives at the start of a later tick, when og.platform sends PlatformAnswered; read it with og.platform.result. Answers are host input, like key presses: the probe's `dump_platform` lists every call, its arguments, its answer and the ticks.
+
+Errors carry the Player's stable codes: offline, timeout, invalid, unauthorized, not_found, conflict, too_large, rate_limited, unavailable, failed; retryable is true for offline, timeout, unavailable and rate_limited.
+
+- **TypeScript**: functions are the namespace `og.platform`; components, resources and events are tokens on `og`.
+- **Publish builds**: kept (members may override).
+- **Skill**: `og-platform-sdk`, which teaches the module (how much of it to use, and how to prove it).
+- **Index**: [every module and name](index.md).
+
+```ogt
+module platform {
+  # declarations follow, each quoted below
+```
+
+<sub>`api.ogt` line 7489</sub>
+
+## Contents
+
+| Name | Kind | Summary |
+|---|---|---|
+| [`PlatformOrder`](#type-PlatformOrder) | enum | How a leaderboard sorts; the first submission to a board fixes it. |
+| [`og.PlatformAnswered`](#record-PlatformAnswered) | event | An answer arrived: sent by og.platform at the start of the tick it was applied, read by systems the tick after (og.platform.result has it at once). |
+| [`StoreSetDesc`](#type-StoreSetDesc) | desc struct | A write to the store. |
+| [`LeaderboardSubmitDesc`](#type-LeaderboardSubmitDesc) | desc struct | A score. |
+| [`LeaderboardQueryDesc`](#type-LeaderboardQueryDesc) | desc struct | Which entries. |
+| [`PointDesc`](#type-PointDesc) | desc struct | Origin Point for something the player did. |
+| [`AiMarkDesc`](#type-AiMarkDesc) | desc struct | Marks content the game shows as generated by AI, for the platform's disclosure. |
+| [`SaveSlotDesc`](#type-SaveSlotDesc) | desc struct | A save slot: a long text (a world.snapshot()) kept across as many store keys as it needs. |
+| [`LoadSlotDesc`](#type-LoadSlotDesc) | desc struct | Which slot to read, and how much of it. |
+| [`PlatformError`](#type-PlatformError) | struct | Why a call failed. |
+| [`PlatformResult`](#type-PlatformResult) | struct | The answer to one call. |
+| [`PlatformInfo`](#type-PlatformInfo) | struct | What answers platform calls here. |
+| [`og.platform.storeGet`](#fn-storeGet) | function | Read one key of the player's store for this game. |
+| [`og.platform.storeSet`](#fn-storeSet) | function | Write one key of the player's store for this game; with a revision, only if nobody wrote it since (another device, another tab). |
+| [`og.platform.storeList`](#fn-storeList) | function | The keys of the player's store and their revisions. |
+| [`og.platform.leaderboardSubmit`](#fn-leaderboardSubmit) | function | Submit a score; the board keeps the player's best. |
+| [`og.platform.leaderboardTop`](#fn-leaderboardTop) | function | The best entries of a board, and the player's own. |
+| [`og.platform.leaderboardAround`](#fn-leaderboardAround) | function | The entries around the player's rank. |
+| [`og.platform.telemetry`](#fn-telemetry) | function | Record a game event for the game's analytics. |
+| [`og.platform.point`](#fn-point) | function | Ask for Origin Point for something the player did. |
+| [`og.platform.aiMark`](#fn-aiMark) | function | Disclose AI-generated content the game shows. |
+| [`og.platform.loadSettings`](#fn-loadSettings) | function | Ask for the game's saved settings (volume, controls, language): store.get of the key `og.settings`. Where the Player has no store, or is offline, the shell answers from the browser's own storage; natively, from the local store. |
+| [`og.platform.saveSettings`](#fn-saveSettings) | function | Save the game's settings under `og.settings` (the last save wins), with the same local fallback as loadSettings. |
+| [`og.platform.saveSlot`](#fn-saveSlot) | function | Save a long text under a slot, in as many store keys as it needs: a mid-size 3D world's snapshot is over a key's 64 KiB (examples/kestrel-stair's 93 entities: about 78 KB). The parts go in the bank of keys the slot's last save did not use (`<slot>.a*` or `<slot>.b*`), then the manifest (`<slot>`: the bank, the part count, the length, a checksum and `meta`) is written last, at the revision read before: so a save cut short leaves the last one whole, and another device's save landing meanwhile is a conflict, never a mix. One request for all of it; a slot takes at most 17 of the player's 64 keys for this game. og-game §17. |
+| [`og.platform.loadSlot`](#fn-loadSlot) | function | Read a slot saveSlot wrote: its manifest, then its parts, joined and checked against the manifest's length and checksum. One request for all of it. |
+| [`og.platform.result`](#fn-result) | function | The answer to a call, once it arrived. |
+| [`og.platform.info`](#fn-info) | function | What answers platform calls here, and what it answers. |
+| [`og.platform.now`](#fn-now) | function | The host's wall-clock time, UTC milliseconds since 1970, as of this tick: what the host last told the engine (when it attached, and with every answer, applied at a tick's start like the answers) moved on by the ticks since. The one wall-clock read game code may make: it is host input, so a replay with the same answers gives the same values. Use it to know how long the game was closed (a save's time against a launch's), never to time play (that is og.Time). |
+
+## Functions
+
+<a id="fn-storeGet"></a>
+
+### `og.platform.storeGet`
+
+Read one key of the player's store for this game.
+
+```ts
+og.platform.storeGet(world: World, key: string): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `key` | `string` | no | The key. |
+
+**Returns** `Result<number>`: Refused for a malformed key. The answer's data is `{ key, value, revision }` (value null and revision 0 for a key never written).
+
+Binding symbol `og_platform_store_get` · publish builds: kept
+
+```ogt
+fn storeGet {
+  doc "Read one key of the player's store for this game."
+  param world World "The world."
+  param key String "The key."
+  returns Result.u32 "Refused for a malformed key. The answer's data is `{ key, value, revision }` (value null and revision 0 for a key never written)."
+}
+```
+
+<sub>`api.ogt` line 7604</sub>
+
+<a id="fn-storeSet"></a>
+
+### `og.platform.storeSet`
+
+Write one key of the player's store for this game; with a revision, only if nobody wrote it since (another device, another tab).
+
+```ts
+og.platform.storeSet(world: World, desc?: StoreSetDesc): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `StoreSetDesc` | yes | The key, the value and the revision it must be at. |
+
+**Returns** `Result<number>`: Refused for a malformed key or a value over 64 KiB. The answer's data is `{ key, revision }` (the new revision); `conflict` when the key moved past desc.revision.
+
+Binding symbol `og_platform_store_set` · publish builds: kept
+
+```ogt
+fn storeSet {
+  doc "Write one key of the player's store for this game; with a revision, only if nobody wrote it since (another device, another tab)."
+  param world World "The world."
+  param desc StoreSetDesc "The key, the value and the revision it must be at."
+  returns Result.u32 "Refused for a malformed key or a value over 64 KiB. The answer's data is `{ key, revision }` (the new revision); `conflict` when the key moved past desc.revision."
+}
+```
+
+<sub>`api.ogt` line 7611</sub>
+
+<a id="fn-storeList"></a>
+
+### `og.platform.storeList`
+
+The keys of the player's store and their revisions.
+
+```ts
+og.platform.storeList(world: World): number
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+
+**Returns** `number`: The answer's data is `{ keys: [{ key, revision }] }`.
+
+Binding symbol `og_platform_store_list` · publish builds: kept
+
+```ogt
+fn storeList {
+  doc "The keys of the player's store and their revisions."
+  param world World "The world."
+  returns u32 "The answer's data is `{ keys: [{ key, revision }] }`."
+}
+```
+
+<sub>`api.ogt` line 7618</sub>
+
+<a id="fn-leaderboardSubmit"></a>
+
+### `og.platform.leaderboardSubmit`
+
+Submit a score; the board keeps the player's best.
+
+```ts
+og.platform.leaderboardSubmit(world: World, desc?: LeaderboardSubmitDesc): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `LeaderboardSubmitDesc` | yes | The board, the score and its order. |
+
+**Returns** `Result<number>`: Refused for a score that is not finite. The answer's data is `{ board, rank, best }`, or `{ board, rank: null, queued: true }` while offline.
+
+Binding symbol `og_platform_leaderboard_submit` · publish builds: kept
+
+```ogt
+fn leaderboardSubmit {
+  doc "Submit a score; the board keeps the player's best."
+  param world World "The world."
+  param desc LeaderboardSubmitDesc "The board, the score and its order."
+  returns Result.u32 "Refused for a score that is not finite. The answer's data is `{ board, rank, best }`, or `{ board, rank: null, queued: true }` while offline."
+}
+```
+
+<sub>`api.ogt` line 7624</sub>
+
+<a id="fn-leaderboardTop"></a>
+
+### `og.platform.leaderboardTop`
+
+The best entries of a board, and the player's own.
+
+```ts
+og.platform.leaderboardTop(world: World, desc?: LeaderboardQueryDesc): number
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `LeaderboardQueryDesc` | yes | The board and how many. |
+
+**Returns** `number`: The answer's data is `{ board, order, entries: [{ rank, name, score, me }], me }`.
+
+Binding symbol `og_platform_leaderboard_top` · publish builds: kept
+
+```ogt
+fn leaderboardTop {
+  doc "The best entries of a board, and the player's own."
+  param world World "The world."
+  param desc LeaderboardQueryDesc "The board and how many."
+  returns u32 "The answer's data is `{ board, order, entries: [{ rank, name, score, me }], me }`."
+}
+```
+
+<sub>`api.ogt` line 7631</sub>
+
+<a id="fn-leaderboardAround"></a>
+
+### `og.platform.leaderboardAround`
+
+The entries around the player's rank.
+
+```ts
+og.platform.leaderboardAround(world: World, desc?: LeaderboardQueryDesc): number
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `LeaderboardQueryDesc` | yes | The board and how many around the player. |
+
+**Returns** `number`: The answer's data is the leaderboardTop shape with the entries around the player's rank.
+
+Binding symbol `og_platform_leaderboard_around` · publish builds: kept
+
+```ogt
+fn leaderboardAround {
+  doc "The entries around the player's rank."
+  param world World "The world."
+  param desc LeaderboardQueryDesc "The board and how many around the player."
+  returns u32 "The answer's data is the leaderboardTop shape with the entries around the player's rank."
+}
+```
+
+<sub>`api.ogt` line 7638</sub>
+
+<a id="fn-telemetry"></a>
+
+### `og.platform.telemetry`
+
+Record a game event for the game's analytics.
+
+```ts
+og.platform.telemetry(world: World, name: string, attrs?: unknown): Result<void>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `name` | `string` | no | The event: `level.started`, `level.completed`, `boss.defeated` (letters, digits, `.`, `_`; the Player files it as `game.custom.<name>`). |
+| `attrs` | `unknown` | yes | Its attributes: an object of at most 16 strings (up to 512 characters), numbers, booleans or null, keys a lowercase letter then letters, digits and `_`. |
+
+**Returns** `Result<void>`: Refused for a malformed name or attributes. Fire and forget: nothing answers.
+
+Binding symbol `og_platform_telemetry` · publish builds: kept
+
+```ogt
+fn telemetry {
+  doc "Record a game event for the game's analytics."
+  param world World "The world."
+  param name String "The event: `level.started`, `level.completed`, `boss.defeated` (letters, digits, `.`, `_`; the Player files it as `game.custom.<name>`)."
+  param attrs Json "Its attributes: an object of at most 16 strings (up to 512 characters), numbers, booleans or null, keys a lowercase letter then letters, digits and `_`." {
+    optional true
+  }
+  returns Result.Void "Refused for a malformed name or attributes. Fire and forget: nothing answers."
+}
+```
+
+<sub>`api.ogt` line 7645</sub>
+
+<a id="fn-point"></a>
+
+### `og.platform.point`
+
+Ask for Origin Point for something the player did.
+
+```ts
+og.platform.point(world: World, desc?: PointDesc): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `PointDesc` | yes | Why and how many. |
+
+**Returns** `Result<number>`: Refused for a reason outside 1 to 64 of letters, digits, `.`, `_` and `-`. The answer's data is `{ granted, balance }`; under a Player today always `{ granted: 0, balance: null }` (the platform grants nothing until a release carries an approved point policy), locally the amount asked.
+
+Binding symbol `og_platform_point` · publish builds: kept
+
+```ogt
+fn point {
+  doc "Ask for Origin Point for something the player did."
+  param world World "The world."
+  param desc PointDesc "Why and how many."
+  returns Result.u32 "Refused for a reason outside 1 to 64 of letters, digits, `.`, `_` and `-`. The answer's data is `{ granted, balance }`; under a Player today always `{ granted: 0, balance: null }` (the platform grants nothing until a release carries an approved point policy), locally the amount asked."
+}
+```
+
+<sub>`api.ogt` line 7655</sub>
+
+<a id="fn-aiMark"></a>
+
+### `og.platform.aiMark`
+
+Disclose AI-generated content the game shows.
+
+```ts
+og.platform.aiMark(world: World, desc?: AiMarkDesc): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `AiMarkDesc` | yes | What was generated. |
+
+**Returns** `Result<number>`: Refused for an empty kind or label. The answer's data is `{ marked: true }`.
+
+Binding symbol `og_platform_ai_mark` · publish builds: kept
+
+```ogt
+fn aiMark {
+  doc "Disclose AI-generated content the game shows."
+  param world World "The world."
+  param desc AiMarkDesc "What was generated."
+  returns Result.u32 "Refused for an empty kind or label. The answer's data is `{ marked: true }`."
+}
+```
+
+<sub>`api.ogt` line 7662</sub>
+
+<a id="fn-loadSettings"></a>
+
+### `og.platform.loadSettings`
+
+Ask for the game's saved settings (volume, controls, language): store.get of the key `og.settings`. Where the Player has no store, or is offline, the shell answers from the browser's own storage; natively, from the local store.
+
+```ts
+og.platform.loadSettings(world: World): number
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+
+**Returns** `number`: The request; its answer's data is `{ key, value, revision }` (value null before the first save).
+
+Binding symbol `og_platform_load_settings` · publish builds: kept
+
+```ogt
+fn loadSettings {
+  doc "Ask for the game's saved settings (volume, controls, language): store.get of the key `og.settings`. Where the Player has no store, or is offline, the shell answers from the browser's own storage; natively, from the local store."
+  param world World "The world."
+  returns u32 "The request; its answer's data is `{ key, value, revision }` (value null before the first save)."
+}
+```
+
+<sub>`api.ogt` line 7669</sub>
+
+<a id="fn-saveSettings"></a>
+
+### `og.platform.saveSettings`
+
+Save the game's settings under `og.settings` (the last save wins), with the same local fallback as loadSettings.
+
+```ts
+og.platform.saveSettings(world: World, value: unknown): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `value` | `unknown` | no | The settings: an object, at most 64 KiB encoded. |
+
+**Returns** `Result<number>`: Refused for a value that is not an object or is too large.
+
+Binding symbol `og_platform_save_settings` · publish builds: kept
+
+```ogt
+fn saveSettings {
+  doc "Save the game's settings under `og.settings` (the last save wins), with the same local fallback as loadSettings."
+  param world World "The world."
+  param value Json "The settings: an object, at most 64 KiB encoded."
+  returns Result.u32 "Refused for a value that is not an object or is too large."
+}
+```
+
+<sub>`api.ogt` line 7675</sub>
+
+<a id="fn-saveSlot"></a>
+
+### `og.platform.saveSlot`
+
+Save a long text under a slot, in as many store keys as it needs: a mid-size 3D world's snapshot is over a key's 64 KiB (examples/kestrel-stair's 93 entities: about 78 KB). The parts go in the bank of keys the slot's last save did not use (`<slot>.a*` or `<slot>.b*`), then the manifest (`<slot>`: the bank, the part count, the length, a checksum and `meta`) is written last, at the revision read before: so a save cut short leaves the last one whole, and another device's save landing meanwhile is a conflict, never a mix. One request for all of it; a slot takes at most 17 of the player's 64 keys for this game. og-game §17.
+
+```ts
+og.platform.saveSlot(world: World, desc?: SaveSlotDesc): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `SaveSlotDesc` | yes | The slot, the text and what a title shows of it. |
+
+**Returns** `Result<number>`: Refused for a malformed slot name, a text over 512 KiB or a meta over 4 KiB. The answer arrives when the manifest is written: data `{ slot, parts, bytes, revision }`; an error is the first refused part's, or the manifest's (`conflict`: another save of the slot landed meanwhile; the slot holds that one).
+
+Binding symbol `og_platform_save_slot` · publish builds: kept
+
+```ogt
+fn saveSlot {
+  doc "Save a long text under a slot, in as many store keys as it needs: a mid-size 3D world's snapshot is over a key's 64 KiB (examples/kestrel-stair's 93 entities: about 78 KB). The parts go in the bank of keys the slot's last save did not use (`<slot>.a*` or `<slot>.b*`), then the manifest (`<slot>`: the bank, the part count, the length, a checksum and `meta`) is written last, at the revision read before: so a save cut short leaves the last one whole, and another device's save landing meanwhile is a conflict, never a mix. One request for all of it; a slot takes at most 17 of the player's 64 keys for this game. og-game §17."
+  param world World "The world."
+  param desc SaveSlotDesc "The slot, the text and what a title shows of it."
+  returns Result.u32 "Refused for a malformed slot name, a text over 512 KiB or a meta over 4 KiB. The answer arrives when the manifest is written: data `{ slot, parts, bytes, revision }`; an error is the first refused part's, or the manifest's (`conflict`: another save of the slot landed meanwhile; the slot holds that one)."
+}
+```
+
+<sub>`api.ogt` line 7682</sub>
+
+<a id="fn-loadSlot"></a>
+
+### `og.platform.loadSlot`
+
+Read a slot saveSlot wrote: its manifest, then its parts, joined and checked against the manifest's length and checksum. One request for all of it.
+
+```ts
+og.platform.loadSlot(world: World, desc?: LoadSlotDesc): Result<number>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `desc` | `LoadSlotDesc` | yes | The slot, and whether to read its meta alone. |
+
+**Returns** `Result<number>`: Refused for a malformed slot name. The answer's data is `{ slot, text, meta, parts, bytes, revision }`: text and meta null for a slot never saved, text null with metaOnly; `invalid` for a key that holds no slot manifest or parts that do not match it.
+
+Binding symbol `og_platform_load_slot` · publish builds: kept
+
+```ogt
+fn loadSlot {
+  doc "Read a slot saveSlot wrote: its manifest, then its parts, joined and checked against the manifest's length and checksum. One request for all of it."
+  param world World "The world."
+  param desc LoadSlotDesc "The slot, and whether to read its meta alone."
+  returns Result.u32 "Refused for a malformed slot name. The answer's data is `{ slot, text, meta, parts, bytes, revision }`: text and meta null for a slot never saved, text null with metaOnly; `invalid` for a key that holds no slot manifest or parts that do not match it."
+}
+```
+
+<sub>`api.ogt` line 7689</sub>
+
+<a id="fn-result"></a>
+
+### `og.platform.result`
+
+The answer to a call, once it arrived.
+
+```ts
+og.platform.result(world: World, request: number): PlatformResult | null
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `request` | `number` | no | The call. |
+
+**Returns** `PlatformResult | null`: Null while it is in flight, or for an unknown request.
+
+Binding symbol `og_platform_result` · publish builds: kept
+
+```ogt
+fn result {
+  doc "The answer to a call, once it arrived."
+  param world World "The world."
+  param request u32 "The call."
+  returns Option.PlatformResult "Null while it is in flight, or for an unknown request."
+}
+```
+
+<sub>`api.ogt` line 7696</sub>
+
+<a id="fn-info"></a>
+
+### `og.platform.info`
+
+What answers platform calls here, and what it answers.
+
+```ts
+og.platform.info(world: World): PlatformInfo
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+
+**Returns** `PlatformInfo`.
+
+Binding symbol `og_platform_info` · publish builds: kept
+
+```ogt
+fn info {
+  doc "What answers platform calls here, and what it answers."
+  param world World "The world."
+  returns PlatformInfo
+}
+```
+
+<sub>`api.ogt` line 7703</sub>
+
+<a id="fn-now"></a>
+
+### `og.platform.now`
+
+The host's wall-clock time, UTC milliseconds since 1970, as of this tick: what the host last told the engine (when it attached, and with every answer, applied at a tick's start like the answers) moved on by the ticks since. The one wall-clock read game code may make: it is host input, so a replay with the same answers gives the same values. Use it to know how long the game was closed (a save's time against a launch's), never to time play (that is og.Time).
+
+```ts
+og.platform.now(world: World): number
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+
+**Returns** `number`: UTC milliseconds; 0 until a host has told the time (`none`).
+
+Binding symbol `og_platform_now` · publish builds: kept
+
+```ogt
+fn now {
+  doc "The host's wall-clock time, UTC milliseconds since 1970, as of this tick: what the host last told the engine (when it attached, and with every answer, applied at a tick's start like the answers) moved on by the ticks since. The one wall-clock read game code may make: it is host input, so a replay with the same answers gives the same values. Use it to know how long the game was closed (a save's time against a launch's), never to time play (that is og.Time)."
+  param world World "The world."
+  returns f64 "UTC milliseconds; 0 until a host has told the time (`none`)."
+}
+```
+
+<sub>`api.ogt` line 7709</sub>
+
+## Components, resources and events
+
+<a id="record-PlatformAnswered"></a>
+
+### `og.PlatformAnswered` (event)
+
+An answer arrived: sent by og.platform at the start of the tick it was applied, read by systems the tick after (og.platform.result has it at once).
+
+Token `og.PlatformAnswered`, registered under the schema name `og.PlatformAnswered`; its value type is `PlatformAnswered`.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `request` | `number` | `0` | — | — | — | The call's request number. |
+| `ok` | `boolean` | `false` | — | — | — | Whether it succeeded; og.platform.result has the data or the error. |
+
+```ogt
+event PlatformAnswered {
+  doc "An answer arrived: sent by og.platform at the start of the tick it was applied, read by systems the tick after (og.platform.result has it at once)."
+  field request u32 "The call's request number."
+  field ok bool "Whether it succeeded; og.platform.result has the data or the error."
+}
+```
+
+<sub>`api.ogt` line 7501</sub>
+
+## Types
+
+<a id="type-PlatformOrder"></a>
+
+### `PlatformOrder` (enum)
+
+How a leaderboard sorts; the first submission to a board fixes it.
+
+A string: one of the variants below. The zero value is `"desc"`.
+
+| Variant | Doc |
+|---|---|
+| `"desc"` | Higher is better (scores). |
+| `"asc"` | Lower is better (times). |
+
+```ogt
+enum PlatformOrder {
+  doc "How a leaderboard sorts; the first submission to a board fixes it."
+  variant desc "Higher is better (scores)."
+  variant asc "Lower is better (times)."
+}
+```
+
+<sub>`api.ogt` line 7495</sub>
+
+<a id="type-StoreSetDesc"></a>
+
+### `StoreSetDesc` (desc struct)
+
+A write to the store.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `key` | `string` | `""` | — | — | — | The key: 1 to 64 of letters, digits, `.`, `_` and `-`. |
+| `value` | `unknown` | `null` | — | — | — | Any JSON value, at most 64 KiB encoded. |
+| `revision` | `number` | `0` | — | — | — | Write only if the key is at this revision (a conflict otherwise, whose error carries the revision the key is at now); 0 writes whatever is there (the last write wins). |
+| `create` | `boolean` | `false` | — | — | — | Write only if the key has never been written (a conflict otherwise); revision is then ignored. |
+
+```ogt
+struct StoreSetDesc {
+  doc "A write to the store."
+  desc true
+  field key String "The key: 1 to 64 of letters, digits, `.`, `_` and `-`."
+  field value Json "Any JSON value, at most 64 KiB encoded."
+  field revision u32 "Write only if the key is at this revision (a conflict otherwise, whose error carries the revision the key is at now); 0 writes whatever is there (the last write wins)."
+  field create bool "Write only if the key has never been written (a conflict otherwise); revision is then ignored."
+}
+```
+
+<sub>`api.ogt` line 7507</sub>
+
+<a id="type-LeaderboardSubmitDesc"></a>
+
+### `LeaderboardSubmitDesc` (desc struct)
+
+A score.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `board` | `string` | `"main"` | — | — | — | The board (default `main`). |
+| `score` | `number` | `0` | — | — | — | The score, or a time in seconds for an ascending board. |
+| `order` | `PlatformOrder` | `"desc"` | — | — | — | How the board sorts, fixed by its first submission. |
+
+```ogt
+struct LeaderboardSubmitDesc {
+  doc "A score."
+  desc true
+  field board String "The board (default `main`)." {
+    default "main"
+  }
+  field score f64 "The score, or a time in seconds for an ascending board."
+  field order PlatformOrder "How the board sorts, fixed by its first submission."
+}
+```
+
+<sub>`api.ogt` line 7516</sub>
+
+<a id="type-LeaderboardQueryDesc"></a>
+
+### `LeaderboardQueryDesc` (desc struct)
+
+Which entries.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `board` | `string` | `"main"` | — | — | — | The board (default `main`). |
+| `count` | `number` | `10` | 1 … 100 | — | — | How many entries: the top `count`, or `count` around the player. |
+
+```ogt
+struct LeaderboardQueryDesc {
+  doc "Which entries."
+  desc true
+  field board String "The board (default `main`)." {
+    default "main"
+  }
+  field count u32 "How many entries: the top `count`, or `count` around the player." {
+    default 10
+    min 1
+    max 100
+  }
+}
+```
+
+<sub>`api.ogt` line 7526</sub>
+
+<a id="type-PointDesc"></a>
+
+### `PointDesc` (desc struct)
+
+Origin Point for something the player did.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `reason` | `string` | `""` | — | — | — | Why, as the game names it: `level.completed`, `daily.streak` (1 to 64 of letters, digits, `.`, `_` and `-`). |
+| `amount` | `number` | `1` | 1 … 1000 | — | — | How many points the game asks for; the platform decides what it grants. |
+
+```ogt
+struct PointDesc {
+  doc "Origin Point for something the player did."
+  desc true
+  field reason String "Why, as the game names it: `level.completed`, `daily.streak` (1 to 64 of letters, digits, `.`, `_` and `-`)."
+  field amount u32 "How many points the game asks for; the platform decides what it grants." {
+    default 1
+    min 1
+    max 1000
+  }
+}
+```
+
+<sub>`api.ogt` line 7539</sub>
+
+<a id="type-AiMarkDesc"></a>
+
+### `AiMarkDesc` (desc struct)
+
+Marks content the game shows as generated by AI, for the platform's disclosure.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `kind` | `string` | `""` | — | — | — | What: `text`, `image`, `audio`, `level`, `character` (1 to 32 of a-z, 0-9, `_` and `-`, a letter first). |
+| `label` | `string` | `""` | — | — | — | What the player sees it as, at most 120 characters. |
+| `model` | `string` | `""` | — | — | — | The model or service, when known (at most 80 characters). |
+
+```ogt
+struct AiMarkDesc {
+  doc "Marks content the game shows as generated by AI, for the platform's disclosure."
+  desc true
+  field kind String "What: `text`, `image`, `audio`, `level`, `character` (1 to 32 of a-z, 0-9, `_` and `-`, a letter first)."
+  field label String "What the player sees it as, at most 120 characters."
+  field model String "The model or service, when known (at most 80 characters)."
+}
+```
+
+<sub>`api.ogt` line 7550</sub>
+
+<a id="type-SaveSlotDesc"></a>
+
+### `SaveSlotDesc` (desc struct)
+
+A save slot: a long text (a world.snapshot()) kept across as many store keys as it needs.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `slot` | `string` | `""` | — | — | — | The slot's name: 1 to 60 of letters, digits, `.`, `_` and `-` (`slot1`). Its keys are the name itself (the manifest) and `<slot>.a0`, `<slot>.a1`, ... or `<slot>.b0`, ... (the parts). |
+| `text` | `string` | `""` | — | — | — | The text: at most 512 KiB of UTF-8 (eight parts of 64 KiB). |
+| `meta` | `unknown` | `null` | — | — | — | What a title screen shows of the slot (`{ place, hour }`), kept in the manifest so loadSlot with metaOnly reads it without the parts: any JSON, at most 4 KiB encoded. |
+
+```ogt
+struct SaveSlotDesc {
+  doc "A save slot: a long text (a world.snapshot()) kept across as many store keys as it needs."
+  desc true
+  field slot String "The slot's name: 1 to 60 of letters, digits, `.`, `_` and `-` (`slot1`). Its keys are the name itself (the manifest) and `<slot>.a0`, `<slot>.a1`, ... or `<slot>.b0`, ... (the parts)."
+  field text String "The text: at most 512 KiB of UTF-8 (eight parts of 64 KiB)."
+  field meta Json "What a title screen shows of the slot (`{ place, hour }`), kept in the manifest so loadSlot with metaOnly reads it without the parts: any JSON, at most 4 KiB encoded."
+}
+```
+
+<sub>`api.ogt` line 7558</sub>
+
+<a id="type-LoadSlotDesc"></a>
+
+### `LoadSlotDesc` (desc struct)
+
+Which slot to read, and how much of it.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `slot` | `string` | `""` | — | — | — | The slot's name, as saveSlot wrote it. |
+| `metaOnly` | `boolean` | `false` | — | — | — | Read the manifest alone: the answer's text stays null (a title's Continue label, before the player asks for the world). |
+
+```ogt
+struct LoadSlotDesc {
+  doc "Which slot to read, and how much of it."
+  desc true
+  field slot String "The slot's name, as saveSlot wrote it."
+  field metaOnly bool "Read the manifest alone: the answer's text stays null (a title's Continue label, before the player asks for the world)."
+}
+```
+
+<sub>`api.ogt` line 7566</sub>
+
+<a id="type-PlatformError"></a>
+
+### `PlatformError` (struct)
+
+Why a call failed.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `code` | `string` | `""` | — | — | — | offline, timeout, invalid, unauthorized, not_found, conflict, too_large, rate_limited, unavailable or failed. |
+| `message` | `string` | `""` | — | — | — | What happened, in words. |
+| `retryable` | `boolean` | `false` | — | — | — | Whether the same call may succeed later. |
+| `revision` | `number` | `0` | — | — | — | For a conflict of a conditional write: the revision the key is at now (read it again, merge, write at it); 0 otherwise. |
+
+```ogt
+struct PlatformError {
+  doc "Why a call failed."
+  field code String "offline, timeout, invalid, unauthorized, not_found, conflict, too_large, rate_limited, unavailable or failed."
+  field message String "What happened, in words."
+  field retryable bool "Whether the same call may succeed later."
+  field revision u32 "For a conflict of a conditional write: the revision the key is at now (read it again, merge, write at it); 0 otherwise."
+}
+```
+
+<sub>`api.ogt` line 7573</sub>
+
+<a id="type-PlatformResult"></a>
+
+### `PlatformResult` (struct)
+
+The answer to one call.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `request` | `number` | `0` | — | — | — | The call's request number. |
+| `method` | `string` | `""` | — | — | — | Its method, such as `store.get`. |
+| `ok` | `boolean` | `false` | — | — | — | Whether it succeeded. |
+| `data` | `unknown` | `null` | — | — | — | The answer (see each function); null on failure. |
+| `error` | `PlatformError` | `{ code: "", message: "", retryable: false, revision: 0 }` | — | — | optional | Why it failed. |
+| `tick` | `number` | `0` | — | — | — | The tick it was answered at. |
+| `time` | `number` | `0` | — | `ms` | — | The host's clock when it answered, UTC milliseconds since 1970 (PlatformInfo.clock says whose); 0 when the host gave none. |
+
+```ogt
+struct PlatformResult {
+  doc "The answer to one call."
+  field request u32 "The call's request number."
+  field method String "Its method, such as `store.get`."
+  field ok bool "Whether it succeeded."
+  field data Json "The answer (see each function); null on failure."
+  field error PlatformError "Why it failed." {
+    optional true
+  }
+  field tick u32 "The tick it was answered at."
+  field time f64 "The host's clock when it answered, UTC milliseconds since 1970 (PlatformInfo.clock says whose); 0 when the host gave none." {
+    unit ms
+  }
+}
+```
+
+<sub>`api.ogt` line 7581</sub>
+
+<a id="type-PlatformInfo"></a>
+
+### `PlatformInfo` (struct)
+
+What answers platform calls here.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `host` | `string` | `""` | — | — | — | `player` (a Player frames the game), `local` (the native host's JSON store or the browser's own storage) or `none`. |
+| `capabilities` | `readonly string[]` | `[]` | — | — | — | The methods it answers: store.get, store.set, store.list, leaderboard.submit, leaderboard.top, leaderboard.around, telemetry, point, ai.mark. |
+| `pending` | `number` | `0` | — | — | — | Calls not answered yet. |
+| `clock` | `string` | `""` | — | — | — | Whose clock og.platform.now and the answers' `time` read: `player` (the Player's answers carry its time), `browser` (the web host's own clock: the Player gives no time yet, docs/platform-asks.md), `system` (the native host's system clock), `fixed` (`og run --clock` and playtests: a clock that starts where it is told and moves with the ticks) or `none`. |
+
+```ogt
+struct PlatformInfo {
+  doc "What answers platform calls here."
+  field host String "`player` (a Player frames the game), `local` (the native host's JSON store or the browser's own storage) or `none`."
+  field capabilities List.String "The methods it answers: store.get, store.set, store.list, leaderboard.submit, leaderboard.top, leaderboard.around, telemetry, point, ai.mark."
+  field pending u32 "Calls not answered yet."
+  field clock String "Whose clock og.platform.now and the answers' `time` read: `player` (the Player's answers carry its time), `browser` (the web host's own clock: the Player gives no time yet, docs/platform-asks.md), `system` (the native host's system clock), `fixed` (`og run --clock` and playtests: a clock that starts where it is told and moves with the ticks) or `none`."
+}
+```
+
+<sub>`api.ogt` line 7596</sub>