@rpgjs/client 5.0.0-beta.7 → 5.0.0-beta.9

package/src/Gui/Gui.spec.ts

@@ -0,0 +1,273 @@
+import { describe, expect, test, vi } from "vitest";
+import { Context, injector } from "@signe/di";
+import { signal } from "canvasengine";
+import { PrebuiltGui } from "@rpgjs/common";
+import { WebSocketToken } from "../services/AbstractSocket";
+
+vi.mock("../components/gui", () => {
+  const component = () => null;
+  return {
+    DialogboxComponent: component,
+    ShopComponent: component,
+    SaveLoadComponent: component,
+    MainMenuComponent: component,
+    NotificationComponent: component,
+    TitleScreenComponent: component,
+    GameoverComponent: component,
+  };
+});
+
+const createGui = async () => {
+  const { RpgGui } = await import("./Gui");
+  const context = new Context();
+  const socket = {
+    on: vi.fn(),
+    emit: vi.fn(),
+  };
+  await injector(context, [
+    {
+      provide: WebSocketToken,
+      useValue: socket,
+    },
+  ]);
+  return {
+    gui: new RpgGui(context),
+    socket,
+  };
+};
+
+const CanvasGui = () => null;
+const VueInventory = {
+  name: "inventory",
+  render() {
+    return null;
+  },
+};
+const VueDialog = {
+  name: PrebuiltGui.Dialog,
+  render() {
+    return null;
+  },
+};
+const VueMainMenu = {
+  name: PrebuiltGui.MainMenu,
+  render() {
+    return null;
+  },
+};
+const VueTooltip = {
+  name: "tooltip",
+  rpgAttachToSprite: true,
+  render() {
+    return null;
+  },
+};
+
+describe("RpgGui Vue integration", () => {
+  test("separates CanvasEngine and Vue GUI registries", async () => {
+    const { gui } = await createGui();
+
+    gui.add({
+      id: "canvas-tooltip",
+      component: CanvasGui,
+      attachToSprite: true,
+    });
+    gui.add({
+      id: "inventory",
+      component: VueInventory,
+    });
+    gui.add(VueTooltip);
+
+    expect(gui.get("canvas-tooltip")?.component).toBe(CanvasGui);
+    expect(gui.get("inventory")?.component).toBe(VueInventory);
+    expect(gui.get("tooltip")?.component).toBe(VueTooltip);
+    expect(gui.getAttachedGuis().map(item => item.name)).toEqual(["canvas-tooltip"]);
+    expect(gui.getAttachedVueGuis().map(item => item.name)).toEqual(["tooltip"]);
+  });
+
+  test("synchronizes Vue GUI display and hide states through the Vue bridge", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui.add({
+      id: "inventory",
+      component: VueInventory,
+    });
+    gui._setVueGuiInstance(bridge);
+
+    expect(bridge.initializeGuiStates).toHaveBeenCalledWith([
+      expect.objectContaining({
+        name: "inventory",
+        display: false,
+        data: {},
+        attachToSprite: false,
+      }),
+    ]);
+
+    gui.display("inventory", { gold: 12 });
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: "inventory",
+        display: true,
+        data: { gold: 12 },
+        attachToSprite: false,
+      }),
+    );
+
+    gui.hide("inventory");
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: "inventory",
+        display: false,
+      }),
+    );
+  });
+
+  test("waits for Vue GUI dependencies before display", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+    const dependency = signal<any>(undefined);
+
+    gui.add({
+      id: "inventory",
+      component: VueInventory,
+      dependencies: () => [dependency],
+    });
+    gui._setVueGuiInstance(bridge);
+    gui.display("inventory", { items: ["potion"] });
+
+    expect(gui.isDisplaying("inventory")).toBe(false);
+    expect(bridge.updateGuiState).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        display: true,
+      }),
+    );
+
+    dependency.set({ id: "player" });
+
+    expect(gui.isDisplaying("inventory")).toBe(true);
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: "inventory",
+        display: true,
+        data: { items: ["potion"] },
+      }),
+    );
+  });
+
+  test("allows Vue GUI entries to replace prebuilt CanvasEngine GUIs", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui._setVueGuiInstance(bridge);
+    gui.add({
+      id: PrebuiltGui.Dialog,
+      component: VueDialog,
+    });
+
+    expect(gui.get(PrebuiltGui.Dialog)?.component).toBe(VueDialog);
+    expect(gui.getAll()[PrebuiltGui.Dialog].component).toBe(VueDialog);
+    expect((gui as any).gui()[PrebuiltGui.Dialog]).toBeUndefined();
+    expect(gui.getVueGuis().filter(item => item.name === PrebuiltGui.Dialog)).toHaveLength(1);
+
+    gui.display(PrebuiltGui.Dialog, { text: "Hello" });
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: PrebuiltGui.Dialog,
+        display: true,
+        data: { text: "Hello" },
+      }),
+    );
+
+    gui.hide(PrebuiltGui.Dialog);
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: PrebuiltGui.Dialog,
+        display: false,
+      }),
+    );
+  });
+
+  test("allows CanvasEngine GUI entries to replace Vue GUI entries with the same id", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui._setVueGuiInstance(bridge);
+    gui.add({
+      id: PrebuiltGui.Dialog,
+      component: VueDialog,
+    });
+    gui.add({
+      id: PrebuiltGui.Dialog,
+      component: CanvasGui,
+    });
+
+    expect(gui.get(PrebuiltGui.Dialog)?.component).toBe(CanvasGui);
+    expect(gui.getVueGuis().some(item => item.name === PrebuiltGui.Dialog)).toBe(false);
+    expect((gui as any).gui()[PrebuiltGui.Dialog].component).toBe(CanvasGui);
+    expect(bridge.initializeGuiStates).toHaveBeenLastCalledWith([]);
+  });
+
+  test("keeps main menu optimistic reducers when a Vue GUI replaces the prebuilt component", async () => {
+    const { gui, socket } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui.add({
+      id: PrebuiltGui.MainMenu,
+      component: VueMainMenu,
+    });
+    gui._setVueGuiInstance(bridge);
+    gui.display(PrebuiltGui.MainMenu, {
+      items: [
+        {
+          id: "potion",
+          quantity: 2,
+        },
+      ],
+    });
+
+    gui.guiInteraction(PrebuiltGui.MainMenu, "useItem", { id: "potion" });
+
+    expect(gui.get(PrebuiltGui.MainMenu)?.data().items).toEqual([
+      {
+        id: "potion",
+        quantity: 1,
+      },
+    ]);
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: PrebuiltGui.MainMenu,
+        data: {
+          items: [
+            {
+              id: "potion",
+              quantity: 1,
+            },
+          ],
+        },
+      }),
+    );
+    expect(socket.emit).toHaveBeenCalledWith(
+      "gui.interaction",
+      expect.objectContaining({
+        guiId: PrebuiltGui.MainMenu,
+        name: "useItem",
+      }),
+    );
+  });
+});

