@dryanovski/gamefoo 0.2.1 → 0.2.5

package/dist/core/game_object_register.js

@@ -0,0 +1,134 @@
+/**
+ * Central registry that stores and manages all non-player
+ * {@link GameObject | game objects} within the engine.
+ *
+ * Objects are keyed by their `id` property, so each ID must be unique.
+ * The {@link Engine} delegates per-frame `update` and `render` calls to
+ * this register.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Registering and retrieving objects
+ * ```ts
+ * const register = new GameObjectRegister();
+ *
+ * register.register(tree);
+ * register.register(rock);
+ *
+ * const found = register.get("tree"); // Entity | undefined
+ * console.log(register.has("rock"));  // true
+ * ```
+ *
+ * @example Bulk update / render
+ * ```ts
+ * // Called internally by Engine each frame:
+ * register.updateAll(deltaTime);
+ * register.renderAll(ctx);
+ * ```
+ *
+ * @see {@link Engine.attachObjects} — convenience method that delegates here
+ */
+export default class GameObjectRegister {
+    /**
+     * Internal map from entity ID to its {@link GameObject} instance.
+     */
+    objects = new Map();
+    _cache = null;
+    /**
+     * Adds a game object to the registry.
+     *
+     * If an object with the same `id` already exists it will be
+     * silently overwritten.
+     *
+     * @param object - The game object to register.
+     *
+     * @example
+     * ```ts
+     * register.register(new Crate("crate_1", 200, 150, 32, 32));
+     * ```
+     */
+    register(object) {
+        this.objects.set(object.id, object);
+        this._cache = null;
+    }
+    /**
+     * Retrieves a registered object by its unique ID.
+     *
+     * @param id - The ID of the object to find.
+     * @returns The matching {@link GameObject}, or `undefined` if not found.
+     *
+     * @example
+     * ```ts
+     * const crate = register.get("crate_1");
+     * if (crate) crate.x += 10;
+     * ```
+     */
+    get(id) {
+        return this.objects.get(id);
+    }
+    /**
+     * Checks whether an object with the given ID is registered.
+     *
+     * @param id - The ID to look up.
+     * @returns `true` if the registry contains the object.
+     */
+    has(id) {
+        return this.objects.has(id);
+    }
+    /**
+     * Returns all registered objects as an array.
+     *
+     * Make sure to also cache the objects
+     *
+     * @since 0.2.0
+     *
+     * @returns An array of all {@link GameObject} instances in the registry.
+     */
+    toArray() {
+        if (!this._cache) {
+            this._cache = Array.from(this.objects.values());
+        }
+        return this._cache;
+    }
+    /**
+     * Returns all registered objects that pass the supplied filter.
+     *
+     * @param filter - (optional) A predicate function. Return `true` to include the
+     *   object in the result.
+     * @returns An array of matching {@link GameObject} instances.
+     *
+     * @example
+     * ```ts
+     * const enemies = register.getAll(() => true);
+     * ```
+     */
+    getAll(filter) {
+        if (typeof filter === "function") {
+            return this.toArray().filter(filter);
+        }
+        return this.toArray();
+    }
+    /**
+     * Calls {@link GameObject.update | update(deltaTime)} on every
+     * registered object.
+     *
+     * @param deltaTime - Seconds elapsed since the previous frame.
+     */
+    updateAll(deltaTime) {
+        for (const obj of this.getAll()) {
+            obj.update(deltaTime);
+        }
+    }
+    /**
+     * Calls {@link GameObject.render | render(ctx)} on every registered
+     * object.
+     *
+     * @param ctx - The canvas 2-D rendering context.
+     */
+    renderAll(ctx) {
+        for (const obj of this.getAll()) {
+            obj.render(ctx);
+        }
+    }
+}

package/dist/core/input.js

