@dryanovski/gamefoo 0.2.1 → 0.2.5

package/dist/core/behaviours/healtkit.js

@@ -0,0 +1,153 @@
+import { Behaviour } from "../behaviour";
+/**
+ * Health-tracking behaviour for a {@link Entity}.
+ *
+ * `HealthKit` manages a current and maximum HP value, provides damage
+ * and healing methods, and exposes queries for health percentage and
+ * death state.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Attaching to a player
+ * ```ts
+ * import { HealthKit, Player } from "gamefoo";
+ *
+ * const player = new Player("hero", 400, 300, 50, 50);
+ * player.attachBehaviour(new HealthKit(player, 100));
+ *
+ * player.healthkit?.takeDamage(25);
+ * console.log(player.healthkit?.getHealth());        // 75
+ * console.log(player.healthkit?.getHealthPercent());  // 0.75
+ * ```
+ *
+ * @example Custom max HP
+ * ```ts
+ * const hk = new HealthKit(entity, 50, 200);
+ * // starts at 50 HP, max is 200
+ * hk.heal(999);
+ * console.log(hk.getHealth()); // 200 (clamped to max)
+ * ```
+ *
+ * @see {@link Behaviour} — abstract base class
+ * @see {@link Player}    — has a convenience getter for this behaviour
+ */
+export class HealthKit extends Behaviour {
+    /** @inheritDoc */
+    type = "healthkit";
+    /** Current health points. */
+    health;
+    /** Maximum health points (healing cap). */
+    maxHP;
+    /**
+     * Creates a new health behaviour.
+     *
+     * @param owner  - The entity this behaviour is attached to.
+     * @param health - Starting health value.
+     * @param maxHP  - Maximum health cap. If omitted, defaults to the
+     *   initial `health` value.
+     */
+    constructor(owner, health, maxHP) {
+        super(owner);
+        this.health = health;
+        this.maxHP = maxHP || health;
+    }
+    /**
+     * No-op — health does not change passively each frame.
+     *
+     * @param _deltaTime - Unused.
+     */
+    update(_deltaTime) { }
+    /**
+     * Reduces health by the given amount, clamping at zero.
+     *
+     * @param amount - Damage to apply (positive number).
+     *
+     * @example
+     * ```ts
+     * healthkit.takeDamage(30);
+     * ```
+     */
+    takeDamage(amount) {
+        this.health = Math.max(0, this.health - amount);
+    }
+    /**
+     * Increases health by the given amount, clamping at
+     * {@link HealthKit.maxHP}.
+     *
+     * @param amount - Health to restore (positive number).
+     *
+     * @example
+     * ```ts
+     * healthkit.heal(50);
+     * ```
+     */
+    heal(amount) {
+        this.health = Math.min(this.maxHP, this.health + amount);
+    }
+    /**
+     * Returns the current health value.
+     *
+     * @returns Current HP.
+     */
+    getHealth() {
+        return this.health;
+    }
+    /**
+     * Returns the maximum health cap.
+     *
+     * @returns Maximum HP.
+     */
+    getMaxHealth() {
+        return this.maxHP;
+    }
+    /**
+     * Updates the maximum health cap.
+     *
+     * If the current health exceeds the new cap it is clamped down.
+     *
+     * @param value - The new maximum HP.
+     *
+     * @example
+     * ```ts
+     * healthkit.setMaxHealth(150);
+     * ```
+     */
+    setMaxHealth(value) {
+        this.maxHP = value;
+        if (this.health > this.maxHP) {
+            this.health = this.maxHP;
+        }
+    }
+    /**
+     * Whether the entity is dead (health is zero or below).
+     *
+     * @returns `true` if `health <= 0`.
+     *
+     * @example
+     * ```ts
+     * if (healthkit.isDead()) {
+     *   entity.destroy();
+     * }
+     * ```
+     */
+    isDead() {
+        return this.health <= 0;
+    }
+    /**
+     * Returns health as a normalised ratio in the range `[0, 1]`.
+     *
+     * Useful for rendering health bars.
+     *
+     * @returns `health / maxHP`, or `0` if `maxHP` is zero.
+     *
+     * @example
+     * ```ts
+     * const barWidth = 100 * healthkit.getHealthPercent();
+     * ctx.fillRect(x, y, barWidth, 8);
+     * ```
+     */
+    getHealthPercent() {
+        return this.maxHP > 0 ? this.health / this.maxHP : 0;
+    }
+}

