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

package/src/Game/Map.ts

@@ -1,5 +1,9 @@
 import {
   RpgCommonMap,
+  cloneLightingState,
+  normalizeLightingState,
+  type LightSpot,
+  type LightingState,
   type WeatherState,
   type MapPhysicsInitContext,
   type MapPhysicsEntityContext,
@@ -11,6 +15,43 @@ import { RpgClientEvent } from "./Event";
 import { RpgClientEngine } from "../RpgClientEngine";
 import { inject } from "../core/inject";
 
+type TestGlobalScope = typeof globalThis & {
+  process?: {
+    env?: {
+      TEST?: string;
+    };
+  };
+  __RPGJS_TEST__?: boolean;
+};
+
+const lightingColorsEqual = (
+  left: LightSpot["color"],
+  right: LightSpot["color"],
+): boolean => {
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left)
+      && Array.isArray(right)
+      && left.length === right.length
+      && left.every((value, index) => value === right[index]);
+  }
+  return left === right;
+};
+
+const lightSpotsEqual = (left: LightSpot | undefined, right: LightSpot): boolean => {
+  if (!left) return false;
+  return left.id === right.id
+    && left.x === right.x
+    && left.y === right.y
+    && left.radius === right.radius
+    && left.intensity === right.intensity
+    && lightingColorsEqual(left.color, right.color)
+    && left.flicker === right.flicker
+    && left.flickerSpeed === right.flickerSpeed
+    && left.pulse === right.pulse
+    && left.pulseSpeed === right.pulseSpeed
+    && left.phase === right.phase;
+};
+
 export class RpgClientMap extends RpgCommonMap<any> {
   engine: RpgClientEngine = inject(RpgClientEngine)
   @users(RpgClientPlayer) players = signal<Record<string, RpgClientPlayer>>({});
@@ -18,19 +59,43 @@ export class RpgClientMap extends RpgCommonMap<any> {
   currentPlayer = computed(() => this.players()[this.engine.playerIdSignal()!])
   weatherState = signal<WeatherState | null>(null);
   localWeatherOverride = signal<WeatherState | null>(null);
+  lightingState = signal<LightingState | null>(null);
+  localLightSpots = signal<Record<string, LightSpot>>({});
   weather = computed<WeatherState | null>(() => {
     const local = this.localWeatherOverride() 
     const state = this.weatherState()
     return local ?? state
   });
+  lighting = computed<LightingState | null>(() => {
+    const state = cloneLightingState(this.lightingState());
+    const localSpots = Object.entries(this.localLightSpots()).map(([id, spot]) => ({
+      ...spot,
+      id: spot.id ?? id,
+    }));
+
+    if (!state && localSpots.length === 0) {
+      return null;
+    }
+
+    const next: LightingState = { ...(state ?? {}) };
+    if (!state?.ambient) {
+      delete next.ambient;
+    }
+    next.spots = [
+      ...(state?.spots ?? []),
+      ...localSpots,
+    ];
+    return next;
+  });
   private manualClientPhysicsTick = false;
   private readonly isTestEnvironment: boolean;
 
   constructor() {
     super();
     // Détecter l'environnement de test
-    const isTest = (typeof process !== 'undefined' && process.env?.TEST === 'true')
-      || (typeof window !== 'undefined' && (window as any).__RPGJS_TEST__ === true);
+    const testGlobal = globalThis as TestGlobalScope;
+    const isTest = testGlobal.process?.env?.TEST === 'true'
+      || testGlobal.__RPGJS_TEST__ === true;
     this.isTestEnvironment = isTest;
     if (isTest) {
       this.autoTickEnabled = false;
@@ -51,6 +116,16 @@ export class RpgClientMap extends RpgCommonMap<any> {
     const currentPlayer = !force && currentPlayerId
       ? this.players()[currentPlayerId]
       : undefined;
+    const players = this.players();
+    const events = this.events();
+
+    Object.entries(players).forEach(([id, player]) => {
+      if (!player || (!force && id === currentPlayerId)) return;
+      (player as any).resetAnimationState?.();
+    });
+    Object.values(events).forEach((event) => {
+      (event as any)?.resetAnimationState?.();
+    });
 
     this.players.set(
       currentPlayerId && currentPlayer ? { [currentPlayerId]: currentPlayer } : {}
@@ -58,6 +133,8 @@ export class RpgClientMap extends RpgCommonMap<any> {
     this.events.set({})
     this.weatherState.set(null);
     this.localWeatherOverride.set(null);
+    this.lightingState.set(null);
+    this.localLightSpots.set({});
     this.clearPhysic()
   }
 
@@ -73,6 +150,61 @@ export class RpgClientMap extends RpgCommonMap<any> {
     this.localWeatherOverride.set(null);
   }
 
+  getLighting(): LightingState | null {
+    return this.lighting();
+  }
+
+  addLightSpot(id: string, spot: LightSpot): void {
+    const normalized = normalizeLightingState({ spots: [{ ...spot, id }] });
+    const nextSpot = normalized?.spots?.[0];
+    if (!nextSpot) {
+      return;
+    }
+    this.localLightSpots.update((spots) => {
+      if (lightSpotsEqual(spots[id], nextSpot)) {
+        return spots;
+      }
+      return {
+        ...spots,
+        [id]: nextSpot,
+      };
+    });
+  }
+
+  patchLightSpot(id: string, patch: Partial<LightSpot>): void {
+    this.localLightSpots.update((spots) => {
+      const current = spots[id];
+      if (!current) {
+        return spots;
+      }
+      return {
+        ...spots,
+        [id]: {
+          ...current,
+          ...patch,
+          id,
+          x: patch.x ?? current.x,
+          y: patch.y ?? current.y,
+        },
+      };
+    });
+  }
+
+  removeLightSpot(id: string): void {
+    this.localLightSpots.update((spots) => {
+      if (!(id in spots)) {
+        return spots;
+      }
+      const next = { ...spots };
+      delete next[id];
+      return next;
+    });
+  }
+
+  clearLightSpots(): void {
+    this.localLightSpots.set({});
+  }
+
   stepClientPhysics(deltaMs: number): number {
     if (!this.manualClientPhysicsTick) {
       return 0;

package/src/Game/Object.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test, vi } from "vitest";
+import { signal } from "canvasengine";
+import { appendFramePayload, RpgClientObject, withGraphicDisplayScale } from "./Object";
+
+vi.mock("../RpgClientEngine", () => ({
+  RpgClientEngine: class RpgClientEngine {},
+}));
+
+vi.mock("../core/inject", () => ({
+  inject: () => ({}),
+}));
+
+function createObject() {
+  const object = Object.create(RpgClientObject.prototype) as RpgClientObject;
+  object.animationName = signal("stand");
+  object.graphics = signal(["hero"]) as any;
+  object.animationCurrentIndex = signal(0);
+  object.animationIsPlaying = signal(false);
+  return object;
+}
+
+describe("RpgClientObject animations", () => {
+  test("accepts a single frame payload without requiring iterable spread", () => {
+    expect(
+      appendFramePayload({ stale: true }, { x: 10, y: 20, ts: 1 }),
+    ).toEqual([{ x: 10, y: 20, ts: 1 }]);
+  });
+
+  test("keeps instance scale outside the spritesheet transform scale", () => {
+    expect(withGraphicDisplayScale({ id: "hero" }, 0.5)).toEqual({
+      id: "hero",
+      displayScale: 0.5,
+    });
+  });
+
+  test("marks temporary animation as finished before restoring locomotion animation", async () => {
+    const object = createObject();
+    const animationChanges: Array<{ name: string; isPlaying: boolean }> = [];
+
+    object.animationName.observable.subscribe((name) => {
+      animationChanges.push({
+        name,
+        isPlaying: object.animationIsPlaying(),
+      });
+    });
+
+    const done = object.setAnimation("attack", 1, { timeoutMs: 10000 });
+    object.animationCurrentIndex.set(1);
+
+    await done;
+
+    expect(object.animationName()).toBe("stand");
+    expect(object.animationIsPlaying()).toBe(false);
+    expect(animationChanges).toContainEqual({
+      name: "stand",
+      isPlaying: false,
+    });
+  });
+});

package/src/Game/Object.ts

@@ -1,15 +1,51 @@
 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 { combineLatest, from, map, of, startWith, 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 const withGraphicDisplayScale = (spritesheet: any, scale: unknown): any => {
+  if (!spritesheet || typeof spritesheet !== "object") return spritesheet;
+  if (scale === undefined || scale === null) return spritesheet;
+  return {
+    ...spritesheet,
+    displayScale: scale,
+  };
+};
+
+export const appendFramePayload = (current: unknown, items: unknown): Frame[] => {
+  const frameItems = Array.isArray(items) ? items : items ? [items] : [];
+  const nextFrames = frameItems.flatMap((item): Frame[] =>
+    Array.isArray(item) ? item : [item as Frame]
+  );
+  const currentFrames = Array.isArray(current) ? current as Frame[] : [];
+  return currentFrames.concat(nextFrames);
+};
 
 export abstract class RpgClientObject extends RpgCommonPlayer {
   abstract _type: string;
@@ -20,51 +56,45 @@ 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();
+    const engine = this.engine;
     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.frames = appendFramePayload(this.frames, items);
     });
 
-    this.graphics.observable
+    const graphics$ = this.graphics.observable.pipe(map(({ items }) => items));
+    const graphicScale$ = this._graphicScale.observable.pipe(
+      startWith({ value: this._graphicScale() }),
+      map((payload: any) => payload?.value ?? payload),
+    );
+
+    combineLatest([graphics$, graphicScale$])
     .pipe(
-      map(({ items }) => items),
-      filter(graphics => graphics.length > 0),
-      switchMap(graphics => from(Promise.all(graphics.map(graphic => this.engine.getSpriteSheet(graphic)))))
+      switchMap(([graphics, scale]) => {
+        const graphicRefs = Array.isArray(graphics) ? graphics : [];
+        if (graphicRefs.length === 0) return of([]);
+        return from(Promise.all(graphicRefs.map(async (graphic) => {
+          const spritesheet = await engine.getSpriteSheet(graphic);
+          return withGraphicDisplayScale(spritesheet, scale);
+        })));
+      })
     )
     .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
+    engine.tick
       .pipe
       //throttleTime(10)
       ()
@@ -72,7 +102,7 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
         const frame = this.frames.shift();
         if (frame) {
           if (typeof frame.x !== "number" || typeof frame.y !== "number") return;
-          this.engine.scene.setBodyPosition(
+          engine.scene.setBodyPosition(
             this.id,
             frame.x,
             frame.y,
@@ -101,6 +131,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);
+    this.animationRestoreState = undefined;
+    this.animationIsPlaying.set(false);
+    if (restoreState) {
+      this.animationName.set(restoreState.animationName);
+      this.graphics.set([...restoreState.graphics]);
+    }
+    this.resolveAnimationWait();
+  }
 
   /**
    * Trigger a flash animation on this sprite
@@ -148,13 +210,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 +255,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 +274,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 +297,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 +368,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 +395,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,
+    });
   }
   
   /**