canvasengine 2.0.1-beta.1 → 2.0.1

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;
 
@@ -52,13 +58,21 @@ type AnimationDataFrames = {
   data: TextureOptionsMerging;
 };
 
+export type HitboxAnchorMode = "top-left" | "center" | "foot";
+
+export type Hitbox = {
+  w: number;
+  h: number;
+  anchorMode?: HitboxAnchorMode;
+};
+
 export enum StandardAnimation {
   Stand = "stand",
   Walk = "walk",
 }
 
 export class CanvasSprite extends DisplayObject(PixiSprite) {
-  public hitbox: { w: number; h: number };
+  public hitbox: Hitbox | null = null;
   public applyTransform: (
     frame: FrameOptionsMerging,
     data: TextureOptionsMerging,
@@ -73,15 +87,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 +266,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
@@ -163,20 +307,37 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
     }
   }
 
-  async onMount(params: Element<CanvasSprite>) {
+  async onMount(params: Element<any>) {
+    // 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) {
+      const resolvedDefinition = definition instanceof Promise ? await definition : definition;
+      this.spritesheet = resolvedDefinition.value ?? resolvedDefinition;
       await this.createAnimations();
     }
+    if (sheet?.params) {
+      this.sheetParams = sheet.params;
+    }
+    if (sheet?.playing && this.has(sheet.playing)) {
+      this.sheetCurrentAnimation = sheet.playing;
+      this.play(this.sheetCurrentAnimation, [this.sheetParams]);
+    }
     if (sheet.params) {
       for (let key in propObservables?.sheet["params"]) {
         const value = propObservables?.sheet["params"][key] as Signal;
@@ -184,11 +345,13 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
           this.subscriptionSheet.push(
             value.observable.subscribe((value) => {
               if (this.animations.size == 0) return;
-              this.play(this.sheetCurrentAnimation, [{ [key]: value }]);
+              if (!this.has(this.sheetCurrentAnimation)) return;
+              this.play(this.sheetCurrentAnimation, [{ ...this.sheetParams, [key]: value }]);
             })
           );
         } else {
-          this.play(this.sheetCurrentAnimation, [{ [key]: value }]);
+          if (!this.has(this.sheetCurrentAnimation)) continue;
+          this.play(this.sheetCurrentAnimation, [{ ...this.sheetParams, [key]: value }]);
         }
       }
     }
@@ -212,57 +375,136 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
 
       if (!this.isMounted) return;
 
-      if (_isMoving) {
-        this.sheetCurrentAnimation = StandardAnimation.Walk;
-      } else {
-        this.sheetCurrentAnimation = StandardAnimation.Stand;
-      }
+      const animationName = this.getMovementAnimationName(_isMoving);
+      if (!animationName) return;
 
-      this.play(this.sheetCurrentAnimation, [this.sheetParams]);
+      this.sheetCurrentAnimation = animationName;
+      if (this.spritesheet) 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') {
+      const resolvedValue = definition.value instanceof Promise ? await definition.value : definition.value;
+      this.spritesheet = resolvedValue ?? 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 !== undefined) {
+      this.hitbox = this.normalizeHitbox(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);
+    if (this.hitbox && !this.spritesheet) {
+      this.applyHitboxAnchor(this.texture.width, this.texture.height);
     }
   }
 
+  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 {
     return this.animations.has(name);
   }
@@ -277,9 +519,37 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
     return this.currentAnimation.name == name;
   }
 
