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

package/src/Game/Object.ts

@@ -130,12 +130,12 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
     const restoreState = this.animationRestoreState;
     this.clearAnimationControls();
     this.animationCurrentIndex.set(0);
+    this.animationRestoreState = undefined;
+    this.animationIsPlaying.set(false);
     if (restoreState) {
       this.animationName.set(restoreState.animationName);
       this.graphics.set([...restoreState.graphics]);
     }
-    this.animationRestoreState = undefined;
-    this.animationIsPlaying.set(false);
     this.resolveAnimationWait();
   }
 

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/RpgClient.ts

@@ -2,11 +2,13 @@ import { ComponentFunction, Signal } from 'canvasengine'
 import { RpgClientEngine } from './RpgClientEngine'
 import { Loader, Container } from 'pixi.js'
 import { RpgClientObject } from './Game/Object'
+import type { RpgClientEvent } from './Game/Event'
 import { type MapPhysicsEntityContext, type MapPhysicsInitContext, type RpgActionName } from '@rpgjs/common'
 import type {
     ClientProjectileSpawn,
     RenderedProjectileProps,
 } from './Game/ProjectileManager'
+import type { ClientVisualMap } from './Game/ClientVisuals'
 
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
@@ -18,6 +20,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 +154,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
@@ -721,6 +758,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.
      *

package/src/RpgClientEngine.ts

@@ -7,6 +7,8 @@ import { LoadMapService, LoadMapToken } from "./services/loadMap";
 import { RpgSound } from "./Sound";
 import { RpgResource } from "./Resource";
 import { Hooks, ModulesToken, Direction, normalizeLightingState, Vector2 } from "@rpgjs/common";
+import type { EventComponentConfig } from "./RpgClient";
+import type { RpgClientEvent } from "./Game/Event";
 import { load } from "@signe/sync";
 import { RpgClientMap } from "./Game/Map"
 import { RpgGui } from "./Gui/Gui";
@@ -30,8 +32,11 @@ import { NotificationManager } from "./Gui/NotificationManager";
 import { SaveClientService } from "./services/save";
 import { getCanMoveValue } from "./utils/readPropValue";
 import { ProjectileManager, type ClientProjectileImpact, type ClientProjectileSpawn } from "./Game/ProjectileManager";
+import { ClientVisualRegistry, type ClientVisualHandler, type ClientVisualMap, type ClientVisualPacket } from "./Game/ClientVisuals";
 import { normalizeActionInput } from "./services/actionInput";
 import { createClientPointerContext, type ClientPointerContext } from "./services/pointerContext";