package/src/Gui/Gui.ts

@@ -3,12 +3,12 @@ import { signal, Signal, WritableSignal } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "../services/AbstractSocket";
 import { DialogboxComponent, ShopComponent, SaveLoadComponent, MainMenuComponent, NotificationComponent, TitleScreenComponent, GameoverComponent } from "../components/gui";
 import { combineLatest, Subscription } from "rxjs";
-import { delay, PrebuiltGui } from "@rpgjs/common";
+import { PrebuiltGui } from "@rpgjs/common";
 
 interface GuiOptions {
   name?: string;
   id?: string;
-  component: any;
+  component?: any;
   display?: boolean;
   data?: any;
   /**
@@ -28,19 +28,36 @@ interface GuiOptions {
    * @default false
    */
   attachToSprite?: boolean;
+  /**
+   * Vue v4 compatibility flag. Prefer attachToSprite in v5 projects.
+   */
+  rpgAttachToSprite?: boolean;
 }
 
-interface GuiInstance {
+export interface GuiInstance {
   name: string;
   component: any;
   display: WritableSignal<boolean>;
   data: WritableSignal<any>;
   autoDisplay: boolean;
-  dependencies?: () => Signal[];
+  dependencies?: Signal[];
   subscription?: Subscription;
   attachToSprite?: boolean;
 }
 
+type GuiState = {
+  name: string;
+  component: any;
+  display: boolean;
+  data: any;
+  attachToSprite: boolean;
+};
+
+type VueGuiBridge = {
+  updateGuiState?: (state: GuiState) => void;
+  initializeGuiStates?: (states: GuiState[]) => void;
+};
+
 interface GuiAction {
   guiId: string;
   name: string;
@@ -117,7 +134,7 @@ export class RpgGui {
   private webSocket: AbstractWebsocket;
   gui = signal<Record<string, GuiInstance>>({});
   extraGuis: GuiInstance[] = [];
-  private vueGuiInstance: any = null; // Reference to VueGui instance
+  private vueGuiInstance: VueGuiBridge | null = null;
   private optimisticReducers = new Map<string, OptimisticReducer[]>();
   private pendingActions = new Map<string, GuiAction[]>();
   /**
@@ -196,6 +213,7 @@ export class RpgGui {
    */
   _setVueGuiInstance(vueGuiInstance: any) {
     this.vueGuiInstance = vueGuiInstance;
+    this._initializeVueComponents();
   }
 
   /**
@@ -207,21 +225,9 @@ export class RpgGui {
    * @param data - Component data
    */
   private _notifyVueGui(guiId: string, display: boolean, data: any = {}) {
-    if (this.vueGuiInstance && this.vueGuiInstance.vm) {
-      // Find the GUI in extraGuis
-      const extraGui = this.extraGuis.find(gui => gui.name === guiId);
-      if (extraGui) {
-        // Update the Vue component's display state and data
-        this.vueGuiInstance.vm.gui[guiId] = {
-          name: guiId,
-          display,
-          data,
-          attachToSprite: extraGui.attachToSprite || false
-        };
-        // Trigger Vue reactivity
-        this.vueGuiInstance.vm.gui = Object.assign({}, this.vueGuiInstance.vm.gui);
-      }
-    }
+    const extraGui = this.extraGuis.find(gui => gui.name === guiId);
+    if (!extraGui) return;
+    this.vueGuiInstance?.updateGuiState?.(this.toGuiState(extraGui, display, data));
   }
 
   /**
@@ -229,20 +235,9 @@ export class RpgGui {
    * This should be called after VueGui is mounted
    */
   _initializeVueComponents() {
-    if (this.vueGuiInstance && this.vueGuiInstance.vm) {
-      // Initialize all extraGuis in the Vue instance
-      this.extraGuis.forEach(gui => {
-        this.vueGuiInstance.vm.gui[gui.name] = {
-          name: gui.name,
-          display: gui.display(),
-          data: gui.data(),
-          attachToSprite: gui.attachToSprite || false
-        };
-      });
-      
-      // Trigger Vue reactivity
-      this.vueGuiInstance.vm.gui = Object.assign({}, this.vueGuiInstance.vm.gui);
-    }
+    this.vueGuiInstance?.initializeGuiStates?.(
+      this.extraGuis.map(gui => this.toGuiState(gui))
+    );
   }
 
   guiInteraction(guiId: string, name: string, data: any) {
@@ -301,35 +296,46 @@ export class RpgGui {
    * });
    * ```
    */
-  add(gui: GuiOptions) {
-    const guiId = gui.name || gui.id;
+  add(gui: GuiOptions | any) {
+    const component = this.resolveComponent(gui);
+    const guiId = this.resolveGuiId(gui, component);
     if (!guiId) {
       throw new Error("GUI must have a name or id");
     }
+    const attachToSprite = this.resolveAttachToSprite(gui, component);
     const guiInstance: GuiInstance = {
       name: guiId,
-      component: gui.component,
-      display: signal(gui.display || false),
-      data: signal(gui.data || {}),
+      component,
+      display: signal<boolean>(gui.display || false),
+      data: signal<any>(gui.data || {}),
       autoDisplay: gui.autoDisplay || false,
       dependencies: gui.dependencies ? gui.dependencies() : [],
-      attachToSprite: gui.attachToSprite || false,
+      attachToSprite,
     };
 
-    // Accept both CanvasEngine components (.ce) and Vue components
-    // Vue components will be handled by VueGui if available
-    if (typeof gui.component !== 'function') {
-      guiInstance.component = gui;
-      this.extraGuis.push(guiInstance);
+    if (this.isVueComponentInstance(guiInstance)) {
+      this.removeCanvasGui(guiId);
+      const existingIndex = this.extraGuis.findIndex(existing => existing.name === guiId);
+      if (existingIndex >= 0) {
+        this.extraGuis[existingIndex].subscription?.unsubscribe();
+        this.extraGuis[existingIndex] = guiInstance;
+      } else {
+        this.extraGuis.push(guiInstance);
+      }
+
+      this._initializeVueComponents();
       
-      // Auto display Vue components if enabled
       if (guiInstance.autoDisplay) {
-        this._notifyVueGui(guiId, true, gui.data || {});
+        this.display(guiId, gui.data);
+      } else {
+        this._notifyVueGui(guiId, guiInstance.display(), guiInstance.data());
       }
       return;
     }
 
+    this.removeVueGui(guiId);
     this.gui()[guiId] = guiInstance;
+    this._initializeVueComponents();
 
     // Auto display if enabled and it's a CanvasEngine component
     if (guiInstance.autoDisplay && typeof gui.component === 'function') {
@@ -357,8 +363,15 @@ export class RpgGui {
    * ```
    */
   getAttachedGuis(): GuiInstance[] {
-    const allGuis = this.getAll();
-    return Object.values(allGuis).filter(gui => gui.attachToSprite === true);
+    return Object.values(this.gui()).filter(gui => gui.attachToSprite === true);
+  }
+
+  getVueGuis(): GuiInstance[] {
+    return [...this.extraGuis];
+  }
+
+  getAttachedVueGuis(): GuiInstance[] {
+    return this.extraGuis.filter(gui => gui.attachToSprite === true);
   }
 
   /**
@@ -461,7 +474,7 @@ export class RpgGui {
     // Use runtime dependencies or config dependencies
     const deps = dependencies.length > 0 
       ? dependencies 
-      : (guiInstance.dependencies ? guiInstance.dependencies() : []);
+      : (guiInstance.dependencies ?? []);
 
     if (deps.length > 0) {
       // Subscribe to dependencies
@@ -522,6 +535,48 @@ export class RpgGui {
     return this.extraGuis.some(gui => gui.name === id);
   }
 
+  private isVueComponentInstance(gui: GuiInstance) {
+    return typeof gui.component !== "function";
+  }
+
+  private removeCanvasGui(guiId: string) {
+    const current = this.gui();
+    if (!(guiId in current)) return;
+    const next = { ...current };
+    delete next[guiId];
+    this.gui.set(next);
+  }
+
+  private removeVueGui(guiId: string) {
+    const removed = this.extraGuis.filter(existing => existing.name === guiId);
+    removed.forEach(gui => gui.subscription?.unsubscribe());
+    if (removed.length > 0) {
+      this.extraGuis = this.extraGuis.filter(existing => existing.name !== guiId);
+    }
+  }
+
+  private resolveComponent(gui: GuiOptions | any) {
+    return gui?.component ?? gui;
+  }
+
+  private resolveGuiId(gui: GuiOptions | any, component: any) {
+    return gui?.name || gui?.id || component?.name || component?.__name;
+  }
+
+  private resolveAttachToSprite(gui: GuiOptions | any, component: any) {
+    return !!(gui?.attachToSprite || gui?.rpgAttachToSprite || component?.attachToSprite || component?.rpgAttachToSprite);
+  }
+
+  private toGuiState(gui: GuiInstance, display = gui.display(), data = gui.data()): GuiState {
+    return {
+      name: gui.name,
+      component: gui.component,
+      display,
+      data,
+      attachToSprite: gui.attachToSprite || false,
+    };
+  }
+
   private clearPendingActions(guiId: string) {
     this.pendingActions.delete(guiId);
   }

package/src/Resource.ts

@@ -64,7 +64,7 @@ export class RpgResource {
       // Extract image path from spritesheet
       const imageLink = spritesheet?.image || spritesheet?.imageSource || undefined;
       if (imageLink) {
-        RpgResource._spritesheets.set(id, imageLink);
+        RpgResource._spritesheets.set(String(id), imageLink);
       }
     });
 
@@ -147,4 +147,3 @@ export class RpgResource {
     return RpgResource._sounds;
   }
 }
-

package/src/RpgClient.ts

@@ -7,6 +7,12 @@ import { type MapPhysicsEntityContext, type MapPhysicsInitContext } from '@rpgjs
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
 type SceneMap = Container
+export type SpriteComponentConfig = ComponentFunction | {
+    component: ComponentFunction
+    props?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>)
+    data?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>)
+    dependencies?: (object: RpgClientObject) => any[]
+}
 
 export interface RpgSpriteBeforeRemoveContext {
     reason?: string
@@ -93,7 +99,7 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsBehind?: ComponentFunction[]
+    componentsBehind?: SpriteComponentConfig[]
     
     /**
      * Array of components to render in front of the sprite
@@ -108,7 +114,28 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsInFront?: ComponentFunction[]
+    componentsInFront?: SpriteComponentConfig[]
+
+    /**
+     * Reusable sprite components addressable by server-side component definitions.
+     *
+     * The server sends only the component id and serializable props. The client
+     * registry maps that id to the CanvasEngine component that renders it.
+     *
+     * @prop {Record<string, ComponentFunction>} [components]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import GuildBadge from './components/guild-badge.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   components: {
+     *     guildBadge: GuildBadge
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, ComponentFunction>
     
     /**
      * As soon as the sprite is initialized
@@ -512,6 +539,13 @@ export interface RpgClient {
          * ```
          */
         attachToSprite?: boolean
+        /**
+         * Vue v4 compatibility alias for `attachToSprite`.
+         *
+         * Prefer `attachToSprite` in v5 projects. This is read by `@rpgjs/vue`
+         * for Vue GUI components migrated from the v4 GUI API.
+         */
+        rpgAttachToSprite?: boolean
     } | any)[],
 
     /**