+  private getFirstAnimationName(): string | undefined {
+    return this.animations.keys().next().value;
+  }
+
+  private getPlayableAnimationName(preferred?: string): string | undefined {
+    if (preferred && this.has(preferred)) {
+      return preferred;
+    }
+    return this.getFirstAnimationName();
+  }
+
+  private getMovementAnimationName(isMoving: boolean): string | undefined {
+    const standardAnimation = isMoving
+      ? StandardAnimation.Walk
+      : StandardAnimation.Stand;
+
+    if (this.has(standardAnimation)) {
+      return standardAnimation;
+    }
+
+    if (this.sheetCurrentAnimation && this.has(this.sheetCurrentAnimation)) {
+      return this.sheetCurrentAnimation;
+    }
+
+    if (this.currentAnimation?.name && this.has(this.currentAnimation.name)) {
+      return this.currentAnimation.name;
+    }
+  }
+
   stop() {
     this.currentAnimation = null;
-    this.destroy();
   }
 
   play(name: string, params: any[] = []) {
@@ -321,7 +591,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 +605,55 @@ 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();
+      const animationName = this.getPlayableAnimationName(this.sheetCurrentAnimation);
+      if (animationName) {
+        this.sheetCurrentAnimation = animationName;
+        this.play(animationName, [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 ||
@@ -391,26 +714,12 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
       }
 
       const realSize = getVal<"spriteRealSize">("spriteRealSize");
-      const heightOfSprite =
-        typeof realSize == "number" ? realSize : realSize?.height;
-      const widthOfSprite =
-        typeof realSize == "number" ? realSize : realSize?.width;
-
-      const applyAnchorBySize = () => {
-        if (heightOfSprite && this.hitbox) {
-          const { spriteWidth, spriteHeight } = data;
-          const w = (spriteWidth - this.hitbox.w) / 2 / spriteWidth;
-          const gap = (spriteHeight - heightOfSprite) / 2;
-          const h = (spriteHeight - this.hitbox.h - gap) / spriteHeight;
-          this.anchor.set(w, h);
-        }
-      };
 
       if (frame.sound) {
         //RpgSound.get(frame.sound).play()
       }
 
-      applyAnchorBySize();
+      this.applyHitboxAnchor(data.spriteWidth, data.spriteHeight, realSize);
 
       applyTransform("anchor");
       applyTransform("scale");
@@ -438,9 +747,80 @@ export class CanvasSprite extends DisplayObject(PixiSprite) {
       this.frameIndex++;
     }
   }
+
+  private applyHitboxAnchor(
+    spriteWidth: number,
+    spriteHeight: number,
+    realSize?: TextureOptionsMerging["spriteRealSize"]
+  ) {
+    if (!this.hitbox || !spriteWidth || !spriteHeight || !this.anchor) {
+      return;
+    }
+
+    const heightOfSprite =
+      typeof realSize === "number" ? realSize : realSize?.height;
+    const resolvedHeight = heightOfSprite ?? spriteHeight;
+    const gap = Math.max(0, (spriteHeight - resolvedHeight) / 2);
+    const hitboxTopLeftX = this.clamp(
+      (spriteWidth - this.hitbox.w) / 2 / spriteWidth
+    );
+    const hitboxTopLeftY = this.clamp(
+      (spriteHeight - this.hitbox.h - gap) / spriteHeight
+    );
+    const hitboxCenterX = this.clamp(
+      hitboxTopLeftX + this.hitbox.w / 2 / spriteWidth
+    );
+    const hitboxCenterY = this.clamp(
+      hitboxTopLeftY + this.hitbox.h / 2 / spriteHeight
+    );
+    const footY = this.clamp((spriteHeight - gap) / spriteHeight);
+
+    let anchorX = hitboxTopLeftX;
+    let anchorY = hitboxTopLeftY;
+
+    switch (this.hitbox.anchorMode ?? "top-left") {
+      case "center":
+        anchorX = hitboxCenterX;
+        anchorY = hitboxCenterY;
+        break;
+      case "foot":
+        anchorX = hitboxCenterX;
+        anchorY = footY;
+        break;
+      case "top-left":
+      default:
+        break;
+    }
+
+    this.anchor.set(anchorX, anchorY);
+  }
+
+  private normalizeHitbox(hitbox: unknown): Hitbox | null {
+    const resolvedHitbox = (hitbox as any)?.value ?? hitbox;
+    if (!resolvedHitbox || typeof resolvedHitbox !== "object") {
+      return null;
+    }
+
+    const { w, h, anchorMode } = resolvedHitbox as Partial<Hitbox>;
+    if (typeof w !== "number" || typeof h !== "number") {
+      return null;
+    }
+
+    return {
+      w,
+      h,
+      anchorMode,
+    };
+  }
+
+  private clamp(value: number) {
+    return Math.min(1, Math.max(0, value));
+  }
 }
 
-export interface CanvasSprite extends PixiSprite {}
+export interface CanvasSprite extends PixiSprite {
+  layout: Layout | null;
+}
 
 registerComponent("Sprite", CanvasSprite);
 
@@ -452,6 +832,7 @@ export interface SpriteProps extends DisplayObjectProps {
     params?: any;
     onFinish?: () => void;
   };
+  hitbox?: Hitbox;
   scaleMode?: number;
   image?: string;
   rectangle?: {
@@ -483,11 +864,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);
 };