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

package/dist/RpgClient.d.ts

@@ -2,8 +2,10 @@ import { ComponentFunction, Signal } from 'canvasengine';
 import { RpgClientEngine } from './RpgClientEngine';
 import { Loader, Container } from 'pixi.js';
 import { RpgClientObject } from './Game/Object';
+import { RpgClientEvent } from './Game/Event';
 import { MapPhysicsEntityContext, MapPhysicsInitContext, RpgActionName } from '@rpgjs/common';
 import { ClientProjectileSpawn, RenderedProjectileProps } from './Game/ProjectileManager';
+import { ClientVisualMap } from './Game/ClientVisuals';
 type RpgComponent = RpgClientObject;
 type SceneMap = Container;
 export type SpriteComponentConfig = ComponentFunction | {
@@ -12,6 +14,14 @@ export type SpriteComponentConfig = ComponentFunction | {
     data?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>);
     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;
@@ -131,6 +141,30 @@ 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
      *
@@ -675,6 +709,36 @@ export interface RpgClient {
         id: string;
         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/dist/RpgClientEngine.d.ts

@@ -1,11 +1,15 @@
 import { Trigger } from 'canvasengine';
 import { AbstractWebsocket } from './services/AbstractSocket';
 import { Direction, RpgActionInput, RpgActionName } from '@rpgjs/common';
+import { EventComponentConfig } from './RpgClient';
+import { RpgClientEvent } from './Game/Event';
 import { RpgClientMap } from './Game/Map';
 import { AnimationManager } from './Game/AnimationManager';
 import { Observable } from 'rxjs';
 import { ProjectileManager } from './Game/ProjectileManager';
+import { ClientVisualRegistry, ClientVisualHandler, ClientVisualMap, ClientVisualPacket } from './Game/ClientVisuals';
 import { ClientPointerContext } from './services/pointerContext';
+import { EventComponentResolver } from './Game/EventComponentResolver';
 import * as PIXI from "pixi.js";
 type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
     start(config?: T): Promise<void>;
@@ -33,6 +37,7 @@ export declare class RpgClientEngine<T = any> {
     spritesheets: Map<string | number, any>;
     sounds: Map<string, any>;
     componentAnimations: any[];
+    clientVisuals: ClientVisualRegistry;
     projectiles: ProjectileManager;
     pointer: ClientPointerContext;
     private spritesheetResolver?;
@@ -48,6 +53,7 @@ export declare class RpgClientEngine<T = any> {
     spriteComponentsBehind: import('canvasengine').WritableArraySignal<any[]>;
     spriteComponentsInFront: import('canvasengine').WritableArraySignal<any[]>;
     spriteComponents: Map<string, any>;
+    private eventComponentResolvers;
     /** ID of the sprite that the camera should follow. null means follow the current player */
     cameraFollowTargetId: import('canvasengine').WritableSignal<string | null>;
     /** Trigger for map shake animation */
@@ -77,6 +83,9 @@ export declare class RpgClientEngine<T = any> {
     private eventsReceived$;
     private onAfterLoadingSubscription?;
     private sceneResetQueued;
+    private mapTransitionInProgress;
+    private currentMapRoomId?;
+    private socketListenersInitialized;
     private tickSubscriptions;
     private resizeHandler?;
     private pointerMoveHandler?;
@@ -125,6 +134,9 @@ export declare class RpgClientEngine<T = any> {
     private prepareSyncPayload;
     private normalizeAckWithSyncState;
     private initListeners;
+    private beginMapTransfer;
+    private clearComponentAnimations;
+    private shouldProcessProjectilePacket;
     private callConnectError;
     private flushPendingSyncPackets;
     private applySyncPacket;
@@ -502,8 +514,52 @@ export declare class RpgClientEngine<T = any> {
      * @returns The CanvasEngine component, or undefined when missing
      */
     getSpriteComponent(id: string): any;
+    /**
+     * 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): EventComponentResolver;
+    /**
+     * 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;
     registerProjectileComponent(type: string, component: any): any;
     getProjectileComponent(type: string): any;
+    /**
+     * 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): ClientVisualHandler;
+    /**
+     * Register several named client visual macros.
+     *
+     * @param visuals - Map of visual names to client-side handlers
+     */
+    registerClientVisuals(visuals: ClientVisualMap): void;
+    /**
+     * 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): Promise<void>;
     /**
      * Add a component animation to the engine
      *
@@ -588,6 +644,7 @@ export declare class RpgClientEngine<T = any> {
     get socket(): AbstractWebsocket;
     get playerId(): string | null;
     get scene(): RpgClientMap;
+    getObjectById(id: string): any;
     private getPhysicsTick;
     private getPhysicsTickDurationMs;
     private updateServerTickEstimate;

package/dist/RpgClientEngine.js

@@ -19,8 +19,11 @@ import __ce_component$3 from "./components/dynamics/bar.ce.js";
 import __ce_component$4 from "./components/dynamics/shape.ce.js";
 import __ce_component$5 from "./components/dynamics/image.ce.js";
 import { NotificationManager } from "./Gui/NotificationManager.js";
+import { normalizeRoomMapId } from "./utils/mapId.js";
 import { ProjectileManager } from "./Game/ProjectileManager.js";
+import { ClientVisualRegistry } from "./Game/ClientVisuals.js";
 import { createClientPointerContext } from "./services/pointerContext.js";
+import { EventComponentResolverRegistry } from "./Game/EventComponentResolver.js";
 import { Howl, bootstrapCanvas, signal, trigger } from "canvasengine";
 import { Direction, ModulesToken, PredictionController, Vector2, normalizeLightingState } from "@rpgjs/common";
 import { BehaviorSubject, combineLatest, filter, lastValueFrom, switchMap, take } from "rxjs";
@@ -36,12 +39,14 @@ var RpgClientEngine = class {
 		this.spritesheets = /* @__PURE__ */ new Map();
 		this.sounds = /* @__PURE__ */ new Map();
 		this.componentAnimations = [];
+		this.clientVisuals = new ClientVisualRegistry();
 		this.pointer = createClientPointerContext();
 		this.particleSettings = { emitters: [] };
 		this.playerIdSignal = signal(null);
 		this.spriteComponentsBehind = signal([]);
 		this.spriteComponentsInFront = signal([]);
 		this.spriteComponents = /* @__PURE__ */ new Map();
+		this.eventComponentResolvers = new EventComponentResolverRegistry();
 		this.cameraFollowTargetId = signal(null);
 		this.mapShakeTrigger = trigger();
 		this.controlsReady = signal(void 0);
@@ -66,6 +71,8 @@ var RpgClientEngine = class {
 		this.playersReceived$ = new BehaviorSubject(false);
 		this.eventsReceived$ = new BehaviorSubject(false);
 		this.sceneResetQueued = false;
+		this.mapTransitionInProgress = false;
+		this.socketListenersInitialized = false;
 		this.tickSubscriptions = [];
 		this.pendingSyncPackets = [];
 		this.notificationManager = new NotificationManager();
@@ -178,6 +185,7 @@ var RpgClientEngine = class {
 		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();
 		await lastValueFrom(this.hooks.callHooks("client-engine-onStart", this));
@@ -271,6 +279,8 @@ var RpgClientEngine = class {
 		};
 	}
 	initListeners() {
+		if (this.socketListenersInitialized) return;
+		this.socketListenersInitialized = true;
 		this.webSocket.on("sync", (data) => {
 			if (!this.tick) {
 				this.pendingSyncPackets.push(data);
@@ -288,12 +298,8 @@ var RpgClientEngine = class {
 			console.debug(`[Ping/Pong] RTT: ${this.rtt}ms, ServerTick: ${data.serverTick}, FrameOffset: ${this.frameOffset}`);
 		});
 		this.webSocket.on("changeMap", (data) => {
-			this.sceneResetQueued = true;
-			this.sceneMap.weatherState.set(null);
-			this.sceneMap.lightingState.set(null);
-			this.sceneMap.clearLightSpots();
-			this.projectiles.clear();
-			this.cameraFollowTargetId.set(null);
+			const nextMapId = typeof data?.mapId === "string" ? data.mapId : void 0;
+			this.beginMapTransfer(nextMapId);
 			const transferToken = typeof data?.transferToken === "string" ? data.transferToken : void 0;
 			this.loadScene(data.mapId, transferToken);
 		});
@@ -303,19 +309,27 @@ var RpgClientEngine = class {
 			const player = object ? this.sceneMap.getObjectById(object) : void 0;
 			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();
 		});
 		this.webSocket.on("notification", (data) => {
@@ -408,6 +422,31 @@ var RpgClientEngine = class {
 			this.callConnectError(error);
 		});
 	}
+	beginMapTransfer(nextMapId) {
+		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();
+	}
+	clearComponentAnimations() {
+		this.componentAnimations.forEach((componentAnimation) => {
+			componentAnimation.instance?.clear?.();
+		});
+	}
+	shouldProcessProjectilePacket(data) {
+		if (this.mapTransitionInProgress) return false;
+		const packetMapId = normalizeRoomMapId(typeof data?.mapId === "string" ? data.mapId : void 0);
+		const currentMapId = normalizeRoomMapId(this.currentMapRoomId);
+		return !packetMapId || !currentMapId || packetMapId === currentMapId;
+	}
 	async callConnectError(error) {
 		await lastValueFrom(this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket));
 	}
@@ -522,12 +561,9 @@ var RpgClientEngine = class {
 			query: transferToken ? { transferToken } : void 0
 		});
 		try {
-			await this.webSocket.reconnect(() => {
-				inject(SaveClientService).initialize();
-				this.initListeners();
-				this.guiService._initialize();
-			});
+			await this.webSocket.reconnect();
 		} catch (error) {
+			this.mapTransitionInProgress = false;
 			this.stopPingPong();
 			await this.callConnectError(error);
 			throw error;
@@ -539,6 +575,8 @@ var RpgClientEngine = class {
 		if (players && Object.keys(players).length > 0) this.playersReceived$.next(true);
 		if (this.sceneMap.events() !== void 0) this.eventsReceived$.next(true);
 		this.mapLoadCompleted$.next(true);
+		this.currentMapRoomId = mapId;
+		this.mapTransitionInProgress = false;
 		this.sceneMap.configureClientPrediction(this.predictionEnabled);
 		this.sceneMap.loadPhysic();
 	}
@@ -960,6 +998,27 @@ var RpgClientEngine = class {
 	getSpriteComponent(id) {
 		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) {
+		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) {
+		return this.eventComponentResolvers.resolve(event);
+	}
 	registerProjectileComponent(type, component) {
 		return this.projectiles.register(type, component);
 	}
@@ -967,6 +1026,39 @@ var RpgClientEngine = class {
 		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, handler) {
+		return this.clientVisuals.register(name, handler);
+	}
+	/**
+	* Register several named client visual macros.
+	*
+	* @param visuals - Map of visual names to client-side handlers
+	*/
+	registerClientVisuals(visuals) {
+		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) {
+		return this.clientVisuals.play(packet, this);
+	}
+	/**
 	* Add a component animation to the engine
 	* 
 	* Component animations are temporary visual effects that can be displayed
@@ -1123,6 +1215,9 @@ var RpgClientEngine = class {
 	get scene() {
 		return this.sceneMap;
 	}
+	getObjectById(id) {
+		return this.sceneMap?.getObjectById(id);
+	}
 	getPhysicsTick() {
 		return this.sceneMap?.getTick?.() ?? 0;
 	}
@@ -1565,6 +1660,7 @@ var RpgClientEngine = class {
 			this.cameraFollowTargetId.set(null);
 			this.spriteComponentsBehind.set([]);
 			this.spriteComponentsInFront.set([]);
+			this.eventComponentResolvers.clear();
 			this.spritesheets.clear();
 			this.sounds.clear();
 			this.componentAnimations = [];