@umicat/phaser-sdk 1.0.0 → 1.0.1

package/SDK-GUIDE.md

@@ -626,10 +626,11 @@ class GameScene extends Phaser.Scene {
     // ...wire physics + input on `this.player`...
   }
   update() {
-    // Safe: loadWorldScene suspends update() during its await, so any
-    // class field assigned after `await loadWorldScene(...)` is defined
-    // by the first time update() ticks. No `if (!this.player) return;`
-    // guard needed.
+    // Safe: an async create() suspends update() until it resolves. The SDK
+    // gates this in createUmicatGame (since 1.0.1) for EVERY registered
+    // scene, so any class field assigned after ANY `await` in create() —
+    // loadWorldScene, saves.get(), umicatReady, a fetch — is defined by the
+    // first time update() ticks. No `if (!this.player) return;` guard needed.
     this.player.setVelocityX(0);
   }
 }

package/dist/core/UmicatGame.js

@@ -6,11 +6,70 @@ import { setupEditorModeListener } from '../scene/EditorMode.js';
 import { ORIENTATION_DIMENSIONS } from '../orientation.js';
 import { setRenderScriptRegistry, } from '../scene/renderScripts.js';
 import { UmicatHudScene } from '../scene/HudRuntime.js';
+/**
+ * Make a Promise-returning `create()` safe against Phaser's update loop.
+ *
+ * Phaser does NOT await an async `create()`. The moment `create()` suspends
+ * at its first `await`, Phaser flips the scene to RUNNING and starts calling
+ * `update()` every frame — so any object the game builds *after* that await
+ * (a HUD text, the player sprite) is `undefined` for those frames. An
+ * `update()` that reads it throws on every frame and the game appears frozen
+ * on the loading screen. This is a very easy trap to fall into: the docs
+ * pattern `const hi = await saves.get('highScore')` at the top of `create()`
+ * is enough to trigger it.
+ *
+ * We give async `create()` the same guarantee `preload()` already has —
+ * "update() does not run until setup is finished" — by wrapping each scene so
+ * `update()` is a no-op until the `create()` promise settles. Synchronous
+ * `create()` is untouched (it never returns a thenable, so the gate is never
+ * armed). Re-runs cleanly across `scene.restart()` since the flag lives on
+ * the scene instance and is re-armed each create().
+ */
+function guardAsyncCreate(SceneClass) {
+    const proto = SceneClass.prototype;
+    // Patch the prototype at most once, even under HMR / repeated factory calls.
+    if (proto.__umicatGuarded)
+        return;
+    const origCreate = proto.create;
+    if (typeof origCreate !== 'function')
+        return; // no create() → nothing to gate
+    proto.__umicatGuarded = true;
+    const PENDING = '__umicatCreatePending';
+    proto.create = function (...args) {
+        const ret = origCreate.apply(this, args);
+        if (ret && typeof ret.then === 'function') {
+            this[PENDING] = true;
+            Promise.resolve(ret)
+                .catch((e) => {
+                // Surface the failure instead of hanging update() forever.
+                // eslint-disable-next-line no-console
+                console.error('[umicat] async create() rejected:', e);
+            })
+                .finally(() => {
+                this[PENDING] = false;
+            });
+        }
+        return ret;
+    };
+    const origUpdate = proto.update;
+    if (typeof origUpdate === 'function') {
+        proto.update = function (...args) {
+            if (this[PENDING])
+                return undefined; // setup still running — skip this frame
+            return origUpdate.apply(this, args);
+        };
+    }
+}
 /**
  * Create an Umicat-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
  */
 export function createUmicatGame(options) {
+    // Harden every game scene against the async-create()/update() race before
+    // Phaser instantiates them (see guardAsyncCreate). The auto-registered
+    // UmicatHudScene is ours and uses a sync create(), so it's left alone.
+    for (const SceneClass of options.scenes)
+        guardAsyncCreate(SceneClass);
     const { width, height } = 'orientation' in options && options.orientation
         ? ORIENTATION_DIMENSIONS[options.orientation]
         : { width: options.width, height: options.height };

package/dist/core/phaser-global.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/phaser-global.js

@@ -0,0 +1,10 @@
+import Phaser from 'phaser';
+// phaser3-rex-plugins (e.g. the NinePatch plugin) were written for Phaser 3's
+// UMD build, which set a global `window.Phaser`. Their module bodies reference a
+// bare `Phaser` at eval time (e.g. `Phaser.Utils.Objects.GetValue`). Phaser 4 is
+// pure ESM and does NOT expose a global, so those plugins throw
+// "Phaser is not defined". Expose Phaser on globalThis here.
+//
+// IMPORTANT: this module must be imported BEFORE any `phaser3-rex-plugins/*`
+// import so the global exists before the plugin's top-level code evaluates.
+globalThis.Phaser = Phaser;

package/package.json

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