@@ -0,0 +1,170 @@
+/**
+ * Unified keyboard and mouse input manager.
+ *
+ * `Input` listens to `keydown`, `keyup`, `mousedown`, `mouseup`, and
+ * `mousemove` events on the `window` and exposes a polling API so game
+ * logic can query the current state at any point during a frame rather
+ * than relying on event callbacks.
+ *
+ * All keyboard keys are stored **lowercased** for case-insensitive
+ * look-ups.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Polling keys
+ * ```ts
+ * const input = new Input();
+ *
+ * function update() {
+ *   if (input.isKeyDown("w")) {
+ *     player.y -= speed;
+ *   }
+ * }
+ * ```
+ *
+ * @example Checking mouse state
+ * ```ts
+ * const input = new Input();
+ *
+ * if (input.isMouseButtonDown(0)) {           // left-click
+ *   const { x, y } = input.getMousePosition();
+ *   shoot(x, y);
+ * }
+ * ```
+ *
+ * @see {@link Control} — behaviour that consumes `Input` for player movement
+ */
+export default class Input {
+    /**
+     * Set of currently-pressed keyboard keys (lowercased).
+     *
+     * Populated on `keydown`, cleared on `keyup`.
+     */
+    keys = new Set();
+    /**
+     * Set of currently-pressed mouse button indices.
+     *
+     * Standard mapping: `0` = left, `1` = middle, `2` = right.
+     */
+    mouseButtons = new Set();
+    /**
+     * Last known mouse position in **client** (viewport) coordinates.
+     *
+     * @defaultValue `{ x: 0, y: 0 }`
+     */
+    mousePosition = { x: 0, y: 0 };
+    /**
+     * Creates a new `Input` instance and attaches global event listeners
+     * to the `window`.
+     *
+     * @remarks
+     * Only one `Input` instance should exist at a time to avoid
+     * duplicate listeners. If you need to tear down, call {@link Input.reset}
+     * to clear tracked state.
+     */
+    constructor() {
+        window.addEventListener("keydown", (e) => {
+            this.keys.add(e.key.toLowerCase());
+        });
+        window.addEventListener("keyup", (e) => {
+            this.keys.delete(e.key.toLowerCase());
+        });
+        window.addEventListener("mousedown", (e) => {
+            this.mouseButtons.add(e.button);
+        });
+        window.addEventListener("mouseup", (e) => {
+            this.mouseButtons.delete(e.button);
+        });
+        window.addEventListener("mousemove", (e) => {
+            this.mousePosition.x = e.clientX;
+            this.mousePosition.y = e.clientY;
+        });
+    }
+    /**
+     * Checks whether a specific key is currently held down.
+     *
+     * @param key - The key name to check (case-insensitive).
+     *   Uses the standard {@link KeyboardEvent.key} values (e.g. `"a"`,
+     *   `"ArrowLeft"`, `"Shift"`).
+     * @returns `true` if the key is currently pressed.
+     *
+     * @example
+     * ```ts
+     * if (input.isKeyDown("space")) {
+     *   player.jump();
+     * }
+     * ```
+     */
+    isKeyDown(key) {
+        return this.keys.has(key.toLowerCase());
+    }
+    /**
+     * Returns a snapshot of all keys that are currently held down.
+     *
+     * The returned `Set` is a **copy** — mutating it does not affect
+     * the internal state.
+     *
+     * @returns A new `Set<string>` of pressed key names (lowercased).
+     *
+     * @example
+     * ```ts
+     * const pressed = input.getPressedKeys();
+     * console.log([...pressed]); // e.g. ["w", "shift"]
+     * ```
+     */
+    getPressedKeys() {
+        return new Set(this.keys);
+    }
+    /**
+     * Checks whether a specific mouse button is currently held down.
+     *
+     * @param button - The mouse button index (`0` = left, `1` = middle,
+     *   `2` = right).
+     * @returns `true` if the button is currently pressed.
+     *
+     * @example
+     * ```ts
+     * if (input.isMouseButtonDown(2)) {
+     *   openContextMenu();
+     * }
+     * ```
+     */
+    isMouseButtonDown(button) {
+        return this.mouseButtons.has(button);
+    }
+    /**
+     * Returns the last known mouse position in client (viewport)
+     * coordinates.
+     *
+     * The returned object is a **copy** — mutating it does not affect
+     * the internal state.
+     *
+     * @returns An `{ x, y }` object with the mouse coordinates.
+     *
+     * @example
+     * ```ts
+     * const pos = input.getMousePosition();
+     * ctx.fillRect(pos.x, pos.y, 4, 4); // draw cursor dot
+     * ```
+     */
+    getMousePosition() {
+        return { ...this.mousePosition };
+    }
+    /**
+     * Clears all tracked key and mouse-button state.
+     *
+     * Useful when pausing the game or switching scenes to prevent stale
+     * input from carrying over.
+     *
+     * @example
+     * ```ts
+     * engine.pause();
+     * input.reset();
+     * ```
+     */
+    reset() {
+        this.keys.clear();
+        this.mouseButtons.clear();
+    }
+}

package/dist/core/sprite.js

@@ -0,0 +1,222 @@
+import Asset from "./asset";
+/**
+ * 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. */
+    image;
+    /** Width of a single frame cell in pixels. */
+    width;
+    /** Height of a single frame cell in pixels. */
+    height;
+    /**
+     * Number of frame columns in the spritesheet, computed as
+     * `Math.floor(image.width / width)`.
+     */
+    columns;
+    /**
+     * Number of frame rows in the spritesheet, computed as
+     * `Math.floor(image.height / height)`.
+     */
+    rows;
+    /**
+     * Named animation definitions keyed by animation name.
+     *
+     * Populated from the optional `animations` parameter passed to the
+     * constructor.
+     */
+    animations;
+    /**
+     * @since 0.2.0
+     */
+    frames;
+    /**
+     * 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, width, height, animations) {
+        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, config, animations) {
+        const sprite = Object.create(Sprite.prototype);
+        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.
+     */
+    static generateGridFrames(image, config) {
+        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();
+        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, regions, animations) {
+        const sprite = Object.create(Sprite.prototype);
+        sprite.image = image;
+        sprite.frames = new Map(Object.entries(regions));
+        sprite.animations = new Map(Object.entries(animations || {}));
+        return sprite;
+    }
+    static async fromAseprite(imagePath, jsonPath) {
+        const [image, response] = await Promise.all([Asset.load(imagePath), fetch(jsonPath)]);
+        const data = await response.json();
+        const regions = {};
+        for (const [name, entry] of Object.entries(data.frames)) {
+            const f = entry.frame;
+            regions[name] = { x: f.x, y: f.y, width: f.w, height: f.h };
+        }
+        const animations = {};
+        if (data.meta?.frameTags) {
+            for (const tag of data.meta.frameTags) {
+                const frameNames = [];
+                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]]?.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) {
+        const rect = this.frames.get(frame);
+        if (!rect) {
+            throw new Error(`Frame "${frame}" not found in sprite`);
+        }
+        return rect;
+    }
+}

package/dist/core/utils/perlin_noise.js

@@ -0,0 +1,183 @@
+/**
+ * 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.
+     */
+    perm;
+    /**
+     * 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 = 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
+     */
+    fade(t) {
+        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
+     */
+    lerp(a, b, t) {
+        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
+     */
+    grad(hash, x, y) {
+        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, y) {
+        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, y, octaves = 4, lacunarity = 2, persistence = 0.5) {
+        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;
+    }
+}