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

package/src/Game/Object.ts

@@ -1,15 +1,33 @@
 import { Hooks, ModulesToken, RpgCommonPlayer } from "@rpgjs/common";
-import { trigger, signal, effect } from "canvasengine";
-import { filter, from, map, Subscription, switchMap } from "rxjs";
+import { trigger, signal, type Trigger } from "canvasengine";
+import { from, map, of, Subscription, switchMap } from "rxjs";
 import { inject } from "../core/inject";
 import { RpgClientEngine } from "../RpgClientEngine";
-import TextComponent from "../components/dynamics/text.ce";
+type Frame = { x: number; y: number; ts: number };
 
-const DYNAMIC_COMPONENTS = {
-  text: TextComponent,
-}
+type AnimationRestoreOptions = {
+  restoreAnimationName?: string;
+  restoreGraphics?: any[];
+  timeoutMs?: number;
+};
 
-type Frame = { x: number; y: number; ts: 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;
@@ -20,8 +38,11 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
   _param = signal({});
   frames: Frame[] = [];
   graphicsSignals = signal<any[]>([]);
-  _component = {} // temporary component memory
-  flashTrigger = trigger();
+  flashTrigger: ConfigurableTrigger<FlashTriggerOptions> = trigger<FlashTriggerOptions>();
+  private animationRestoreState?: {
+    animationName: string;
+    graphics: any[];
+  };
 
   constructor() {
     super();
@@ -39,31 +60,15 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
     this.graphics.observable
     .pipe(
       map(({ items }) => items),
-      filter(graphics => graphics.length > 0),
-      switchMap(graphics => from(Promise.all(graphics.map(graphic => this.engine.getSpriteSheet(graphic)))))
+      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.componentsTop.observable
-    .pipe(
-      filter(value => value !== null && value !== undefined),
-      map((value) => typeof value === 'string' ? JSON.parse(value) : value),
-    )
-    .subscribe(({components}) => {
-      for (const component of components) {
-        for (const [key, value] of Object.entries(component)) {
-          this._component = value as any; // temporary component memory
-          console.log(value)
-          const type = (value as any).type as keyof typeof DYNAMIC_COMPONENTS;
-          if (DYNAMIC_COMPONENTS[type]) {
-            this.engine.addSpriteComponentInFront(DYNAMIC_COMPONENTS[type]);
-          }
-        }
-      }
-    });
-
     this.engine.tick
       .pipe
       //throttleTime(10)
@@ -101,6 +106,38 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
   }
 
   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
@@ -148,13 +185,7 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
    * });
    * ```
    */
-  flash(options?: {
-    type?: 'alpha' | 'tint' | 'both';
-    duration?: number;
-    cycles?: number;
-    alpha?: number;
-    tint?: number | string;
-  }): void {
+  flash(options?: FlashOptions): void {
     const flashOptions = {
       type: options?.type || 'alpha',
       duration: options?.duration ?? 300,
@@ -199,12 +230,14 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
    * ```
    */
   resetAnimationState() {
+    if (this.animationRestoreState) {
+      this.finishTemporaryAnimation();
+      return;
+    }
     this.animationIsPlaying.set(false);
     this.animationCurrentIndex.set(0);
-    if (this.animationSubscription) {
-      this.animationSubscription.unsubscribe();
-      this.animationSubscription = undefined;
-    }
+    this.clearAnimationControls();
+    this.resolveAnimationWait();
   }
 
   /**
@@ -216,17 +249,19 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
    *
    * @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
-   * player.setAnimation('attack', 3);
+   * await player.setAnimation('attack', 3);
    *
    * // Play continuous spell animation
    * player.setAnimation('spell');
    * ```
    */
-  setAnimation(animationName: string, nbTimes?: number): void;
+  setAnimation(animationName: string, nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;
   /**
    * Set a custom animation with temporary graphic change
    *
@@ -237,37 +272,68 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
    * @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
-   * player.setAnimation('attack', 'hero_attack', 3);
+   * await player.setAnimation('attack', 'hero_attack', 3);
    * ```
    */
-  setAnimation(animationName: string, graphic?: string | string[], nbTimes?: number): void;
-  setAnimation(animationName: string, graphicOrNbTimes?: string | string[] | number, nbTimes?: number): void {
-    if (this.animationIsPlaying()) return;
-    this.animationIsPlaying.set(true);
-    const previousAnimationName = this.animationName();
-    const previousGraphics = this.graphics();
-    this.animationCurrentIndex.set(0);
-
+  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;
-      finalNbTimes = nbTimes ?? Infinity;
+      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)) {
@@ -277,28 +343,26 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
       }
     }
 
