@rpgjs/client 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/Game/Object.ts

@@ -1,16 +1,411 @@
-import { RpgCommonPlayer } from "@rpgjs/common";
-import { trigger, signal } from "canvasengine";
+import { Hooks, ModulesToken, RpgCommonPlayer } from "@rpgjs/common";
+import { trigger, signal, type Trigger } from "canvasengine";
+import { from, map, of, Subscription, switchMap } from "rxjs";
+import { inject } from "../core/inject";
+import { RpgClientEngine } from "../RpgClientEngine";
+type Frame = { x: number; y: number; ts: number };
+
+type AnimationRestoreOptions = {
+  restoreAnimationName?: string;
+  restoreGraphics?: any[];
+  timeoutMs?: number;
+};
+
+type FlashType = 'alpha' | 'tint' | 'both';
+
+type FlashOptions = {
+  type?: FlashType;
+  duration?: number;
+  cycles?: number;
+  alpha?: number;
+  tint?: number | string;
+};
+
+type FlashTriggerOptions = Omit<FlashOptions, "tint"> & {
+  tint: number;
+};
+
+type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
+  start(config?: T): Promise<void>;
+};
 
 export abstract class RpgClientObject extends RpgCommonPlayer {
-  abstract type: string;
-  emitParticleTrigger = trigger()
-  particleName = signal('')
-
-  flash(color: string, duration: number = 100) {
-    const lastTint = this.tint()
-    this.tint.set(color);
-    setTimeout(() => {
-      this.tint.set(lastTint)
-    }, duration)
-  }
-}   
+  abstract _type: string;
+  emitParticleTrigger = trigger();
+  particleName = signal("");
+  animationCurrentIndex = signal(0);
+  animationIsPlaying = signal(false);
+  _param = signal({});
+  frames: Frame[] = [];
+  graphicsSignals = signal<any[]>([]);
+  flashTrigger: ConfigurableTrigger<FlashTriggerOptions> = trigger<FlashTriggerOptions>();
+  private animationRestoreState?: {
+    animationName: string;
+    graphics: any[];
+  };
+
+  constructor() {
+    super();
+    this.hooks.callHooks("client-sprite-onInit", this).subscribe();
+
+    this._frames.observable.subscribe(({ items }) => {
+      if (!this.id) return;
+      //if (this.id == this.engine.playerIdSignal()!) return;
+      const nextFrames = items.flatMap((item): Frame[] =>
+        Array.isArray(item) ? item : [item]
+      );
+      this.frames = [...this.frames, ...nextFrames];
+    });
+
+    this.graphics.observable
+    .pipe(
+      map(({ items }) => items),
+      switchMap(graphics => {
+        if (graphics.length === 0) return of([]);
+        return from(Promise.all(graphics.map(graphic => this.engine.getSpriteSheet(graphic))));
+      })
+    )
+    .subscribe((sheets) => {  
+      this.graphicsSignals.set(sheets);
+    });
+
+    this.engine.tick
+      .pipe
+      //throttleTime(10)
+      ()
+      .subscribe(() => {
+        const frame = this.frames.shift();
+        if (frame) {
+          if (typeof frame.x !== "number" || typeof frame.y !== "number") return;
+          this.engine.scene.setBodyPosition(
+            this.id,
+            frame.x,
+            frame.y,
+            "top-left"
+          );
+        }
+      });
+  }
+
+  /**
+   * Access the shared client hook registry.
+   *
+   * @returns The hook service used to register and trigger client-side hooks.
+   */
+  get hooks() {
+    return inject<Hooks>(ModulesToken);
+  }
+
+  /**
+   * Access the current client engine instance.
+   *
+   * @returns The active {@link RpgClientEngine} instance.
+   */
+  get engine() {
+    return inject(RpgClientEngine);
+  }
+
+  private animationSubscription?: Subscription;
+  private animationResetTimeout?: ReturnType<typeof setTimeout>;
+  private animationWaitResolve?: () => void;
+
+  private clearAnimationControls() {
+    if (this.animationSubscription) {
+      this.animationSubscription.unsubscribe();
+      this.animationSubscription = undefined;
+    }
+    if (this.animationResetTimeout) {
+      clearTimeout(this.animationResetTimeout);
+      this.animationResetTimeout = undefined;
+    }
+  }
+
+  private resolveAnimationWait() {
+    const resolve = this.animationWaitResolve;
+    this.animationWaitResolve = undefined;
+    resolve?.();
+  }
+
+  private finishTemporaryAnimation() {
+    const restoreState = this.animationRestoreState;
+    this.clearAnimationControls();
+    this.animationCurrentIndex.set(0);
+    if (restoreState) {
+      this.animationName.set(restoreState.animationName);
+      this.graphics.set([...restoreState.graphics]);
+    }
+    this.animationRestoreState = undefined;
+    this.animationIsPlaying.set(false);
+    this.resolveAnimationWait();
+  }
+
+  /**
+   * Trigger a flash animation on this sprite
+   * 
+   * This method triggers a flash effect using CanvasEngine's flash directive.
+   * The flash can be configured with various options including type (alpha, tint, or both),
+   * duration, cycles, and color.
+   * 
+   * ## Design
+   * 
+   * The flash uses a trigger system that is connected to the flash directive in the
+   * character component. This allows for flexible configuration and can be triggered
+   * from both server events and client-side code.
+   * 
+   * @param options - Flash configuration options
+   * @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')
+   * @param options.duration - Duration of the flash animation in milliseconds (default: 300)
+   * @param options.cycles - Number of flash cycles (flash on/off) (default: 1)
+   * @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)
+   * @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)
+   * 
+   * @example
+   * ```ts
+   * // Simple flash with default settings (alpha flash)
+   * player.flash();
+   * 
+   * // Flash with red tint
+   * player.flash({ type: 'tint', tint: 0xff0000 });
+   * 
+   * // Flash with both alpha and tint
+   * player.flash({ 
+   *   type: 'both', 
+   *   alpha: 0.5, 
+   *   tint: 0xff0000,
+   *   duration: 200,
+   *   cycles: 2
+   * });
+   * 
+   * // Quick damage flash
+   * player.flash({ 
+   *   type: 'tint', 
+   *   tint: 0xff0000, 
+   *   duration: 150,
+   *   cycles: 1
+   * });
+   * ```
+   */
+  flash(options?: FlashOptions): void {
+    const flashOptions = {
+      type: options?.type || 'alpha',
+      duration: options?.duration ?? 300,
+      cycles: options?.cycles ?? 1,
+      alpha: options?.alpha ?? 0.3,
+      tint: options?.tint ?? 0xffffff,
+    };
+    
+    // Convert color name to hex if needed
+    let tintValue = flashOptions.tint;
+    if (typeof tintValue === 'string') {
+      // Common color name to hex mapping
+      const colorMap: Record<string, number> = {
+        'white': 0xffffff,
+        'red': 0xff0000,
+        'green': 0x00ff00,
+        'blue': 0x0000ff,
+        'yellow': 0xffff00,
+        'cyan': 0x00ffff,
+        'magenta': 0xff00ff,
+        'black': 0x000000,
+      };
+      tintValue = colorMap[tintValue.toLowerCase()] ?? 0xffffff;
+    }
+    
+    this.flashTrigger.start({
+      ...flashOptions,
+      tint: tintValue,
+    });
+  }
+
+  /**
+   * Reset animation state when animation changes externally
+   *
+   * This method should be called when the animation changes due to movement
+   * or other external factors to ensure the animation system doesn't get stuck
+   *
+   * @example
+   * ```ts
+   * // Reset when player starts moving
+   * player.resetAnimationState();
+   * ```
+   */
+  resetAnimationState() {
+    if (this.animationRestoreState) {
+      this.finishTemporaryAnimation();
+      return;
+    }
+    this.animationIsPlaying.set(false);
+    this.animationCurrentIndex.set(0);
+    this.clearAnimationControls();
+    this.resolveAnimationWait();
+  }
+
+  /**
+   * Set a custom animation for a specific number of times
+   *
+   * Plays a custom animation for the specified number of repetitions.
+   * The animation system prevents overlapping animations and automatically
+   * returns to the previous animation when complete.
+   *
+   * @param animationName - Name of the animation to play
+   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+   * @param options - Restore and timeout options
+   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out
+   *
+   * @example
+   * ```ts
+   * // Play attack animation 3 times
+   * await player.setAnimation('attack', 3);
+   *
+   * // Play continuous spell animation
+   * player.setAnimation('spell');
+   * ```
+   */
+  setAnimation(animationName: string, nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;
+  /**
+   * Set a custom animation with temporary graphic change
+   *
+   * Plays a custom animation for the specified number of repetitions and temporarily
+   * changes the player's graphic (sprite sheet) during the animation. The graphic
+   * is automatically reset when the animation finishes.
+   *
+   * @param animationName - Name of the animation to play
+   * @param graphic - The graphic(s) to temporarily use during the animation
+   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+   * @param options - Restore and timeout options
+   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out
+   *
+   * @example
+   * ```ts
+   * // Play attack animation with temporary graphic change
+   * await player.setAnimation('attack', 'hero_attack', 3);
+   * ```
+   */
+  setAnimation(animationName: string, graphic?: string | string[], nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;
+  setAnimation(
+    animationName: string,
+    graphicOrNbTimes?: string | string[] | number,
+    nbTimesOrOptions?: number | AnimationRestoreOptions,
+    options?: AnimationRestoreOptions
+  ): Promise<void> {
+    let graphic: string | string[] | undefined;
+    let finalNbTimes: number = Infinity;
+    let restoreOptions: AnimationRestoreOptions | undefined = options;
+
+    // Handle overloads
+    if (typeof graphicOrNbTimes === 'number') {
+      // setAnimation(animationName, nbTimes)
+      finalNbTimes = graphicOrNbTimes;
+      restoreOptions = typeof nbTimesOrOptions === 'object' ? nbTimesOrOptions : options;
+    } else if (graphicOrNbTimes !== undefined) {
+      // setAnimation(animationName, graphic, nbTimes)
+      graphic = graphicOrNbTimes;
+      if (typeof nbTimesOrOptions === 'number') {
+        finalNbTimes = nbTimesOrOptions;
+      } else {
+        finalNbTimes = Infinity;
+        restoreOptions = nbTimesOrOptions ?? options;
+      }
+    } else {
+      // setAnimation(animationName) - nbTimes remains Infinity
+      finalNbTimes = Infinity;
+    }
+
+    if (this.animationIsPlaying()) {
+      this.finishTemporaryAnimation();
+    }
+
+    const waitPromise =
+      finalNbTimes === Infinity
+        ? Promise.resolve()
+        : new Promise<void>((resolve) => {
+            this.animationWaitResolve = resolve;
+          });
+
+    this.animationIsPlaying.set(true);
+    const previousAnimationName =
+      restoreOptions?.restoreAnimationName ?? this.animationName();
+    const previousGraphics = restoreOptions?.restoreGraphics
+      ? [...restoreOptions.restoreGraphics]
+      : [...this.graphics()];
+    this.animationRestoreState = {
+      animationName: previousAnimationName,
+      graphics: previousGraphics,
+    };
+    this.animationCurrentIndex.set(0);
+
+    // Temporarily change graphic if provided
+    if (graphic !== undefined) {
+      if (Array.isArray(graphic)) {
+        this.graphics.set(graphic);
+      } else {
+        this.graphics.set([graphic]);
+      }
+    }
+
+    this.clearAnimationControls();
+
+    this.animationSubscription =
+      this.animationCurrentIndex.observable.subscribe((index) => {
+        if (index >= finalNbTimes) {
+          this.finishTemporaryAnimation();
+        }
+      });
+
+    if (finalNbTimes !== Infinity) {
+      this.animationResetTimeout = setTimeout(() => {
+        if (this.animationIsPlaying()) {
+          this.finishTemporaryAnimation();
+        }
+      }, restoreOptions?.timeoutMs ?? Math.max(1000, finalNbTimes * 1000));
+    }
+
+    this.animationName.set(animationName);
+
+    return waitPromise;
+  }
+
+  /**
+   * Display a registered component animation effect on this object.
+   *
+   * @param id - Identifier of the component animation to play.
+   * @param params - Parameters forwarded to the animation effect.
+   * @returns A promise resolved when the animation component calls `onFinish`.
+   */
+  showComponentAnimation(id: string, params: any): Promise<void> {
+    const engine = inject(RpgClientEngine);
+    return engine.getComponentAnimation(id).displayEffect(params, this);
+  }
+
+  /**
+   * Display a registered spritesheet animation effect on this object.
+   *
+   * @param graphic - Identifier of the spritesheet to use.
+   * @param animationName - Name of the animation inside the spritesheet.
+   * @returns A promise resolved when the animation component calls `onFinish`.
+   */
+  showAnimation(graphic: string, animationName: string = 'default'): Promise<void> {
+    return this.showComponentAnimation('animation', {
+      graphic,
+      animationName,
+    });
+  }
+  
+  /**
+   * Check whether this client object represents an event.
+   *
+   * @returns `true` if the object type is `event`, otherwise `false`.
+   */
+  isEvent(): boolean {
+    return this._type === 'event';
+  }
+
+  /**
+   * Check whether this client object represents a player.
+   *
+   * @returns `true` if the object type is `player`, otherwise `false`.
+   */
+  isPlayer(): boolean {
+    return this._type === 'player';
+  }
+}

package/src/Game/Player.ts

@@ -1,5 +1,5 @@
 import { RpgClientObject } from "./Object";
 
 export class RpgClientPlayer extends RpgClientObject {
-    type = 'player'
+    _type = 'player'
 }   

package/src/Gui/Gui.spec.ts

@@ -0,0 +1,273 @@
+import { describe, expect, test, vi } from "vitest";
+import { Context, injector } from "@signe/di";
+import { signal } from "canvasengine";
+import { PrebuiltGui } from "@rpgjs/common";
+import { WebSocketToken } from "../services/AbstractSocket";
+
+vi.mock("../components/gui", () => {
+  const component = () => null;
+  return {
+    DialogboxComponent: component,
+    ShopComponent: component,
+    SaveLoadComponent: component,
+    MainMenuComponent: component,
+    NotificationComponent: component,
+    TitleScreenComponent: component,
+    GameoverComponent: component,
+  };
+});
+
+const createGui = async () => {
+  const { RpgGui } = await import("./Gui");
+  const context = new Context();
+  const socket = {
+    on: vi.fn(),
+    emit: vi.fn(),
+  };
+  await injector(context, [
+    {
+      provide: WebSocketToken,
+      useValue: socket,
+    },
+  ]);
+  return {
+    gui: new RpgGui(context),
+    socket,
+  };
+};
+
+const CanvasGui = () => null;
+const VueInventory = {
+  name: "inventory",
+  render() {
+    return null;
+  },
+};
+const VueDialog = {
+  name: PrebuiltGui.Dialog,
+  render() {
+    return null;
+  },
+};
+const VueMainMenu = {
+  name: PrebuiltGui.MainMenu,
+  render() {
+    return null;
+  },
+};
+const VueTooltip = {
+  name: "tooltip",
+  rpgAttachToSprite: true,
+  render() {
+    return null;
+  },
+};
+
+describe("RpgGui Vue integration", () => {
+  test("separates CanvasEngine and Vue GUI registries", async () => {
+    const { gui } = await createGui();
+
+    gui.add({
+      id: "canvas-tooltip",
+      component: CanvasGui,
+      attachToSprite: true,
+    });
+    gui.add({
+      id: "inventory",
+      component: VueInventory,
+    });
+    gui.add(VueTooltip);
+
+    expect(gui.get("canvas-tooltip")?.component).toBe(CanvasGui);
+    expect(gui.get("inventory")?.component).toBe(VueInventory);
+    expect(gui.get("tooltip")?.component).toBe(VueTooltip);
+    expect(gui.getAttachedGuis().map(item => item.name)).toEqual(["canvas-tooltip"]);
+    expect(gui.getAttachedVueGuis().map(item => item.name)).toEqual(["tooltip"]);
+  });
+
+  test("synchronizes Vue GUI display and hide states through the Vue bridge", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui.add({
+      id: "inventory",
+      component: VueInventory,
+    });
+    gui._setVueGuiInstance(bridge);
+
+    expect(bridge.initializeGuiStates).toHaveBeenCalledWith([
+      expect.objectContaining({
+        name: "inventory",
+        display: false,
+        data: {},
+        attachToSprite: false,
+      }),
+    ]);
+
+    gui.display("inventory", { gold: 12 });
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: "inventory",
+        display: true,
+        data: { gold: 12 },
+        attachToSprite: false,
+      }),
+    );
+
+    gui.hide("inventory");
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: "inventory",
+        display: false,
+      }),
+    );
+  });
+
+  test("waits for Vue GUI dependencies before display", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+    const dependency = signal<any>(undefined);
+
+    gui.add({
+      id: "inventory",
+      component: VueInventory,
+      dependencies: () => [dependency],
+    });
+    gui._setVueGuiInstance(bridge);
+    gui.display("inventory", { items: ["potion"] });
+
+    expect(gui.isDisplaying("inventory")).toBe(false);
+    expect(bridge.updateGuiState).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        display: true,
+      }),
+    );
+
+    dependency.set({ id: "player" });
+
+    expect(gui.isDisplaying("inventory")).toBe(true);
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: "inventory",
+        display: true,
+        data: { items: ["potion"] },
+      }),
+    );
+  });
+
+  test("allows Vue GUI entries to replace prebuilt CanvasEngine GUIs", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui._setVueGuiInstance(bridge);
+    gui.add({
+      id: PrebuiltGui.Dialog,
+      component: VueDialog,
+    });
+
+    expect(gui.get(PrebuiltGui.Dialog)?.component).toBe(VueDialog);
+    expect(gui.getAll()[PrebuiltGui.Dialog].component).toBe(VueDialog);
+    expect((gui as any).gui()[PrebuiltGui.Dialog]).toBeUndefined();
+    expect(gui.getVueGuis().filter(item => item.name === PrebuiltGui.Dialog)).toHaveLength(1);
+
+    gui.display(PrebuiltGui.Dialog, { text: "Hello" });
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: PrebuiltGui.Dialog,
+        display: true,
+        data: { text: "Hello" },
+      }),
+    );
+
+    gui.hide(PrebuiltGui.Dialog);
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: PrebuiltGui.Dialog,
+        display: false,
+      }),
+    );
+  });
+
+  test("allows CanvasEngine GUI entries to replace Vue GUI entries with the same id", async () => {
+    const { gui } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui._setVueGuiInstance(bridge);
+    gui.add({
+      id: PrebuiltGui.Dialog,
+      component: VueDialog,
+    });
+    gui.add({
+      id: PrebuiltGui.Dialog,
+      component: CanvasGui,
+    });
+
+    expect(gui.get(PrebuiltGui.Dialog)?.component).toBe(CanvasGui);
+    expect(gui.getVueGuis().some(item => item.name === PrebuiltGui.Dialog)).toBe(false);
+    expect((gui as any).gui()[PrebuiltGui.Dialog].component).toBe(CanvasGui);
+    expect(bridge.initializeGuiStates).toHaveBeenLastCalledWith([]);
+  });
+
+  test("keeps main menu optimistic reducers when a Vue GUI replaces the prebuilt component", async () => {
+    const { gui, socket } = await createGui();
+    const bridge = {
+      updateGuiState: vi.fn(),
+      initializeGuiStates: vi.fn(),
+    };
+
+    gui.add({
+      id: PrebuiltGui.MainMenu,
+      component: VueMainMenu,
+    });
+    gui._setVueGuiInstance(bridge);
+    gui.display(PrebuiltGui.MainMenu, {
+      items: [
+        {
+          id: "potion",
+          quantity: 2,
+        },
+      ],
+    });
+
+    gui.guiInteraction(PrebuiltGui.MainMenu, "useItem", { id: "potion" });
+
+    expect(gui.get(PrebuiltGui.MainMenu)?.data().items).toEqual([
+      {
+        id: "potion",
+        quantity: 1,
+      },
+    ]);
+    expect(bridge.updateGuiState).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        name: PrebuiltGui.MainMenu,
+        data: {
+          items: [
+            {
+              id: "potion",
+              quantity: 1,
+            },
+          ],
+        },
+      }),
+    );
+    expect(socket.emit).toHaveBeenCalledWith(
+      "gui.interaction",
+      expect.objectContaining({
+        guiId: PrebuiltGui.MainMenu,
+        name: "useItem",
+      }),
+    );
+  });
+});