@arcadible/sdk 1.3.0 → 1.3.1

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.initBegin(); // first thing in your game's code
+arcadible.initProgress(0.5);
+// … load, build the scene, and draw the first frame …
+await arcadible.initEnd();
+```
+
+Call `initBegin()` 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 `initEnd()` once your first frame is drawn. Arcadible shows your splash and the progress until then, and `initEnd()` 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 `initBegin()` 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 `initEnd()` 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/lifecycle/client.js

@@ -20,7 +20,7 @@ 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 initBegin() as your code starts, before anything you await or schedule for later.`);
     };
     const onLoad = function () {
         if (loaded)

package/dist/version.d.ts

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

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.3.1";

package/package.json

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