@dryanovski/gamefoo 0.2.3 → 0.2.5

package/src/core/sprite.ts

@@ -0,0 +1,339 @@
+import Asset from "./asset";
+
+/**
+ * Describes a single named animation within a {@link Sprite} sheet.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example
+ * ```ts
+ * const walkAnim: AnimationDefinition = {
+ *   frames: [0, 1, 2, 3],
+ *   duration: 0.15,
+ *   loop: true,
+ * };
+ * ```
+ */
+interface AnimationDefinition {
+  /** Ordered frame indices into the spritesheet grid. */
+  frames: (string | number)[];
+  /** Time in seconds each frame is displayed before advancing. */
+  duration: number;
+  /** Whether the animation restarts from frame 0 after the last frame. */
+  loop: boolean;
+}
+
+/**
+ * Describes the position and size of a single frame within a {@link Sprite}
+ * sheet.
+ *
+ * @category Core
+ * @since 0.2.0
+ *
+ * @example
+ * ```ts
+ * const frame: SpriteFrame = {
+ *  x: 32,
+ *  y: 64,
+ *  width: 32,
+ *  height: 32,
+ *  anchor: { x: 16, y: 16 },
+ *  };
+ *  ```
+ */
+interface SpriteFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  anchor?: { x: number; y: number };
+}
+
+/**
+ * Configuration options for slicing a {@link Sprite} sheet into a grid of
+ * frames.
+ *
+ * @category Core
+ * @since 0.2.0
+ *
+ * @example
+ * ```ts
+ * const config: GridConfig = {
+ *  frameWidth: 32,
+ *  frameHeight: 32,
+ *  offsetX: 0,
+ *  offsetY: 0,
+ *  spacingX: 0,
+ *  spacingY: 0,
+ *  count: 16,
+ *  };
+ *  ```
+ */
+interface GridConfig {
+  frameWidth: number;
+  frameHeight: number;
+  /* left margin before the first column */
+  offsetX?: number;
+  /* top margin before the first row */
+  offsetY?: number;
+  /* horizontal gap between cells */
+  spacingX?: number;
+  /* vertical gap between cells */
+  spacingY?: number;
+  /* total number of frames in the sheet (optional, can be inferred from image size) */
+  count?: number;
+}
+
+/**
+ * Metadata wrapper around an {@link HTMLImageElement} that describes how
+ * it is sliced into a uniform grid of frames and what named animations
+ * are available.
+ *
+ * `Sprite` does **not** handle rendering itself — use
+ * {@link SpriteRender} to play animations on an entity.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Loading and creating a sprite
+ * ```ts
+ * import { Asset } from "gamefoo";
+ *
+ * const image = await Asset.load("hero.png");
+ * const sprite = new Sprite(image, 32, 32, {
+ *   idle: { frames: [0, 1], duration: 0.25, loop: true },
+ *   run:  { frames: [2, 3, 4, 5], duration: 0.1, loop: true },
+ * });
+ * ```
+ *
+ * @example Querying frame coordinates
+ * ```ts
+ * const rect = sprite.getFrameRect(5);
+ * ctx.drawImage(
+ *   sprite.image,
+ *   rect.x, rect.y, rect.width, rect.height,
+ *   destX, destY, rect.width, rect.height,
+ * );
+ * ```
+ *
+ * @see {@link SpriteRender} — behaviour that plays sprite animations
+ * @see {@link Asset}        — image loading utility
+ */
+export default class Sprite {
+  /** The underlying image element containing the full spritesheet. */
+  public image: HTMLImageElement;
+
+  /** Width of a single frame cell in pixels. */
+  readonly width: number;
+
+  /** Height of a single frame cell in pixels. */
+  readonly height: number;
+
+  /**
+   * Number of frame columns in the spritesheet, computed as
+   * `Math.floor(image.width / width)`.
+   */
+  readonly columns: number;
+
+  /**
+   * Number of frame rows in the spritesheet, computed as
+   * `Math.floor(image.height / height)`.
+   */
+  readonly rows: number;
+
+  /**
+   * Named animation definitions keyed by animation name.
+   *
+   * Populated from the optional `animations` parameter passed to the
+   * constructor.
+   */
+  public animations: Map<string, AnimationDefinition>;
+
+  /**
+   * @since 0.2.0
+   */
+  public frames: Map<number | string, SpriteFrame>;
+
+  /**
+   * Creates a new spritesheet descriptor.
+   *
+   * @param image      - A fully-loaded `HTMLImageElement` containing the
+   *   spritesheet texture.
+   * @param width      - Width of each individual frame in pixels.
+   * @param height     - Height of each individual frame in pixels.
+   * @param animations - Optional map of named animation definitions.
+   *   Keys are animation names (e.g. `"idle"`, `"run"`).
+   *
+   * @example
+   * ```ts
+   * const sprite = new Sprite(img, 64, 64, {
+   *   idle: { frames: [0], duration: 1, loop: false },
+   * });
+   * ```
+   */
+  constructor(
+    image: HTMLImageElement,
+    width: number,
+    height: number,
+    animations?: Record<string, AnimationDefinition>,
+  ) {
+    this.image = image;
+    this.width = width;
+    this.height = height;
+    this.columns = Math.floor(image.width / width);
+    this.rows = Math.floor(image.height / height);
+
+    this.frames = Sprite.generateGridFrames(image, {
+      frameWidth: width,
+      frameHeight: height,
+    });
+
+    this.animations = new Map(Object.entries(animations || {}));
+  }
+
+  /**
+   * Alternative constructor for spritesheets that are already sliced into a
+   * uniform grid of frames.
+   *
+   * @since 0.2.0
+   *
+   * @param image      - A fully-loaded `HTMLImageElement` containing the
+   *  spritesheet texture.
+   * @param config     - Configuration options for slicing the image into a
+   *  grid of frames.
+   * @param animations - Optional map of named animation definitions.
+   *  Keys are animation names (e.g. `"idle"`, `"run"`).
+   *
+   * @example
+   *  ```ts
+   *  const sprite = Sprite.fromGrid(img, {
+   *  frameWidth: 64,
+   *
+   *  frameHeight: 64,
+   *  offsetX: 0,
+   *  offsetY: 0,
+   *  spacingX: 0,
+   *  spacingY: 0,
+   *  count: 16,
+   *  }, {
+   *  idle: { frames: [0, 1], duration: 0.25, loop: true },
+   *  run:  { frames: [2, 3, 4, 5], duration: 0.1, loop: true },
+   *  });
+   *  ```
+   */
+  static fromGrid(
+    image: HTMLImageElement,
+    config: GridConfig,
+    animations?: Record<string, AnimationDefinition>,
+  ): Sprite {
+    const sprite = Object.create(Sprite.prototype) as Sprite;
+    sprite.image = image;
+    sprite.frames = Sprite.generateGridFrames(image, config);
+    sprite.animations = new Map(Object.entries(animations || {}));
+    return sprite;
+  }
+
+  /**
+   * Helper method to compute frame rectangles for a spritesheet sliced into a
+   * uniform grid.
+   *
+   * @since 0.2.0
+   *
+   * @param image  - A fully-loaded `HTMLImageElement` containing the
+   * spritesheet texture.
+   * @param config - Configuration options for slicing the image into a grid of
+   * frames.
+   *
+   * @returns A map of frame indices to their corresponding source rectangles.
+   *  Frame indices are zero-based and laid out left-to-right, top-to-bottom.
+   *  The source rectangles are in pixel coordinates relative to the top-left corner
+   *  of the source image.
+   */
+  private static generateGridFrames(image: HTMLImageElement, config: GridConfig): Map<number, SpriteFrame> {
+    const { frameWidth, frameHeight, offsetX = 0, offsetY = 0, spacingX = 0, spacingY = 0 } = config;
+
+    const cols = Math.floor((image.width - offsetX + spacingX) / (frameWidth + spacingX));
+    const rows = Math.floor((image.height - offsetY + spacingY) / (frameHeight + spacingY));
+    const total = config.count ?? cols * rows;
+    const frames = new Map<number, SpriteFrame>();
+
+    for (let i = 0; i < total; i++) {
+      const col = i % cols;
+      const row = Math.floor(i / cols);
+      frames.set(i, {
+        x: offsetX + col * (frameWidth + spacingX),
+        y: offsetY + row * (frameHeight + spacingY),
+        width: frameWidth,
+        height: frameHeight,
+      });
+    }
+    return frames;
+  }
+
+  static fromAtlas(
+    image: HTMLImageElement,
+    regions: Record<string, SpriteFrame>,
+    animations?: Record<string, AnimationDefinition>,
+  ): Sprite {
+    const sprite = Object.create(Sprite.prototype) as Sprite;
+    sprite.image = image;
+    sprite.frames = new Map(Object.entries(regions));
+    sprite.animations = new Map(Object.entries(animations || {}));
+    return sprite;
+  }
+
+  static async fromAseprite(imagePath: string, jsonPath: string): Promise<Sprite> {
+    const [image, response] = await Promise.all([Asset.load(imagePath), fetch(jsonPath)]);
+    const data = await response.json();
+
+    const regions: Record<string, SpriteFrame> = {};
+    for (const [name, entry] of Object.entries(data.frames)) {
+      const f = (entry as any).frame;
+      regions[name] = { x: f.x, y: f.y, width: f.w, height: f.h };
+    }
+
+    const animations: Record<string, AnimationDefinition> = {};
+    if (data.meta?.frameTags) {
+      for (const tag of data.meta.frameTags) {
+        const frameNames: string[] = [];
+        for (let i = tag.from; i <= tag.to; i++) {
+          const key = Object.keys(data.frames)[i];
+          if (key) frameNames.push(key);
+        }
+        animations[tag.name] = {
+          frames: frameNames,
+          duration: ((data.frames[frameNames[0]!] as any)?.duration ?? 100) / 1000,
+          loop: tag.direction !== "forward_once",
+        };
+      }
+    }
+
+    return Sprite.fromAtlas(image, regions, animations);
+  }
+
+  /**
+   * Computes the source rectangle for a given frame index within the
+   * spritesheet.
+   *
+   * Frame indices are zero-based and laid out left-to-right,
+   * top-to-bottom.
+   *
+   * @param frame - Zero-based frame index.
+   * @returns An `{ x, y, width, height }` rectangle in pixel coordinates
+   *   relative to the top-left corner of the source image.
+   *
+   * @example
+   * ```ts
+   * // For a 4-column sheet, frame 5 → col 1, row 1
+   * const rect = sprite.getFrameRect(5);
+   * ```
+   */
+  getFrameRect(frame: number | string): SpriteFrame {
+    const rect = this.frames.get(frame);
+    if (!rect) {
+      throw new Error(`Frame "${frame}" not found in sprite`);
+    }
+    return rect;
+  }
+}

