@dryanovski/gamefoo 0.2.3 → 0.2.5

package/dist/core/animate.js

@@ -0,0 +1,147 @@
+/**
+ * Frame-based sprite animation controller.
+ *
+ * `Animate` steps through a sequence of spritesheet cells at a given
+ * frame rate. It tracks elapsed time internally and advances the
+ * current frame index each time the interval elapses.
+ *
+ * > **Note:** The {@link Animate.draw} method is currently a stub —
+ * > it resolves the correct frame but does not yet perform the actual
+ * > `drawImage` call.  Use {@link SpriteRender} for production
+ * > sprite rendering.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Creating a walk animation
+ * ```ts
+ * const walkFrames = [
+ *   { col: 0, row: 0 },
+ *   { col: 1, row: 0 },
+ *   { col: 2, row: 0 },
+ *   { col: 3, row: 0 },
+ * ];
+ *
+ * const anim = new Animate("walk", walkFrames, 32, 32, 12);
+ * ```
+ *
+ * @example Updating in a game loop
+ * ```ts
+ * function update(delta: number) {
+ *   anim.update(delta);
+ *   anim.draw(ctx, entity.x, entity.y);
+ * }
+ * ```
+ *
+ * @see {@link SpriteRender} — behaviour-based alternative for entity rendering
+ * @see {@link Sprite}       — spritesheet metadata container
+ */
+export default class Animate {
+    /** Identifier for this animation (e.g. `"walk"`, `"idle"`). */
+    key;
+    /** Ordered list of spritesheet cells that make up the animation. */
+    frames;
+    /** Width of a single frame in pixels. */
+    frameW;
+    /** Height of a single frame in pixels. */
+    frameH;
+    /**
+     * Index into {@link Animate.frames} of the frame currently being
+     * displayed.
+     *
+     * @defaultValue `0`
+     */
+    currentFrame = 0;
+    /**
+     * Milliseconds accumulated since the last frame advance.
+     *
+     * @defaultValue `0`
+     */
+    elapsed = 0;
+    /** Computed time between frames in milliseconds (`1000 / fps`). */
+    interval;
+    /** Playback speed in frames per second. */
+    fps;
+    /**
+     * Creates a new animation sequence.
+     *
+     * @param key    - A unique name for this animation (used as a look-up key).
+     * @param frames - An ordered array of `{ col, row }` cells from the
+     *   spritesheet.
+     * @param frameW - Width of each frame in pixels.
+     * @param frameH - Height of each frame in pixels.
+     * @param fps    - Playback speed in frames per second.
+     *
+     * @example
+     * ```ts
+     * const idle = new Animate(
+     *   "idle",
+     *   [{ col: 0, row: 1 }, { col: 1, row: 1 }],
+     *   64, 64,
+     *   8,
+     * );
+     * ```
+     */
+    constructor(key, frames, frameW, frameH, fps) {
+        this.key = key;
+        this.frames = frames;
+        this.frameW = frameW;
+        this.frameH = frameH;
+        this.fps = fps;
+        this.interval = 1000 / this.fps;
+    }
+    /**
+     * Advances the animation clock and moves to the next frame when the
+     * interval has elapsed.
+     *
+     * @param delta - Time elapsed since the last call, **in milliseconds**.
+     *
+     * @example
+     * ```ts
+     * // Inside a requestAnimationFrame loop:
+     * anim.update(deltaMs);
+     * ```
+     */
+    update(delta) {
+        this.elapsed += delta;
+        if (this.elapsed >= this.interval) {
+            this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+            this.elapsed = 0;
+        }
+    }
+    /**
+     * Draws the current animation frame to the canvas.
+     *
+     * @remarks
+     * This method is currently a **stub**. It resolves the correct
+     * `{ col, row }` cell but does not perform the actual
+     * `ctx.drawImage()` call. Wire it to {@link Asset} or use
+     * {@link SpriteRender} for full rendering.
+     *
+     * @param _ctx   - The canvas 2-D rendering context.
+     * @param _destX - Destination X coordinate on the canvas.
+     * @param _destY - Destination Y coordinate on the canvas.
+     */
+    draw(_ctx, _destX, _destY) {
+        const frame = this.frames[this.currentFrame];
+        if (!frame)
+            return;
+        const { col: _col, row: _row } = frame;
+        // Asset.drawFrame(ctx, key, col, row, frameW, frameH, destX, destY)
+    }
+    /**
+     * Resets the animation to its first frame.
+     *
+     * Call this when switching animations or restarting a sequence.
+     *
+     * @example
+     * ```ts
+     * anim.reset();
+     * anim.update(0); // ensures frame 0 is active
+     * ```
+     */
+    reset() {
+        this.currentFrame = 0;
+        this.elapsed = 0;
+    }
+}