-    // Clean up any existing subscription
-    if (this.animationSubscription) {
-      this.animationSubscription.unsubscribe();
-    }
+    this.clearAnimationControls();
 
     this.animationSubscription =
       this.animationCurrentIndex.observable.subscribe((index) => {
         if (index >= finalNbTimes) {
-          this.animationCurrentIndex.set(0);
-          this.animationName.set(previousAnimationName);
-          // Reset graphic to previous value if it was changed
-          if (graphic !== undefined) {
-            this.graphics.set(previousGraphics);
-          }
-          this.animationIsPlaying.set(false);
-          if (this.animationSubscription) {
-            this.animationSubscription.unsubscribe();
-            this.animationSubscription = undefined;
-          }
+          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;
   }
 
   /**
@@ -306,10 +370,25 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
    *
    * @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) {
+  showComponentAnimation(id: string, params: any): Promise<void> {
     const engine = inject(RpgClientEngine);
-    engine.getComponentAnimation(id).displayEffect(params, this);
+    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,
+    });
   }
   
   /**

package/src/Game/ProjectileManager.spec.ts

@@ -0,0 +1,338 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { Hooks } from "@rpgjs/common";
+import { ProjectileManager } from "./ProjectileManager";
+
+describe("ProjectileManager", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("renders registered projectile components from compact spawn data", () => {
+    const onSpawn = vi.fn();
+    const hooks = new Hooks([{ projectiles: { onSpawn } }], "client");
+    const manager = new ProjectileManager(hooks);
+    const component = () => null;
+
+    manager.register("fireball", component);
+    manager.spawnBatch([
+      {
+        id: "p1",
+        type: "fireball",
+        origin: { x: 10, y: 20 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    const current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].component).toBe(component);
+    expect(current[0].props.x).toBeGreaterThanOrEqual(10);
+    expect(current[0].props.angle).toBe(0);
+    expect(onSpawn).toHaveBeenCalledWith(expect.objectContaining({ id: "p1", type: "fireball" }));
+  });
+
+  test("starts visuals at the spawn origin even when a server tick estimate exists", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(2000);
+
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p-latency",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 120,
+        range: 500,
+        ttl: 5,
+        spawnTick: 10,
+      },
+    ], {
+      currentServerTick: 16,
+      tickDurationMs: 1000 / 60,
+    });
+
+    const current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.elapsed).toBeCloseTo(0, 3);
+    expect(current[0].props.x).toBeCloseTo(0, 3);
+  });
+
+  test("keeps delayed projectiles until their visual delay has elapsed", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1000);
+
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    manager.register("spark", () => null);
+    manager.spawnBatch([
+      {
+        id: "p-delayed",
+        type: "spark",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+        delay: 0.1,
+      },
+    ]);
+
+    vi.setSystemTime(1050);
+    manager.step();
+    expect(manager.current()).toHaveLength(0);
+
+    vi.setSystemTime(1110);
+    manager.step();
+    const current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.elapsed).toBeCloseTo(0.01, 3);
+  });
+
+  test("keeps impacted projectiles briefly so components can react", () => {
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p2",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    manager.impactBatch([{ id: "p2", x: 42, y: 0, distance: 42 }]);
+
+    const current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.impact?.x).toBe(42);
+    expect(current[0].props.destroyed).toBe(true);
+  });
+
+  test("keeps hit destroys briefly even if the destroy packet arrives before impact", () => {
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p3",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    manager.destroyBatch([{ id: "p3", reason: "hit", x: 48, y: 0, distance: 48 }]);
+
+    const current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.impact?.x).toBe(48);
+    expect(current[0].props.destroyed).toBe(true);
+  });
+
+  test("freezes hit destroys at the authoritative impact position until the impact completes", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1000);
+
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks);
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p4",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    vi.setSystemTime(1200);
+    manager.destroyBatch([{ id: "p4", reason: "hit", x: 48, y: 0, distance: 48 }]);
+
+    vi.setSystemTime(1300);
+    manager.step();
+    let current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.x).toBe(48);
+    expect(current[0].props.distance).toBe(48);
+    expect(current[0].props.impactProgress).toBeCloseTo(100 / 350, 3);
+
+    vi.setSystemTime(1600);
+    manager.step();
+    current = manager.current();
+    expect(current).toHaveLength(0);
+  });
+
+  test("clamps visual movement at the predicted impact without starting the impact animation", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1000);
+
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks, () => ({
+      id: "p5",
+      targetId: "target",
+      x: 30,
+      y: 0,
+      distance: 30,
+    }));
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p5",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    vi.setSystemTime(1200);
+    manager.step();
+    let current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.x).toBe(20);
+    expect(current[0].props.impact).toBeUndefined();
+    expect(current[0].props.destroyed).toBe(false);
+
+    vi.setSystemTime(1400);
+    manager.step();
+    current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.x).toBe(30);
+    expect(current[0].props.distance).toBe(30);
+    expect(current[0].props.impact).toBeUndefined();
+    expect(current[0].props.destroyed).toBe(false);
+
+    manager.impactBatch([{ id: "p5", targetId: "target", x: 32, y: 0, distance: 32 }]);
+    current = manager.current();
+    expect(current[0].props.x).toBe(30);
+    expect(current[0].props.distance).toBe(30);
+    expect(current[0].props.impact?.x).toBe(32);
+    expect(current[0].props.destroyed).toBe(true);
+  });
+
+  test("uses the authoritative impact position when the predicted target differs", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1000);
+
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks, () => ({
+      id: "p7",
+      targetId: "wall",
+      x: 30,
+      y: 0,
+      distance: 30,
+    }));
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p7",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    vi.setSystemTime(1400);
+    manager.step();
+    manager.impactBatch([{ id: "p7", targetId: "target", x: 45, y: 0, distance: 45 }]);
+
+    const current = manager.current();
+    expect(current[0].props.x).toBe(45);
+    expect(current[0].props.distance).toBe(45);
+    expect(current[0].props.impact?.x).toBe(45);
+  });
+
+  test("keeps an unconfirmed predicted impact clamped until the server resolves it", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1000);
+
+    const hooks = new Hooks([], "client");
+    const manager = new ProjectileManager(hooks, () => ({
+      id: "p6",
+      targetId: "ignored",
+      x: 30,
+      y: 0,
+      distance: 30,
+    }));
+    manager.register("arrow", () => null);
+    manager.spawnBatch([
+      {
+        id: "p6",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+      },
+    ]);
+
+    vi.setSystemTime(1400);
+    manager.step();
+    expect(manager.current()[0].props.x).toBe(30);
+
+    vi.setSystemTime(1900);
+    manager.step();
+    const current = manager.current();
+    expect(current).toHaveLength(1);
+    expect(current[0].props.x).toBe(30);
+    expect(current[0].props.impact).toBeUndefined();
+    expect(current[0].props.destroyed).toBe(false);
+
+    manager.destroyBatch([{ id: "p6", reason: "range" }]);
+    expect(manager.current()[0].props.x).toBe(30);
+    expect(manager.current()[0].props.destroyed).toBe(true);
+  });
+
+  test("skips local impact prediction when the server marks the projectile as non-predictable", () => {
+    const hooks = new Hooks([], "client");
+    const predictionResolver = vi.fn();
+    const manager = new ProjectileManager(hooks, predictionResolver);
+    manager.register("arrow", () => null);
+
+    manager.spawnBatch([
+      {
+        id: "p-no-predict",
+        type: "arrow",
+        origin: { x: 0, y: 0 },
+        direction: { x: 1, y: 0 },
+        speed: 100,
+        range: 500,
+        ttl: 5,
+        spawnTick: 1,
+        predictImpact: false,
+      },
+    ]);
+
+    expect(predictionResolver).not.toHaveBeenCalled();
+  });
+});