@arcadible/sdk 1.4.0 → 1.4.2

package/README.md

@@ -35,18 +35,18 @@ The package is for a game with a build step, such as a Vite project. A game with
 ```js
 import { arcadible } from "@arcadible/sdk";
 
-await arcadible.initStart(); // first thing in your game's code
+await arcadible.initStart(); // as your code starts, before anything it awaits
 arcadible.initProgress(0.5);
 // … load, build the scene, and draw the first frame …
 await arcadible.initComplete();
 ```
 
-Call `initStart()` first thing in your game's code, report how far along you are with `initProgress()`, from 0 to 1, if you can measure it, and call `initComplete()` once your first frame is drawn. Arcadible shows your splash and the progress until then, and `initComplete()` resolves once the loading screen has faded into your game.
+Call `initStart()` as your code starts, before anything it awaits, report how far along you are with `initProgress()`, from 0 to 1, if you can measure it, and call `initComplete()` once your first frame is drawn. Arcadible shows your splash and the progress until then, and `initComplete()` resolves once the loading screen has faded into your game.
 
 ## Save and load
 
 ```js
-// once the saves have loaded
+// as your game starts, after initStart()
 const saved = await arcadible.saves.read("progress");
 const progress = saved ? JSON.parse(saved) : { level: 1 };
 
@@ -54,7 +54,7 @@ const progress = saved ? JSON.parse(saved) : { level: 1 };
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-A save is a name holding one string. Once `initStart()` has resolved, `readSync`, `listSync`, and `infoSync` answer at once from memory, for reads during play. Every call that fails rejects (or, for the sync calls, throws) with an `ArcadibleError`, whose `code` says what to do. `arcadible.saves.where` says who can read the saves back: every version of the game, only this build, or only until the page closes.
+Saves are for what your game remembers between sessions, such as progress, settings, and preferences, not a general key/value store: up to 32 saves, 1 MB together, each named as you choose. A save is a name holding one string. Read your saves once as your game starts, keep the state in your game, and write at checkpoints. Every call returns a promise, and one that fails rejects with an `ArcadibleError`, whose `code` says what to do. `arcadible.saves.where` says who can read the saves back: every version of the game, only this build, or only until the page closes.
 
 Off Arcadible, such as on your dev server, the package still works, with the same rules and limits: there's no loading screen, so `initComplete()` resolves at once, saves are kept in the game's own browser storage, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 

package/dist/bus/protocol.js

@@ -40,6 +40,7 @@ export const Codes = {
     Busy: "busy",
     Full: "full",
     Invalid: "invalid",
+    // only `readSync`, `listSync`, and `infoSync` throw it, before `ready`.
     NotReady: "not_ready",
     Timeout: "timeout",
     TooLarge: "too_large",

package/dist/client.d.ts

@@ -24,8 +24,8 @@ export interface Arcadible {
     /** Saves that carry over between the game's versions. */
     readonly saves: Saves;
     /**
-     * Starts the game's initialization: call it first, before anything you
-     * await, and Arcadible shows the game's loading screen until
+     * Starts the game's initialization: call it as your code starts, before
+     * anything it awaits, and Arcadible shows the game's loading screen until
      * `initComplete()`.
      * It resolves as `ready` does, once the SDK and the saves are ready.
      */

package/dist/lifecycle/rules.js

@@ -14,8 +14,7 @@ export const Names = {
     Complete: "lifecycle.initComplete",
 };
 // The first SDK that sends them. An older one doesn't, so the page takes its
-// loading screen down at `load`, without waiting to hear. 1.3's SDKs sent
-// these under other names, so the page treats them as older too.
+// loading screen down at `load`, without waiting to hear.
 export const INIT_SINCE = "1.4.0";
 // How long `initComplete()` waits for the page to say the game is visible:
 // past the loading screen's minimum and fade, and a device held the wrong

package/dist/saves/client.d.ts

@@ -12,17 +12,28 @@ export interface Saves {
     info(name: string): Promise<SaveInfo | null>;
     /** Removes the save, if there is one. */
     remove(name: string): Promise<void>;
-    /** After `ready`, the save's string from memory; before it, throws `not_ready`. */
+    /**
+     * The save's string from memory, once `ready` has settled; before it,
+     * throws `not_ready`. Prefer `await read(name)`: read once as the game
+     * starts, and keep the state in the game.
+     */
     readSync(name: string): string | null;
-    /** After `ready`, the names of the game's saves from memory, sorted. */
+    /**
+     * The names of the game's saves from memory, sorted, once `ready` has
+     * settled. Prefer `await list()`.
+     */
     listSync(): string[];
-    /** After `ready`, the save's version and time from memory, or `null`. */
+    /**
+     * Which version wrote the save, and when, from memory, once `ready` has
+     * settled. Prefer `await info(name)`.
+     */
     infoSync(name: string): SaveInfo | null;
     /**
-     * Who can read the saves back, once `ready` has settled: `"game"` (every
-     * version of the game), `"build"` (only this build), or `"memory"` (only
-     * until the page closes). `undefined` until it's known. Other values may
-     * be added: treat one you don't know as `"game"`.
+     * Who can read the saves back, once `initStart()` or `ready` has
+     * settled: `"game"` (every version of the game), `"build"` (only this
+     * build), or `"memory"` (only until the page closes). `undefined` until
+     * it's known. Other values may be added: treat one you don't know as
+     * `"game"`.
      */
     readonly where: Where | undefined;
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.4.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 // The client's version, sent in its hello and shown as `arcadible.version`,
 // for bug reports. It matches package.json (test/unit/protocol.test.ts).
-export const VERSION = "1.4.0";
+export const VERSION = "1.4.2";

package/package.json

@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.4.0"
+  "version": "1.4.2"
 }