@unboxy/phaser-sdk 0.2.15 → 0.2.16

package/SDK-GUIDE.md

@@ -15,16 +15,28 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 
 | field | type | note |
 |-------|------|------|
-| `width` | `number` | required |
-| `height` | `number` | required |
+| `orientation` | `'portrait' \| 'landscape'` | mutually exclusive with `width`/`height`. Resolves to preset dims from `ORIENTATION_DIMENSIONS`. **Since 0.2.16.** |
+| `width` | `number` | required if `orientation` is omitted |
+| `height` | `number` | required if `orientation` is omitted |
 | `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. |
 
+`orientation` and explicit `width`/`height` are a TypeScript union — pass one or the other, not both. The compiler rejects mixed usage.
+
 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`.
 
+### Orientation presets
+
+```ts
+import { ORIENTATION_DIMENSIONS } from '@unboxy/phaser-sdk';
+// { landscape: { width: 1280, height: 720 }, portrait: { width: 720, height: 1280 } }
+```
+
+The orientation a game uses is decided **once at game creation** and baked into the template's `src/config.ts`. There is no runtime API to flip orientation — switching mid-development would invalidate every screen layout.
+
 ### 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`:
@@ -544,6 +556,7 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.16** — added orientation presets. `createUnboxyGame` now accepts an `orientation: 'portrait' | 'landscape'` option as an alternative to explicit `width`/`height` (TS union — pass one or the other). New exports: `Orientation` type and `ORIENTATION_DIMENSIONS` map (`landscape: 1280×720`, `portrait: 720×1280`). Lets games declare orientation once and have a single source of truth for canvas dimensions.
 - **0.2.15** — fix: `ChatFacade.subscribeToPlayers` early-returned when `state.players` was `undefined` at construction time, which it always is on a fresh `joinOrCreate` (Colyseus delivers initial state as a separate message a few ms later). The early return meant `onStateChange` never subscribed and `system.joined` / `system.left` stayed silent in production despite the 0.2.14 callback-API fix. Now: always subscribe; treat the first state change as initial hydration (silent), subsequent changes do real diff. Three regression tests cover the deferred-hydration flow.
 - **0.2.14** — fix: `ChatFacade` `system.joined` / `system.left` events were silently no-op'ing in production. The lifecycle subscription used `state.players.onAdd` / `.onRemove` instance methods that Colyseus 0.16 removed in favour of `getStateCallbacks(room)`; the runtime check `typeof players.onAdd === 'function'` evaluated false, so neither system message fired. Now uses `room.onStateChange` + a known-names diff — robust to future Colyseus API changes. Tests updated to match. Patch-only; no API change for game code.
 - **0.2.13** — added `room.chat` helper for in-game chat. New API: `room.chat.send(text)` (returns `Promise<void>`) + `room.chat.onMessage(handler)`, plus exports `ChatMessage`, `ChatMessageKind`, and `MAX_CHAT_TEXT_LEN`. Wraps the existing `'chat'` wildcard relay with local echo (sender sees own message synchronously), stamped `displayName` on every payload, trim + 500-char silent truncate, and auto-emitted `kind: 'system.joined'` / `'system.left'` messages computed locally from `room.state.players` add/remove events (no wire traffic). Replaces the raw `room.send('chat', text)` pattern in the Multiplayer chapter — raw still works but loses local echo, length cap, and join/leave events.

package/dist/core/UnboxyGame.d.ts

@@ -1,9 +1,6 @@
 import Phaser from 'phaser';
-export interface UnboxyGameOptions {
-    /** Game width in pixels */
-    width: number;
-    /** Game height in pixels */
-    height: number;
+import { type Orientation } from '../orientation.js';
+interface UnboxyGameBaseOptions {
     /** Phaser scene classes to register */
     scenes: (new (...args: any[]) => Phaser.Scene)[];
     /** Background color (default: '#1a1a2e') */
@@ -15,8 +12,24 @@ export interface UnboxyGameOptions {
     /** Phaser plugin registrations (e.g. `phaser3-rex-plugins` virtual joystick) */
     plugins?: Phaser.Types.Core.PluginObject;
 }
+/**
+ * Either pass `orientation` (preset dims from ORIENTATION_DIMENSIONS) OR
+ * explicit `width`/`height` — not both. The TS union enforces this at
+ * compile time so games can't drift out of the orientation presets by
+ * accident.
+ */
+export type UnboxyGameOptions = (UnboxyGameBaseOptions & {
+    orientation: Orientation;
+    width?: never;
+    height?: never;
+}) | (UnboxyGameBaseOptions & {
+    width: number;
+    height: number;
+    orientation?: never;
+});
 /**
  * Create an Unboxy-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
  */
 export declare function createUnboxyGame(options: UnboxyGameOptions): Phaser.Game;
+export {};

package/dist/core/UnboxyGame.js

@@ -1,19 +1,23 @@
 import Phaser from 'phaser';
 import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
 import { setupRecordingListener } from '../recording/RecordingManager.js';
+import { ORIENTATION_DIMENSIONS } from '../orientation.js';
 /**
  * Create an Unboxy-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
  */
 export function createUnboxyGame(options) {
+    const { width, height } = 'orientation' in options && options.orientation
+        ? ORIENTATION_DIMENSIONS[options.orientation]
+        : { width: options.width, height: options.height };
     const config = {
         type: Phaser.AUTO,
         backgroundColor: options.backgroundColor ?? '#1a1a2e',
         scale: {
             mode: Phaser.Scale.FIT,
             autoCenter: Phaser.Scale.CENTER_BOTH,
-            width: options.width,
-            height: options.height,
+            width,
+            height,
         },
         render: {
             preserveDrawingBuffer: true,

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { createUnboxyGame } from './core/UnboxyGame.js';
 export type { UnboxyGameOptions } from './core/UnboxyGame.js';
 export { UnboxyScene } from './core/UnboxyScene.js';
+export { ORIENTATION_DIMENSIONS } from './orientation.js';
+export type { Orientation } from './orientation.js';
 export { setupScreenshotListener, takeScreenshot } from './screenshot/ScreenshotManager.js';
 export { setupRecordingListener } from './recording/RecordingManager.js';
 export { Unboxy } from './core/Unboxy.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // Core
 export { createUnboxyGame } from './core/UnboxyGame.js';
 export { UnboxyScene } from './core/UnboxyScene.js';
+export { ORIENTATION_DIMENSIONS } from './orientation.js';
 // Screenshot
 export { setupScreenshotListener, takeScreenshot } from './screenshot/ScreenshotManager.js';
 // Recording

package/dist/orientation.d.ts

@@ -0,0 +1,5 @@
+export type Orientation = 'portrait' | 'landscape';
+export declare const ORIENTATION_DIMENSIONS: Record<Orientation, {
+    width: number;
+    height: number;
+}>;

package/dist/orientation.js

@@ -0,0 +1,4 @@
+export const ORIENTATION_DIMENSIONS = {
+    landscape: { width: 1280, height: 720 },
+    portrait: { width: 720, height: 1280 },
+};

package/package.json

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