canvasengine 2.0.0-beta.4 → 2.0.0-beta.41

package/src/components/Sprite.ts

@@ -1,5 +1,7 @@
-import { computed, effect, isSignal, Signal, WritableSignal } from "@signe/reactive";
+import { Howl } from 'howler';
+import { computed, effect, isSignal, Signal } from "@signe/reactive";
 import {
+  Application,
   Assets,
   Container,
   Sprite as PixiSprite,
@@ -10,7 +12,9 @@ import { Subscription } from "rxjs";
 import {
   Element,
   createComponent,
+  isElement,
   registerComponent,
+  isElementFrozen,
 } from "../engine/reactive";
 import { arrayEquals, isFunction } from "../engine/utils";
 import { DisplayObject } from "./DisplayObject";
@@ -24,6 +28,8 @@ import {
 import { ComponentFunction } from "../engine/signal";
 import { DisplayObjectProps } from "./types/DisplayObject";
 import { AnimatedSignal, isAnimatedSignal } from "../engine/animation";
+import { Layout } from '@pixi/layout';
+import { GlobalAssetLoader } from "../utils/GlobalAssetLoader";
 
 const log = console.log;
 
@@ -73,15 +79,127 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
   private subscriptionSheet: Subscription[] = [];
   private sheetParams: any = {};
   private sheetCurrentAnimation: string = StandardAnimation.Stand;
+  private app: Application | null = null;
   onFinish: () => void;
+  private globalLoader: GlobalAssetLoader | null = null;
+  private trackedAssetIds: Set<string> = new Set();
+
+  get renderer() {
+    return this.app?.renderer;
+  }
 
   private currentAnimationContainer: Container | null = null;
 
+  /**
+   * Auto-detects image dimensions by loading the image and reading its natural size
+   * This is used when width/height are not explicitly provided in the spritesheet definition
+   * 
+   * @param imagePath - Path to the image file
+   * @returns Object containing the detected width and height of the image
+   * 
+   * @example
+   * ```typescript
+   * const { width, height } = await sprite.detectImageDimensions('path/to/image.png');
+   * // width: 256, height: 128
+   * ```
+   */
+  private async detectImageDimensions(imagePath: string): Promise<{ width: number; height: number }> {
+    if (!imagePath || typeof imagePath !== 'string' || imagePath.trim() === '') {
+      throw new Error(`Invalid image path provided to detectImageDimensions: ${imagePath}`);
+    }
+
+    // Register asset in global loader if available
+    let assetId: string | null = null;
+    if (this.globalLoader) {
+      assetId = this.globalLoader.registerAsset(imagePath);
+      this.trackedAssetIds.add(assetId);
+    }
+
+    const texture = await Assets.load(imagePath, (progress) => {
+      if (this.globalLoader && assetId) {
+        this.globalLoader.updateProgress(assetId, progress);
+      }
+    });
+
+    // Mark as complete
+    if (this.globalLoader && assetId) {
+      this.globalLoader.completeAsset(assetId);
+    }
+
+    return {
+      width: texture.width,
+      height: texture.height,
+    };
+  }
+
+  /**
+   * Creates textures from a spritesheet image by cutting it into frames
+   * Automatically detects image dimensions if width/height are not provided
+   * 
+   * @param options - Texture options containing image path, dimensions, and frame configuration
+   * @returns A 2D array of textures organized by rows and columns
+   * 
+   * @example
+   * ```typescript
+   * // With explicit dimensions
+   * const textures = await sprite.createTextures({
+   *   image: 'path/to/image.png',
+   *   width: 256,
+   *   height: 128,
+   *   framesWidth: 4,
+   *   framesHeight: 2,
+   *   spriteWidth: 64,
+   *   spriteHeight: 64
+   * });
+   * 
+   * // Without dimensions (automatically detected)
+   * const textures = await sprite.createTextures({
+   *   image: 'path/to/image.png',
+   *   framesWidth: 4,
+   *   framesHeight: 2,
+   *   spriteWidth: 64,
+   *   spriteHeight: 64
+   * });
+   * ```
+   */
   private async createTextures(
     options: Required<TextureOptionsMerging>
   ): Promise<Texture[][]> {
-    const { width, height, framesHeight, framesWidth, image, offset } = options;
-    const texture = await Assets.load(image);
+    let { width, height, framesHeight, framesWidth, image, offset } = options;
+
+    if (!image || typeof image !== 'string' || image.trim() === '') {
+      console.warn('Invalid image path provided to createTextures:', image);
+      return [];
+    }
+
+    // Register asset in global loader if available
+    let assetId: string | null = null;
+    if (this.globalLoader) {
+      assetId = this.globalLoader.registerAsset(image);
+      this.trackedAssetIds.add(assetId);
+    }
+
+    const texture = await Assets.load(image, (progress) => {
+      if (this.globalLoader && assetId) {
+        this.globalLoader.updateProgress(assetId, progress);
+      }
+    });
+
+    // Mark as complete
+    if (this.globalLoader && assetId) {
+      this.globalLoader.completeAsset(assetId);
+    }
+
+    // Auto-detect width and height from the image if not provided
+    if (!width || width <= 0) {
+      width = texture.width;
+      options.width = width;
+    }
+    if (!height || height <= 0) {
+      height = texture.height;
+      options.height = height;
+    }
+
     const spriteWidth = options.spriteWidth;
     const spriteHeight = options.spriteHeight;
     const frames: Texture[][] = [];
@@ -140,12 +258,30 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
       } as any;
       const {
         rectWidth,
-        width = 0,
+        width: widthOption = 0,
         framesWidth = 1,
         rectHeight,
-        height = 0,
+        height: heightOption = 0,
         framesHeight = 1,
+        image,
       } = optionsTextures;
+
+      // Auto-detect width and height from the image if not provided
+      let width = widthOption;
+      let height = heightOption;
+
+      if (image && ((!width || width <= 0) || (!height || height <= 0))) {
+        const dimensions = await this.detectImageDimensions(image);
+        if (!width || width <= 0) {
+          width = dimensions.width;
+          optionsTextures.width = width;
+        }
+        if (!height || height <= 0) {
+          height = dimensions.height;
+          optionsTextures.height = height;
+        }
+      }
+
       optionsTextures.spriteWidth = rectWidth ? rectWidth : width / framesWidth;
       optionsTextures.spriteHeight = rectHeight
         ? rectHeight
@@ -164,17 +300,26 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
   }
 
   async onMount(params: Element<CanvasSprite>) {
+    // Set #element manually for freeze checking before calling super.onMount
+    // We need to set it early so update() can check freeze state
+    (this as any)['#element'] = params;
+    
     const { props, propObservables } = params;
     const tick: Signal = props.context.tick;
     const sheet = props.sheet ?? {};
+    const definition = props.sheet?.definition ?? {};
+    this.app = props.context.app();
+    // Get global loader from context if available
+    this.globalLoader = props.context?.globalLoader || null;
     if (sheet?.onFinish) {
       this.onFinish = sheet.onFinish;
     }
     this.subscriptionTick = tick.observable.subscribe((value) => {
+      if (this.destroyed) return
       this.update(value);
     });
-    if (props.sheet?.definition) {
-      this.spritesheet = props.sheet.definition;
+    if (definition) {
+      this.spritesheet = definition.value ?? definition;
       await this.createAnimations();
     }
     if (sheet.params) {
@@ -218,49 +363,123 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
         this.sheetCurrentAnimation = StandardAnimation.Stand;
       }
 
-      this.play(this.sheetCurrentAnimation, [this.sheetParams]);
+      if (this.spritesheet && this.has(this.sheetCurrentAnimation)) this.play(this.sheetCurrentAnimation, [this.sheetParams]);
     });
-
     super.onMount(params);
   }
 
   async onUpdate(props) {
+    if (this.destroyed) return
     super.onUpdate(props);
 
-    const sheet = props.sheet;
+    // Initialize globalLoader from context if not already set
+    if (!this.globalLoader && props.context?.globalLoader) {
+      this.globalLoader = props.context.globalLoader;
+    }
+
+    const setTexture = async (image: string) => {
+      if (!image || typeof image !== 'string' || image.trim() === '') {
+        console.warn('Invalid image path provided to setTexture:', image);
+        return null;
+      }
+
+      // Register asset in global loader if available
+      let assetId: string | null = null;
+      if (this.globalLoader) {
+        assetId = this.globalLoader.registerAsset(image);
+        this.trackedAssetIds.add(assetId);
+      }
+
+      const onProgress = this.fullProps.loader?.onProgress;
+      const texture = await Assets.load(image, (progress) => {
+        // Update global loader progress
+        if (this.globalLoader && assetId) {
+          this.globalLoader.updateProgress(assetId, progress);
+        }
+        // Call local loader callback if provided
+        if (onProgress) onProgress(progress);
+        if (progress == 1) {
+          // Mark as complete in global loader
+          if (this.globalLoader && assetId) {
+            this.globalLoader.completeAsset(assetId);
+          }
+          const onComplete = this.fullProps.loader?.onComplete;
+          if (onComplete) {
+            // hack to memoize the texture
+            setTimeout(() => {
+              onComplete(texture);
+            });
+          }
+        }
+      });
+
+      return texture
+    }
+
+    const sheet = props.sheet
+    const definition = props.sheet?.definition ?? {};
+
+    if (definition?.type === 'reset') {
+      this.spritesheet = definition.value ?? definition;
+      await this.resetAnimations();
+    }
+
     if (sheet?.params) this.sheetParams = sheet?.params;
 
-    if (sheet?.playing && this.isMounted) {
+    if (sheet?.playing && this.isMounted && this.spritesheet && this.animations.size > 0) {
       this.sheetCurrentAnimation = sheet?.playing;
       this.play(this.sheetCurrentAnimation, [this.sheetParams]);
     }
 
-    if (props.hitbox) this.hitbox = props.hitbox;
+    if (props.hitbox) this.hitbox = props.hitbox.value ?? props.hitbox;
 
     if (props.scaleMode) this.baseTexture.scaleMode = props.scaleMode;
     else if (props.image && this.fullProps.rectangle === undefined) {
-      this.texture = await Assets.load(this.fullProps.image);
+      const texture = await setTexture(this.fullProps.image);
+      if (texture) {
+        this.texture = texture;
+      }
     } else if (props.texture) {
-      this.texture = props.texture;
+      if (isElement(props.texture)) {
+        const textureInstance = props.texture.componentInstance;
+        textureInstance.subjectInit
+          .subscribe()
+        this.texture = this.renderer?.generateTexture(props.texture.componentInstance);
+      } else {
+        this.texture = props.texture;
+      }
     }
-
     if (props.rectangle !== undefined) {
       const { x, y, width, height } = props.rectangle?.value ?? props.rectangle;
-      const texture = await Assets.load(this.fullProps.image);
-      this.texture = new Texture({
-        source: texture.source,
-        frame: new Rectangle(x, y, width, height),
-      });
+      const texture = await setTexture(this.fullProps.image);
+      if (texture) {
+        this.texture = new Texture({
+          source: texture.source,
+          frame: new Rectangle(x, y, width, height),
+        });
+      }
     }
   }
 
-  onDestroy(): void {
-    super.onDestroy();
-    this.subscriptionSheet.forEach((sub) => sub.unsubscribe());
-    this.subscriptionTick.unsubscribe();
-    if (this.currentAnimationContainer && this.parent instanceof Container) {
-      this.parent.removeChild(this.currentAnimationContainer);
-    }
+  async onDestroy(parent: Element, afterDestroy: () => void): Promise<void> {
+    const _afterDestroy = async () => {
+      // Clean up tracked assets from global loader
+      if (this.globalLoader) {
+        this.trackedAssetIds.forEach((assetId) => {
+          this.globalLoader!.removeAsset(assetId);
+        });
+        this.trackedAssetIds.clear();
+      }
+      this.subscriptionSheet.forEach((sub) => sub.unsubscribe());
+      this.subscriptionTick.unsubscribe();
+      if (this.currentAnimationContainer && this.parent instanceof Container) {
+        this.parent.removeChild(this.currentAnimationContainer);
+      }
+      if (afterDestroy) {
+        afterDestroy();
+      }
+    };
+    await super.onDestroy(parent, _afterDestroy);
   }
 
   has(name: string): boolean {
@@ -279,7 +498,6 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
 
   stop() {
     this.currentAnimation = null;
-    this.destroy();
   }
 
   play(name: string, params: any[] = []) {
@@ -321,7 +539,12 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
     const sound = this.currentAnimation.data.sound;
 
     if (sound) {
-      //RpgSound.get(sound).play()
+      new Howl({
+        src: sound,
+        autoplay: true,
+        loop: false,
+        volume: 1,
+      })
     }
 
     // Updates immediately to avoid flickering
@@ -330,7 +553,51 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
     });
   }
 
+  /**
+   * Resets the sprite by destroying and recreating all animations
+   * This method clears the current animation state, destroys existing textures,
+   * and recreates all animations from the spritesheet
+   * 
+   * @example
+   * ```typescript
+   * // Reset all animations to their initial state
+   * sprite.resetAnimations();
+   * 
+   * // Reset and then play a specific animation
+   * await sprite.resetAnimations();
+   * sprite.play('walk');
+   * ```
+   */
+  async resetAnimations(): Promise<void> {
+    // Stop current animation
+    this.stop();
+
+    // Clear all animations and textures
+    this.animations.clear();
+
+    // Reset animation state
+    this.currentAnimation = null;
+    this.currentAnimationContainer = null;
+    this.time = 0;
+    this.frameIndex = 0;
+
+    // Clear children
+    this.removeChildren();
+
+    // Recreate animations from spritesheet
+    if (this.spritesheet) {
+      await this.createAnimations();
+      this.play(this.sheetCurrentAnimation, [this.sheetParams]);
+    }
+  }
+
   update({ deltaRatio }) {
+    // Block animation update if element is frozen
+    const element = this.getElement();
+    if (element && isElementFrozen(element)) {
+      return;
+    }
+    
     if (
       !this.isPlaying() ||
       !this.currentAnimation ||
@@ -396,6 +663,7 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
       const widthOfSprite =
         typeof realSize == "number" ? realSize : realSize?.width;
 
+
       const applyAnchorBySize = () => {
         if (heightOfSprite && this.hitbox) {
           const { spriteWidth, spriteHeight } = data;
@@ -440,7 +708,9 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
   }
 }
 
-export interface CanvasSprite extends PixiSprite {}
+export interface CanvasSprite extends PixiSprite {
+  layout: Layout | null;
+}
 
 registerComponent("Sprite", CanvasSprite);
 
@@ -483,11 +753,17 @@ export interface SpritePropsWithSheet
     params?: any;
     onFinish?: () => void;
   };
+  loader?: {
+    onProgress?: (progress: number) => void;
+    onComplete?: (texture: Texture) => void;
+  };
 }
 
 export type SpritePropTypes = SpritePropsWithImage | SpritePropsWithSheet;
 
 // Update the Sprite function to use the props interface
 export const Sprite: ComponentFunction<SpritePropTypes> = (props) => {
+  // Ensure component is registered in test environments where module cache may differ
+  registerComponent("Sprite", CanvasSprite);
   return createComponent("Sprite", props);
 };

package/src/components/Text.ts

@@ -1,15 +1,16 @@
 import { Text as PixiText, TextStyle } from "pixi.js";
-import { createComponent, registerComponent } from "../engine/reactive";
-import { DisplayObject } from "./DisplayObject";
+import { createComponent, registerComponent, Element, Props } from "../engine/reactive";
+import { DisplayObject, ComponentInstance } from "./DisplayObject";
 import { DisplayObjectProps } from "./types/DisplayObject";
 import { Signal } from "@signe/reactive";
-import { on } from "../engine/trigger";
+import { on, isTrigger } from "../engine/trigger";
+import { Howl } from "howler";
 
 enum TextEffect {
   Typewriter = "typewriter",
 }
 
-interface TextProps extends DisplayObjectProps {
+export interface TextProps extends DisplayObjectProps {
   text?: string;
   style?: Partial<TextStyle>;
   color?: string;
@@ -20,7 +21,13 @@ interface TextProps extends DisplayObjectProps {
     start?: () => void;
     onComplete?: () => void;
     skip?: () => void;
+    sound?: {
+      src: string;
+      volume?: number;
+      rate?: number;
+    };
   };
+  context?: any; // Ensure context is available, ideally typed from a base prop or injected
 }
 
 class CanvasText extends DisplayObject(PixiText) {
@@ -31,10 +38,19 @@ class CanvasText extends DisplayObject(PixiText) {
   private _wordWrapWidth: number = 0;
   private typewriterOptions: any = {};
   private skipSignal?: () => void;
+  private typewriterSound?: Howl;
+  private lastSoundTime: number = 0;
+  private soundDuration: number = 0; // Duration of the sound in milliseconds
 
-  onMount(args) {
-    super.onMount(args);
-    const { props } = args;
+  /**
+   * Called when the component is mounted to the scene graph.
+   * Initializes the typewriter effect if configured.
+   * @param {Element<CanvasText>} element - The element being mounted with parent and props.
+   * @param {number} [index] - The index of the component among its siblings.
+   */
+  async onMount(element: Element<CanvasText>, index?: number): Promise<void> {
+    const { props } = element;
+    await super.onMount(element, index);
     const tick: Signal = props.context.tick;
 
     if (props.text && props.typewriter) {
@@ -44,12 +60,18 @@ class CanvasText extends DisplayObject(PixiText) {
       // Set typewriter options
       if (props.typewriter) {
         this.typewriterOptions = props.typewriter;
-        if (this.typewriterOptions.skip) {
+        if (this.typewriterOptions.skip && isTrigger(this.typewriterOptions.skip)) {
           on(this.typewriterOptions.skip, () => {
             this.skipTypewriter();
           });
         }
+        // Initialize typewriter sound if configured
+        if (this.typewriterOptions.sound) {
+          this.initializeTypewriterSound();
+        }
       }
+      // Update layout after initializing typewriter
+      this.updateLayout();
     }
     this.subscriptionTick = tick.observable.subscribe(() => {
       if (props.typewriter) {
@@ -63,15 +85,21 @@ class CanvasText extends DisplayObject(PixiText) {
     if (props.typewriter) {
       if (props.typewriter) {
         this.typewriterOptions = props.typewriter;
+        // Reinitialize sound if sound configuration changed
+        if (props.typewriter.sound) {
+          this.initializeTypewriterSound();
+        }
       }
     }
-    if (props.text) {
-      this.text = props.text;
+    if (props.text !== undefined) {
+      this.text = ''+props.text;
     }
     if (props.text !== undefined && props.text !== this.fullText && this.fullProps.typewriter) {
       this.text = "";
       this.currentIndex = 0;
       this.fullText = props.text;
+      // Update layout after resetting typewriter
+      this.updateLayout();
     }
     if (props.style) {
       for (const key in props.style) {
@@ -90,6 +118,59 @@ class CanvasText extends DisplayObject(PixiText) {
     if (props.fontFamily) {
       this.style.fontFamily = props.fontFamily;
     }
+    
+    // Use the centralized layout update method
+    this.updateLayout();
+  }
+
+  get onCompleteCallback() {
+    return this.typewriterOptions.onComplete;
+  }
+
+  /**
+   * Initializes the typewriter sound effect using Howler.
+   * Creates a Howl instance with the configured sound settings.
+   * Calculates the sound duration to prevent overlapping sounds.
+   */
+  private initializeTypewriterSound() {
+    if (!this.typewriterOptions.sound?.src) return;
+    
+    this.typewriterSound = new Howl({
+      src: [this.typewriterOptions.sound.src],
+      volume: this.typewriterOptions.sound.volume ?? 0.5,
+      rate: this.typewriterOptions.sound.rate ?? 1.0,
+      preload: true,
+      onload: () => {
+        // Calculate sound duration in milliseconds
+        if (this.typewriterSound) {
+          const duration = this.typewriterSound.duration();
+          const rate = this.typewriterOptions.sound?.rate ?? 1.0;
+          this.soundDuration = (duration / rate) * 1000;
+        }
+      }
+    });
+  }
+
+  /**
+   * Plays the typewriter sound with duration-based cooldown to prevent overlapping sounds.
+   * @param {number} currentTime - The current timestamp to check against sound duration.
+   */
+  private playTypewriterSound(currentTime: number) {
+    if (!this.typewriterSound || !this.typewriterOptions.sound) return;
+    
+    // Check if enough time has passed since the last sound play
+    // Use the actual sound duration to prevent overlap
+    if (this.soundDuration > 0 && currentTime - this.lastSoundTime < this.soundDuration) return;
+    
+    this.typewriterSound.play();
+    this.lastSoundTime = currentTime;
+  }
+
+  /**
+   * Updates the layout properties of the text component.
+   * This method ensures consistent width, height and word wrap behavior.
+   */
+  private updateLayout() {
     if (this._wordWrapWidth) {
       this.setWidth(this._wordWrapWidth);
     } else {
@@ -98,10 +179,6 @@ class CanvasText extends DisplayObject(PixiText) {
     this.setHeight(this.height);
   }
 
-  get onCompleteCallback() {
-    return this.typewriterOptions.onComplete;
-  }
-
   private typewriterEffect() {
     if (this.currentIndex < this.fullText.length) {
       const nextIndex = Math.min(
@@ -111,6 +188,14 @@ class CanvasText extends DisplayObject(PixiText) {
       this.text = this.fullText.slice(0, nextIndex);
       this.currentIndex = nextIndex;
 
+      // Play typewriter sound if configured
+      if (this.typewriterOptions.sound) {
+        this.playTypewriterSound(Date.now());
+      }
+
+      // Update layout after text change to maintain proper word wrap and dimensions
+      this.updateLayout();
+
       // Check if typewriter effect is complete
       if (
         this.currentIndex === this.fullText.length &&
@@ -128,15 +213,37 @@ class CanvasText extends DisplayObject(PixiText) {
     }
     this.text = this.fullText;
     this.currentIndex = this.fullText.length;
+    
+    // Update layout after setting full text to maintain proper word wrap and dimensions
+    this.updateLayout();
   }
 
-  onDestroy(): void {
-    super.onDestroy();
-    this.subscriptionTick.unsubscribe();
+  /**
+   * Called when the component is about to be destroyed.
+   * Unsubscribes from the tick observable and cleans up sound resources.
+   * @param {Element<any>} parent - The parent element.
+   * @param {() => void} [afterDestroy] - An optional callback function to be executed after the component's own destruction logic.
+   */
+  async onDestroy(parent: Element<any>, afterDestroy?: () => void): Promise<void> {
+    const _afterDestroy = async () => {
+      if (this.subscriptionTick) {
+        this.subscriptionTick.unsubscribe();
+      }
+      // Clean up typewriter sound
+      if (this.typewriterSound) {
+        this.typewriterSound.stop();
+        this.typewriterSound.unload();
+        this.typewriterSound = undefined;
+      }
+      if (afterDestroy) {
+        afterDestroy();
+      }
+    }
+    await super.onDestroy(parent, _afterDestroy);
   }
 }
 
-interface CanvasText extends PixiText {}
+// interface CanvasText extends PixiText {} // Removed as it's redundant and causes type conflicts
 
 registerComponent("Text", CanvasText);