@umicat/phaser-sdk 1.0.16 → 1.0.17

package/SDK-GUIDE.md

@@ -79,9 +79,14 @@ if (umicat) {
   umicat.isAuthenticated; // boolean
   umicat.gameId;          // stable platform-issued game id
   umicat.host;            // 'umicat-home-ui' | 'standalone' | 'discord' (future)
+  umicat.locale;          // player's UI language, e.g. 'en' | 'zh-CN' (string)
 }
 ```
 
+`umicat.locale` (since 1.0.17) is the player's preferred language from the host —
+default your game's UI + AI-NPC language to it instead of asking. For multi-language
+games + the **CJK font handling** that avoids tofu boxes, see the `game-i18n` skill.
+
 ### Save data — `umicat.saves`
 
 Per-user key-value store scoped to `(gameId, userId)`. Backed by the Umicat backend when authenticated, by localStorage when standalone/anonymous — **the API is identical either way**. Games should never branch on auth state for save logic.

package/dist/core/Transport.d.ts

@@ -19,6 +19,9 @@ export interface Transport {
      * `umicat.rooms.*` is unavailable in that case.
      */
     readonly realtimeUrl?: string;
+    /** The player's preferred language (BCP-47-ish, e.g. 'en', 'zh-CN'). The host
+     *  provides it at handshake; standalone falls back to the browser locale. */
+    readonly locale?: string;
     /** `timeoutMs` overrides the default RPC timeout — runtime-AI calls need
      *  longer than the 10s default for LLM latency. */
     call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;

package/dist/core/Umicat.d.ts

@@ -33,6 +33,9 @@ export declare class Umicat {
     get isAuthenticated(): boolean;
     /** Stable game identifier issued by the host. May be a placeholder when standalone. */
     get gameId(): string;
+    /** The player's preferred language (e.g. 'en', 'zh-CN'). Use it to default the
+     *  game's UI + AI NPC language. See the game-i18n skill. */
+    get locale(): string;
     /** Which transport Umicat.init() selected. Useful for debugging. */
     get host(): TransportKind;
     /**

package/dist/core/Umicat.js

@@ -40,6 +40,9 @@ export class Umicat {
     get isAuthenticated() { return this.transport.user !== null; }
     /** Stable game identifier issued by the host. May be a placeholder when standalone. */
     get gameId() { return this.transport.gameId; }
+    /** The player's preferred language (e.g. 'en', 'zh-CN'). Use it to default the
+     *  game's UI + AI NPC language. See the game-i18n skill. */
+    get locale() { return this.transport.locale ?? 'en'; }
     /** Which transport Umicat.init() selected. Useful for debugging. */
     get host() { return this.transport.kind; }
     /**

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

@@ -9,6 +9,7 @@ export declare class LocalStorageTransport implements Transport {
     readonly gameId: string;
     readonly kind: "standalone";
     readonly user: UmicatUser | null;
+    readonly locale: string;
     constructor(gameId: string);
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
     private savesPrefix;

package/dist/core/transports/LocalStorageTransport.js

@@ -9,6 +9,8 @@ export class LocalStorageTransport {
         this.gameId = gameId;
         this.kind = 'standalone';
         this.user = null;
+        // No host to tell us the player's language — best-effort from the browser.
+        this.locale = (typeof navigator !== 'undefined' && navigator.language) ? navigator.language : 'en';
     }
     async call(method, params) {
         switch (method) {

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

@@ -10,6 +10,7 @@ export declare class PostMessageTransport implements Transport {
     user: UmicatUser | null;
     gameId: string;
     realtimeUrl?: string;
+    locale?: string;
     private pending;
     private seq;
     private constructor();

package/dist/core/transports/PostMessageTransport.js

@@ -68,6 +68,7 @@ export class PostMessageTransport {
         transport.user = init.user;
         transport.gameId = init.gameId;
         transport.realtimeUrl = init.realtimeUrl;
+        transport.locale = init.locale;
         transport.installResultListener();
         return transport;
     }

package/dist/protocol.d.ts

@@ -28,6 +28,12 @@ export interface InitMessage {
      * here after fetching a JWT via the 'realtime.getToken' RPC.
      */
     realtimeUrl?: string;
+    /**
+     * The player's preferred language (the host's UI locale, e.g. 'en', 'zh-CN',
+     * 'ja'). Lets a game default its UI + AI NPC language to the player's without
+     * asking. Absent in standalone mode → SDK falls back to the browser locale.
+     */
+    locale?: string;
 }
 export interface RpcResultOk {
     type: 'umicat:rpc.result';

package/package.json

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