@rpgjs/client 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/Sound.ts

@@ -0,0 +1,253 @@
+import { Howler } from 'canvasengine';
+import { RpgClientEngine } from './RpgClientEngine';
+import { inject } from './core/inject';
+
+/**
+ * Sound decorator options
+ * 
+ * Defines the configuration for a sound that can be played in the game.
+ * The sound can be a single file or multiple files (for different formats).
+ * 
+ * @interface SoundOptions
+ */
+export interface SoundOptions {
+  /**
+   * Sound identifier. Used to retrieve the sound later with RpgSound.get()
+   * 
+   * @type {string}
+   */
+  id?: string;
+
+  /**
+   * Single sound file path. Use require() to wrap the path.
+   * 
+   * @type {string}
+   * @example
+   * sound: require('./assets/sound.ogg')
+   */
+  sound?: string;
+
+  /**
+   * Multiple sounds with different IDs. The key is the sound ID and the value is the file path.
+   * Use require() to wrap each path.
+   * 
+   * @type {{ [id: string]: string }}
+   * @example
+   * sounds: {
+   *   hero: require('./assets/hero.ogg'),
+   *   monster: require('./assets/monster.ogg')
+   * }
+   */
+  sounds?: { [id: string]: string };
+
+  /**
+   * Whether the sound should loop when it finishes playing.
+   * 
+   * @type {boolean}
+   * @default false
+   */
+  loop?: boolean;
+
+  /**
+   * Volume level (0.0 to 1.0).
+   * 
+   * @type {number}
+   * @default 1.0
+   */
+  volume?: number;
+}
+
+/**
+ * Metadata stored on the class decorated with @Sound
+ * 
+ * @interface SoundMetadata
+ */
+interface SoundMetadata {
+  id?: string;
+  sound?: string;
+  sounds?: { [id: string]: string };
+  loop?: boolean;
+  volume?: number;
+}
+
+const SOUND_METADATA_KEY = Symbol('rpgjs:sound');
+
+/**
+ * Sound decorator
+ * 
+ * Decorates a class to define a sound configuration. The decorated class can be
+ * added to the RpgClient module configuration, and the sound will be automatically
+ * registered and available through RpgSound.get().
+ * 
+ * ## Design
+ * 
+ * The decorator stores metadata on the class that is later used by the module loader
+ * to register sounds with the engine. The sound is created using Howler.js for
+ * advanced audio features like looping, volume control, and cross-browser compatibility.
+ * 
+ * @param options - Sound configuration options
+ * 
+ * @example
+ * ```ts
+ * import { Sound } from '@rpgjs/client'
+ * 
+ * @Sound({
+ *   id: 'town-music',
+ *   sound: require('./sound/town.ogg'),
+ *   loop: true,
+ *   volume: 0.5
+ * })
+ * export class TownMusic {}
+ * 
+ * // Multiple sounds in one class
+ * @Sound({
+ *   sounds: {
+ *     hero: require('./assets/hero.ogg'),
+ *     monster: require('./assets/monster.ogg')
+ *   },
+ *   loop: true
+ * })
+ * export class CharacterSounds {}
+ * ```
+ */
+export function Sound(options: SoundOptions) {
+  return function <T extends { new (...args: any[]): {} }>(constructor: T) {
+    const metadata: SoundMetadata = {
+      id: options.id,
+      sound: options.sound,
+      sounds: options.sounds,
+      loop: options.loop,
+      volume: options.volume,
+    };
+
+    // Store metadata on the class
+    (constructor as any)[SOUND_METADATA_KEY] = metadata;
+
+    return constructor;
+  };
+}
+
+/**
+ * Get sound metadata from a decorated class
+ * 
+ * @param soundClass - The class decorated with @Sound
+ * @returns The sound metadata or undefined
+ */
+export function getSoundMetadata(soundClass: any): SoundMetadata | undefined {
+  return (soundClass as any)[SOUND_METADATA_KEY];
+}
+
+/**
+ * RpgSound class
+ * 
+ * Provides a unified API to manage sounds in the game. Uses Howler.js internally
+ * for advanced audio features. Sounds can be retrieved by ID and controlled
+ * using Howler.js methods.
+ * 
+ * ## Design
+ * 
+ * RpgSound acts as a facade over Howler.js, providing easy access to sounds
+ * registered in the engine. It supports both individual sound control and
+ * global sound management (volume, mute, etc.).
+ * 
+ * @example
+ * ```ts
+ * import { RpgSound } from '@rpgjs/client'
+ * 
+ * // Play a sound
+ * RpgSound.get('town-music').play()
+ * 
+ * // Control volume
+ * RpgSound.get('town-music').volume(0.5)
+ * 
+ * // Stop a sound
+ * RpgSound.get('town-music').stop()
+ * 
+ * // Global volume control
+ * RpgSound.global.volume(0.2)
+ * ```
+ */
+export class RpgSound {
+  private static engine: RpgClientEngine | null = null;
+
+  /**
+   * Initialize RpgSound with the engine instance
+   * 
+   * This is called automatically by the engine during initialization.
+   * 
+   * @param engine - The RpgClientEngine instance
+   */
+  static init(engine: RpgClientEngine): void {
+    RpgSound.engine = engine;
+  }
+
+  /**
+   * Get a sound by its ID
+   * 
+   * Retrieves a Howler sound instance from the engine's sound cache.
+   * The sound must be registered beforehand (via @Sound decorator or manually).
+   * 
+   * @param id - The sound identifier
+   * @returns The Howler sound instance, or undefined if not found
+   * 
+   * @example
+   * ```ts
+   * // Get and play a sound
+   * const sound = RpgSound.get('town-music');
+   * if (sound) {
+   *   sound.play();
+   * }
+   * 
+   * // Chain methods
+   * RpgSound.get('battle-theme')?.volume(0.8).play();
+   * ```
+   */
+  static get(id: string): any {
+    if (!RpgSound.engine) {
+      console.warn('RpgSound not initialized. Make sure the engine has started.');
+      return undefined;
+    }
+
+    const sound = RpgSound.engine.sounds.get(id);
+    if (!sound) {
+      console.warn(`Sound with id "${id}" not found`);
+      return undefined;
+    }
+
+    // If the sound is a Howler instance, return it directly
+    if (sound && typeof sound.play === 'function') {
+      return sound;
+    }
+
+    // If the sound has a src property, try to create a Howler instance
+    if (sound && sound.src) {
+      // This should have been handled during addSound, but just in case
+      return sound;
+    }
+
+    return sound;
+  }
+
+  /**
+   * Global Howler instance for managing all sounds
+   * 
+   * Provides access to Howler.js global methods for controlling all sounds
+   * at once (volume, mute, etc.).
+   * 
+   * @example
+   * ```ts
+   * // Set global volume to 20%
+   * RpgSound.global.volume(0.2)
+   * 
+   * // Mute all sounds
+   * RpgSound.global.mute(true)
+   * 
+   * // Unmute all sounds
+   * RpgSound.global.mute(false)
+   * ```
+   */
+  static get global(): typeof Howler {
+    return Howler;
+  }
+}
+

