@rpgjs/client 5.0.0-alpha.21 → 5.0.0-alpha.23

package/src/Gui/Gui.ts

@@ -195,14 +195,13 @@ export class RpgGui {
     if (!guiId) {
       throw new Error("GUI must have a name or id");
     }
-
     const guiInstance: GuiInstance = {
       name: guiId,
       component: gui.component,
       display: signal(gui.display || false),
       data: signal(gui.data || {}),
       autoDisplay: gui.autoDisplay || false,
-      dependencies: gui.dependencies,
+      dependencies: gui.dependencies ? gui.dependencies() : [],
       attachToSprite: gui.attachToSprite || false,
     };
 
@@ -317,8 +316,9 @@ export class RpgGui {
       // Handle Vue component display
       this._handleVueComponentDisplay(id, data, dependencies, guiInstance);
     } else {
-      // Handle CanvasEngine component display
-      this._handleCanvasComponentDisplay(id, data, dependencies, guiInstance);
+      guiInstance.data.set(data);
+      guiInstance.display.set(true);
+      console.log(guiInstance.dependencies)
     }
   }
 
@@ -371,33 +371,7 @@ export class RpgGui {
    * @param guiInstance - GUI instance
    */
   private _handleCanvasComponentDisplay(id: string, data: any, dependencies: Signal[], guiInstance: GuiInstance) {
-    // Unsubscribe from previous subscription if exists
-    if (guiInstance.subscription) {
-      guiInstance.subscription.unsubscribe();
-      guiInstance.subscription = undefined;
-    }
-
-    // Use runtime dependencies or config dependencies
-    const deps = dependencies.length > 0 
-      ? dependencies 
-      : (guiInstance.dependencies ? guiInstance.dependencies() : []);
-
-    if (deps.length > 0) {
-      // Subscribe to dependencies
-      guiInstance.subscription = combineLatest(
-        deps.map(dependency => dependency.observable)
-      ).subscribe((values) => {
-        if (values.every(value => value !== undefined)) {
-          guiInstance.data.set(data);
-          guiInstance.display.set(true);
-        }
-      });
-      return;
-    }
-
-    // No dependencies, display immediately
-    guiInstance.data.set(data);
-    guiInstance.display.set(true);
+    
   }
 
   /**

package/src/RpgClientEngine.ts

@@ -1,6 +1,6 @@
 import Canvas from "./components/scenes/canvas.ce";
-import { Context, inject } from "@signe/di";
-import { signal, bootstrapCanvas, Howler, Howl } from "canvasengine";
+import { inject } from './core/inject'
+import { signal, bootstrapCanvas, KeyboardControls, Howl, trigger } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "./services/AbstractSocket";
 import { LoadMapService, LoadMapToken } from "./services/loadMap";
 import { RpgSound } from "./Sound";
@@ -12,6 +12,7 @@ import { load } from "@signe/sync";
 import { RpgClientMap } from "./Game/Map"
 import { RpgGui } from "./Gui/Gui";
 import { AnimationManager } from "./Game/AnimationManager";
+import { TransitionManager } from "./Game/TransitionManager";
 import { lastValueFrom, Observable } from "rxjs";
 import { GlobalConfigToken } from "./module";
 import * as PIXI from "pixi.js";
@@ -20,7 +21,6 @@ import {
   PredictionController,
   type PredictionState,
 } from "@rpgjs/common";
-import { KeyboardControls } from "./services/keyboardControls";
 
 export class RpgClientEngine<T = any> {
   private guiService: RpgGui;
@@ -37,6 +37,7 @@ export class RpgClientEngine<T = any> {
   spritesheets: Map<string, any> = new Map();
   sounds: Map<string, any> = new Map();
   componentAnimations: any[] = [];
+  transitions: any[] = [];
   private spritesheetResolver?: (id: string) => any | Promise<any>;
   private soundResolver?: (id: string) => any | Promise<any>;
   particleSettings: {
@@ -49,6 +50,10 @@ export class RpgClientEngine<T = any> {
   playerIdSignal = signal<string | null>(null);
   spriteComponentsBehind = signal<any[]>([]);
   spriteComponentsInFront = signal<any[]>([]);
+  /** ID of the sprite that the camera should follow. null means follow the current player */
+  cameraFollowTargetId = signal<string | null>(null);
+  /** Trigger for map shake animation */
+  mapShakeTrigger = trigger();
 
   private predictionEnabled = false;
   private prediction?: PredictionController<Direction>;
@@ -61,12 +66,12 @@ export class RpgClientEngine<T = any> {
   private readonly PING_INTERVAL_MS = 5000; // Send ping every 5 seconds
   private lastInputTime = 0;
 
-  constructor(public context: Context) {
-    this.webSocket = inject(context, WebSocketToken);
-    this.guiService = inject(context, RpgGui);
-    this.loadMapService = inject(context, LoadMapToken);
-    this.hooks = inject<Hooks>(context, ModulesToken);
-    this.globalConfig = inject(context, GlobalConfigToken)
+  constructor(public context) {
+    this.webSocket = inject(WebSocketToken);
+    this.guiService = inject(RpgGui);
+    this.loadMapService = inject(LoadMapToken);
+    this.hooks = inject<Hooks>(ModulesToken);
+    this.globalConfig = inject(GlobalConfigToken)
 
     if (!this.globalConfig) {
       this.globalConfig = {} as T
@@ -124,8 +129,8 @@ export class RpgClientEngine<T = any> {
    * ```
    */
   setKeyboardControls(controlInstance: any) {
-    const currentValues = this.context.values['inject:' + KeyboardControls]
-    this.context.values['inject:' + KeyboardControls] = {
+    const currentValues = this.context.values['inject:' + 'KeyboardControls']
+    this.context.values['inject:' + 'KeyboardControls'] = {
       ...currentValues,
       values: new Map([['__default__', controlInstance]])
     }
@@ -158,6 +163,7 @@ export class RpgClientEngine<T = any> {
     this.hooks.callHooks("client-gui-load", this).subscribe();
     this.hooks.callHooks("client-particles-load", this).subscribe();
     this.hooks.callHooks("client-componentAnimations-load", this).subscribe();
+    this.hooks.callHooks("client-transitions-load", this).subscribe();
     this.hooks.callHooks("client-sprite-load", this).subscribe();
 
     await lastValueFrom(this.hooks.callHooks("client-engine-onStart", this));
@@ -214,6 +220,8 @@ export class RpgClientEngine<T = any> {
 
     this.webSocket.on("changeMap", (data) => {
       this.sceneMap.reset()
+      // Reset camera follow to default (follow current player) when changing maps
+      this.cameraFollowTargetId.set(null);
       this.loadScene(data.mapId);
     });
 
@@ -242,6 +250,33 @@ export class RpgClientEngine<T = any> {
       this.stopSound(soundId);
     });
 
+    this.webSocket.on("stopAllSounds", () => {
+      this.stopAllSounds();
+    });
+
+    this.webSocket.on("cameraFollow", (data) => {
+      const { targetId, smoothMove } = data;
+      this.setCameraFollow(targetId, smoothMove);
+    });
+
+    this.webSocket.on("flash", (data) => {
+      const { object, type, duration, cycles, alpha, tint } = data;
+      const sprite = object ? this.sceneMap.getObjectById(object) : undefined;
+      if (sprite && typeof sprite.flash === 'function') {
+        sprite.flash({ type, duration, cycles, alpha, tint });
+      }
+    });
+
+    this.webSocket.on("shakeMap", (data) => {
+      const { intensity, duration, frequency, direction } = data || {};
+      this.mapShakeTrigger.start({
+        intensity,
+        duration,
+        frequency,
+        direction
+      });
+    });
+
     this.webSocket.on('open', () => {
       this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
       // Start ping/pong for synchronization
@@ -673,6 +708,79 @@ export class RpgClientEngine<T = any> {
     }
   }
 
+  /**
+   * Stop all currently playing sounds
+   * 
+   * This method stops all sounds that are currently playing.
+   * Useful when changing maps to prevent sound overlap.
+   * 
+   * @example
+   * ```ts
+   * // Stop all sounds
+   * engine.stopAllSounds();
+   * ```
+   */
+  stopAllSounds(): void {
+    this.sounds.forEach((sound) => {
+      if (sound && sound.stop) {
+        sound.stop();
+      }
+    });
+  }
+
+  /**
+   * Set the camera to follow a specific sprite
+   * 
+   * This method changes which sprite the camera viewport should follow.
+   * The camera will smoothly animate to the target sprite if smoothMove options are provided.
+   * 
+   * ## Design
+   * 
+   * The camera follow target is stored in a signal that is read by sprite components.
+   * Each sprite checks if it should be followed by comparing its ID with the target ID.
+   * When smoothMove options are provided, the viewport animation is handled by CanvasEngine's
+   * viewport system.
+   * 
+   * @param targetId - The ID of the sprite to follow. Set to null to follow the current player
+   * @param smoothMove - Animation options. Can be a boolean (default: true) or an object with time and ease
+   * @param smoothMove.time - Duration of the animation in milliseconds (optional)
+   * @param smoothMove.ease - Easing function name from https://easings.net (optional)
+   * 
+   * @example
+   * ```ts
+   * // Follow another player with default smooth animation
+   * engine.setCameraFollow(otherPlayerId, true);
+   * 
+   * // Follow an event with custom smooth animation
+   * engine.setCameraFollow(eventId, {
+   *   time: 1000,
+   *   ease: "easeInOutQuad"
+   * });
+   * 
+   * // Follow without animation (instant)
+   * engine.setCameraFollow(targetId, false);
+   * 
+   * // Return to following current player
+   * engine.setCameraFollow(null);
+   * ```
+   */
+  setCameraFollow(
+    targetId: string | null,
+    smoothMove?: boolean | { time?: number; ease?: string }
+  ): void {
+    // Store smoothMove options for potential future use with viewport animation
+    // For now, we just set the target ID and let CanvasEngine handle the viewport follow
+    // The smoothMove options could be used to configure viewport animation if CanvasEngine supports it
+    this.cameraFollowTargetId.set(targetId);
+    
+    // If smoothMove is an object, we could store it for viewport configuration
+    // This would require integration with CanvasEngine's viewport animation system
+    if (typeof smoothMove === "object" && smoothMove !== null) {
+      // Future: Apply smoothMove.time and smoothMove.ease to viewport animation
+      // For now, CanvasEngine handles viewport following automatically
+    }
+  }
+
   addParticle(particle: any) {
     this.particleSettings.emitters.push(particle)
     return particle;
@@ -682,13 +790,38 @@ export class RpgClientEngine<T = any> {
    * Add a component to render behind sprites
    * Components added with this method will be displayed with a lower z-index than the sprite
    * 
-   * @param component - The component to add behind sprites
-   * @returns The added component
+   * Supports multiple formats:
+   * 1. Direct component: `ShadowComponent`
+   * 2. Configuration object: `{ component: LightHalo, props: {...} }`
+   * 3. With dynamic props: `{ component: LightHalo, props: (object) => {...} }`
+   * 4. With dependencies: `{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }`
+   * 
+   * Components with dependencies will only be displayed when all dependencies are resolved (!= undefined).
+   * The object (sprite) is passed to the dependencies function to allow sprite-specific dependency resolution.
+   * 
+   * @param component - The component to add behind sprites, or a configuration object
+   * @param component.component - The component function to render
+   * @param component.props - Static props object or function that receives the sprite object and returns props
+   * @param component.dependencies - Function that receives the sprite object and returns an array of Signals
+   * @returns The added component or configuration
    * 
    * @example
    * ```ts
    * // Add a shadow component behind all sprites
    * engine.addSpriteComponentBehind(ShadowComponent);
+   * 
+   * // Add a component with static props
+   * engine.addSpriteComponentBehind({ 
+   *   component: LightHalo, 
+   *   props: { radius: 30 } 
+   * });
+   * 
+   * // Add a component with dynamic props and dependencies
+   * engine.addSpriteComponentBehind({ 
+   *   component: HealthBar, 
+   *   props: (object) => ({ hp: object.hp(), maxHp: object.param.maxHp() }),
+   *   dependencies: (object) => [object.hp, object.param.maxHp]
+   * });
    * ```
    */
   addSpriteComponentBehind(component: any) {
@@ -700,16 +833,41 @@ export class RpgClientEngine<T = any> {
    * Add a component to render in front of sprites
    * Components added with this method will be displayed with a higher z-index than the sprite
    * 
-   * @param component - The component to add in front of sprites
-   * @returns The added component
+   * Supports multiple formats:
+   * 1. Direct component: `HealthBarComponent`
+   * 2. Configuration object: `{ component: StatusIndicator, props: {...} }`
+   * 3. With dynamic props: `{ component: HealthBar, props: (object) => {...} }`
+   * 4. With dependencies: `{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }`
+   * 
+   * Components with dependencies will only be displayed when all dependencies are resolved (!= undefined).
+   * The object (sprite) is passed to the dependencies function to allow sprite-specific dependency resolution.
+   * 
+   * @param component - The component to add in front of sprites, or a configuration object
+   * @param component.component - The component function to render
+   * @param component.props - Static props object or function that receives the sprite object and returns props
+   * @param component.dependencies - Function that receives the sprite object and returns an array of Signals
+   * @returns The added component or configuration
    * 
    * @example
    * ```ts
    * // Add a health bar component in front of all sprites
    * engine.addSpriteComponentInFront(HealthBarComponent);
+   * 
+   * // Add a component with static props
+   * engine.addSpriteComponentInFront({ 
+   *   component: StatusIndicator, 
+   *   props: { type: 'poison' } 
+   * });
+   * 
+   * // Add a component with dynamic props and dependencies
+   * engine.addSpriteComponentInFront({ 
+   *   component: HealthBar, 
+   *   props: (object) => ({ hp: object.hp(), maxHp: object.param.maxHp() }),
+   *   dependencies: (object) => [object.hp, object.param.maxHp]
+   * });
    * ```
    */
-  addSpriteComponentInFront(component: any) {
+  addSpriteComponentInFront(component: any | { component: any, props: (object: any) => any, dependencies?: (object: any) => any[] }) {
     this.spriteComponentsInFront.update((components: any[]) => [...components, component])
     return component
   }
@@ -779,6 +937,196 @@ export class RpgClientEngine<T = any> {
     return componentAnimation.instance
   }
 
+  /**
+   * Add a transition to the engine
+   * 
+   * Transitions are screen effects that can be displayed during scene changes,
+   * map loading, or any other moment where a visual transition is needed.
+   * They are displayed on top of the entire canvas and can have custom props
+   * that can be functions (similar to ComponentAnimation).
+   * 
+   * @param transition - The transition configuration
+   * @param transition.id - Unique identifier for the transition
+   * @param transition.component - The component function to render
+   * @param transition.props - Optional props to pass to the component (can be a function)
+   * @returns The added transition configuration
+   * 
+   * @example
+   * ```ts
+   * // Add a fade transition
+   * engine.addTransition({
+   *   id: 'fade',
+   *   component: FadeComponent
+   * });
+   * 
+   * // Add a transition with props
+   * engine.addTransition({
+   *   id: 'slide',
+   *   component: SlideComponent,
+   *   props: { direction: 'left', duration: 500 }
+   * });
+   * 
+   * // Add a transition with function props
+   * engine.addTransition({
+   *   id: 'custom',
+   *   component: CustomTransition,
+   *   props: (engine) => ({ width: engine.width(), height: engine.height() })
+   * });
+   * ```
+   */
+  addTransition(transition: {
+    component: any,
+    id: string,
+    props?: any | ((engine: RpgClientEngine) => any)
+  }) {
+    const instance = new TransitionManager()
+    this.transitions.push({
+      id: transition.id,
+      component: transition.component,
+      props: transition.props,
+      instance: instance,
+      current: instance.current
+    })
+    return transition;
+  }
+
+  /**
+   * Remove a transition from the engine
+   * 
+   * Removes a transition by its ID. This will not affect any currently
+   * running transitions, only prevent new ones from being started.
+   * 
+   * @param id - The unique identifier of the transition to remove
+   * @returns true if the transition was found and removed, false otherwise
+   * 
+   * @example
+   * ```ts
+   * // Remove a transition
+   * engine.removeTransition('fade');
+   * ```
+   */
+  removeTransition(id: string): boolean {
+    const index = this.transitions.findIndex((transition) => transition.id === id);
+    if (index !== -1) {
+      this.transitions.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Modify an existing transition
+   * 
+   * Updates the component or props of an existing transition. This will
+   * not affect any currently running transitions, only future ones.
+   * 
+   * @param id - The unique identifier of the transition to modify
+   * @param updates - The updates to apply (component and/or props)
+   * @returns true if the transition was found and modified, false otherwise
+   * 
+   * @example
+   * ```ts
+   * // Update transition props
+   * engine.modifyTransition('fade', {
+   *   props: { duration: 2000, color: 'white' }
+   * });
+   * 
+   * // Update transition component
+   * engine.modifyTransition('fade', {
+   *   component: NewFadeComponent
+   * });
+   * ```
+   */
+  modifyTransition(id: string, updates: {
+    component?: any,
+    props?: any | ((engine: RpgClientEngine) => any)
+  }): boolean {
+    const transition = this.transitions.find((transition) => transition.id === id);
+    if (!transition) {
+      return false;
+    }
+    if (updates.component !== undefined) {
+      transition.component = updates.component;
+    }
+    if (updates.props !== undefined) {
+      transition.props = updates.props;
+    }
+    return true;
+  }
+
+  /**
+   * Get a transition by its ID
+   * 
+   * Retrieves the TransitionManager instance for a specific transition,
+   * which can be used to start the transition.
+   * 
+   * @param id - The unique identifier of the transition
+   * @returns The TransitionManager instance for the transition
+   * @throws Error if the transition is not found
+   * 
+   * @example
+   * ```ts
+   * // Get a transition and start it
+   * const fadeTransition = engine.getTransition('fade');
+   * fadeTransition.start({ duration: 1000 });
+   * ```
+   */
+  getTransition(id: string): TransitionManager {
+    const transition = this.transitions.find((transition) => transition.id === id)
+    if (!transition) {
+      throw new Error(`Transition with id ${id} not found`)
+    }
+    return transition.instance
+  }
+
+  /**
+   * Start a transition
+   * 
+   * Convenience method to start a transition by its ID. This combines
+   * getTransition and start into a single call. The transition will
+   * automatically receive an onFinish callback to remove itself when done.
+   * 
+   * @param id - The unique identifier of the transition to start
+   * @param props - Additional props to pass to the transition component
+   * @returns The created transition object
+   * 
+   * @example
+   * ```ts
+   * // Start a fade transition
+   * engine.startTransition('fade', { duration: 1000, color: 'black' });
+   * 
+   * // Start with onFinish callback
+   * engine.startTransition('fade', {
+   *   duration: 1000,
+   *   onFinish: () => console.log('Fade complete')
+   * });
+   * ```
+   */
+  startTransition(id: string, props: any = {}) {
+    const transition = this.transitions.find((t) => t.id === id);
+    if (!transition) {
+      throw new Error(`Transition with id ${id} not found`);
+    }
+
+    // Get base props (can be a function or object)
+    let baseProps = {};
+    if (transition.props) {
+      if (typeof transition.props === 'function') {
+        baseProps = transition.props(this);
+      } else {
+        baseProps = transition.props;
+      }
+    }
+
+    // Merge base props with provided props (provided props take precedence)
+    const finalProps = {
+      ...baseProps,
+      ...props,
+    };
+
+    return transition.instance.start(finalProps);
+  }
+
   async processInput({ input }: { input: Direction }) {
     const timestamp = Date.now();
     let frame: number;
@@ -900,6 +1248,72 @@ export class RpgClientEngine<T = any> {
     this.inputFrameCounter = 0;
   }
 
+  /**
+   * Trigger a flash animation on a sprite
+   * 
+   * This method allows you to trigger a flash effect on any sprite from client-side code.
+   * The flash can be configured with various options including type (alpha, tint, or both),
+   * duration, cycles, and color.
+   * 
+   * ## Design
+   * 
+   * The flash is applied directly to the sprite object using its flash trigger.
+   * This is useful for client-side visual feedback, UI interactions, or local effects
+   * that don't need to be synchronized with the server.
+   * 
+   * @param spriteId - The ID of the sprite to flash. If not provided, flashes the current player
+   * @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
+   * // Flash the current player with default settings
+   * engine.flash();
+   * 
+   * // Flash a specific sprite with red tint
+   * engine.flash('sprite-id', { type: 'tint', tint: 0xff0000 });
+   * 
+   * // Flash with both alpha and tint for dramatic effect
+   * engine.flash(undefined, { 
+   *   type: 'both', 
+   *   alpha: 0.5, 
+   *   tint: 0xff0000,
+   *   duration: 200,
+   *   cycles: 2
+   * });
+   * 
+   * // Quick damage flash on current player
+   * engine.flash(undefined, { 
+   *   type: 'tint', 
+   *   tint: 'red', 
+   *   duration: 150,
+   *   cycles: 1
+   * });
+   * ```
+   */
+  flash(
+    spriteId?: string,
+    options?: {
+      type?: 'alpha' | 'tint' | 'both';
+      duration?: number;
+      cycles?: number;
+      alpha?: number;
+      tint?: number | string;
+    }
+  ): void {
+    const targetId = spriteId || this.playerId;
+    if (!targetId) return;
+
+    const sprite = this.sceneMap.getObjectById(targetId);
+    if (sprite && typeof sprite.flash === 'function') {
+      sprite.flash(options);
+    }
+  }
+
   private applyServerAck(ack: { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction }) {
     if (this.predictionEnabled && this.prediction) {
       this.prediction.applyServerAck({