@unboxy/phaser-sdk 0.2.7 → 0.2.9

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,7 @@ 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.

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.7';
+const SDK_VERSION = '0.2.8';
 /**
  * Unboxy platform services bound to the current (game, user).
  *

package/dist/core/UnboxyGame.d.ts

@@ -12,6 +12,8 @@ export interface UnboxyGameOptions {
     pixelArt?: boolean;
     /** Custom physics config (default: arcade with no gravity) */
     physics?: Phaser.Types.Core.PhysicsConfig;
+    /** Phaser plugin registrations (e.g. `phaser3-rex-plugins` virtual joystick) */
+    plugins?: Phaser.Types.Core.PluginObject;
 }
 /**
  * Create an Unboxy-enhanced Phaser game instance.

package/dist/core/UnboxyGame.js

@@ -23,6 +23,7 @@ export function createUnboxyGame(options) {
             default: 'arcade',
             arcade: { gravity: { x: 0, y: 0 }, debug: false },
         },
+        ...(options.plugins ? { plugins: options.plugins } : {}),
         scene: options.scenes,
     };
     const game = new Phaser.Game(config);

package/package.json

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