package/src/components/{effects → animations}/animation.ce

@@ -1,19 +1,16 @@
 <Sprite sheet x y anchor={0.5} />
 
 <script>
-  import { signal } from "canvasengine";
   import { RpgClientEngine } from "../../RpgClientEngine";
   import { inject } from "../../core/inject";
 
-  const { x, y, name, onFinish } = defineProps();
+  const { x, y, animationName, graphic, onFinish } = defineProps();
 
   const client = inject(RpgClientEngine);
-  const spritesheets = client.spritesheets;
 
   const sheet = {
-    definition: spritesheets.get(name()),
-    playing: 'default',
+    definition: client.getSpriteSheet(graphic()),
+    playing: animationName() ?? 'default',
     onFinish
   };
-
 </script>

package/src/components/{effects → animations}/index.ts

@@ -1,7 +1,7 @@
 import Hit from "./hit.ce";
 import Animation from "./animation.ce";
 
-export const PrebuiltEffects = {
+export const PrebuiltComponentAnimations = {
     Hit,
     Animation
 }

package/src/components/character.ce

@@ -1,55 +1,71 @@
-<Container x y zIndex={y} viewportFollow={isMe} controls>
+<Container x={smoothX} y={smoothY} zIndex={y} viewportFollow={isMe} controls onBeforeDestroy visible>
+  @for (component of componentsBehind) {
+    <Container>
+      <component object />
+    </Container>
+  } 
   <Particle emit={@emitParticleTrigger} settings={@particleSettings} zIndex={1000} name={particleName} />
-  @for (graphicId of graphics) {
-    <Sprite sheet={@sheet(@graphicId)} direction tint />
-  }
-  <!-- <Ellipse 
-    x={shadow.@x} 
-    y={shadow.@y} 
-    width={shadow.@width} 
-    height={shadow.@height} 
-    color="black" 
-    blur={10} 
-    alpha={0.5}
-  /> -->
+  <Container>
+    @for (graphicObj of graphicsSignals) {
+      <Sprite sheet={@sheet(@graphicObj)} direction tint hitbox />
+    }
+  </Container>
+  @for (component of componentsInFront) {
+    <Container>
+      <component object />
+    </Container>
+  } 
 </Container>
 
 <script>
-  import { signal, effect, mount, computed } from "canvasengine";
+  import { signal, effect, mount, computed, tick, animatedSignal } from "canvasengine";
+  import { lastValueFrom, combineLatest, pairwise, filter, map, startWith } from "rxjs";
   import { Particle } from "@canvasengine/presets";
-  import { GameEngineToken } from "@rpgjs/common";
+  import { GameEngineToken, ModulesToken } from "@rpgjs/common";
   import { RpgClientEngine } from "../RpgClientEngine";
   import { inject } from "../core/inject";  
   import { Direction } from "@rpgjs/common";
   import Hit from "./effects/hit.ce";
+  import PlayerComponents from "./player-components.ce";
 
-  const { object, id, isMe } = defineProps();
+  const { object, id } = defineProps();
 
   const client = inject(RpgClientEngine);
+  const hooks = inject(ModulesToken);
 
   const spritesheets = client.spritesheets;
+  const playerId = client.playerId;
+  const componentsBehind = client.spriteComponentsBehind;
+  const componentsInFront = client.spriteComponentsInFront;
+  const isMe = computed(() => id() === playerId);
+
+  const { 
+    x, 
+    y, 
+    tint, 
+    direction, 
+    animationName, 
+    animationCurrentIndex,
+    emitParticleTrigger, 
+    particleName, 
+    graphics, 
+    hitbox,
+    isConnected,
+    graphicsSignals
+  } = object;
 
-  const x = object.x;
-  const y = object.y;
-  const tint = object.tint;
-  const direction = object.direction;
-  const animationName = object.animationName;
-  const emitParticleTrigger = object.emitParticleTrigger;
   const particleSettings = client.particleSettings;
-  const particleName = object.particleName;
-  const graphics = object.graphics;
-
-  const hitbox = object.hitbox;
-  const widthShadow = 10;
-  const shadow = computed(() => ({
-    x: hitbox().w / 2,
-    y: hitbox().h - (hitbox().h / 2),
-    width: hitbox().w + widthShadow,
-    height: hitbox().h,
-  }))
+
   const canControls = () => isMe() && object.canMove()
   const keyboardControls = client.globalConfig.keyboardControls;
 
+  const visible = computed(() => {
+    if (object.type === 'event') {
+      return true
+    }
+    return isConnected()
+  });
+
   const controls = signal({
     down: {
       repeat: true,
@@ -84,7 +100,7 @@
       keyDown() {
         if (canControls()) {
           client.processAction({ action: 'action' })
-          // particleName.set('hit') 
+           // particleName.set('hit') 
           // emitParticleTrigger.start()
           // object.flash('red')
         }
@@ -92,13 +108,125 @@
     },
   });
 
-  const sheet = (graphicId) => {
+  const smoothX = animatedSignal(x(), {
+    duration: isMe() ? 0 : 0
+  });
+
+  const smoothY = animatedSignal(y(), {
+    duration: isMe() ? 0 : 0,
+  });
+
+  const realAnimationName = signal(animationName());
+
+  const xSubscription = x.observable.subscribe((value) => {
+    smoothX.set(value);
+  });
+
+  const ySubscription = y.observable.subscribe((value) => {
+    smoothY.set(value);
+  });
+  
+  const sheet = (graphicObject) => {
     return {
-      definition: spritesheets.get(graphicId),
-      playing: animationName,
+      definition: graphicObject,
+      playing: realAnimationName,
       params: {
         direction
       },
+      onFinish() {
+        animationCurrentIndex.update(index => index + 1)
+      }
     };
   }
+
+  // Combine animation change detection with movement state from smoothX/smoothY
+  const movementAnimations = ['walk', 'stand'];
+  const epsilon = 0; // movement threshold to consider the easing still running
+
+  const stateX$ = smoothX.animatedState.observable;
+  const stateY$ = smoothY.animatedState.observable;
+  const animationName$ = animationName.observable;
+
+  const moving$ = combineLatest([stateX$, stateY$]).pipe(
+    map(([sx, sy]) => {
+      const xFinished = Math.abs(sx.value.current - sx.value.end) <= epsilon;
+      const yFinished = Math.abs(sy.value.current - sy.value.end) <= epsilon;
+      return !xFinished || !yFinished; // moving if X or Y is not finished
+    }),
+    startWith(false)
+  );
+
+  const animationChange$ = animationName$.pipe(
+    startWith(animationName()),
+    pairwise(),
+    filter(([prev, curr]) => prev !== curr)
+  );
+
+  const animationMovementSubscription = combineLatest([animationChange$, moving$]).subscribe(([[prev, curr], isMoving]) => {
+    if (curr == 'stand' && !isMoving) {
+      realAnimationName.set(curr);
+    }
+    else if (curr == 'walk' && isMoving) {
+      realAnimationName.set(curr);
+    }
+    else if (!movementAnimations.includes(curr)) {
+      realAnimationName.set(curr);
+    }
+    if (!isMoving && object.animationIsPlaying && object.animationIsPlaying()) {
+      if (movementAnimations.includes(curr)) {
+        if (typeof object.resetAnimationState === 'function') {
+          object.resetAnimationState();
+        }
+      }
+    }
+  });
+
+  /**
+   * Cleanup subscriptions and call hooks before sprite destruction.
+   *
+   * # Design
+   * - Prevent memory leaks by unsubscribing from all local subscriptions created in this component.
+   * - Execute destruction hooks to notify modules and scene map of sprite removal.
+   *
+   * @example
+   * await onBeforeDestroy();
+   */
+  const onBeforeDestroy = async () => {
+    animationMovementSubscription.unsubscribe();
+    xSubscription.unsubscribe();
+    ySubscription.unsubscribe();
+    await lastValueFrom(hooks.callHooks("client-sprite-onDestroy", object)) 
+    await lastValueFrom(hooks.callHooks("client-sceneMap-onRemoveSprite", client.sceneMap, object))
+  }
+
+  mount((element) => {
+    hooks.callHooks("client-sprite-onAdd", object).subscribe()
+    hooks.callHooks("client-sceneMap-onAddSprite", client.sceneMap, object).subscribe()
+  })
+
+  /**
+   * Calculate Y position for components above player
+   */
+  const getComponentsTopY = () => {
+    const layout = componentsTopData()?.layout || {};
+    const hitboxValue = typeof hitbox === 'function' ? hitbox() : hitbox;
+    const playerHeight = hitboxValue?.h || 32;
+    const marginBottom = layout.marginBottom ?? 0;
+    return -(playerHeight / 2) - marginBottom;
+  };
+
+  /**
+   * Calculate Y position for components below player
+   */
+  const getComponentsBottomY = () => {
+    const layout = componentsBottomData()?.layout || {};
+    const hitboxValue = typeof hitbox === 'function' ? hitbox() : hitbox;
+    const playerHeight = hitboxValue?.h || 32;
+    const marginTop = layout.marginTop ?? 0;
+    return (playerHeight / 2) + marginTop;
+  };
+
+  tick(() => {
+    hooks.callHooks("client-sprite-onUpdate").subscribe()
+  })
 </script>

package/src/components/dynamics/parse-value.ts

@@ -0,0 +1,80 @@
+import { computed } from "canvasengine";
+
+interface MatchResult {
+    property: string;
+    fullMatch: string;
+    index: number;
+}
+
+export const parseDynamicValue = (value: any, object?: any) => {
+    if (typeof value !== 'string') {
+        return computed(() => String(value ?? ''));
+    }
+
+    // Find all dynamic references like {propertyName}
+    const pattern = /\{([^}]+)\}/g;
+    const matches: MatchResult[] = [];
+    let match;
+    
+    while ((match = pattern.exec(value)) !== null) {
+        matches.push({
+            property: match[1],
+            fullMatch: match[0],
+            index: match.index!
+        });
+    }
+
+    // If no dynamic references found, return simple computed
+    if (matches.length === 0) {
+        return computed(() => value);
+    }
+
+    // Create computed that tracks all referenced signals
+    return computed(() => {
+        let result = value;
+        
+        // Replace from end to start to preserve indices
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const { property, fullMatch } = matches[i];
+            
+            // Try to access the property from the object
+            // Support nested properties like {param.maxHp}
+            let propertyValue = '';
+            try {
+                const propertyPath = property.split('.');
+                let currentValue = object;
+                
+                for (let j = 0; j < propertyPath.length; j++) {
+                    const prop = propertyPath[j];
+                    
+                    // Check if currentValue is a signal (function) and call it
+                    if (typeof currentValue === 'function') {
+                        currentValue = currentValue();
+                    }
+                    
+                    // Access the property
+                    if (currentValue && typeof currentValue === 'object' && prop in currentValue) {
+                        currentValue = currentValue[prop];
+                    } else {
+                        currentValue = undefined;
+                        break;
+                    }
+                }
+                
+                // If the final value is a signal, call it
+                if (typeof currentValue === 'function') {
+                    currentValue = currentValue();
+                }
+                
+                propertyValue = currentValue != null ? String(currentValue) : '';
+            } catch (error) {
+                // If property doesn't exist or can't be accessed, use empty string
+                propertyValue = '';
+            }
+            
+            result = result.replace(fullMatch, propertyValue);
+        }
+        
+        return result;
+    });
+};