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

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.22",
   "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.1",
     "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.21",
+    "@rpgjs/server": "5.0.0-beta.22",
+    "@rpgjs/ui-css": "5.0.0-beta.21",
+    "@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);
+    }
+  }
+}

package/src/Game/EventComponentResolver.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "vitest";
+import { EventComponentResolverRegistry, normalizeEventComponent } from "./EventComponentResolver";
+
+describe("EventComponentResolverRegistry", () => {
+  test("uses the last resolver returning a custom event component", () => {
+    const registry = new EventComponentResolverRegistry();
+    const firstComponent = (() => null) as any;
+    const secondComponent = (() => null) as any;
+    const event = { id: "event-1" } as any;
+
+    registry.add(() => firstComponent);
+    registry.add(() => null);
+    registry.add(() => ({ component: secondComponent, props: { variant: "open" } }));
+
+    expect(registry.resolve(event)).toEqual({
+      component: secondComponent,
+      props: { variant: "open" }
+    });
+  });
+
+  test("returns null when no resolver matches", () => {
+    const registry = new EventComponentResolverRegistry();
+
+    registry.add(() => undefined);
+    registry.add(() => null);
+
+    expect(registry.resolve({ id: "event-1" } as any)).toBeNull();
+  });
+
+  test("can clear registered resolvers", () => {
+    const registry = new EventComponentResolverRegistry();
+    const component = (() => null) as any;
+
+    registry.add(() => component);
+    registry.clear();
+
+    expect(registry.resolve({ id: "event-1" } as any)).toBeNull();
+  });
+
+  test("always injects the real sprite prop for direct components", () => {
+    const component = (() => null) as any;
+    const sprite = { id: "event-1" } as any;
+
+    expect(normalizeEventComponent(component, sprite)).toEqual({
+      component,
+      props: { sprite },
+      dependencies: [],
+      renderGraphic: false
+    });
+  });
+
+  test("keeps custom props from replacing the sprite prop", () => {
+    const component = (() => null) as any;
+    const sprite = { id: "real-event" } as any;
+    const spoofedSprite = { id: "spoofed-event" };
+
+    const normalized = normalizeEventComponent({
+      component,
+      props: { sprite: spoofedSprite, variant: "wood" },
+      dependencies: () => ["ready"],
+      renderGraphic: true
+    }, sprite);
+
+    expect(normalized).toEqual({
+      component,
+      props: { variant: "wood", sprite },
+      dependencies: ["ready"],
+      renderGraphic: true
+    });
+  });
+
+  test("supports dynamic props", () => {
+    const component = (() => null) as any;
+    const sprite = { id: "event-1", name: "CHEST" } as any;
+
+    expect(normalizeEventComponent({
+      component,
+      props: (event) => ({ label: (event as any).name })
+    }, sprite)?.props).toEqual({
+      label: "CHEST",
+      sprite
+    });
+  });
+});

package/src/Game/EventComponentResolver.ts

@@ -0,0 +1,74 @@
+import type { EventComponentConfig, EventComponentSprite } from "../RpgClient";
+import type { RpgClientEvent } from "./Event";
+
+export type EventComponentResolver = (event: EventComponentSprite) => EventComponentConfig | null | undefined;
+
+export interface NormalizedEventComponentConfig {
+  component: any;
+  props: Record<string, any>;
+  dependencies: any[];
+  renderGraphic: boolean;
+}
+
+export class EventComponentResolverRegistry {
+  private resolvers: EventComponentResolver[] = [];
+
+  add(resolver: EventComponentResolver) {
+    this.resolvers.push(resolver);
+    return resolver;
+  }
+
+  resolve(event: RpgClientEvent): EventComponentConfig | null {
+    let resolved: EventComponentConfig | null = null;
+    this.resolvers.forEach((resolver) => {
+      const result = resolver(event as EventComponentSprite);
+      if (result !== undefined && result !== null) {
+        resolved = result;
+      }
+    });
+    return resolved;
+  }
+
+  clear() {
+    this.resolvers = [];
+  }
+}
+
+function withoutReservedSpriteProp(props: unknown): Record<string, any> {
+  if (!props || typeof props !== "object") return {};
+  const { sprite: _ignoredSprite, ...safeProps } = props as Record<string, any>;
+  return safeProps;
+}
+
+export function normalizeEventComponent(
+  componentConfig: EventComponentConfig | null | undefined,
+  sprite: RpgClientEvent
+): NormalizedEventComponentConfig | null {
+  if (!componentConfig) return null;
+
+  if (typeof componentConfig === "object" && "component" in componentConfig) {
+    const propsValue = componentConfig.props !== undefined
+      ? componentConfig.props
+      : componentConfig.data;
+    const props = typeof propsValue === "function"
+      ? propsValue(sprite as EventComponentSprite)
+      : propsValue;
+
+    return {
+      component: componentConfig.component,
+      props: {
+        ...withoutReservedSpriteProp(props),
+        sprite
+      },
+      dependencies: componentConfig.dependencies ? componentConfig.dependencies(sprite as EventComponentSprite) : [],
+      renderGraphic: componentConfig.renderGraphic === true
+    };
+  }
+
+  return {
+    component: componentConfig,
+    props: { sprite },
+    dependencies: [],
+    renderGraphic: false
+  };
+}