@unboxy/phaser-sdk 0.2.6 → 0.2.8

package/SDK-GUIDE.md

@@ -286,6 +286,40 @@ Rules of thumb:
 - **Do not implement position sync via messages.** You will reinvent delta compression badly and spend more bandwidth. Use `room.player.set('pos', {x,y})`.
 - **Server is authoritative but permissive** — it doesn't validate what you put in `data`. Treat inbound values from other players as untrusted (don't eval, validate shape before reading).
 
+#### Making remote motion feel smooth
+
+State updates arrive at roughly 20 Hz (every ~50 ms). If you re-render remote entities by snapping directly to `room.player.get(sid, 'pos')` each frame, their movement will visibly step. Pick a smoothing technique that fits the game:
+
+**Interpolation** — good for continuous motion (platformer, shooter, racer). Keep a `target` on each remote sprite, update it from state, lerp toward it each frame.
+
+```ts
+// On state change, just update the target
+room.onStateChange(() => {
+  room.state.players.forEach((_p, sid) => {
+    if (sid === room.sessionId) return;
+    const pos = room.player.get<{x:number;y:number}>(sid, 'pos');
+    if (pos) remoteSprites.get(sid)!.target = pos;
+  });
+});
+
+// In your scene's update() loop
+remoteSprites.forEach((s) => {
+  s.sprite.x = Phaser.Math.Linear(s.sprite.x, s.target.x, 0.2);
+  s.sprite.y = Phaser.Math.Linear(s.sprite.y, s.target.y, 0.2);
+});
+```
+
+Pair this with **client-side prediction for the LOCAL player**: render your own sprite from a locally-predicted position (updated by input every frame) so input feels instant, not gated on the round trip. Publish the predicted position to state at ~10–20 Hz with `room.player.set('pos', predicted)`. You rarely need to reconcile in casual games; trust the local prediction.
+
+**Extrapolation** — good for projectiles and other predictable trajectories. Send `{ x, y, vx, vy, t }` once on spawn, let each client simulate locally with `x += vx * dt`. Only re-sync on events that change the trajectory (hit, bounce, destroy). Uses far less bandwidth than per-frame position sync.
+
+**Snap** — the right choice for:
+- Infrequent updates: score, hp, current turn, chat messages, lobby ready flags.
+- Turn-based games: pieces jumping to their next square shouldn't glide.
+- Discrete grids: same reason.
+
+Don't blindly apply interpolation to everything. It's wrong for a chess piece and wasteful on a hp bar.
+
 #### Availability
 
 - Requires sign-in. Anonymous players get `RpcError('UNAUTHENTICATED')`.
@@ -314,6 +348,8 @@ Rules of thumb:
 
 ## Changelog
 
+- **0.2.8** — docs: added "Making remote motion feel smooth" section to the multiplayer chapter with concrete examples for interpolation (continuous motion), extrapolation (projectiles), and snap (discrete/turn-based/infrequent). No code changes — version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.
+- **0.2.7** — fixed handshake race on slow-mounting hosts. `PostMessageTransport.connect` now retries `unboxy:hello` every 200 ms until `unboxy:init` arrives (previously one-shot → lost on Android/mobile where React mounted after the iframe first fired hello). Default handshake timeout bumped from 2 s → 5 s.
 - **0.2.6** — redesigned `unboxy.rooms` around two generic primitives: delta-synced KV state (`room.player.set/get/delete`, `room.data.set/get/delete`) + transient relay (`room.send` / `room.on`). Server no longer bakes in game-specific fields like x/y/color/ready or a `move` handler — games define their own shapes via opaque JSON values, same contract as `gameData` / `saves`.
 - **0.2.5** — added `unboxy.rooms` module (server-authoritative multiplayer rooms backed by Colyseus on unboxy-realtime-service). Requires sign-in. Host must advertise `realtime` capability. Colyseus client loaded lazily — single-player games do not pay for the dependency.
 - **0.2.4** — added `unboxy.gameData` module (game-scope key-value store for scoreboards, shared state)

package/dist/core/Unboxy.d.ts