package/dist/core/asset.js

@@ -0,0 +1,74 @@
+/**
+ * Static image asset loader with an in-memory cache.
+ *
+ * `Asset` wraps the native `Image` constructor with a `Promise`-based
+ * API and caches loaded images by URL so repeated requests for the same
+ * source resolve instantly.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Loading an image
+ * ```ts
+ * const image = await Asset.load("sprites/hero.png");
+ * ctx.drawImage(image, 0, 0);
+ * ```
+ *
+ * @example Pre-loading multiple assets
+ * ```ts
+ * await Promise.all([
+ *   Asset.load("sprites/hero.png"),
+ *   Asset.load("sprites/enemy.png"),
+ *   Asset.load("tiles/grass.png"),
+ * ]);
+ * ```
+ *
+ * @see {@link Sprite} — consumes loaded images for spritesheet slicing
+ */
+export default class Asset {
+    /**
+     * Internal cache mapping source URLs to their loaded
+     * `HTMLImageElement` instances.
+     */
+    static cache = new Map();
+    /**
+     * Loads an image from the given URL.
+     *
+     * If the image has been loaded before, the cached `HTMLImageElement`
+     * is returned immediately (the `Promise` resolves synchronously on
+     * the microtask queue).
+     *
+     * @param src - URL or relative path of the image to load.
+     * @returns A `Promise` that resolves with the loaded
+     *   `HTMLImageElement`.
+     *
+     * @throws {Error} If the image fails to load (e.g. 404 or network
+     *   error). The error message includes the failing `src`.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const img = await Asset.load("missing.png");
+     * } catch (err) {
+     *   console.error(err); // "Failed to load image: missing.png"
+     * }
+     * ```
+     */
+    static async load(src) {
+        const cache = Asset.cache.get(src);
+        if (cache) {
+            return cache;
+        }
+        return new Promise((resolve, reject) => {
+            const image = new Image();
+            image.onload = () => {
+                Asset.cache.set(src, image);
+                resolve(image);
+            };
+            image.onerror = (_error) => {
+                reject(new Error(`Failed to load image: ${src}`));
+            };
+            image.src = src;
+        });
+    }
+}

package/dist/core/behaviour.js

@@ -0,0 +1,88 @@
+/**
+ * Abstract base class for all entity behaviours in the GameFoo engine.
+ *
+ * A **behaviour** is a self-contained unit of logic (input handling,
+ * collision response, health tracking, rendering, etc.) that can be
+ * attached to any {@link Entity} at runtime via
+ * {@link Entity.attachBehaviour}.
+ *
+ * Subclasses **must** implement:
+ * - {@link Behaviour.type | type} — a unique string identifier (e.g. `"control"`, `"healthkit"`).
+ * - {@link Behaviour.update | update} — called once per frame with `deltaTime`.
+ *
+ * Subclasses **may** override:
+ * - {@link Behaviour.render | render} — draw debug visuals or overlays.
+ * - {@link Behaviour.onAttach | onAttach} — setup hook when added to an entity.
+ * - {@link Behaviour.onDetach | onDetach} — teardown hook when removed.
+ *
+ * @typeParam T - The entity type this behaviour operates on.
+ *   Defaults to {@link Entity}; narrow it to {@link DynamicEntity} or
+ *   {@link Player} when the behaviour needs velocity, speed, etc.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Creating a custom behaviour
+ * ```ts
+ * import { Behaviour, type Entity } from "gamefoo";
+ *
+ * class Gravity extends Behaviour<Entity> {
+ *   readonly type = "gravity";
+ *
+ *   update(deltaTime: number): void {
+ *     this.owner.y += 9.8 * 60 * deltaTime;
+ *   }
+ * }
+ * ```
+ *
+ * @example Attaching to an entity
+ * ```ts
+ * const entity = new Player("hero", 100, 100, 32, 32);
+ * entity.attachBehaviour(new Gravity(entity));
+ * ```
+ *
+ * @see {@link Entity.attachBehaviour}
+ * @see {@link Entity.detachBehaviour}
+ */
+export class Behaviour {
+    /**
+     * Reference to the entity that owns this behaviour.
+     * Available to subclasses for reading and mutating entity state.
+     */
+    owner;
+    /**
+     * Execution priority — lower numbers run first.
+     *
+     * When an entity has multiple behaviours, they are sorted by priority
+     * before each update/render pass.
+     *
+     * @defaultValue `1`
+     */
+    priority = 1;
+    /**
+     * Whether this behaviour is currently active.
+     *
+     * Disabled behaviours are skipped during both
+     * {@link Entity.updateBehaviours} and {@link Entity.renderBehaviours}.
+     *
+     * @defaultValue `true`
+     */
+    enabled = true;
+    /**
+     * Derived look-up key, equal to {@link Behaviour.type} in lowercase.
+     *
+     * Used internally by the entity's behaviour map so that look-ups are
+     * case-insensitive.
+     */
+    get key() {
+        return this.type.toLowerCase();
+    }
+    /**
+     * Creates a new behaviour bound to the given entity.
+     *
+     * @param owner - The entity this behaviour will operate on.
+     */
+    constructor(owner) {
+        this.owner = owner;
+    }
+}

