@arcadible/sdk 1.3.0 → 1.4.0

package/README.md

@@ -7,11 +7,12 @@
 <h1 align="center">Arcadible SDK</h1>
 
 <p align="center">
-  Saves that carry over from one version of your game to the next.
+  Arcadible's loading screen for your game, and saves that carry over from one version to the next.
 </p>
 
 <p align="center">
   <a href="https://developer.arcadible.com/references/arcadible-sdk">Docs</a> ·
+  <a href="https://developer.arcadible.com/build/initialization">Initialization</a> ·
   <a href="https://developer.arcadible.com/build/saves">Saves</a> ·
   <a href="https://arcadible.com">Arcadible</a> ·
   <a href="https://studio.arcadible.com">Studio</a>
@@ -19,7 +20,7 @@
 
 <br>
 
-Each build of a game on [Arcadible](https://arcadible.com) has its own origin, so its browser storage starts empty with every update. Saves made through the Arcadible SDK are kept by the play page instead, on the player's device, so they carry over. The SDK is optional, and saves are all it does.
+The Arcadible SDK is optional: a game runs on [Arcadible](https://arcadible.com) without it. With it, a game gets two things from the play page around it: its [initialization](https://developer.arcadible.com/build/initialization), bracketed, so Arcadible's loading screen shows the game's splash and progress until its first frame is drawn, and [saves](https://developer.arcadible.com/build/saves), kept by the play page, so the player's progress carries over from one version to the next.
 
 ## Install
 
@@ -29,29 +30,39 @@ npm install @arcadible/sdk
 
 The package is for a game with a build step, such as a Vite project. A game without one uses the [hosted script](https://developer.arcadible.com/references/arcadible-sdk#install) instead.
 
-## Save and load
+## Initialization
 
 ```js
 import { arcadible } from "@arcadible/sdk";
 
-// at startup: once the saves have loaded, the player's progress, or a new game.
-await arcadible.ready;
+await arcadible.initStart(); // first thing in your game's code
+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.
+
+## Save and load
+
+```js
+// once the saves have loaded
 const saved = await arcadible.saves.read("progress");
 const progress = saved ? JSON.parse(saved) : { level: 1 };
 
-// at a checkpoint:
+// at a checkpoint
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-A save is a name holding one string. `arcadible.ready` settles once the game's saves have loaded, and never fails; calls made before it wait for it, and from then on `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.
+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.
 
-Off Arcadible, such as on your dev server, the package works on its own, with the same rules and limits: saves are kept on the page's own origin, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
+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`.
 
 ## Learn more
 
-- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): installing it, the hosted script, `ready` and `build`, and every code.
-- [`arcadible.saves`](https://developer.arcadible.com/references/arcadible-sdk/saves): every call, what it returns, and when it fails.
+- [Initialization](https://developer.arcadible.com/build/initialization): where each call goes, progress, and what comes after.
 - [Saves](https://developer.arcadible.com/build/saves): using saves well, across versions, channels, and tabs, and where they're kept.
+- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call, the saves' included, and every code.
 - [Limits](https://developer.arcadible.com/references/limits#saves): how many saves, and how large.
 
 ## License

package/dist/bus/protocol.js

@@ -1,6 +1,6 @@
 // The bus's rules, shared by both ends so they can't drift apart: the
 // handshake, the message shapes, the error codes, and the limits on what
-// crosses it (DESIGN.md, section 4). It knows nothing of any module.
+// crosses it. It knows nothing of any module.
 // [declare]
 // The bus's own version: the handshake and the message shapes. New modules,
 // names, and fields are additions within it.
@@ -15,9 +15,9 @@ export const REQUEST_TIMEOUT = 10_000;
 // included, whatever framed it. Who may frame a build is decided outside the
 // game, where it can change: on Arcadible by each build's `frame-ancestors`,
 // which the browser enforces before the game runs, and elsewhere by whoever
-// serves it. So the host is never trusted with anything of value (DESIGN.md,
-// section 4). Only `null` is refused: a `file://` page or a sandboxed frame,
-// which can't be told apart.
+// serves it. So the host is never trusted with anything of value. Only
+// `null` is refused: a `file://` page or a sandboxed frame, which can't be
+// told apart.
 export function isHostOrigin(origin, origins) {
     return origins
         ? origins.includes(origin)
@@ -29,7 +29,7 @@ export const MAX_IN_FLIGHT = 64;
 // The largest message either side sends: room for a whole 1 MB save, or
 // every save at once (a game's are 1 MB together), and the rest of the
 // message. The page refuses a larger request, and never sends a larger
-// answer or event (DESIGN.md, section 4).
+// answer or event.
 export const MAX_MESSAGE = 1024 * 1024 + 64 * 1024;
 // [declare]
 // Every code a call can fail with. Worth retrying: `busy`, `timeout`, and

package/dist/client.d.ts

@@ -24,22 +24,23 @@ export interface Arcadible {
     /** Saves that carry over between the game's versions. */
     readonly saves: Saves;
     /**
-     * Begins the game's initialization: call it first, before anything you
-     * await, and Arcadible shows the game's loading screen until `initEnd()`.
+     * Starts the game's initialization: call it first, before anything you
+     * await, and Arcadible shows the game's loading screen until
+     * `initComplete()`.
      * It resolves as `ready` does, once the SDK and the saves are ready.
      */
-    initBegin(): Promise<Ready>;
+    initStart(): Promise<Ready>;
     /**
      * How far along the initialization is, from 0 to 1, measured however the
      * game likes. Optional; a lower value than the last is ignored.
      */
     initProgress(fraction: number): void;
     /**
-     * Ends the initialization, once the game's first frame is drawn:
+     * Completes the initialization, once the game's first frame is drawn:
      * Arcadible takes its loading screen down, and this resolves once the
      * game is visible.
      */
-    initEnd(): Promise<void>;
+    initComplete(): Promise<void>;
 }
 export type ClientOptions = {
     window?: Window;

package/dist/client.js

@@ -47,15 +47,15 @@ export function createClient(options = {}) {
             return settled ? settled.build : undefined;
         },
         saves,
-        initBegin() {
-            lifecycle.begin();
+        initStart() {
+            lifecycle.start();
             return ready;
         },
         initProgress(fraction) {
             lifecycle.progress(fraction);
         },
-        initEnd() {
-            return lifecycle.end();
+        initComplete() {
+            return lifecycle.complete();
         },
     };
 }

package/dist/lifecycle/client.d.ts

@@ -1,7 +1,7 @@
 import type { Bus } from "../bus/client.js";
 export type Lifecycle = {
-    begin(): void;
+    start(): void;
     progress(fraction: unknown): void;
-    end(): Promise<void>;
+    complete(): Promise<void>;
 };
 export declare function createLifecycle(bus: Bus, win: Window | undefined): Lifecycle;

package/dist/lifecycle/client.js

@@ -1,18 +1,18 @@
-// The game's side of its initialization: `initBegin`, `initProgress`, and
-// `initEnd` on `arcadible` (DESIGN.md, section 7, Initialization). The page
-// keeps its loading screen only for a game that began before its own `load`,
-// which this side reports, once, as it happens, so the page decides without
-// a timer. Calls after that do nothing, and the console says why once.
+// The game's side of its initialization: `initStart`, `initProgress`, and
+// `initComplete` on `arcadible`. The page keeps its loading screen only for
+// a game that started before its own `load`, which this side reports, once,
+// as it happens, so the page decides without a timer. Calls after that do
+// nothing, and the console says why once.
 import { isObject, log } from "../bus/protocol.js";
-import { END_TIMEOUT, fractionOf, Names } from "./rules.js";
+import { COMPLETE_TIMEOUT, fractionOf, Names } from "./rules.js";
 // [function]
 export function createLifecycle(bus, win) {
-    // began before the game's `load`: the loading screen is the page's to
-    // keep. `false` once `load` passed without a begin.
-    let begun = null;
+    // started before the game's `load`: the loading screen is the page's to
+    // keep. `false` once `load` passed without a start.
+    let started = null;
     let loaded = false;
     let last = -1;
-    let ended = null;
+    let completed = null;
     let warnedLate = false;
     let warnedValue = false;
     const framed = Boolean(win && win.parent !== win);
@@ -20,33 +20,33 @@ export function createLifecycle(bus, win) {
         if (warnedLate || !framed)
             return;
         warnedLate = true;
-        log("warn", `${call} came after the page loaded, so Arcadible's loading screen was already down. Call initBegin() first, before anything you await.`);
+        log("warn", `${call} came after the page loaded, so Arcadible's loading screen was already down. Call initStart() as your code starts, before anything you await or schedule for later.`);
     };
     const onLoad = function () {
         if (loaded)
             return;
         loaded = true;
-        if (begun === null)
-            begun = false;
-        bus.emit(Names.Loaded, { begun });
+        if (started === null)
+            started = false;
+        bus.emit(Names.Loaded, { started });
     };
-    const begin = function (call) {
-        if (begun !== null) {
-            if (!begun)
+    const start = function (call) {
+        if (started !== null) {
+            if (!started)
                 late(call);
             return;
         }
         if (loaded) {
-            begun = false;
+            started = false;
             late(call);
             return;
         }
-        begun = true;
-        bus.emit(Names.Begin);
+        started = true;
+        bus.emit(Names.Start);
     };
     // [start]
-    // the game's own `load` is the frame's on the page: a game that began by
-    // then keeps the loading screen. A script that runs after it (added by
+    // the game's own `load` is the frame's on the page: a game that started
+    // by then keeps the loading screen. A script that runs after it (added by
     // code, late) reports at once.
     if (win && typeof win.addEventListener === "function") {
         if (win.document?.readyState === "complete")
@@ -55,8 +55,8 @@ export function createLifecycle(bus, win) {
             win.addEventListener("load", onLoad, { once: true });
     }
     return {
-        begin() {
-            begin("initBegin");
+        start() {
+            start("initStart");
         },
         progress(fraction) {
             const value = fractionOf(fraction);
@@ -67,22 +67,26 @@ export function createLifecycle(bus, win) {
                 }
                 return;
             }
-            begin("initProgress");
-            if (!begun || ended || value <= last)
+            start("initProgress");
+            if (!started || completed || value <= last)
                 return;
             last = value;
             bus.emit(Names.Progress, { fraction: value });
         },
-        end() {
-            if (ended)
-                return ended;
-            begin("initEnd");
+        complete() {
+            if (completed)
+                return completed;
+            start("initComplete");
             // a page without a loading screen, an older one, or none standing
             // alone, answers `unsupported`: the game is visible already.
-            ended = begun
-                ? bus.request(Names.End, {}, isObject, { timeout: END_TIMEOUT }).then(() => undefined, () => undefined)
+            completed = started
+                ? bus
+                    .request(Names.Complete, {}, isObject, {
+                    timeout: COMPLETE_TIMEOUT,
+                })
+                    .then(() => undefined, () => undefined)
                 : Promise.resolve();
-            return ended;
+            return completed;
         },
     };
 }

package/dist/lifecycle/rules.d.ts

@@ -1,10 +1,10 @@
 export declare const Names: {
-    readonly Begin: "lifecycle.initBegin";
+    readonly Start: "lifecycle.initStart";
     readonly Progress: "lifecycle.initProgress";
     readonly Loaded: "lifecycle.loaded";
-    readonly End: "lifecycle.initEnd";
+    readonly Complete: "lifecycle.initComplete";
 };
-export declare const INIT_SINCE = "1.3.0";
-export declare const END_TIMEOUT = 60000;
+export declare const INIT_SINCE = "1.4.0";
+export declare const COMPLETE_TIMEOUT = 60000;
 export declare function reportsInit(client: unknown): boolean;
 export declare function fractionOf(value: unknown): number | null;

package/dist/lifecycle/rules.js

@@ -1,28 +1,28 @@
 // The game's initialization on the bus, shared by both ends: the messages'
-// names, and the first SDK that sends them (DESIGN.md, section 7,
-// Initialization). On the bus they're `lifecycle`'s; games call them on
-// `arcadible` itself.
+// names, and the first SDK that sends them. On the bus they're
+// `lifecycle`'s; games call them on `arcadible` itself.
 // [declare]
 export const Names = {
-    // the game began its initialization: an event.
-    Begin: "lifecycle.initBegin",
+    // the game started its initialization: an event.
+    Start: "lifecycle.initStart",
     // how far along it is, `{ fraction }`, from 0 to 1: an event.
     Progress: "lifecycle.initProgress",
-    // the game's own `load`, `{ begun }`: whether it began before it. An
+    // the game's own `load`, `{ started }`: whether it started before it. An
     // event, sent once, so the page decides without a timer.
     Loaded: "lifecycle.loaded",
     // its first frame is drawn: a request, answered once the game is visible.
-    End: "lifecycle.initEnd",
+    Complete: "lifecycle.initComplete",
 };
-// The first SDK that sends them. An older one can't, so the page takes its
-// loading screen down at `load`, without waiting to hear.
-export const INIT_SINCE = "1.3.0";
-// How long `initEnd()` waits for the page to say the game is visible: past
-// the loading screen's minimum and fade, and a device held the wrong way
-// for a while. Past it, the game goes on as if visible.
-export const END_TIMEOUT = 60_000;
+// 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.
+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
+// way for a while. Past it, the game goes on as if visible.
+export const COMPLETE_TIMEOUT = 60_000;
 // [function]
-// a version's numbers, `1.3.0-beta.1` as [1, 3, 0], or null.
+// a version's numbers, `1.4.0-beta.1` as [1, 4, 0], or null.
 function numbers(version) {
     const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(version);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;

package/dist/lifecycle/server.d.ts

@@ -1,8 +1,8 @@
 import type { Module } from "../bus/server.js";
 export type LifecycleHost = {
-    begin(): void;
+    start(): void;
     progress(fraction: number): void;
-    loaded(begun: boolean): void;
-    end(): Promise<void>;
+    loaded(started: boolean): void;
+    complete(): Promise<void>;
 };
 export declare function lifecycleServer(host: LifecycleHost): () => Module;

package/dist/lifecycle/server.js

@@ -1,7 +1,8 @@
 // The page's side of the game's initialization: it passes what the game
-// reports to the page's loading screen, and answers `initEnd` once the page
-// says the game is visible. A page without a loading screen leaves it out,
-// so `initEnd` gets `unsupported`, which a game takes as visible at once.
+// reports to the page's loading screen, and answers `initComplete` once the
+// page says the game is visible. A page without a loading screen leaves it
+// out, so `initComplete` gets `unsupported`, which a game takes as visible
+// at once.
 // [import]
 import { isObject } from "../bus/protocol.js";
 import { fractionOf, Names } from "./rules.js";
@@ -9,23 +10,23 @@ import { fractionOf, Names } from "./rules.js";
 export function lifecycleServer(host) {
     return () => ({
         handlers: {
-            [Names.End]: {
+            [Names.Complete]: {
                 parallel: true,
                 run: async () => {
-                    await host.end();
+                    await host.complete();
                     return {};
                 },
             },
         },
         events: {
-            [Names.Begin]: () => host.begin(),
+            [Names.Start]: () => host.start(),
             [Names.Progress]: (data) => {
                 const fraction = isObject(data) ? fractionOf(data["fraction"]) : null;
                 if (fraction !== null)
                     host.progress(fraction);
             },
             [Names.Loaded]: (data) => {
-                host.loaded(isObject(data) && data["begun"] === true);
+                host.loaded(isObject(data) && data["started"] === true);
             },
         },
     });

package/dist/saves/rules.js

@@ -1,9 +1,9 @@
 // Saves' rules, shared by the game's side and the page's so they can't drift
-// apart: the shapes, the limits, and their checks (DESIGN.md, section 6).
+// apart: the shapes, the limits, and their checks.
 // [import]
 import { ArcadibleError, Codes, isNumber, isObject, isStringOrNull, utf8Size, } from "../bus/protocol.js";
 // [declare]
-// Saves' limits, the same everywhere (DESIGN.md, section 6, Limits).
+// Saves' limits, the same everywhere.
 export const MAX_SAVES = 32;
 // Every save's document together, in UTF-8 bytes.
 export const MAX_TOTAL = 1024 * 1024;
@@ -48,8 +48,8 @@ export function checkWrite(saves, name, data) {
     return null;
 }
 // [function]
-// What the page sends of a save, checked for only what a game relies on
-// (DESIGN.md, The host is never trusted): extra fields pass.
+// What the page sends of a save, checked for only what a game relies on,
+// since the host is never trusted: extra fields pass.
 export function isSaveMeta(value) {
     return (isObject(value) &&
         isStringOrNull(value["version"]) &&

package/dist/version.d.ts

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

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.3.0";
+export const VERSION = "1.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": "Offst, Inc.",
-  "description": "The Arcadible SDK: saves that carry over between a game's versions on Arcadible.",
+  "description": "The Arcadible SDK: Arcadible's loading screen for a game's initialization, and saves that carry over between its versions.",
   "devDependencies": {
     "@playwright/test": "1.63.0",
     "@types/node": "^25.0.3",
@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.3.0"
+  "version": "1.4.0"
 }