package/dist/core/behaviours/sprite_render.js

@@ -0,0 +1,193 @@
+import { Behaviour } from "../behaviour";
+/**
+ * Sprite animation renderer that can be attached to any {@link Entity}.
+ *
+ * `SpriteRender` plays named animations defined in a {@link Sprite}
+ * sheet, advancing frames based on each animation's `duration` and
+ * `loop` settings. It supports horizontal flipping for left/right
+ * facing and an optional pixel offset for fine-tuning draw position.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Attaching and playing an animation
+ * ```ts
+ * import { Asset, Sprite, SpriteRender, Player } from "gamefoo";
+ *
+ * const image  = await Asset.load("hero.png");
+ * const sheet  = 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 },
+ * });
+ *
+ * const player = new Player("hero", 100, 100, 32, 32);
+ * const sr     = new SpriteRender(player, sheet);
+ * player.attachBehaviour(sr);
+ *
+ * sr.play("idle");
+ * ```
+ *
+ * @example Flipping for directional facing
+ * ```ts
+ * if (velocity.x < 0) {
+ *   spriteRender.setFlipX(true);
+ * } else if (velocity.x > 0) {
+ *   spriteRender.setFlipX(false);
+ * }
+ * ```
+ *
+ * @see {@link Sprite}    — spritesheet metadata
+ * @see {@link Asset}     — image loader
+ * @see {@link Behaviour} — abstract base class
+ */
+export default class SpriteRender extends Behaviour {
+    /** @inheritDoc */
+    type = "sprite";
+    /** The spritesheet this renderer draws from. */
+    sheet;
+    /**
+     * Name of the currently playing animation, or `null` if stopped.
+     *
+     * @defaultValue `null`
+     */
+    currentFrame = null;
+    /**
+     * Index into the current animation's `frames` array.
+     *
+     * @defaultValue `0`
+     */
+    currentFrameIndex = 0;
+    /**
+     * Seconds accumulated towards the next frame advance.
+     *
+     * @defaultValue `0`
+     */
+    elapsedTime = 0;
+    /**
+     * Whether the sprite is drawn mirrored horizontally.
+     *
+     * @defaultValue `false`
+     */
+    flipX = false;
+    /**
+     * Pixel offset applied to the draw position, relative to the
+     * entity's origin.
+     *
+     * @defaultValue `{ x: 0, y: 0 }`
+     */
+    offset = { x: 0, y: 0 };
+    /**
+     * Creates a sprite renderer bound to the given entity and sheet.
+     *
+     * @param owner - The entity whose position determines where the
+     *   sprite is drawn.
+     * @param sheet - A {@link Sprite} containing the image and animation
+     *   definitions.
+     */
+    constructor(owner, sheet) {
+        super(owner);
+        this.sheet = sheet;
+    }
+    /**
+     * Starts (or switches to) the named animation.
+     *
+     * If the requested animation is already playing, the call is a no-op
+     * so the current playback position is preserved.
+     *
+     * @param animation - Name matching a key in
+     *   {@link Sprite.animations}.
+     *
+     * @example
+     * ```ts
+     * spriteRender.play("run");
+     * ```
+     */
+    play(animation) {
+        if (this.currentFrame === animation) {
+            return;
+        }
+        this.currentFrame = animation;
+        this.currentFrameIndex = 0;
+        this.elapsedTime = 0;
+    }
+    /**
+     * Stops the current animation and resets playback state.
+     *
+     * After calling `stop`, nothing is drawn until {@link SpriteRender.play}
+     * is called again.
+     */
+    stop() {
+        this.currentFrame = null;
+        this.currentFrameIndex = 0;
+        this.elapsedTime = 0;
+    }
+    /**
+     * Enables or disables horizontal flipping.
+     *
+     * Useful for mirroring a character sprite when facing left.
+     *
+     * @param flip - `true` to mirror horizontally, `false` for normal.
+     */
+    setFlipX(flip) {
+        this.flipX = flip;
+    }
+    /**
+     * Advances the animation clock and moves to the next frame when the
+     * animation's `duration` has elapsed.
+     *
+     * If the animation does not loop, it holds on the last frame.
+     *
+     * @param deltaTime - Seconds elapsed since the previous frame.
+     */
+    update(deltaTime) {
+        if (!this.currentFrame) {
+            return;
+        }
+        const animation = this.sheet.animations.get(this.currentFrame);
+        if (!animation) {
+            console.warn(`Animation "${this.currentFrame}" not found in sprite sheet.`);
+            return;
+        }
+        this.elapsedTime += deltaTime;
+        if (this.elapsedTime >= animation.duration) {
+            this.elapsedTime -= animation.duration;
+            this.currentFrameIndex++;
+            if (this.currentFrameIndex >= animation.frames.length) {
+                this.currentFrameIndex = animation.loop ? 0 : animation.frames.length - 1;
+            }
+        }
+    }
+    /**
+     * Draws the current animation frame to the canvas.
+     *
+     * Respects {@link SpriteRender.flipX} by temporarily mirroring the
+     * canvas transform, and applies {@link SpriteRender.offset} to the
+     * draw position.
+     *
+     * @param ctx - The canvas 2-D rendering context.
+     */
+    render(ctx) {
+        if (!this.currentFrame) {
+            return;
+        }
+        const animation = this.sheet.animations.get(this.currentFrame);
+        if (!animation) {
+            return;
+        }
+        const frameKey = animation.frames[this.currentFrameIndex];
+        const { x, y, width, height } = this.sheet.getFrameRect(frameKey);
+        const pos = this.owner.getPosition();
+        const drawX = pos.x + this.offset.x;
+        const drawY = pos.y + this.offset.y;
+        const size = this.owner.getSize();
+        if (this.flipX) {
+            ctx.save();
+            ctx.scale(-1, 1);
+            ctx.drawImage(this.sheet.image, x, y, width, height, -(drawX + size.width), drawY, size.width, size.height);
+            ctx.restore();
+        }
+        else {
+            ctx.drawImage(this.sheet.image, x, y, width, height, drawX, drawY, size.width, size.height);
+        }
+    }
+}