package/dist/core/behaviours/collidable.js

@@ -0,0 +1,186 @@
+import { Behaviour } from "../behaviour";
+/**
+ * Collision behaviour that can be attached to any {@link Entity}.
+ *
+ * When attached, the `Collidable` automatically registers itself with
+ * the engine's {@link World} (via {@link Collidable.onAttach}) and
+ * unregisters on detach. Each frame the `World` queries the collider's
+ * shape, bounds, and tags to determine intersections.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Creating and attaching a box collider
+ * ```ts
+ * import { Collidable, Entity, type CollisionInfo } from "gamefoo";
+ *
+ * const entity = new Enemy("goblin", 100, 200, 30, 30);
+ *
+ * entity.attachBehaviour(
+ *   new Collidable(entity, engine.collisions, {
+ *     shape: { type: "aabb", width: 30, height: 30 },
+ *     layer: 0,
+ *     tags: new Set(["enemy"]),
+ *     solid: true,
+ *     collidesWith: new Set(["player"]),
+ *     onCollision: (info: CollisionInfo) => {
+ *       console.log(`${info.self.id} hit ${info.other.id}`);
+ *     },
+ *   }),
+ * );
+ * ```
+ *
+ * @example Circle collider for a projectile
+ * ```ts
+ * entity.attachBehaviour(
+ *   new Collidable(bullet, engine.collisions, {
+ *     shape: { type: "circle", radius: 4 },
+ *     tags: new Set(["bullet"]),
+ *     collidesWith: new Set(["enemy"]),
+ *   }),
+ * );
+ * ```
+ *
+ * @see {@link World}          — the collision detection system
+ * @see {@link ColliderShape}  — supported shape types
+ * @see {@link CollisionInfo}  — payload delivered to callbacks
+ * @see {@link Behaviour}      — abstract base class
+ */
+export class Collidable extends Behaviour {
+    /** @inheritDoc */
+    type = "collidable";
+    /**
+     * Geometric shape used for intersection tests.
+     *
+     * @see {@link ColliderShape}
+     */
+    shape;
+    /**
+     * Collision layer. Only colliders sharing the same layer value are
+     * tested.
+     *
+     * @defaultValue `0`
+     */
+    layer = 0;
+    /**
+     * Tags identifying this collider (e.g. `"player"`, `"enemy"`).
+     *
+     * @defaultValue empty `Set`
+     */
+    tags = new Set();
+    /**
+     * Tags this collider wants to be notified about.
+     *
+     * @defaultValue empty `Set`
+     */
+    collidesWith = new Set();
+    /**
+     * Whether this collider participates in overlap resolution.
+     *
+     * @defaultValue `false`
+     */
+    solid = false;
+    /**
+     * Whether the owning entity is immovable during overlap resolution.
+     *
+     * @defaultValue `false`
+     */
+    fixed = false;
+    /**
+     * User-supplied callback invoked when a tag-matched collision is
+     * detected.
+     */
+    onCollision;
+    /** Reference to the {@link World} this collider is registered with. */
+    world;
+    /**
+     * Creates a new collidable behaviour.
+     *
+     * @param owner   - The game object entity that owns this collider.
+     * @param world   - The collision {@link World} to register with.
+     * @param options - Configuration for shape, tags, solidity, and
+     *   callbacks. See {@link CollidableOptions}.
+     */
+    constructor(owner, world, options) {
+        super(owner);
+        this.world = world;
+        const size = owner.getSize();
+        this.shape = options.shape ?? {
+            type: "aabb",
+            width: size.width,
+            height: size.height,
+        };
+        this.layer = options.layer ?? 0;
+        this.tags = options.tags ?? new Set();
+        this.solid = options.solid ?? false;
+        this.fixed = options.fixed ?? false;
+        this.collidesWith = options.collidesWith ?? new Set();
+        this.onCollision = options.onCollision || (() => { });
+    }
+    /**
+     * No-op — collision logic lives in {@link World.detect}.
+     *
+     * @param _deltaTime - Unused.
+     */
+    update(_deltaTime) { }
+    /**
+     * Lifecycle hook: registers this collider with the {@link World}
+     * when the behaviour is attached to an entity.
+     *
+     * @see {@link Behaviour.onAttach}
+     */
+    onAttach() {
+        this.world.register(this);
+    }
+    /**
+     * Lifecycle hook: removes this collider from the {@link World}
+     * when the behaviour is detached.
+     *
+     * @see {@link Behaviour.onDetach}
+     */
+    onDetach() {
+        this.world.unregister(this);
+    }
+    /**
+     * Returns the {@link Entity} that owns this behaviour.
+     *
+     * Used by the {@link World} to read and mutate entity position
+     * during overlap resolution.
+     *
+     * @returns The owning entity.
+     */
+    getOwner() {
+        return this.owner;
+    }
+    /**
+     * Computes this collider's axis-aligned bounding rectangle in
+     * world-space, accounting for the shape's optional offset.
+     *
+     * @returns A {@link WorldBounds} rectangle.
+     *
+     * @example
+     * ```ts
+     * const bounds = collidable.getWorldBounds();
+     * // { x: 100, y: 200, width: 30, height: 30 }
+     * ```
+     */
+    getWorldBounds() {
+        const pos = this.owner.getPosition();
+        const offset = "offset" in this.shape && this.shape.offset ? this.shape.offset : { x: 0, y: 0 };
+        if (this.shape.type === "aabb") {
+            return {
+                x: pos.x + offset.x,
+                y: pos.y + offset.y,
+                width: this.shape.width,
+                height: this.shape.height,
+            };
+        }
+        const r = this.shape.radius;
+        return {
+            x: pos.x + offset.x - r,
+            y: pos.y + offset.y - r,
+            width: r * 2,
+            height: r * 2,
+        };
+    }
+}