@@ -4,7 +4,7 @@ import { GameDataModule } from '../gamedata/GameDataModule.js';
 import { RealtimeModule } from '../realtime/RealtimeModule.js';
 import type { UnboxyUser } from '../protocol.js';
 export interface UnboxyInitOptions {
-    /** Handshake timeout in ms when running inside a host. Default 2000. */
+    /** Handshake timeout in ms when running inside a host. Default 5000. */
     handshakeTimeoutMs?: number;
     /**
      * Game ID used for the localStorage fallback. Ignored when connected to a

package/dist/core/Unboxy.js

@@ -4,7 +4,7 @@ import { SavesModule } from '../saves/SavesModule.js';
 import { GameDataModule } from '../gamedata/GameDataModule.js';
 import { RealtimeModule } from '../realtime/RealtimeModule.js';
 // Kept in sync with package.json on each publish.
-const SDK_VERSION = '0.2.6';
+const SDK_VERSION = '0.2.8';
 /**
  * Unboxy platform services bound to the current (game, user).
  *
@@ -50,7 +50,7 @@ export class Unboxy {
      * Discord Activity support is designed for but not shipped in this version.
      */
     static async init(options = {}) {
-        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 2000;
+        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
         const standaloneGameId = options.standaloneGameId ?? 'standalone';
         const pm = await PostMessageTransport.connect(handshakeTimeoutMs, SDK_VERSION);
         if (pm)

package/dist/core/transports/PostMessageTransport.d.ts

@@ -15,9 +15,14 @@ export declare class PostMessageTransport implements Transport {
     private constructor();
     /**
      * Perform the handshake. Resolves once parent has replied with `unboxy:init`.
-     * Rejects if no response within `timeoutMs`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
      */
-    static connect(timeoutMs?: number, sdkVersion?: string): Promise<PostMessageTransport | null>;
+    static connect(timeoutMs?: number, sdkVersion?: string, helloRetryMs?: number): Promise<PostMessageTransport | null>;
     private installResultListener;
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
 }

package/dist/core/transports/PostMessageTransport.js

@@ -15,35 +15,51 @@ export class PostMessageTransport {
     }
     /**
      * Perform the handshake. Resolves once parent has replied with `unboxy:init`.
-     * Rejects if no response within `timeoutMs`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
      */
-    static async connect(timeoutMs = 2000, sdkVersion = '0.0.0') {
+    static async connect(timeoutMs = 5000, sdkVersion = '0.0.0', helloRetryMs = 200) {
         if (typeof window === 'undefined' || window.parent === window)
             return null;
         const transport = new PostMessageTransport(window.parent);
-        const initPromise = new Promise((resolve) => {
+        const hello = {
+            type: 'unboxy:hello',
+            protocolVersion: PROTOCOL_VERSION,
+            sdkVersion,
+        };
+        const init = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                window.removeEventListener('message', onMessage);
+                clearInterval(helloInterval);
+                clearTimeout(timeoutHandle);
+                resolve(value);
+            };
             const onMessage = (event) => {
                 if (event.source !== window.parent)
                     return;
                 const data = event.data;
                 if (!data || data.type !== 'unboxy:init')
                     return;
-                window.removeEventListener('message', onMessage);
-                resolve(data);
+                finish(data);
             };
             window.addEventListener('message', onMessage);
-            setTimeout(() => {
-                window.removeEventListener('message', onMessage);
-                resolve(null);
-            }, timeoutMs);
+            // Fire the first hello immediately, then keep retrying until init
+            // arrives or timeout fires. Retries are cheap (a postMessage with a
+            // small payload); the parent's RPC host replies on first valid hello.
+            transport.parent.postMessage(hello, '*');
+            const helloInterval = setInterval(() => {
+                transport.parent.postMessage(hello, '*');
+            }, helloRetryMs);
+            const timeoutHandle = setTimeout(() => finish(null), timeoutMs);
         });
-        const hello = {
-            type: 'unboxy:hello',
-            protocolVersion: PROTOCOL_VERSION,
-            sdkVersion,
-        };
-        transport.parent.postMessage(hello, '*');
-        const init = await initPromise;
         if (!init)
             return null;
         if (init.protocolVersion !== PROTOCOL_VERSION) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",