@unboxy/phaser-sdk 0.2.8 → 0.2.10

package/SDK-GUIDE.md

@@ -11,6 +11,39 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 - `unboxy.gameData` — **per-game** key-value store (read by anyone; write requires auth)
 - `unboxy.rooms` — **multiplayer rooms** (server-authoritative state sync, requires sign-in and host support)
 
+## `createUnboxyGame` options
+
+| field | type | note |
+|-------|------|------|
+| `width` | `number` | required |
+| `height` | `number` | required |
+| `scenes` | `Phaser.Scene class[]` | required |
+| `backgroundColor` | `string` | defaults to `'#1a1a2e'` |
+| `pixelArt` | `boolean` | defaults to `false` |
+| `physics` | `Phaser.Types.Core.PhysicsConfig` | defaults to arcade physics, no gravity |
+| `plugins` | `Phaser.Types.Core.PluginObject` | forwarded as-is into the Phaser `GameConfig`. **Since 0.2.9.** Earlier versions silently dropped this field. |
+
+Any field not listed is ignored. If you need something else (e.g. `callbacks`, custom `render` options), use plain `new Phaser.Game(config)` instead of `createUnboxyGame`.
+
+### Registering third-party Phaser plugins (e.g. rexUI)
+
+Pass them via the `plugins` option — do NOT try to register them inside a scene's `preload`:
+
+```ts
+import VirtualJoystickPlugin from 'phaser3-rex-plugins/plugins/virtualjoystick-plugin.js';
+
+createUnboxyGame({
+  // ...
+  plugins: {
+    global: [
+      { key: 'rexVirtualJoystick', plugin: VirtualJoystickPlugin, start: true },
+    ],
+  },
+});
+```
+
+Then in a scene: `this.plugins.get('rexVirtualJoystick').add(this, { ... })`.
+
 ## Platform services
 
 Initialize once at module load — resolves the host (home-ui, standalone, etc.) and returns a bound instance. Scenes read from the resulting promise.
@@ -348,6 +381,8 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.10** — docs: added a `createUnboxyGame` options table (including the new `plugins` field) and a third-party Phaser plugin registration example. No code changes; version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.
+- **0.2.9** — `createUnboxyGame` now forwards the optional `plugins` field to Phaser's `GameConfig`. Previously the option was accepted at the call site but silently dropped — any `phaser3-rex-plugins` (or similar) registration never took effect, and `this.plugins.get(key)` returned undefined at runtime. Purely additive; no effect on games that don't pass `plugins`. Lets the `phaser-rex-touch` agent skill work end-to-end.
 - **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`.

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.8",
+  "version": "0.2.10",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",