@rpgjs/client 5.0.0-beta.2 → 5.0.0-beta.20

package/dist/services/standalone.d.ts

@@ -9,9 +9,11 @@ interface StandaloneOptions {
 declare class BridgeWebsocket extends AbstractWebsocket {
     protected context: Context;
     private server;
+    readonly mode: "standalone";
     private room;
     private socket;
-    private pendingOn;
+    private socketRoom?;
+    private listeners;
     private rooms;
     private serverInstance;
     constructor(context: Context, server: any, options?: StandaloneOptions);
@@ -55,6 +57,7 @@ declare class BridgeWebsocket extends AbstractWebsocket {
      * ```
      */
     reconnect(listeners?: (data: any) => void): Promise<void>;
+    private detachCurrentSocket;
     getServer(): any;
     getSocket(): any;
 }

package/dist/services/standalone.js

@@ -2,8 +2,9 @@ import { AbstractWebsocket, WebSocketToken } from "./AbstractSocket.js";
 import { provideSaveClient } from "./save.js";
 import { RpgGui } from "../Gui/Gui.js";
 import { RpgClientEngine } from "../RpgClientEngine.js";
-import { ClientIo, ServerIo } from "../node_modules/.pnpm/@signe_room@2.9.0/node_modules/@signe/room/dist/index.js";
+import { ClientIo, ServerIo } from "../node_modules/.pnpm/@signe_room@3.1.0_react@19.2.7/node_modules/@signe/room/dist/index.js";
 import { provideKeyboardControls } from "./keyboardControls.js";
+import { normalizeStandaloneMessage } from "./standalone-message.js";
 import { UpdateMapService, UpdateMapToken } from "@rpgjs/common";
 //#region src/services/standalone.ts
 var BridgeWebsocket = class extends AbstractWebsocket {
@@ -11,7 +12,8 @@ var BridgeWebsocket = class extends AbstractWebsocket {
 		super(context);
 		this.context = context;
 		this.server = server;
-		this.pendingOn = [];
+		this.mode = "standalone";
+		this.listeners = [];
 		this.rooms = {
 			partyFn: async (roomId) => {
 				this.room = new ServerIo(roomId, this.rooms);
@@ -34,6 +36,7 @@ var BridgeWebsocket = class extends AbstractWebsocket {
 		return this._connection(listeners);
 	}
 	async _connection(listeners) {
+		this.detachCurrentSocket();
 		this.serverInstance = this.context.get("server");
 		this.socket = new ClientIo(this.serverInstance, "player-client-id");
 		const url = new URL("http://localhost");
@@ -42,29 +45,37 @@ var BridgeWebsocket = class extends AbstractWebsocket {
 			headers: { "Content-Type": "application/json" }
 		});
 		listeners?.(this.socket);
-		await this.serverInstance.onConnect(this.socket.conn, { request });
 		this.room.clients.set(this.socket.id, this.socket);
-		this.pendingOn.forEach(({ event, callback }) => this.socket.addEventListener(event, callback));
-		this.pendingOn = [];
+		this.socketRoom = this.room;
+		this.listeners.forEach(({ handler }) => {
+			this.socket.addEventListener("message", handler);
+		});
+		await this.serverInstance.onConnect(this.socket.conn, { request });
 		return this.socket;
 	}
 	on(key, callback) {
+		if (this.listeners.some((listener) => listener.event === key && listener.callback === callback)) return;
 		const handler = (event) => {
-			const object = JSON.parse(event);
+			const object = normalizeStandaloneMessage(event);
 			if (object.type === key) callback(object.value);
 		};
-		if (!this.socket) {
-			this.pendingOn.push({
-				event: "message",
-				callback: handler
-			});
-			return;
-		}
-		this.socket.addEventListener("message", handler);
+		this.listeners.push({
+			event: key,
+			callback,
+			handler
+		});
+		this.socket?.addEventListener("message", handler);
 	}
 	off(event, callback) {
-		if (!this.socket) return;
-		this.socket.removeEventListener(event, callback);
+		const remaining = [];
+		for (const listener of this.listeners) {
+			if (listener.event === event && listener.callback === callback) {
+				this.socket?.removeEventListener("message", listener.handler);
+				continue;
+			}
+			remaining.push(listener);
+		}
+		this.listeners = remaining;
 	}
 	emit(event, data) {
 		this.socket.send({
@@ -111,6 +122,15 @@ var BridgeWebsocket = class extends AbstractWebsocket {
 			listeners?.(socket);
 		});
 	}
+	detachCurrentSocket() {
+		if (!this.socket) return;
+		this.listeners.forEach(({ handler }) => {
+			this.socket.removeEventListener("message", handler);
+		});
+		this.socketRoom?.clients?.delete?.(this.socket.id);
+		this.socket = void 0;
+		this.socketRoom = void 0;
+	}
 	getServer() {
 		return this.serverInstance;
 	}

package/dist/services/standalone.js.map

@@ -1 +1 @@
-{"version":3,"file":"standalone.js","names":[],"sources":["../../src/services/standalone.ts"],"sourcesContent":["import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from \"./AbstractSocket\";\nimport { ClientIo, ServerIo } from \"@signe/room\";\nimport { Context } from \"@signe/di\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\nimport { UpdateMapService, UpdateMapToken } from \"@rpgjs/common\";\nimport { LoadMapToken } from \"./loadMap\";\nimport { RpgGui } from \"../Gui/Gui\";\nimport { provideKeyboardControls } from \"./keyboardControls\";\nimport { provideSaveClient } from \"./save\";\n\ntype ServerIo = any;\ntype ClientIo = any;\n\ninterface StandaloneOptions {\n  env?: Record<string, any>;\n}\n\nclass BridgeWebsocket extends AbstractWebsocket {\n  private room: ServerIo;\n  private socket: ClientIo;\n  private pendingOn: Array<{ event: string; callback: (data: any) => void }> = [];\n  private rooms = {\n    partyFn: async (roomId: string) => {\n      this.room = new ServerIo(roomId, this.rooms);\n      const server = new this.server(this.room)\n      await server.onStart();\n      await server.subRoom.onStart()\n      this.context.set('server', server)\n      return server\n    },\n    env: {}\n  }\n  private serverInstance: any;\n\n  constructor(protected context: Context, private server: any, options: StandaloneOptions = {}) {\n    super(context);\n    // fake room\n    this.rooms.env = options.env || {};\n    this.room = new ServerIo(\"lobby-1\", this.rooms);\n  }\n\n  async connection(listeners?: (data: any) => void) {\n    this.serverInstance = new this.server(this.room);\n    await this.serverInstance.onStart();\n    await this.serverInstance.subRoom.onStart()\n    this.context.set('server', this.serverInstance)\n    return this._connection(listeners)\n  }\n\n  private async _connection(listeners?: (data: any) => void) {\n    this.serverInstance = this.context.get('server')\n    this.socket = new ClientIo(this.serverInstance, 'player-client-id');\n    const url = new URL('http://localhost')\n    const request = new Request(url.toString(), {\n      method: 'GET',\n      headers: {\n        'Content-Type': 'application/json'\n      }\n    })\n    listeners?.(this.socket)\n    await this.serverInstance.onConnect(this.socket.conn as any, { request } as any);\n    this.room.clients.set(this.socket.id, this.socket);\n    this.pendingOn.forEach(({ event, callback }) => this.socket.addEventListener(event, callback));\n    this.pendingOn = [];\n    return this.socket\n  }\n\n  on(key: string, callback: (data: any) => void) {\n    const handler = (event) => {\n      const object = JSON.parse(event);\n      if (object.type === key) {\n        callback(object.value);\n      }\n    };\n    if (!this.socket) {\n      this.pendingOn.push({ event: \"message\", callback: handler });\n      return;\n    }\n    this.socket.addEventListener(\"message\", handler);\n  }\n\n  off(event: string, callback: (data: any) => void) {\n    if (!this.socket) return;\n    this.socket.removeEventListener(event, callback);\n  }\n\n  emit(event: string, data: any) {\n    this.socket.send({\n      action: event,\n      value: data,\n    });\n  }\n\n  /**\n   * Update underlying connection properties before a reconnect\n   *\n   * Design\n   * - Dynamically register a factory for the requested room to ensure a fresh server instance\n   * - Swap the internal ServerIo to target the new room\n   *\n   * @param params - Properties to update\n   * @param params.room - The target room id (e.g. `map-simplemap2`)\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-simplemap2' })\n   * await websocket.reconnect()\n   * ```\n   */\n  updateProperties(_params: SocketUpdateProperties) {\n    // empty\n  }\n\n  /**\n   * Reconnect the client to the current Party room\n   *\n   * Design\n   * - Must be called after `updateProperties()` when switching rooms\n   * - Rebuilds the client <-> server bridge and re-triggers connection listeners\n   *\n   * @param listeners - Optional callback to re-bind event handlers on the new socket\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-dungeon' })\n   * await websocket.reconnect((socket) => {\n   *   // re-bind events here\n   * })\n   * ```\n   */\n  async reconnect(listeners?: (data: any) => void): Promise<void> {\n    await this._connection((socket) => {\n      listeners?.(socket)\n    })\n  }\n\n  getServer() {\n    return this.serverInstance\n  }\n\n  getSocket() {\n    return this.socket\n  }\n}\n\nclass UpdateMapStandaloneService extends UpdateMapService {\n  private server: any;\n\n  /**\n   * Update the current room map data on the server side\n   *\n   * Design\n   * - Uses the in-memory server instance stored in context (standalone mode)\n   * - Builds a local HTTP-like request to the current Party room endpoint\n   *\n   * @param map - The map payload to apply on the server\n   *\n   * @example\n   * ```ts\n   * await updateMapService.update({ width: 1024, height: 768, events: [] })\n   * ```\n   */\n  async update(map: any) {\n    this.server = this.context.get('server')\n    const roomId = this.server?.room?.id ?? 'lobby-1'\n    const req = {\n      url: `http://localhost/parties/main/${roomId}/map/update`,\n      method: 'POST',\n      headers: new Headers({}),\n      json: async () => {\n        return map;\n      }\n    };\n    await this.server.onRequest(req)\n  }\n}\n\nexport function provideRpg(server: any, options: StandaloneOptions = {}) {\n  return [\n    {\n      provide: WebSocketToken,\n      useFactory: (context: Context) => new BridgeWebsocket(context, server, options),\n    },\n    {\n      provide: UpdateMapToken,\n      useClass: UpdateMapStandaloneService,\n    },\n    provideKeyboardControls(),\n    provideSaveClient(),\n    RpgGui,\n    RpgClientEngine,\n  ];\n}\n"],"mappings":"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"}
+{"version":3,"file":"standalone.js","names":[],"sources":["../../src/services/standalone.ts"],"sourcesContent":["import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from \"./AbstractSocket\";\nimport { ClientIo, ServerIo } from \"@signe/room\";\nimport { Context } from \"@signe/di\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\nimport { UpdateMapService, UpdateMapToken } from \"@rpgjs/common\";\nimport { LoadMapToken } from \"./loadMap\";\nimport { RpgGui } from \"../Gui/Gui\";\nimport { provideKeyboardControls } from \"./keyboardControls\";\nimport { provideSaveClient } from \"./save\";\nimport { normalizeStandaloneMessage } from \"./standalone-message\";\n\ntype ServerIo = any;\ntype ClientIo = any;\n\ninterface StandaloneOptions {\n  env?: Record<string, any>;\n}\n\nclass BridgeWebsocket extends AbstractWebsocket {\n  readonly mode = \"standalone\" as const;\n\n  private room: ServerIo;\n  private socket: ClientIo;\n  private socketRoom?: ServerIo;\n  private listeners: Array<{\n    event: string;\n    callback: (data: any) => void;\n    handler: (event: any) => void;\n  }> = [];\n  private rooms = {\n    partyFn: async (roomId: string) => {\n      this.room = new ServerIo(roomId, this.rooms);\n      const server = new this.server(this.room)\n      await server.onStart();\n      await server.subRoom.onStart()\n      this.context.set('server', server)\n      return server\n    },\n    env: {}\n  }\n  private serverInstance: any;\n\n  constructor(protected context: Context, private server: any, options: StandaloneOptions = {}) {\n    super(context);\n    // fake room\n    this.rooms.env = options.env || {};\n    this.room = new ServerIo(\"lobby-1\", this.rooms);\n  }\n\n  async connection(listeners?: (data: any) => void) {\n    this.serverInstance = new this.server(this.room);\n    await this.serverInstance.onStart();\n    await this.serverInstance.subRoom.onStart()\n    this.context.set('server', this.serverInstance)\n    return this._connection(listeners)\n  }\n\n  private async _connection(listeners?: (data: any) => void) {\n    this.detachCurrentSocket();\n    this.serverInstance = this.context.get('server')\n    this.socket = new ClientIo(this.serverInstance, 'player-client-id');\n    const url = new URL('http://localhost')\n    const request = new Request(url.toString(), {\n      method: 'GET',\n      headers: {\n        'Content-Type': 'application/json'\n      }\n    })\n    listeners?.(this.socket)\n    this.room.clients.set(this.socket.id, this.socket);\n    this.socketRoom = this.room;\n    this.listeners.forEach(({ handler }) => {\n      this.socket.addEventListener(\"message\", handler);\n    });\n    await this.serverInstance.onConnect(this.socket.conn as any, { request } as any);\n    return this.socket\n  }\n\n  on(key: string, callback: (data: any) => void) {\n    if (\n      this.listeners.some(\n        (listener) => listener.event === key && listener.callback === callback\n      )\n    ) {\n      return;\n    }\n    const handler = (event) => {\n      const object = normalizeStandaloneMessage(event);\n      if (object.type === key) {\n        callback(object.value);\n      }\n    };\n    this.listeners.push({ event: key, callback, handler });\n    this.socket?.addEventListener(\"message\", handler);\n  }\n\n  off(event: string, callback: (data: any) => void) {\n    const remaining: typeof this.listeners = [];\n    for (const listener of this.listeners) {\n      if (listener.event === event && listener.callback === callback) {\n        this.socket?.removeEventListener(\"message\", listener.handler);\n        continue;\n      }\n      remaining.push(listener);\n    }\n    this.listeners = remaining;\n  }\n\n  emit(event: string, data: any) {\n    this.socket.send({\n      action: event,\n      value: data,\n    });\n  }\n\n  /**\n   * Update underlying connection properties before a reconnect\n   *\n   * Design\n   * - Dynamically register a factory for the requested room to ensure a fresh server instance\n   * - Swap the internal ServerIo to target the new room\n   *\n   * @param params - Properties to update\n   * @param params.room - The target room id (e.g. `map-simplemap2`)\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-simplemap2' })\n   * await websocket.reconnect()\n   * ```\n   */\n  updateProperties(_params: SocketUpdateProperties) {\n    // empty\n  }\n\n  /**\n   * Reconnect the client to the current Party room\n   *\n   * Design\n   * - Must be called after `updateProperties()` when switching rooms\n   * - Rebuilds the client <-> server bridge and re-triggers connection listeners\n   *\n   * @param listeners - Optional callback to re-bind event handlers on the new socket\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-dungeon' })\n   * await websocket.reconnect((socket) => {\n   *   // re-bind events here\n   * })\n   * ```\n   */\n  async reconnect(listeners?: (data: any) => void): Promise<void> {\n    await this._connection((socket) => {\n      listeners?.(socket)\n    })\n  }\n\n  private detachCurrentSocket() {\n    if (!this.socket) return;\n    this.listeners.forEach(({ handler }) => {\n      this.socket.removeEventListener(\"message\", handler);\n    });\n    this.socketRoom?.clients?.delete?.(this.socket.id);\n    this.socket = undefined as any;\n    this.socketRoom = undefined;\n  }\n\n  getServer() {\n    return this.serverInstance\n  }\n\n  getSocket() {\n    return this.socket\n  }\n}\n\nclass UpdateMapStandaloneService extends UpdateMapService {\n  private server: any;\n\n  /**\n   * Update the current room map data on the server side\n   *\n   * Design\n   * - Uses the in-memory server instance stored in context (standalone mode)\n   * - Builds a local HTTP-like request to the current Party room endpoint\n   *\n   * @param map - The map payload to apply on the server\n   *\n   * @example\n   * ```ts\n   * await updateMapService.update({ width: 1024, height: 768, events: [] })\n   * ```\n   */\n  async update(map: any) {\n    this.server = this.context.get('server')\n    const roomId = this.server?.room?.id ?? 'lobby-1'\n    const req = {\n      url: `http://localhost/parties/main/${roomId}/map/update`,\n      method: 'POST',\n      headers: new Headers({}),\n      json: async () => {\n        return map;\n      }\n    };\n    await this.server.onRequest(req)\n  }\n}\n\nexport function provideRpg(server: any, options: StandaloneOptions = {}) {\n  return [\n    {\n      provide: WebSocketToken,\n      useFactory: (context: Context) => new BridgeWebsocket(context, server, options),\n    },\n    {\n      provide: UpdateMapToken,\n      useClass: UpdateMapStandaloneService,\n    },\n    provideKeyboardControls(),\n    provideSaveClient(),\n    RpgGui,\n    RpgClientEngine,\n  ];\n}\n"],"mappings":"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"}

package/dist/services/standalone.spec.d.ts

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

package/dist/utils/getEntityProp.js

@@ -1,3 +1,4 @@
+import { readPropValue } from "./readPropValue.js";
 import { computed } from "canvasengine";
 //#region src/utils/getEntityProp.ts
 var entityPropMap = {
@@ -6,17 +7,17 @@ var entityPropMap = {
 	gold: (entity) => entity._gold(),
 	hp: (entity) => entity.hpSignal(),
 	sp: (entity) => entity.spSignal(),
-	name: (entity) => entity.name(),
+	name: (entity) => entity.name,
 	type: (entity) => entity.type(),
 	x: (entity) => entity.x(),
 	y: (entity) => entity.y(),
 	z: (entity) => entity.z(),
 	tint: (entity) => entity.tint(),
 	direction: (entity) => entity.direction(),
-	speed: (entity) => entity.speed(),
+	speed: (entity) => entity.speed,
 	hitbox: (entity) => entity.hitbox(),
 	animation: (entity) => entity.animationName(),
-	canMove: (entity) => entity.canMove(),
+	canMove: (entity) => readPropValue(entity._canMove ?? entity.canMove),
 	graphics: (entity) => entity.graphics(),
 	items: (entity) => entity.items(),
 	equipments: (entity) => entity.equipments(),

package/dist/utils/getEntityProp.js.map

@@ -1 +1 @@
-{"version":3,"file":"getEntityProp.js","names":[],"sources":["../../src/utils/getEntityProp.ts"],"sourcesContent":["import { computed, Signal } from \"canvasengine\";\nimport { RpgClientObject } from \"../Game/Object\";\n\nconst BUILTIN_PARAM_KEYS = [\n  \"maxHp\",\n  \"maxSp\",\n  \"atk\",\n  \"pdef\",\n  \"sdef\",\n  \"str\",\n  \"agi\",\n  \"int\",\n  \"dex\",\n] as const;\n\ntype BuiltInParamKey = typeof BUILTIN_PARAM_KEYS[number];\ntype ParamPropKey = `params.${BuiltInParamKey}` | `params.${string}`;\n\nconst entityPropMap = {\n  level: (entity: RpgClientObject) => entity._level(),\n  exp: (entity: RpgClientObject) => entity._exp(),\n  gold: (entity: RpgClientObject) => entity._gold(),\n  hp: (entity: RpgClientObject) => entity.hpSignal(),\n  sp: (entity: RpgClientObject) => entity.spSignal(),\n  name: (entity: RpgClientObject) => entity.name(),\n  type: (entity: RpgClientObject) => entity.type(),\n  x: (entity: RpgClientObject) => entity.x(),\n  y: (entity: RpgClientObject) => entity.y(),\n  z: (entity: RpgClientObject) => entity.z(),\n  tint: (entity: RpgClientObject) => entity.tint(),\n  direction: (entity: RpgClientObject) => entity.direction(),\n  speed: (entity: RpgClientObject) => entity.speed(),\n  hitbox: (entity: RpgClientObject) => entity.hitbox(),\n  animation: (entity: RpgClientObject) => entity.animationName(),\n  canMove: (entity: RpgClientObject) => entity.canMove(),\n  graphics: (entity: RpgClientObject) => entity.graphics(),\n  items: (entity: RpgClientObject) => entity.items(),\n  equipments: (entity: RpgClientObject) => entity.equipments(),\n  states: (entity: RpgClientObject) => entity.states(),\n  skills: (entity: RpgClientObject) => entity.skills(),\n  effects: (entity: RpgClientObject) => entity._effects(),\n  componentsTop: (entity: RpgClientObject) => entity.componentsTop(),\n  componentsBottom: (entity: RpgClientObject) => entity.componentsBottom(),\n  componentsCenter: (entity: RpgClientObject) => entity.componentsCenter(),\n  componentsLeft: (entity: RpgClientObject) => entity.componentsLeft(),\n  componentsRight: (entity: RpgClientObject) => entity.componentsRight(),\n} as const;\n\ntype EntityPropMap = typeof entityPropMap;\ntype EntityPropKey = keyof EntityPropMap | ParamPropKey;\ntype EntityPropValue<K extends EntityPropKey> = K extends keyof EntityPropMap\n  ? ReturnType<EntityPropMap[K]>\n  : K extends `params.${string}`\n  ? number | undefined\n  : never;\n\nconst isSignal = <T>(value: unknown): value is Signal<T> =>\n  typeof value === \"function\";\n\nconst toSignal = <T>(value: Signal<T> | T): Signal<T> =>\n  isSignal<T>(value) ? value : computed(() => value);\n\nexport const getEntityProp = <K extends EntityPropKey>(\n  entity: Signal<RpgClientObject | undefined> | RpgClientObject | undefined,\n  key: K\n): Signal<EntityPropValue<K>> => {\n  const entitySignal = toSignal(entity);\n\n  return computed(() => {\n    const current = entitySignal();\n    if (!current) {\n      return undefined as EntityPropValue<K>;\n    }\n\n    if (Object.prototype.hasOwnProperty.call(entityPropMap, key)) {\n      const getter = entityPropMap[key as keyof EntityPropMap];\n      return getter(current) as EntityPropValue<K>;\n    }\n\n    if (key.startsWith(\"params.\")) {\n      const paramKey = key.slice(\"params.\".length);\n      return current._param?.()?.[paramKey] as EntityPropValue<K>;\n    }\n\n    return undefined as EntityPropValue<K>;\n  });\n};\n"],"mappings":";;AAkBA,IAAM,gBAAgB;CACpB,QAAQ,WAA4B,OAAO,QAAQ;CACnD,MAAM,WAA4B,OAAO,MAAM;CAC/C,OAAO,WAA4B,OAAO,OAAO;CACjD,KAAK,WAA4B,OAAO,UAAU;CAClD,KAAK,WAA4B,OAAO,UAAU;CAClD,OAAO,WAA4B,OAAO,MAAM;CAChD,OAAO,WAA4B,OAAO,MAAM;CAChD,IAAI,WAA4B,OAAO,GAAG;CAC1C,IAAI,WAA4B,OAAO,GAAG;CAC1C,IAAI,WAA4B,OAAO,GAAG;CAC1C,OAAO,WAA4B,OAAO,MAAM;CAChD,YAAY,WAA4B,OAAO,WAAW;CAC1D,QAAQ,WAA4B,OAAO,OAAO;CAClD,SAAS,WAA4B,OAAO,QAAQ;CACpD,YAAY,WAA4B,OAAO,eAAe;CAC9D,UAAU,WAA4B,OAAO,SAAS;CACtD,WAAW,WAA4B,OAAO,UAAU;CACxD,QAAQ,WAA4B,OAAO,OAAO;CAClD,aAAa,WAA4B,OAAO,YAAY;CAC5D,SAAS,WAA4B,OAAO,QAAQ;CACpD,SAAS,WAA4B,OAAO,QAAQ;CACpD,UAAU,WAA4B,OAAO,UAAU;CACvD,gBAAgB,WAA4B,OAAO,eAAe;CAClE,mBAAmB,WAA4B,OAAO,kBAAkB;CACxE,mBAAmB,WAA4B,OAAO,kBAAkB;CACxE,iBAAiB,WAA4B,OAAO,gBAAgB;CACpE,kBAAkB,WAA4B,OAAO,iBAAiB;CACvE;AAUD,IAAM,YAAe,UACnB,OAAO,UAAU;AAEnB,IAAM,YAAe,UACnB,SAAY,MAAM,GAAG,QAAQ,eAAe,MAAM;AAEpD,IAAa,iBACX,QACA,QAC+B;CAC/B,MAAM,eAAe,SAAS,OAAO;AAErC,QAAO,eAAe;EACpB,MAAM,UAAU,cAAc;AAC9B,MAAI,CAAC,QACH;AAGF,MAAI,OAAO,UAAU,eAAe,KAAK,eAAe,IAAI,EAAE;GAC5D,MAAM,SAAS,cAAc;AAC7B,UAAO,OAAO,QAAQ;;AAGxB,MAAI,IAAI,WAAW,UAAU,EAAE;GAC7B,MAAM,WAAW,IAAI,MAAM,EAAiB;AAC5C,UAAO,QAAQ,UAAU,GAAG;;GAI9B"}
+{"version":3,"file":"getEntityProp.js","names":[],"sources":["../../src/utils/getEntityProp.ts"],"sourcesContent":["import { computed, Signal } from \"canvasengine\";\nimport { RpgClientObject } from \"../Game/Object\";\nimport { readPropValue } from \"./readPropValue\";\n\nconst BUILTIN_PARAM_KEYS = [\n  \"maxHp\",\n  \"maxSp\",\n  \"atk\",\n  \"pdef\",\n  \"sdef\",\n  \"str\",\n  \"agi\",\n  \"int\",\n  \"dex\",\n] as const;\n\ntype BuiltInParamKey = typeof BUILTIN_PARAM_KEYS[number];\ntype ParamPropKey = `params.${BuiltInParamKey}` | `params.${string}`;\n\nconst entityPropMap = {\n  level: (entity: RpgClientObject) => entity._level(),\n  exp: (entity: RpgClientObject) => entity._exp(),\n  gold: (entity: RpgClientObject) => entity._gold(),\n  hp: (entity: RpgClientObject) => entity.hpSignal(),\n  sp: (entity: RpgClientObject) => entity.spSignal(),\n  name: (entity: RpgClientObject) => entity.name,\n  type: (entity: RpgClientObject) => entity.type(),\n  x: (entity: RpgClientObject) => entity.x(),\n  y: (entity: RpgClientObject) => entity.y(),\n  z: (entity: RpgClientObject) => entity.z(),\n  tint: (entity: RpgClientObject) => entity.tint(),\n  direction: (entity: RpgClientObject) => entity.direction(),\n  speed: (entity: RpgClientObject) => entity.speed,\n  hitbox: (entity: RpgClientObject) => entity.hitbox(),\n  animation: (entity: RpgClientObject) => entity.animationName(),\n  canMove: (entity: RpgClientObject) => readPropValue<boolean>((entity as any)._canMove ?? entity.canMove),\n  graphics: (entity: RpgClientObject) => entity.graphics(),\n  items: (entity: RpgClientObject) => entity.items(),\n  equipments: (entity: RpgClientObject) => entity.equipments(),\n  states: (entity: RpgClientObject) => entity.states(),\n  skills: (entity: RpgClientObject) => entity.skills(),\n  effects: (entity: RpgClientObject) => entity._effects(),\n  componentsTop: (entity: RpgClientObject) => entity.componentsTop(),\n  componentsBottom: (entity: RpgClientObject) => entity.componentsBottom(),\n  componentsCenter: (entity: RpgClientObject) => entity.componentsCenter(),\n  componentsLeft: (entity: RpgClientObject) => entity.componentsLeft(),\n  componentsRight: (entity: RpgClientObject) => entity.componentsRight(),\n} as const;\n\ntype EntityPropMap = typeof entityPropMap;\ntype EntityPropKey = keyof EntityPropMap | ParamPropKey;\ntype EntityPropValue<K extends EntityPropKey> = K extends keyof EntityPropMap\n  ? ReturnType<EntityPropMap[K]>\n  : K extends `params.${string}`\n  ? number | undefined\n  : never;\n\nconst isSignal = <T>(value: unknown): value is Signal<T> =>\n  typeof value === \"function\";\n\nconst toSignal = <T>(value: Signal<T> | T): Signal<T> =>\n  isSignal<T>(value) ? value : computed(() => value);\n\nexport const getEntityProp = <K extends EntityPropKey>(\n  entity: Signal<RpgClientObject | undefined> | RpgClientObject | undefined,\n  key: K\n): Signal<EntityPropValue<K>> => {\n  const entitySignal = toSignal(entity);\n\n  return computed(() => {\n    const current = entitySignal();\n    if (!current) {\n      return undefined as EntityPropValue<K>;\n    }\n\n    if (Object.prototype.hasOwnProperty.call(entityPropMap, key)) {\n      const getter = entityPropMap[key as keyof EntityPropMap];\n      return getter(current) as EntityPropValue<K>;\n    }\n\n    if (key.startsWith(\"params.\")) {\n      const paramKey = key.slice(\"params.\".length);\n      return current._param?.()?.[paramKey] as EntityPropValue<K>;\n    }\n\n    return undefined as EntityPropValue<K>;\n  });\n};\n"],"mappings":";;;AAmBA,IAAM,gBAAgB;CACpB,QAAQ,WAA4B,OAAO,OAAO;CAClD,MAAM,WAA4B,OAAO,KAAK;CAC9C,OAAO,WAA4B,OAAO,MAAM;CAChD,KAAK,WAA4B,OAAO,SAAS;CACjD,KAAK,WAA4B,OAAO,SAAS;CACjD,OAAO,WAA4B,OAAO;CAC1C,OAAO,WAA4B,OAAO,KAAK;CAC/C,IAAI,WAA4B,OAAO,EAAE;CACzC,IAAI,WAA4B,OAAO,EAAE;CACzC,IAAI,WAA4B,OAAO,EAAE;CACzC,OAAO,WAA4B,OAAO,KAAK;CAC/C,YAAY,WAA4B,OAAO,UAAU;CACzD,QAAQ,WAA4B,OAAO;CAC3C,SAAS,WAA4B,OAAO,OAAO;CACnD,YAAY,WAA4B,OAAO,cAAc;CAC7D,UAAU,WAA4B,cAAwB,OAAe,YAAY,OAAO,OAAO;CACvG,WAAW,WAA4B,OAAO,SAAS;CACvD,QAAQ,WAA4B,OAAO,MAAM;CACjD,aAAa,WAA4B,OAAO,WAAW;CAC3D,SAAS,WAA4B,OAAO,OAAO;CACnD,SAAS,WAA4B,OAAO,OAAO;CACnD,UAAU,WAA4B,OAAO,SAAS;CACtD,gBAAgB,WAA4B,OAAO,cAAc;CACjE,mBAAmB,WAA4B,OAAO,iBAAiB;CACvE,mBAAmB,WAA4B,OAAO,iBAAiB;CACvE,iBAAiB,WAA4B,OAAO,eAAe;CACnE,kBAAkB,WAA4B,OAAO,gBAAgB;AACvE;AAUA,IAAM,YAAe,UACnB,OAAO,UAAU;AAEnB,IAAM,YAAe,UACnB,SAAY,KAAK,IAAI,QAAQ,eAAe,KAAK;AAEnD,IAAa,iBACX,QACA,QAC+B;CAC/B,MAAM,eAAe,SAAS,MAAM;CAEpC,OAAO,eAAe;EACpB,MAAM,UAAU,aAAa;EAC7B,IAAI,CAAC,SACH;EAGF,IAAI,OAAO,UAAU,eAAe,KAAK,eAAe,GAAG,GAAG;GAC5D,MAAM,SAAS,cAAc;GAC7B,OAAO,OAAO,OAAO;EACvB;EAEA,IAAI,IAAI,WAAW,SAAS,GAAG;GAC7B,MAAM,WAAW,IAAI,MAAM,CAAgB;GAC3C,OAAO,QAAQ,SAAS,IAAI;EAC9B;CAGF,CAAC;AACH"}

package/dist/utils/getEntityProp.spec.d.ts

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

package/dist/utils/mapId.d.ts

@@ -0,0 +1 @@
+export declare const normalizeRoomMapId: (mapId: string | undefined) => string | undefined;

package/dist/utils/mapId.js

@@ -0,0 +1,6 @@
+//#region src/utils/mapId.ts
+var normalizeRoomMapId = (mapId) => typeof mapId === "string" ? mapId.replace(/^map-/, "") : void 0;
+//#endregion
+export { normalizeRoomMapId };
+
+//# sourceMappingURL=mapId.js.map

package/dist/utils/mapId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapId.js","names":[],"sources":["../../src/utils/mapId.ts"],"sourcesContent":["export const normalizeRoomMapId = (mapId: string | undefined): string | undefined =>\n  typeof mapId === \"string\" ? mapId.replace(/^map-/, \"\") : undefined;\n"],"mappings":";AAAA,IAAa,sBAAsB,UACjC,OAAO,UAAU,WAAW,MAAM,QAAQ,SAAS,EAAE,IAAI,KAAA"}

package/dist/utils/readPropValue.d.ts

@@ -0,0 +1,2 @@
+export declare const readPropValue: <T = unknown>(value: unknown) => T;
+export declare const getCanMoveValue: (entity: any) => boolean;

package/dist/utils/readPropValue.js

@@ -0,0 +1,13 @@
+//#region src/utils/readPropValue.ts
+var readPropValue = (value) => {
+	if (typeof value === "function") return readPropValue(value());
+	if (value && typeof value === "object" && "value" in value) return readPropValue(value.value);
+	return value;
+};
+var getCanMoveValue = (entity) => {
+	return readPropValue(entity?._canMove ?? entity?.canMove) !== false;
+};
+//#endregion
+export { getCanMoveValue, readPropValue };
+
+//# sourceMappingURL=readPropValue.js.map

package/dist/utils/readPropValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readPropValue.js","names":[],"sources":["../../src/utils/readPropValue.ts"],"sourcesContent":["export const readPropValue = <T = unknown>(value: unknown): T => {\n  if (typeof value === \"function\") {\n    return readPropValue((value as () => unknown)());\n  }\n\n  if (value && typeof value === \"object\" && \"value\" in value) {\n    return readPropValue((value as { value: unknown }).value);\n  }\n\n  return value as T;\n};\n\nexport const getCanMoveValue = (entity: any): boolean => {\n  const value = readPropValue(entity?._canMove ?? entity?.canMove);\n  return value !== false;\n};\n"],"mappings":";AAAA,IAAa,iBAA8B,UAAsB;CAC/D,IAAI,OAAO,UAAU,YACnB,OAAO,cAAe,MAAwB,CAAC;CAGjD,IAAI,SAAS,OAAO,UAAU,YAAY,WAAW,OACnD,OAAO,cAAe,MAA6B,KAAK;CAG1D,OAAO;AACT;AAEA,IAAa,mBAAmB,WAAyB;CAEvD,OADc,cAAc,QAAQ,YAAY,QAAQ,OACjD,MAAU;AACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/client",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.20",
   "description": "RPGJS is a framework for creating RPG/MMORPG games",
   "main": "dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,25 +17,25 @@
   "author": "Samuel Ronce",
   "license": "MIT",
   "peerDependencies": {
-    "@canvasengine/presets": "*",
-    "canvasengine": "*",
+    "@canvasengine/presets": "^2.0.0",
+    "canvasengine": "^2.0.0",
     "pixi.js": "^8.9.2"
   },
   "dependencies": {
-    "@rpgjs/common": "5.0.0-beta.2",
-    "@rpgjs/server": "5.0.0-beta.2",
-    "@rpgjs/ui-css": "5.0.0-beta.2",
-    "@signe/di": "^2.9.0",
-    "@signe/room": "^2.9.0",
-    "@signe/sync": "^2.9.0",
+    "@rpgjs/common": "5.0.0-beta.20",
+    "@rpgjs/server": "5.0.0-beta.20",
+    "@rpgjs/ui-css": "5.0.0-beta.20",
+    "@signe/di": "3.1.0",
+    "@signe/room": "3.1.0",
+    "@signe/sync": "3.1.0",
     "pixi-filters": "^6.1.5",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@canvasengine/compiler": "2.0.0-beta.56",
-    "vite": "^8.0.3",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.2"
+    "@canvasengine/compiler": "2.0.0",
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.2",
+    "vitest": "^4.1.9"
   },
   "type": "module",
   "scripts": {

package/src/Game/AnimationManager.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test, vi } from "vitest";
+import { AnimationManager } from "./AnimationManager";
+
+describe("AnimationManager", () => {
+  test("resolves displayEffect when the component calls onFinish", async () => {
+    const manager = new AnimationManager();
+    const done = manager.displayEffect({}, { x: 10, y: 20 });
+
+    expect(manager.current()).toHaveLength(1);
+    manager.current()[0].onFinish();
+
+    await expect(done).resolves.toBeUndefined();
+    expect(manager.current()).toHaveLength(0);
+  });
+
+  test("keeps onFinish idempotent and forwards user callback data", async () => {
+    const manager = new AnimationManager();
+    const onFinish = vi.fn();
+    const done = manager.displayEffect({ onFinish }, { x: 10, y: 20 });
+    const finish = manager.current()[0].onFinish;
+
+    finish({ ok: true });
+    finish({ ok: false });
+
+    await done;
+    expect(onFinish).toHaveBeenCalledTimes(1);
+    expect(onFinish).toHaveBeenCalledWith({ ok: true });
+    expect(manager.current()).toHaveLength(0);
+  });
+});

package/src/Game/AnimationManager.ts

@@ -4,18 +4,34 @@ import { signal } from "canvasengine";
 export class AnimationManager {
   current = signal<any[]>([]);
 
-  displayEffect(params: any, player: RpgCommonPlayer | { x: number, y: number }) {
+  clear(): void {
+    this.current.set([]);
+  }
+
+  displayEffect(params: any, player: RpgCommonPlayer | { x: number, y: number }): Promise<void> {
     const id = generateUID();
-    this.current().push({
-      ...params,
-      id,
-      x: player.x,
-      y: player.y,
-      object: player,
-      onFinish: () => {
+    const effectParams = params ?? {};
+    return new Promise<void>((resolve) => {
+      let finished = false;
+      const finish = (data?: any) => {
+        if (finished) return;
+        finished = true;
         const index = this.current().findIndex((value) => value.id === id);
-        this.current().splice(index, 1);
-      },
+        if (index !== -1) {
+          this.current().splice(index, 1);
+        }
+        effectParams.onFinish?.(data);
+        resolve();
+      };
+
+      this.current().push({
+        ...effectParams,
+        id,
+        x: player.x,
+        y: player.y,
+        object: player,
+        onFinish: finish,
+      });
     });
   }
 }

package/src/Game/ClientVisuals.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test, vi } from "vitest";
+import { ClientVisualRegistry } from "./ClientVisuals";
+
+describe("ClientVisualRegistry", () => {
+  test("plays registered visual handlers with resolved objects and helpers", async () => {
+    const target = {
+      flash: vi.fn(),
+      showHit: vi.fn(),
+      setAnimation: vi.fn(),
+    };
+    const componentAnimation = {
+      displayEffect: vi.fn(),
+    };
+    const engine = {
+      scene: {},
+      getObjectById: vi.fn(() => target),
+      getComponentAnimation: vi.fn(() => componentAnimation),
+      playSound: vi.fn().mockResolvedValue(undefined),
+      mapShakeTrigger: {
+        start: vi.fn(),
+      },
+    } as any;
+    const registry = new ClientVisualRegistry();
+
+    registry.register("hit", ({ target, data }, helpers) => {
+      helpers.flash(target, { type: "tint", tint: "red" });
+      helpers.showHit(target, `-${data.damage}`);
+      helpers.component("hit-spark", target, { scale: 2 });
+      helpers.sound("hit");
+      helpers.animation(target, "hurt");
+      helpers.shake({ intensity: 2 });
+    });
+
+    await registry.play(
+      {
+        name: "hit",
+        data: {
+          targetId: "enemy-1",
+          damage: 12,
+        },
+      },
+      engine
+    );
+
+    expect(engine.getObjectById).toHaveBeenCalledWith("enemy-1");
+    expect(target.flash).toHaveBeenCalledWith({ type: "tint", tint: "red" });
+    expect(target.showHit).toHaveBeenCalledWith("-12");
+    expect(componentAnimation.displayEffect).toHaveBeenCalledWith(
+      { scale: 2 },
+      target
+    );
+    expect(engine.playSound).toHaveBeenCalledWith("hit", undefined);
+    expect(target.setAnimation).toHaveBeenCalledWith("hurt", 1);
+    expect(engine.mapShakeTrigger.start).toHaveBeenCalledWith({ intensity: 2 });
+  });
+});

package/src/Game/ClientVisuals.ts

@@ -0,0 +1,184 @@
+import type { RpgClientEngine } from "../RpgClientEngine";
+import type { RpgClientMap } from "./Map";
+
+export type ClientVisualPosition = {
+  x: number;
+  y: number;
+  z?: number;
+};
+
+export type ClientVisualPayload = Record<string, any> & {
+  source?: string;
+  sourceId?: string;
+  target?: string;
+  targetId?: string;
+  object?: string;
+  objectId?: string;
+  position?: ClientVisualPosition;
+};
+
+export type ClientVisualPacket = {
+  name: string;
+  data?: ClientVisualPayload;
+};
+
+export type ClientVisualObjectTarget = string | Record<string, any> | undefined | null;
+export type ClientVisualComponentTarget =
+  | ClientVisualObjectTarget
+  | ClientVisualPosition;
+
+export type ClientVisualContext = {
+  name: string;
+  data: ClientVisualPayload;
+  engine: RpgClientEngine;
+  scene: RpgClientMap;
+  source?: any;
+  target?: any;
+  object?: any;
+  position?: ClientVisualPosition;
+};
+
+export type ClientVisualHelpers = {
+  getObject(id?: string | null): any;
+  flash(target?: ClientVisualObjectTarget, options?: Record<string, any>): void;
+  showHit(target: ClientVisualObjectTarget, text: string): void;
+  component(
+    id: string,
+    target?: ClientVisualComponentTarget,
+    params?: Record<string, any>
+  ): void;
+  sound(id: string, options?: { volume?: number; loop?: boolean }): Promise<void>;
+  animation(
+    target: ClientVisualObjectTarget,
+    animationName: string,
+    options?: { graphic?: string | string[]; repeat?: number }
+  ): void;
+  shake(options?: {
+    intensity?: number;
+    duration?: number;
+    frequency?: number;
+    direction?: string;
+  }): void;
+};
+
+export type ClientVisualHandler = (
+  context: ClientVisualContext,
+  helpers: ClientVisualHelpers
+) => void | Promise<void>;
+
+export type ClientVisualMap = Record<string, ClientVisualHandler>;
+
+const isPosition = (value: any): value is ClientVisualPosition =>
+  value &&
+  typeof value === "object" &&
+  typeof value.x === "number" &&
+  typeof value.y === "number";
+
+const resolvePosition = (data: ClientVisualPayload): ClientVisualPosition | undefined => {
+  if (isPosition(data.position)) return data.position;
+  if (typeof data.x === "number" && typeof data.y === "number") {
+    return { x: data.x, y: data.y, z: data.z };
+  }
+  return undefined;
+};
+
+const resolveObject = (engine: RpgClientEngine, target: ClientVisualObjectTarget) => {
+  if (!target) return undefined;
+  if (typeof target === "string") return engine.getObjectById(target);
+  return target;
+};
+
+const resolvePayloadObject = (
+  engine: RpgClientEngine,
+  data: ClientVisualPayload,
+  keys: string[]
+) => {
+  const id = keys
+    .map((key) => data[key])
+    .find((value) => typeof value === "string");
+  return resolveObject(engine, id);
+};
+
+const createClientVisualHelpers = (
+  engine: RpgClientEngine
+): ClientVisualHelpers => ({
+  getObject(id) {
+    if (!id) return undefined;
+    return engine.getObjectById(id);
+  },
+  flash(target, options = {}) {
+    const object = resolveObject(engine, target);
+    object?.flash?.(options);
+  },
+  showHit(target, text) {
+    const object = resolveObject(engine, target);
+    object?.showHit?.(text);
+  },
+  component(id, target, params = {}) {
+    const object = isPosition(target) ? undefined : resolveObject(engine, target);
+    const position = isPosition(target) ? target : undefined;
+    const anchor = object ?? position;
+    if (!anchor) return;
+    engine.getComponentAnimation(id).displayEffect(params, anchor);
+  },
+  sound(id, options) {
+    return engine.playSound(id, options);
+  },
+  animation(target, animationName, options = {}) {
+    const object = resolveObject(engine, target);
+    if (!object?.setAnimation) return;
+    if (options.graphic !== undefined) {
+      object.setAnimation(animationName, options.graphic, options.repeat ?? 1);
+      return;
+    }
+    object.setAnimation(animationName, options.repeat ?? 1);
+  },
+  shake(options = {}) {
+    engine.mapShakeTrigger.start(options);
+  },
+});
+
+export class ClientVisualRegistry {
+  private readonly handlers = new Map<string, ClientVisualHandler>();
+
+  register(name: string, handler: ClientVisualHandler) {
+    this.handlers.set(name, handler);
+    return handler;
+  }
+
+  registerMany(visuals: ClientVisualMap) {
+    Object.entries(visuals).forEach(([name, handler]) => {
+      this.register(name, handler);
+    });
+  }
+
+  get(name: string) {
+    return this.handlers.get(name);
+  }
+
+  async play(packet: ClientVisualPacket, engine: RpgClientEngine) {
+    const handler = this.handlers.get(packet.name);
+    if (!handler) {
+      console.warn(`Client visual "${packet.name}" is not registered`);
+      return;
+    }
+
+    const data = packet.data ?? {};
+    const context: ClientVisualContext = {
+      name: packet.name,
+      data,
+      engine,
+      scene: engine.scene,
+      source: resolvePayloadObject(engine, data, ["sourceId", "source"]),
+      target: resolvePayloadObject(engine, data, ["targetId", "target"]),
+      object: resolvePayloadObject(engine, data, ["objectId", "object"]),
+      position: resolvePosition(data),
+    };
+
+    try {
+      await handler(context, createClientVisualHelpers(engine));
+    } catch (error) {
+      console.error(`Client visual "${packet.name}" failed`, error);
+    }
+  }
+}