package/src/core/utils/perlin_noise.ts

@@ -0,0 +1,196 @@
+/**
+ * Deterministic 2-D Perlin noise generator with fractal Brownian motion
+ * (fBm) support.
+ *
+ * Produces smooth, continuous noise suitable for terrain heightmaps,
+ * cloud textures, procedural vegetation placement, and other organic
+ * patterns. The output is fully reproducible for a given seed.
+ *
+ * The implementation uses a 256-entry permutation table shuffled by a
+ * seeded linear congruential generator (LCG) and Ken Perlin's improved
+ * 5th-order fade curve \( 6t^5 - 15t^4 + 10t^3 \).
+ *
+ * @category Utilities
+ * @since 0.1.0
+ *
+ * @example Basic noise sampling
+ * ```ts
+ * import { PerlinNoise } from "gamefoo";
+ *
+ * const noise = new PerlinNoise(42);
+ * const value = noise.noise2d(1.5, 2.3); // returns a value in [-1, 1]
+ * ```
+ *
+ * @example Generating a heightmap with fBm
+ * ```ts
+ * const noise = new PerlinNoise(12345);
+ * const map: number[][] = [];
+ *
+ * for (let y = 0; y < 128; y++) {
+ *   map[y] = [];
+ *   for (let x = 0; x < 128; x++) {
+ *     map[y][x] = noise.fbm(x * 0.05, y * 0.05, 6, 2, 0.5);
+ *   }
+ * }
+ * ```
+ *
+ * @example Seeded reproducibility
+ * ```ts
+ * const a = new PerlinNoise(7);
+ * const b = new PerlinNoise(7);
+ * console.log(a.noise2d(3, 4) === b.noise2d(3, 4)); // true
+ * ```
+ */
+export class PerlinNoise {
+  /**
+   * Doubled permutation table (512 entries) used for gradient hashing.
+   * Built from a 256-entry shuffle of `[0..255]` seeded by the LCG.
+   */
+  private perm: Uint8Array;
+
+  /**
+   * Creates a new noise generator with the given seed.
+   *
+   * @param seed - An integer seed for the internal LCG. Identical seeds
+   *   produce identical noise fields.
+   *
+   * @defaultValue `0`
+   */
+  constructor(seed: number = 0) {
+    this.perm = new Uint8Array(512);
+    const p = new Uint8Array(256);
+
+    for (let i = 0; i < 256; i++) p[i] = i;
+
+    let s = seed >>> 0;
+    for (let i = 255; i > 0; i--) {
+      s = (Math.imul(1664525, s) + 1013904223) >>> 0;
+      const j = s % (i + 1);
+      [p[i], p[j]] = [p[j]!, p[i]!];
+    }
+
+    for (let i = 0; i < 512; i++) this.perm[i] = p[i & 255]!;
+  }
+
+  /**
+   * Ken Perlin's improved 5th-order fade (smoothstep) curve:
+   * \( 6t^5 - 15t^4 + 10t^3 \).
+   *
+   * @param t - Value in `[0, 1]`.
+   * @returns Smoothed value in `[0, 1]`.
+   *
+   * @internal
+   */
+  private fade(t: number): number {
+    return t * t * t * (t * (t * 6 - 15) + 10);
+  }
+
+  /**
+   * Standard linear interpolation.
+   *
+   * @param a - Start value.
+   * @param b - End value.
+   * @param t - Interpolant in `[0, 1]`.
+   * @returns Interpolated value.
+   *
+   * @internal
+   */
+  private lerp(a: number, b: number, t: number): number {
+    return a + t * (b - a);
+  }
+
+  /**
+   * Computes a pseudo-random gradient dot product from a hash and
+   * 2-D offset.
+   *
+   * Uses the bottom 2 bits of `hash` to select one of four gradient
+   * directions.
+   *
+   * @param hash - Permutation table entry.
+   * @param x    - X offset from the grid point.
+   * @param y    - Y offset from the grid point.
+   * @returns Dot product of the gradient and offset vectors.
+   *
+   * @internal
+   */
+  private grad(hash: number, x: number, y: number): number {
+    const h = hash & 3;
+    const u = h < 2 ? x : y;
+    const v = h < 2 ? y : x;
+    return (h & 1 ? -u : u) + (h & 2 ? -v : v);
+  }
+
+  /**
+   * Samples 2-D Perlin noise at the given coordinates.
+   *
+   * @param x - X coordinate (any real number).
+   * @param y - Y coordinate (any real number).
+   * @returns A noise value in the range `[-1, 1]`.
+   *
+   * @example
+   * ```ts
+   * const n = noise.noise2d(0.5, 0.5);
+   * // n is a smooth, deterministic value in [-1, 1]
+   * ```
+   */
+  noise2d(x: number, y: number): number {
+    const xi = Math.floor(x) & 255;
+    const yi = Math.floor(y) & 255;
+    const xf = x - Math.floor(x);
+    const yf = y - Math.floor(y);
+
+    const u = this.fade(xf);
+    const v = this.fade(yf);
+
+    const aa = this.perm[this.perm[xi]! + yi]!;
+    const ab = this.perm[this.perm[xi]! + yi + 1]!;
+    const ba = this.perm[this.perm[xi + 1]! + yi]!;
+    const bb = this.perm[this.perm[xi + 1]! + yi + 1]!;
+
+    const x1 = this.lerp(this.grad(aa, xf, yf), this.grad(ba, xf - 1, yf), u);
+    const x2 = this.lerp(this.grad(ab, xf, yf - 1), this.grad(bb, xf - 1, yf - 1), u);
+
+    return this.lerp(x1, x2, v);
+  }
+
+  /**
+   * Computes fractal Brownian motion (fBm) by layering multiple
+   * octaves of {@link PerlinNoise.noise2d} with increasing frequency
+   * and decreasing amplitude.
+   *
+   * The result is normalised to `[-1, 1]`.
+   *
+   * @param x           - X coordinate.
+   * @param y           - Y coordinate.
+   * @param octaves     - Number of noise layers to sum.
+   * @param lacunarity  - Frequency multiplier per octave.
+   * @param persistence - Amplitude multiplier per octave (controls
+   *   roughness).
+   * @returns A noise value in `[-1, 1]`.
+   *
+   * @defaultValue octaves = `4`
+   * @defaultValue lacunarity = `2`
+   * @defaultValue persistence = `0.5`
+   *
+   * @example
+   * ```ts
+   * // 6 octaves for high detail:
+   * const height = noise.fbm(x * 0.01, y * 0.01, 6, 2.0, 0.5);
+   * ```
+   */
+  fbm(x: number, y: number, octaves = 4, lacunarity = 2, persistence = 0.5): number {
+    let value = 0;
+    let amplitude = 1;
+    let frequency = 1;
+    let max = 0;
+
+    for (let i = 0; i < octaves; i++) {
+      value += this.noise2d(x * frequency, y * frequency) * amplitude;
+      max += amplitude;
+      amplitude *= persistence;
+      frequency *= lacunarity;
+    }
+
+    return value / max;
+  }
+}