+import { normalizeRoomMapId } from "./utils/mapId";
+import { EventComponentResolverRegistry, type EventComponentResolver } from "./Game/EventComponentResolver";
 
 interface MovementTrajectoryPoint {
   frame: number;
@@ -70,6 +75,7 @@ export class RpgClientEngine<T = any> {
   spritesheets: Map<string | number, any> = new Map();
   sounds: Map<string, any> = new Map();
   componentAnimations: any[] = [];
+  clientVisuals = new ClientVisualRegistry();
   projectiles: ProjectileManager;
   pointer: ClientPointerContext = createClientPointerContext();
   private spritesheetResolver?: (id: string | number) => any | Promise<any>;
@@ -87,6 +93,7 @@ export class RpgClientEngine<T = any> {
   spriteComponentsBehind = signal<any[]>([]);
   spriteComponentsInFront = signal<any[]>([]);
   spriteComponents: Map<string, any> = new Map();
+  private eventComponentResolvers = new EventComponentResolverRegistry();
   /** ID of the sprite that the camera should follow. null means follow the current player */
   cameraFollowTargetId = signal<string | null>(null);
   /** Trigger for map shake animation */
@@ -120,6 +127,9 @@ export class RpgClientEngine<T = any> {
   private eventsReceived$ = new BehaviorSubject<boolean>(false);
   private onAfterLoadingSubscription?: any;
   private sceneResetQueued = false;
+  private mapTransitionInProgress = false;
+  private currentMapRoomId?: string;
+  private socketListenersInitialized = false;
   
   // Store subscriptions and event listeners for cleanup
   private tickSubscriptions: any[] = [];
@@ -266,6 +276,7 @@ export class RpgClientEngine<T = any> {
     this.hooks.callHooks("client-gui-load", this).subscribe();
     this.hooks.callHooks("client-particles-load", this).subscribe();
     this.hooks.callHooks("client-componentAnimations-load", this).subscribe();
+    this.hooks.callHooks("client-clientVisuals-load", this).subscribe();
     this.hooks.callHooks("client-projectiles-load", this).subscribe();
     this.hooks.callHooks("client-sprite-load", this).subscribe();
 
@@ -392,6 +403,9 @@ export class RpgClientEngine<T = any> {
   }
 
   private initListeners() {
+    if (this.socketListenersInitialized) return;
+    this.socketListenersInitialized = true;
+
     this.webSocket.on("sync", (data) => {
       if (!this.tick) {
         this.pendingSyncPackets.push(data);
@@ -420,13 +434,8 @@ export class RpgClientEngine<T = any> {
     });
 
     this.webSocket.on("changeMap", (data) => {
-      this.sceneResetQueued = true;
-      this.sceneMap.weatherState.set(null);
-      this.sceneMap.lightingState.set(null);
-      this.sceneMap.clearLightSpots();
-      this.projectiles.clear();
-      // Reset camera follow to default (follow current player) when changing maps
-      this.cameraFollowTargetId.set(null);
+      const nextMapId = typeof data?.mapId === "string" ? data.mapId : undefined;
+      this.beginMapTransfer(nextMapId);
       const transferToken = typeof data?.transferToken === "string" ? data.transferToken : undefined;
       this.loadScene(data.mapId, transferToken);
     });
@@ -440,22 +449,35 @@ export class RpgClientEngine<T = any> {
       this.getComponentAnimation(id).displayEffect(params, player || position)
     });
 
+    this.webSocket.on("clientVisual", (data) => {
+      this.playClientVisual(data);
+    });
+
     this.webSocket.on("projectile:spawnBatch", (data) => {
+      if (!this.shouldProcessProjectilePacket(data)) return;
       this.projectiles.spawnBatch(data?.projectiles ?? [], {
+        mapId: data?.mapId,
         currentServerTick: this.estimateServerTick(),
         tickDurationMs: this.getPhysicsTickDurationMs(),
       });
     });
 
     this.webSocket.on("projectile:impactBatch", (data) => {
-      this.projectiles.impactBatch(data?.impacts ?? []);
+      if (!this.shouldProcessProjectilePacket(data)) return;
+      this.projectiles.impactBatch(data?.impacts ?? [], {
+        mapId: data?.mapId,
+      });
     });
 
     this.webSocket.on("projectile:destroyBatch", (data) => {
-      this.projectiles.destroyBatch(data?.projectiles ?? []);
+      if (!this.shouldProcessProjectilePacket(data)) return;
+      this.projectiles.destroyBatch(data?.projectiles ?? [], {
+        mapId: data?.mapId,
+      });
     });
 
-    this.webSocket.on("projectile:clear", () => {
+    this.webSocket.on("projectile:clear", (data) => {
+      if (!this.shouldProcessProjectilePacket(data)) return;
       this.projectiles.clear();
     });
 
@@ -573,6 +595,36 @@ export class RpgClientEngine<T = any> {
     })
   }
 
+  private beginMapTransfer(nextMapId?: string) {
+    this.mapTransitionInProgress = true;
+    this.currentMapRoomId = nextMapId;
+    this.sceneResetQueued = false;
+    this.clearClientPredictionStates();
+    this.sceneMap.weatherState.set(null);
+    this.sceneMap.lightingState.set(null);
+    this.sceneMap.clearLightSpots();
+    this.clearComponentAnimations();
+    this.projectiles.setMapId(nextMapId);
+    this.cameraFollowTargetId.set(null);
+    this.sceneMap.reset();
+    this.sceneMap.loadPhysic();
+  }
+
+  private clearComponentAnimations() {
+    this.componentAnimations.forEach((componentAnimation) => {
+      componentAnimation.instance?.clear?.();
+    });
+  }
+
+  private shouldProcessProjectilePacket(data: any): boolean {
+    if (this.mapTransitionInProgress) return false;
+    const packetMapId = normalizeRoomMapId(
+      typeof data?.mapId === "string" ? data.mapId : undefined,
+    );
+    const currentMapId = normalizeRoomMapId(this.currentMapRoomId);
+    return !packetMapId || !currentMapId || packetMapId === currentMapId;
+  }
+
   private async callConnectError(error: any) {
     await lastValueFrom(this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket));
   }
@@ -732,14 +784,10 @@ export class RpgClientEngine<T = any> {
       query: transferToken ? { transferToken } : undefined,
     })
     try {
-      await this.webSocket.reconnect(() => {
-        const saveClient = inject(SaveClientService);
-        saveClient.initialize();
-        this.initListeners()
-        this.guiService._initialize()
-      })
+      await this.webSocket.reconnect()
     }
     catch (error) {
+      this.mapTransitionInProgress = false;
       this.stopPingPong();
       await this.callConnectError(error);
       throw error;
@@ -765,6 +813,8 @@ export class RpgClientEngine<T = any> {
     
     // Signal that map loading is completed (this should be last to ensure other checks are done)
     this.mapLoadCompleted$.next(true);
+    this.currentMapRoomId = mapId;
+    this.mapTransitionInProgress = false;
     this.sceneMap.configureClientPrediction(this.predictionEnabled);
     this.sceneMap.loadPhysic()
   }
@@ -1290,6 +1340,29 @@ export class RpgClientEngine<T = any> {
     return this.spriteComponents.get(id);
   }
 
+  /**
+   * Register a custom event component resolver.
+   *
+   * The last resolver returning a component wins. This lets later modules
+   * override earlier defaults without replacing the whole map scene.
+   *
+   * @param resolver - Function receiving the synced event object
+   * @returns The registered resolver
+   */
+  addEventComponentResolver(resolver: EventComponentResolver) {
+    return this.eventComponentResolvers.add(resolver);
+  }
+
+  /**
+   * Resolve the custom CanvasEngine component for an event, if any.
+   *
+   * @param event - Synced client event object
+   * @returns The component/config returned by the last matching resolver
+   */
+  resolveEventComponent(event: RpgClientEvent): EventComponentConfig | null {
+    return this.eventComponentResolvers.resolve(event);
+  }
+
   registerProjectileComponent(type: string, component: any) {
     return this.projectiles.register(type, component);
   }
@@ -1298,6 +1371,42 @@ export class RpgClientEngine<T = any> {
     return this.projectiles.get(type);
   }
 
+  /**
+   * Register a named client visual macro.
+   *
+   * Client visuals are small client-side functions that group existing visual
+   * primitives such as flash, sound, component animations, sprite animation, or
+   * map shake. The server sends only the visual name and a serializable payload.
+   *
+   * @param name - Stable visual name sent by the server
+   * @param handler - Client-side visual handler
+   * @returns The registered handler
+   */
+  registerClientVisual(name: string, handler: ClientVisualHandler) {
+    return this.clientVisuals.register(name, handler);
+  }
+
+  /**
+   * Register several named client visual macros.
+   *
+   * @param visuals - Map of visual names to client-side handlers
+   */
+  registerClientVisuals(visuals: ClientVisualMap) {
+    this.clientVisuals.registerMany(visuals);
+  }
+
+  /**
+   * Play a registered client visual locally.
+   *
+   * This is also used by the websocket listener when the server calls
+   * `player.clientVisual()` or `map.clientVisual()`.
+   *
+   * @param packet - Visual name and serializable payload
+   */
+  playClientVisual(packet: ClientVisualPacket) {
+    return this.clientVisuals.play(packet, this);
+  }
+
   /**
    * Add a component animation to the engine
    * 
@@ -1485,6 +1594,10 @@ export class RpgClientEngine<T = any> {
     return this.sceneMap
   }
 
+  getObjectById(id: string) {
+    return this.sceneMap?.getObjectById(id);
+  }
+
   private getPhysicsTick(): number {
     return (this.sceneMap as any)?.getTick?.() ?? 0;
   }
@@ -2142,6 +2255,7 @@ export class RpgClientEngine<T = any> {
       this.cameraFollowTargetId.set(null);
       this.spriteComponentsBehind.set([]);
       this.spriteComponentsInFront.set([]);
+      this.eventComponentResolvers.clear();
       
       // Clear maps and arrays
       this.spritesheets.clear();

package/src/components/animations/fx.ce

@@ -0,0 +1,101 @@
+<Fx
+  name={name}
+  preset={preset}
+  trigger={trigger}
+  autostart={autostart}
+  loop={loop}
+  enabled={enabled}
+  x={x}
+  y={y}
+  rotation={rotation}
+  scale={scale}
+  alpha={alpha}
+  timeScale={timeScale}
+  maxParticles={maxParticles}
+  preload={preload}
+  missingTexture={missingTexture}
+  zIndex={zIndex}
+  onStart={onStart}
+  onComplete={finish}
+  onParticleSpawn={onParticleSpawn}
+/>
+
+<script>
+  import { tick } from "canvasengine";
+  import { Fx } from "@canvasengine/presets";
+
+  const {
+    name,
+    preset,
+    trigger,
+    onFinish,
+    onStart,
+    onComplete,
+    onParticleSpawn,
+    displayDuration,
+    duration,
+    autostart,
+    loop,
+    enabled,
+    x,
+    y,
+    rotation,
+    scale,
+    alpha,
+    timeScale,
+    maxParticles,
+    preload,
+    missingTexture,
+    zIndex,
+  } = defineProps({
+    autostart: {
+      default: true,
+    },
+    loop: {
+      default: false,
+    },
+    enabled: {
+      default: true,
+    },
+    rotation: {
+      default: 0,
+    },
+    scale: {
+      default: 1,
+    },
+    alpha: {
+      default: 1,
+    },
+    timeScale: {
+      default: 1,
+    },
+    maxParticles: {
+      default: 600,
+    },
+    preload: {
+      default: true,
+    },
+    missingTexture: {
+      default: "shape",
+    },
+  });
+
+  let elapsedTime = 0;
+  let finished = false;
+
+  function finish(instance) {
+    if (finished) return;
+    finished = true;
+    onComplete?.(instance);
+    onFinish?.(instance);
+  }
+
+  tick(({ deltaTime }) => {
+    const maxDuration = displayDuration?.() ?? (loop() ? duration?.() : undefined);
+    if (!maxDuration || finished) return;
+    elapsedTime += deltaTime;
+    if (elapsedTime >= maxDuration) {
+      finish();
+    }
+  });
+</script>

package/src/components/animations/index.ts

@@ -1,7 +1,9 @@
 import Hit from "./hit.ce";
 import Animation from "./animation.ce";
+import Fx from "./fx.ce";
 
 export const PrebuiltComponentAnimations = {
     Hit,
-    Animation
-}
+    Animation,
+    Fx
+}