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

package/src/Game/Object.ts

@@ -19,6 +19,7 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
   frames: { x: number; y: number; ts: number }[] = [];
   graphicsSignals = signal<any[]>([]);
   _component = {} // temporary component memory
+  flashTrigger = trigger();
 
   constructor() {
     super();
@@ -86,14 +87,87 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
 
   private animationSubscription?: Subscription;
 
-  flash(color: string, duration: number = 100) {
-    return new Promise((resolve) => {
-      const lastTint = this.tint();
-      this.tint.set(color);
-      setTimeout(() => {
-        this.tint.set(lastTint);
-        resolve(true);
-      }, duration);
+  /**
+   * 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?: {
+    type?: 'alpha' | 'tint' | 'both';
+    duration?: number;
+    cycles?: number;
+    alpha?: number;
+    tint?: number | string;
+  }): 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,
     });
   }
 

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 { signal, bootstrapCanvas, KeyboardControls, Howl, trigger } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "./services/AbstractSocket";
 import { LoadMapService, LoadMapToken } from "./services/loadMap";
 import { RpgSound } from "./Sound";
@@ -20,7 +20,6 @@ import {
   PredictionController,
   type PredictionState,
 } from "@rpgjs/common";
-import { KeyboardControls } from "./services/keyboardControls";
 
 export class RpgClientEngine<T = any> {
   private guiService: RpgGui;
@@ -49,6 +48,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>;
@@ -214,6 +217,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 +247,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 +705,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;
@@ -900,6 +1005,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({

package/src/components/character.ce

@@ -1,4 +1,4 @@
-<Container x={smoothX} y={smoothY} zIndex={y} viewportFollow={isMe} controls onBeforeDestroy visible>
+<Container x={smoothX} y={smoothY} zIndex={y} viewportFollow={shouldFollowCamera} controls onBeforeDestroy visible >
   @for (component of componentsBehind) {
     <Container>
       <component object />
@@ -7,7 +7,7 @@
   <Particle emit={@emitParticleTrigger} settings={@particleSettings} zIndex={1000} name={particleName} />
   <Container>
     @for (graphicObj of graphicsSignals) {
-      <Sprite sheet={@sheet(@graphicObj)} direction tint hitbox />
+      <Sprite sheet={@sheet(@graphicObj)} direction tint hitbox flash={flashConfig}  />
     }
   </Container>
   @for (component of componentsInFront) {
@@ -29,7 +29,8 @@
 </Container>
 
 <script>
-  import { signal, effect, mount, computed, tick, animatedSignal } from "canvasengine";
+  import { signal, effect, mount, computed, tick, animatedSignal, on } from "canvasengine";
+
   import { lastValueFrom, combineLatest, pairwise, filter, map, startWith } from "rxjs";
   import { Particle } from "@canvasengine/presets";
   import { GameEngineToken, ModulesToken } from "@rpgjs/common";
@@ -51,6 +52,23 @@
   const componentsBehind = client.spriteComponentsBehind;
   const componentsInFront = client.spriteComponentsInFront;
   const isMe = computed(() => id() === playerId);
+  
+  /**
+   * Determine if the camera should follow this sprite
+   * 
+   * The camera follows this sprite if:
+   * - It's explicitly set as the camera follow target, OR
+   * - It's the current player and no explicit target is set (default behavior)
+   */
+  const shouldFollowCamera = computed(() => {
+    const cameraTargetId = client.cameraFollowTargetId();
+    // If a target is explicitly set, only follow if this sprite is the target
+    if (cameraTargetId !== null) {
+      return id() === cameraTargetId;
+    }
+    // Otherwise, follow the current player (default behavior)
+    return isMe();
+  });
 
   /**
    * Get all attached GUI components that should be rendered on sprites
@@ -80,9 +98,51 @@
     graphics, 
     hitbox,
     isConnected,
-    graphicsSignals
+    graphicsSignals,
+    flashTrigger
   } = object;
 
+  /**
+   * Flash configuration signals for dynamic options
+   * These signals are updated when the flash trigger is activated with options
+   */
+  const flashType = signal<'alpha' | 'tint' | 'both'>('alpha');
+  const flashDuration = signal(300);
+  const flashCycles = signal(1);
+  const flashAlpha = signal(0.3);
+  const flashTint = signal(0xffffff);
+
+  /**
+   * Listen to flash trigger to update configuration dynamically
+   * When flash is triggered with options, update the signals
+   */
+  on(flashTrigger, (data) => {
+    if (data && typeof data === 'object') {
+      if (data.type !== undefined) flashType.set(data.type);
+      if (data.duration !== undefined) flashDuration.set(data.duration);
+      if (data.cycles !== undefined) flashCycles.set(data.cycles);
+      if (data.alpha !== undefined) flashAlpha.set(data.alpha);
+      if (data.tint !== undefined) flashTint.set(data.tint);
+    }
+  });
+
+  /**
+   * Flash configuration for the sprite
+   * 
+   * This configuration is used by the flash directive to create visual feedback effects.
+   * The flash trigger is exposed through the object, allowing both server events and
+   * client-side code to trigger flash animations. Options can be passed dynamically
+   * through the trigger, which updates the reactive signals.
+   */
+  const flashConfig = computed(() => ({
+    trigger: flashTrigger,
+    type: flashType(),
+    duration: flashDuration(),
+    cycles: flashCycles(),
+    alpha: flashAlpha(),
+    tint: flashTint(),
+  }));
+
   const particleSettings = client.particleSettings;
 
   const canControls = () => isMe() && object.canMove()
@@ -135,6 +195,9 @@
         }
       },
     },
+    gamepad: {
+      enabled: true
+    }
   });
 
   const smoothX = animatedSignal(x(), {

package/src/components/prebuilt/index.ts

@@ -20,3 +20,4 @@ export { default as HpBar } from './hp-bar.ce';
 
 
 
+

package/src/components/scenes/draw-map.ce

@@ -1,4 +1,4 @@
-<Container sound={backgroundMusic} >
+<Container sound={backgroundMusic} shake={shakeConfig}>
   <Container sound={backgroundAmbientSound} />
 
   <sceneComponent() data={map.@data} params={map.@params} />
@@ -13,7 +13,8 @@
 </Container>
 
 <script>
-    import { effect, signal, computed, mount } from 'canvasengine'
+    import { NoiseFilter } from 'pixi-filters';
+    import { effect, signal, computed, mount, on, tick } from 'canvasengine'
     import { inject } from "../../core/inject";
     import { RpgClientEngine } from "../../RpgClientEngine";
 
@@ -26,7 +27,7 @@
     const animations = engine.sceneMap.animations
     const backgroundMusic = { src: mapParams?.backgroundMusic, autoplay: true, loop: true }
     const backgroundAmbientSound = { src: mapParams?.backgroundAmbientSound, autoplay: true, loop: true }
-    
+
     const data = signal(map().data)
 
     const scale = mapParams?.scale || 1
@@ -36,4 +37,12 @@
     const clamp = {
       direction: "all"
     }
+
+    const shakeConfig = {
+      trigger: engine.mapShakeTrigger,
+      intensity: 10,
+      duration: 500,
+      frequency: 10,
+      direction: 'both'
+    }
 </script>

package/src/index.ts

@@ -15,4 +15,5 @@ export * from "./components/gui";
 export * from "./Sound";
 export * from "./Resource";
 export { Context } from "@signe/di";
-export * from "./services/keyboardControls";
+export { KeyboardControls, Input } from "canvasengine";
+export { Control } from "./services/keyboardControls";

package/src/module.ts

@@ -1,15 +1,69 @@
 import { findModules, provideModules } from "@rpgjs/common";
+import { FactoryProvider } from "@signe/di";
 import { RpgClientEngine } from "./RpgClientEngine";
 import { RpgClient } from "./RpgClient";
 import { inject } from "@signe/di";
 import { RpgGui } from "./Gui/Gui";
 import { getSoundMetadata } from "./Sound";
 
-export function provideClientModules(modules: RpgClient[]) {
+/**
+ * Type for client modules that can be either:
+ * - An object implementing RpgClient interface
+ * - A class decorated with @RpgModule decorator
+ */
+export type RpgClientModule = RpgClient | (new () => any);
+
+/**
+ * Provides client modules configuration to Dependency Injection
+ * 
+ * This function accepts an array of client modules that can be either:
+ * - Objects implementing the RpgClient interface
+ * - Classes decorated with the @RpgModule decorator (which will be instantiated)
+ * 
+ * @param modules - Array of client modules (objects or classes)
+ * @returns FactoryProvider configuration for DI
+ * @example
+ * ```ts
+ * // Using an object
+ * provideClientModules([
+ *   {
+ *     engine: {
+ *       onConnected(engine) {
+ *         console.log('Client connected')
+ *       }
+ *     }
+ *   }
+ * ])
+ * 
+ * // Using a decorated class
+ * @RpgModule<RpgClient>({
+ *   engine: {
+ *     onStart(engine) {
+ *       console.log('Client started')
+ *     }
+ *   }
+ * })
+ * class MyClientModule {}
+ * 
+ * provideClientModules([MyClientModule])
+ * ```
+ */
+export function provideClientModules(modules: RpgClientModule[]): FactoryProvider {
   return provideModules(modules, "client", (modules, context) => {
     const mainModuleClient = findModules(context, 'Client')
     modules = [...mainModuleClient, ...modules]
     modules = modules.map((module) => {
+      // If module is a class (constructor function), instantiate it
+      // The RpgModule decorator adds properties to the prototype, which will be accessible via the instance
+      if (typeof module === 'function') {
+        const instance = new module() as any;
+        // Copy all enumerable properties (including from prototype) to a plain object
+        const moduleObj: any = {};
+        for (const key in instance) {
+          moduleObj[key] = instance[key];
+        }
+        module = moduleObj;
+      }
       if ('client' in module) {
         module = module.client as any;
       }
@@ -84,7 +138,7 @@ export function provideClientModules(modules: RpgClient[]) {
         const gui = [...module.gui];
         module.gui = {
           load: (engine: RpgClientEngine) => {
-            const guiService = inject(engine.context, RpgGui);
+            const guiService = inject(engine.context, RpgGui) as RpgGui;
             gui.forEach((gui) => {
               guiService.add(gui);
             });

package/src/services/keyboardControls.ts

@@ -1,4 +1,16 @@
-export const KeyboardControls = "KeyboardControlsToken";
+import { KeyboardControls  } from "canvasengine";
+
+export enum Control {
+  Action = 'action',
+  Attack = 'attack',
+  Defense = 'defense',
+  Skill = 'skill',
+  Back = 'back',
+  Up = 1,
+  Down = 3,
+  Right = 2,
+  Left = 4
+}
 
 export function provideKeyboardControls() {
   return {