package/dist/core/behaviours/control.js

@@ -0,0 +1,75 @@
+import { Behaviour } from "../behaviour";
+/**
+ * Keyboard-driven movement behaviour for a {@link Entity}.
+ *
+ * `Control` reads the current keyboard state from an {@link Input}
+ * instance every frame and translates WASD / arrow-key presses into
+ * entity position changes. Diagonal movement is normalised so the
+ * entity moves at a consistent speed in all directions.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Attaching to a player
+ * ```ts
+ * import { Control, Input, Player } from "gamefoo";
+ *
+ * const input  = new Input();
+ * const player = new Player("hero", 400, 300, 50, 50);
+ *
+ * player.attachBehaviour(new Control(player, input));
+ * ```
+ *
+ * @see {@link Input}     — the polling input manager consumed by this behaviour
+ * @see {@link Behaviour} — abstract base class
+ */
+export class Control extends Behaviour {
+    /** @inheritDoc */
+    type = "control";
+    /** The input manager to poll each frame. */
+    input;
+    /**
+     * Movement speed in pixels per second.
+     *
+     * @defaultValue `500`
+     */
+    speed = 500;
+    /**
+     * Creates a new keyboard control behaviour.
+     *
+     * @param owner - The game object entity whose position will be updated.
+     * @param input - The {@link Input} instance to read key state from.
+     */
+    constructor(owner, input) {
+        super(owner);
+        this.input = input;
+    }
+    /**
+     * Reads the current key state and moves the owner entity.
+     *
+     * Supported keys: `W` / `ArrowUp`, `S` / `ArrowDown`,
+     * `A` / `ArrowLeft`, `D` / `ArrowRight`.
+     *
+     * Diagonal input is normalised so the effective speed remains
+     * constant regardless of direction.
+     *
+     * @param deltaTime - Seconds elapsed since the previous frame.
+     */
+    update(deltaTime) {
+        let dx = 0;
+        let dy = 0;
+        if (this.input.isKeyDown("a") || this.input.isKeyDown("arrowleft"))
+            dx -= 1;
+        if (this.input.isKeyDown("d") || this.input.isKeyDown("arrowright"))
+            dx += 1;
+        if (this.input.isKeyDown("w") || this.input.isKeyDown("arrowup"))
+            dy -= 1;
+        if (this.input.isKeyDown("s") || this.input.isKeyDown("arrowdown"))
+            dy += 1;
+        const len = Math.sqrt(dx * dx + dy * dy);
+        if (len > 0) {
+            this.owner.x += (dx / len) * this.speed * deltaTime;
+            this.owner.y += (dy / len) * this.speed * deltaTime;
+        }
+    }
+}