@rpgjs/client 5.0.0-beta.11 → 5.0.0-beta.13

package/src/Game/ProjectileManager.spec.ts

@@ -35,6 +35,117 @@ describe("ProjectileManager", () => {
     expect(onSpawn).toHaveBeenCalledWith(expect.objectContaining({ id: "p1", type: "fireball" }));
   });
 
+  test("ignores projectile packets from another map", () => {
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    const component = () => null;
+
+    manager.register("fireball", component);
+    manager.setMapId("map-town");
+    manager.spawnBatch([
+      {
+        id: "old-map-projectile",
+        type: "fireball",
+        origin: { x: 10, y: 20 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ], { mapId: "map-dungeon" });
+
+    expect(manager.current()).toHaveLength(0);
+
+    manager.spawnBatch([
+      {
+        id: "current-map-projectile",
+        type: "fireball",
+        origin: { x: 10, y: 20 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ], { mapId: "map-town" });
+
+    expect(manager.current()).toHaveLength(1);
+  });
+
+  test("accepts server map ids without the client room prefix", () => {
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    const component = () => null;
+
+    manager.register("fireball", component);
+    manager.setMapId("map-town");
+    manager.spawnBatch([
+      {
+        id: "server-map-projectile",
+        type: "fireball",
+        origin: { x: 10, y: 20 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ], { mapId: "town" });
+
+    expect(manager.getMapId()).toBe("town");
+    expect(manager.current()).toHaveLength(1);
+  });
+
+  test("accepts prefixed map ids when the manager stores the logical map id", () => {
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    const component = () => null;
+
+    manager.register("fireball", component);
+    manager.setMapId("town");
+    manager.spawnBatch([
+      {
+        id: "prefixed-map-projectile",
+        type: "fireball",
+        origin: { x: 10, y: 20 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ], { mapId: "map-town" });
+
+    expect(manager.current()).toHaveLength(1);
+  });
+
+  test("clears projectiles when switching map ids", () => {
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+
+    manager.register("fireball", () => null);
+    manager.setMapId("map-town");
+    manager.spawnBatch([
+      {
+        id: "p1",
+        type: "fireball",
+        origin: { x: 10, y: 20 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ], { mapId: "map-town" });
+
+    expect(manager.current()).toHaveLength(1);
+
+    manager.setMapId("map-dungeon");
+
+    expect(manager.current()).toHaveLength(0);
+  });
+
   test("starts visuals at the spawn origin even when a server tick estimate exists", () => {
     vi.useFakeTimers();
     vi.setSystemTime(2000);

package/src/Game/ProjectileManager.ts

@@ -1,5 +1,6 @@
 import { computed, signal } from "canvasengine";
 import { Hooks } from "@rpgjs/common";
+import { normalizeRoomMapId } from "../utils/mapId";
 
 export interface ClientProjectileSpawn {
   id: string;
@@ -65,6 +66,7 @@ export interface ProjectileSpawnClock {
   now?: number;
   currentServerTick?: number;
   tickDurationMs?: number;
+  mapId?: string;
 }
 
 interface RuntimeProjectile {
@@ -84,6 +86,7 @@ export class ProjectileManager {
   private readonly projectiles = new Map<string, RuntimeProjectile>();
   private readonly version = signal(0);
   private readonly impactDurationMs = 350;
+  private mapId?: string;
 
   constructor(
     private readonly hooks: Hooks,
@@ -118,7 +121,19 @@ export class ProjectileManager {
     return this.components.get(type);
   }
 
+  setMapId(mapId: string | undefined): void {
+    const normalizedMapId = normalizeRoomMapId(mapId);
+    if (this.mapId === normalizedMapId) return;
+    this.mapId = normalizedMapId;
+    this.clear();
+  }
+
+  getMapId(): string | undefined {
+    return this.mapId;
+  }
+
   spawnBatch(projectiles: ClientProjectileSpawn[], clock: ProjectileSpawnClock = {}): void {
+    if (!this.acceptsMap(clock.mapId)) return;
     const now = clock.now ?? Date.now();
     for (const projectile of projectiles) {
       const component = this.components.get(projectile.type);
@@ -142,7 +157,8 @@ export class ProjectileManager {
     this.touch();
   }
 
-  impactBatch(impacts: ClientProjectileImpact[]): void {
+  impactBatch(impacts: ClientProjectileImpact[], context: { mapId?: string } = {}): void {
+    if (!this.acceptsMap(context.mapId)) return;
     const now = Date.now();
     for (const impact of impacts) {
       const projectile = this.projectiles.get(impact.id);
@@ -155,7 +171,8 @@ export class ProjectileManager {
     this.touch();
   }
 
-  destroyBatch(projectiles: ClientProjectileDestroy[]): void {
+  destroyBatch(projectiles: ClientProjectileDestroy[], context: { mapId?: string } = {}): void {
+    if (!this.acceptsMap(context.mapId)) return;
     const now = Date.now();
     for (const destroyed of projectiles) {
       const projectile = this.projectiles.get(destroyed.id);
@@ -241,6 +258,11 @@ export class ProjectileManager {
     };
   }
 
+  private acceptsMap(mapId: string | undefined): boolean {
+    const normalizedMapId = normalizeRoomMapId(mapId);
+    return !normalizedMapId || !this.mapId || normalizedMapId === this.mapId;
+  }
+
   private isWaitingForDelay(projectile: RuntimeProjectile, now: number): boolean {
     const delayMs = (projectile.spawn.delay ?? 0) * 1000;
     return now - projectile.createdAt - delayMs < 0;

package/src/Gui/Gui.spec.ts

@@ -64,6 +64,73 @@ const VueTooltip = {
 };
 
 describe("RpgGui Vue integration", () => {
+  test("tracks GUI open ids and sends them back when closing", async () => {
+    const { gui, socket } = await createGui();
+    await gui._initialize();
+    const openHandler = socket.on.mock.calls.find(([event]) => event === "gui.open")?.[1];
+
+    openHandler({
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: "open-1",
+      data: { message: "Hello" },
+    });
+
+    expect(gui.get(PrebuiltGui.Dialog)?.openId).toBe("open-1");
+
+    gui.guiClose(PrebuiltGui.Dialog, 0, gui.get(PrebuiltGui.Dialog)?.openId);
+
+    expect(socket.emit).toHaveBeenCalledWith("gui.exit", {
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: "open-1",
+      data: 0,
+    });
+  });
+
+  test("does not emit malformed GUI open ids", async () => {
+    const { gui, socket } = await createGui();
+
+    gui.guiClose(PrebuiltGui.Dialog, 0, (() => "open-1") as any);
+
+    expect(socket.emit).toHaveBeenCalledWith("gui.exit", {
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: undefined,
+      data: 0,
+    });
+  });
+
+  test("ignores stale server close events for previous GUI opens", async () => {
+    const { gui, socket } = await createGui();
+    await gui._initialize();
+    const openHandler = socket.on.mock.calls.find(([event]) => event === "gui.open")?.[1];
+    const exitHandler = socket.on.mock.calls.find(([event]) => event === "gui.exit")?.[1];
+
+    openHandler({
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: "open-1",
+      data: { message: "First" },
+    });
+    openHandler({
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: "open-2",
+      data: { message: "Second" },
+    });
+
+    exitHandler({
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: "open-1",
+    });
+
+    expect(gui.isDisplaying(PrebuiltGui.Dialog)).toBe(true);
+    expect(gui.get(PrebuiltGui.Dialog)?.data()).toEqual({ message: "Second" });
+
+    exitHandler({
+      guiId: PrebuiltGui.Dialog,
+      guiOpenId: "open-2",
+    });
+
+    expect(gui.isDisplaying(PrebuiltGui.Dialog)).toBe(false);
+  });
+
   test("separates CanvasEngine and Vue GUI registries", async () => {
     const { gui } = await createGui();
 

package/src/Gui/Gui.ts

@@ -39,6 +39,7 @@ export interface GuiInstance {
   component: any;
   display: WritableSignal<boolean>;
   data: WritableSignal<any>;
+  openId?: string;
   autoDisplay: boolean;
   dependencies?: Signal[];
   subscription?: Subscription;
@@ -50,6 +51,7 @@ type GuiState = {
   component: any;
   display: boolean;
   data: any;
+  openId?: string;
   attachToSprite: boolean;
 };
 
@@ -179,12 +181,18 @@ export class RpgGui {
   }
 
   async _initialize() {
-    this.webSocket.on("gui.open", (data: { guiId: string; data: any }) => {
+    this.webSocket.on("gui.open", (data: { guiId: string; data: any; guiOpenId?: string }) => {
       this.clearPendingActions(data.guiId);
-      this.display(data.guiId, data.data);
+      this.display(data.guiId, data.data, [], data.guiOpenId);
     });
 
-    this.webSocket.on("gui.exit", (guiId: string) => {
+    this.webSocket.on("gui.exit", (payload: string | { guiId: string; guiOpenId?: string }) => {
+      const guiId = typeof payload === "string" ? payload : payload.guiId;
+      const guiOpenId = typeof payload === "string" ? undefined : payload.guiOpenId;
+      const current = this.get(guiId);
+      if (guiOpenId && current?.openId && current.openId !== guiOpenId) {
+        return;
+      }
       this.hide(guiId);
     });
 
@@ -256,9 +264,12 @@ export class RpgGui {
     });
   }
 
-  guiClose(guiId: string, data?: any) {
+  guiClose(guiId: string, data?: any, guiOpenId?: unknown) {
+    const normalizedOpenId =
+      typeof guiOpenId === "string" && guiOpenId.length > 0 ? guiOpenId : undefined;
     this.webSocket.emit("gui.exit", {
       guiId,
+      guiOpenId: normalizedOpenId,
       data,
     });
   }
@@ -308,6 +319,7 @@ export class RpgGui {
       component,
       display: signal<boolean>(gui.display || false),
       data: signal<any>(gui.data || {}),
+      openId: undefined,
       autoDisplay: gui.autoDisplay || false,
       dependencies: gui.dependencies ? gui.dependencies() : [],
       attachToSprite,
@@ -431,7 +443,7 @@ export class RpgGui {
    * gui.display('shop', { shopId: 1 }, [playerSignal, shopSignal]);
    * ```
    */
-  display(id: string, data = {}, dependencies: Signal[] = []) {
+  display(id: string, data = {}, dependencies: Signal[] = [], openId?: string) {
     if (!this.exists(id)) {
       throw throwError(id);
     }
@@ -443,8 +455,9 @@ export class RpgGui {
     
     if (isVueComponent) {
       // Handle Vue component display
-      this._handleVueComponentDisplay(id, data, dependencies, guiInstance);
+      this._handleVueComponentDisplay(id, data, dependencies, guiInstance, openId);
     } else {
+      guiInstance.openId = openId;
       guiInstance.data.set(data);
       guiInstance.display.set(true);
     }
@@ -464,7 +477,7 @@ export class RpgGui {
    * @param dependencies - Runtime dependencies
    * @param guiInstance - GUI instance
    */
-  private _handleVueComponentDisplay(id: string, data: any, dependencies: Signal[], guiInstance: GuiInstance) {
+  private _handleVueComponentDisplay(id: string, data: any, dependencies: Signal[], guiInstance: GuiInstance, openId?: string) {
     // Unsubscribe from previous subscription if exists
     if (guiInstance.subscription) {
       guiInstance.subscription.unsubscribe();
@@ -482,6 +495,7 @@ export class RpgGui {
         deps.map(dependency => dependency.observable)
       ).subscribe((values) => {
         if (values.every(value => value !== undefined)) {
+          guiInstance.openId = openId;
           guiInstance.data.set(data);
           guiInstance.display.set(true);
           this._notifyVueGui(id, true, data);
@@ -491,6 +505,7 @@ export class RpgGui {
     }
 
     // No dependencies, display immediately
+    guiInstance.openId = openId;
     guiInstance.data.set(data);
     guiInstance.display.set(true);
     this._notifyVueGui(id, true, data);
@@ -523,6 +538,7 @@ export class RpgGui {
     }
 
     guiInstance.display.set(false)
+    guiInstance.openId = undefined;
     
     // Check if it's a Vue component and notify VueGui
     const isVueComponent = this.extraGuis.some(gui => gui.name === id);
@@ -573,6 +589,7 @@ export class RpgGui {
       component: gui.component,
       display,
       data,
+      openId: gui.openId,
       attachToSprite: gui.attachToSprite || false,
     };
   }

package/src/RpgClient.ts

@@ -2,11 +2,17 @@ import { ComponentFunction, Signal } from 'canvasengine'
 import { RpgClientEngine } from './RpgClientEngine'
 import { Loader, Container } from 'pixi.js'
 import { RpgClientObject } from './Game/Object'
-import { type MapPhysicsEntityContext, type MapPhysicsInitContext, type RpgActionName } from '@rpgjs/common'
+import type { RpgClientEvent } from './Game/Event'
+import { type I18nMessages, type MapPhysicsEntityContext, type MapPhysicsInitContext, type RpgActionName } from '@rpgjs/common'
 import type {
     ClientProjectileSpawn,
     RenderedProjectileProps,
 } from './Game/ProjectileManager'
+import type { ClientVisualMap } from './Game/ClientVisuals'
+import type {
+    RpgInteractionBehavior,
+    RpgInteractionMatcher,
+} from './services/interactions'
 
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
@@ -18,6 +24,16 @@ export type SpriteComponentConfig = ComponentFunction | {
     dependencies?: (object: RpgClientObject) => any[]
 }
 
+export type EventComponentSprite = RpgClientEvent & Record<string, any>
+
+export type EventComponentConfig = ComponentFunction | {
+    component: ComponentFunction
+    props?: Record<string, any> | ((event: EventComponentSprite) => Record<string, any>)
+    data?: Record<string, any> | ((event: EventComponentSprite) => Record<string, any>)
+    dependencies?: (event: EventComponentSprite) => any[]
+    renderGraphic?: boolean
+}
+
 export interface RpgSpriteBeforeRemoveContext {
     reason?: string
     data?: any
@@ -142,6 +158,31 @@ export interface RpgSpriteHooks {
      * ```
      */
     components?: Record<string, ComponentFunction>
+
+    /**
+     * Resolve a custom CanvasEngine component for a specific event.
+     *
+     * The component always receives the synced event object as the `sprite` prop.
+     * Custom props are merged in addition to `sprite`, but cannot replace it.
+     * Return `null` or `undefined` to keep the default graphic renderer.
+     *
+     * @prop { (event: EventComponentSprite) => EventComponentConfig | null | undefined } [eventComponent]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import ChestEvent from './components/chest-event.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   eventComponent(sprite) {
+     *     if (sprite.name === 'CHEST') {
+     *       return ChestEvent
+     *     }
+     *     return null
+     *   }
+     * }
+     * ```
+     */
+    eventComponent?: (event: EventComponentSprite) => EventComponentConfig | null | undefined
     
     /**
      * As soon as the sprite is initialized
@@ -326,6 +367,14 @@ export interface RpgProjectileHooks {
 }
 
 export interface RpgClient {
+    /**
+     * Default translations owned by this client module.
+     *
+     * Game-level translations provided with `provideI18n()` override module
+     * translations when they share the same locale and key.
+     */
+    i18n?: I18nMessages
+
     /**
      * Add hooks to the player or engine. All modules can listen to the hook
      * 
@@ -721,6 +770,37 @@ export interface RpgClient {
         component: ComponentFunction
     }[]
 
+    /**
+     * Named client-side visual macros.
+     *
+     * Use client visuals when the server needs to trigger a group of existing
+     * client visual primitives at once, such as a flash, damage text, sound,
+     * component animation, and camera shake. The server sends only the visual
+     * name and a serializable payload; the rendering details live on the client.
+     *
+     * For a single sound, flash, or component animation, prefer the direct
+     * server APIs (`playSound`, `flash`, `showComponentAnimation`). Client
+     * visuals are meant to group several visual operations and reduce bandwidth.
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     *
+     * export default defineModule<RpgClient>({
+     *   clientVisuals: {
+     *     hit({ target, data }, helpers) {
+     *       helpers.flash(target, { type: 'tint', tint: 'red' })
+     *       helpers.showHit(target, `-${data.damage}`)
+     *       helpers.sound('hit')
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @prop {Record<string, ClientVisualHandler>} [clientVisuals]
+     * @memberof RpgClient
+     */
+    clientVisuals?: ClientVisualMap
+
     /**
      * Client-side projectile rendering configuration.
      *
@@ -728,4 +808,19 @@ export interface RpgClient {
      * compact spawn/impact/destroy events and the client predicts x/y locally.
      */
     projectiles?: RpgProjectileHooks
+
+    /**
+     * Client-only pointer interactions attached to sprites.
+     *
+     * Use this for hover popovers, selection, drag previews, cursor changes, and
+     * explicit mouse-driven gameplay actions. Pointer feedback stays local unless
+     * the behavior calls `ctx.action(...)`.
+     */
+    interactions?:
+        | ((engine: RpgClientEngine) => void)
+        | {
+            setup?: (engine: RpgClientEngine) => void
+            load?: (engine: RpgClientEngine) => void
+            use?: Array<[RpgInteractionMatcher, RpgInteractionBehavior | ComponentFunction]>
+        }
 }