package/dist/core/camera.js

@@ -0,0 +1,134 @@
+/**
+ * A 2-D viewport camera that tracks a target position within the game
+ * world.
+ *
+ * The camera stores its own `(x, y)` centre and viewport dimensions.
+ * Each frame the {@link Engine} calls {@link Camera.follow} with the
+ * player's position so the viewport stays centred on the action.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Basic usage inside the engine
+ * ```ts
+ * const camera = new Camera(800, 600);
+ * camera.follow(player.getPosition());
+ *
+ * const view = camera.getViewRect();
+ * // view → { x: px - 400, y: py - 300, width: 800, height: 600 }
+ * ```
+ *
+ * @example Manual camera control
+ * ```ts
+ * const camera = new Camera(800, 600);
+ * camera.moveTo({ x: 0, y: 0 });       // jump to origin
+ * console.log(camera.getPosition());    // { x: 0, y: 0 }
+ * ```
+ *
+ * @see {@link Engine} — owns and drives the camera each frame
+ */
+export default class Camera {
+    /** Current X coordinate of the camera centre. */
+    x = 0;
+    /** Current Y coordinate of the camera centre. */
+    y = 0;
+    /** Viewport width in pixels. */
+    width;
+    /** Viewport height in pixels. */
+    height;
+    /**
+     * Creates a camera with the given viewport dimensions.
+     *
+     * @param width  - Viewport width in pixels.
+     * @param height - Viewport height in pixels.
+     */
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+    }
+    /**
+     * Centres the camera on a target position.
+     *
+     * Called by the engine every frame when a player is set.
+     *
+     * @param target - The world-space position to track.
+     *
+     * @example
+     * ```ts
+     * camera.follow(player.getPosition());
+     * ```
+     */
+    follow(target) {
+        this.x = target.x;
+        this.y = target.y;
+    }
+    /**
+     * Instantly teleports the camera to a specific position.
+     *
+     * Functionally identical to {@link Camera.follow} but communicates
+     * intent more clearly for one-shot repositioning (e.g. scene
+     * transitions).
+     *
+     * @param target - The world-space position to jump to.
+     *
+     * @example
+     * ```ts
+     * camera.moveTo({ x: 500, y: 300 });
+     * ```
+     */
+    moveTo(target) {
+        this.x = target.x;
+        this.y = target.y;
+    }
+    /**
+     * Returns the current centre position of the camera.
+     *
+     * @returns A new {@link Vector2} copy of the camera centre.
+     */
+    getPosition() {
+        return { x: this.x, y: this.y };
+    }
+    /**
+     * Computes the axis-aligned rectangle that represents the visible
+     * area in world-space.
+     *
+     * The rectangle is centred on the camera's current position.
+     *
+     * @returns An object with `x` (left edge), `y` (top edge), `width`,
+     *   and `height`.
+     *
+     * @example
+     * ```ts
+     * const rect = camera.getViewRect();
+     * // Use rect to cull off-screen objects
+     * if (entity.x < rect.x || entity.x > rect.x + rect.width) {
+     *   return; // off-screen — skip rendering
+     * }
+     * ```
+     */
+    getViewRect() {
+        return {
+            x: this.x - this.width / 2,
+            y: this.y - this.height / 2,
+            width: this.width,
+            height: this.height,
+        };
+    }
+    /**
+     * Updates the viewport dimensions, e.g. after a window resize.
+     *
+     * @param width  - New viewport width in pixels.
+     * @param height - New viewport height in pixels.
+     *
+     * @example
+     * ```ts
+     * window.addEventListener("resize", () => {
+     *   camera.resize(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    resize(width, height) {
+        this.width = width;
+        this.height = height;
+    }
+}

package/dist/core/engine.d.ts

@@ -1,4 +1,4 @@
-import type { SubSystem } from "@/subsystems/types";
+import type { SubSystem } from "../subsystems/types";
 /**
  * Configuration options for the {@link Engine}.
  *

package/dist/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIpD;;;;;;;;;;;;;;GAcG;AACH,UAAU,YAAY;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAoB;IAElC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAA2B;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAkB;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAkB;IAEjC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAOT;IAEF;;;;;;OAMG;IACI,SAAS,EAAE,MAAM,CAAsB;IAE9C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAmB;IAErC;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;IA2BjF;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAgB/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,GAAG;IAeX;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY;IAkBZ;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK3C;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAwB;IAEzC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI;IA+DZ;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI;IA8BvC;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM;IAEhC;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,IAAI,EAAE,wBAAwB;IAE5C;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK;IAIZ;;;;;;;;OAQG;IACI,WAAW;IAMlB;;;;;;;;;;;;;;;;OAgBG;IACI,OAAO;CAQf"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;;;;;;;;;;;GAcG;AACH,UAAU,YAAY;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAoB;IAElC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAA2B;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAkB;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAkB;IAEjC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAOT;IAEF;;;;;;OAMG;IACI,SAAS,EAAE,MAAM,CAAsB;IAE9C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAmB;IAErC;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;IA2BjF;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAgB/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,GAAG;IAeX;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY;IAkBZ;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK3C;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAwB;IAEzC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI;IA+DZ;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI;IA8BvC;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM;IAEhC;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,IAAI,EAAE,wBAAwB;IAE5C;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK;IAIZ;;;;;;;;OAQG;IACI,WAAW;IAMlB;;;;;;;;;;;;;;;;OAgBG;IACI,OAAO;CAQf"}