@dryanovski/gamefoo 0.0.1 → 0.2.1

package/dist/core/behaviours/healtkit.d.ts

@@ -1,17 +1,134 @@
-import type DynamicEntity from "../../entities/dynamic_entity";
+import type Entity from "../../entities/entity";
 import { Behaviour } from "../behaviour";
-export declare class HealthKit extends Behaviour<DynamicEntity> {
+/**
+ * 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 declare class HealthKit extends Behaviour<Entity> {
+    /** @inheritDoc */
     readonly type = "healthkit";
+    /** Current health points. */
     private health;
+    /** Maximum health points (healing cap). */
     private maxHP;
-    constructor(owner: DynamicEntity, health: number, maxHP?: number);
+    /**
+     * 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: Entity, health: number, maxHP?: number);
+    /**
+     * No-op — health does not change passively each frame.
+     *
+     * @param _deltaTime - Unused.
+     */
     update(_deltaTime: number): void;
+    /**
+     * Reduces health by the given amount, clamping at zero.
+     *
+     * @param amount - Damage to apply (positive number).
+     *
+     * @example
+     * ```ts
+     * healthkit.takeDamage(30);
+     * ```
+     */
     takeDamage(amount: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * Returns the current health value.
+     *
+     * @returns Current HP.
+     */
     getHealth(): number;
+    /**
+     * Returns the maximum health cap.
+     *
+     * @returns Maximum HP.
+     */
     getMaxHealth(): number;
+    /**
+     * 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: number): void;
+    /**
+     * Whether the entity is dead (health is zero or below).
+     *
+     * @returns `true` if `health <= 0`.
+     *
+     * @example
+     * ```ts
+     * if (healthkit.isDead()) {
+     *   entity.destroy();
+     * }
+     * ```
+     */
     isDead(): boolean;
+    /**
+     * 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(): number;
 }
 //# sourceMappingURL=healtkit.d.ts.map

package/dist/core/behaviours/healtkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"healtkit.d.ts","sourceRoot":"","sources":["../../../core/behaviours/healtkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,qBAAa,SAAU,SAAQ,SAAS,CAAC,aAAa,CAAC;IACrD,QAAQ,CAAC,IAAI,eAAe;IAE5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAMhE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAEhC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIhC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI1B,SAAS,IAAI,MAAM;IAInB,YAAY,IAAI,MAAM;IAItB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOjC,MAAM,IAAI,OAAO;IAIjB,gBAAgB,IAAI,MAAM;CAG3B"}
+{"version":3,"file":"healtkit.d.ts","sourceRoot":"","sources":["../../../src/core/behaviours/healtkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAU,SAAQ,SAAS,CAAC,MAAM,CAAC;IAC9C,kBAAkB;IAClB,QAAQ,CAAC,IAAI,eAAe;IAE5B,6BAA6B;IAC7B,OAAO,CAAC,MAAM,CAAS;IAEvB,2CAA2C;IAC3C,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;;OAOG;gBACS,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAMzD;;;;OAIG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAEhC;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI1B;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAInB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOjC;;;;;;;;;;;OAWG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;;;;;;;;OAYG;IACH,gBAAgB,IAAI,MAAM;CAG3B"}

package/dist/core/behaviours/sprite_render.d.ts

@@ -0,0 +1,141 @@
+import type Entity from "../../entities/entity";
+import type { Vector2 } from "../../types";
+import { Behaviour } from "../behaviour";
+import type Sprite from "../sprite";
+/**
+ * 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<Entity> {
+    /** @inheritDoc */
+    readonly type = "sprite";
+    /** The spritesheet this renderer draws from. */
+    private sheet;
+    /**
+     * Name of the currently playing animation, or `null` if stopped.
+     *
+     * @defaultValue `null`
+     */
+    private currentFrame;
+    /**
+     * Index into the current animation's `frames` array.
+     *
+     * @defaultValue `0`
+     */
+    private currentFrameIndex;
+    /**
+     * Seconds accumulated towards the next frame advance.
+     *
+     * @defaultValue `0`
+     */
+    private elapsedTime;
+    /**
+     * Whether the sprite is drawn mirrored horizontally.
+     *
+     * @defaultValue `false`
+     */
+    private flipX;
+    /**
+     * Pixel offset applied to the draw position, relative to the
+     * entity's origin.
+     *
+     * @defaultValue `{ x: 0, y: 0 }`
+     */
+    offset: Vector2;
+    /**
+     * 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: Entity, sheet: Sprite);
+    /**
+     * 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: string): void;
+    /**
+     * Stops the current animation and resets playback state.
+     *
+     * After calling `stop`, nothing is drawn until {@link SpriteRender.play}
+     * is called again.
+     */
+    stop(): void;
+    /**
+     * 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: boolean): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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: CanvasRenderingContext2D): void;
+}
+//# sourceMappingURL=sprite_render.d.ts.map

package/dist/core/behaviours/sprite_render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite_render.d.ts","sourceRoot":"","sources":["../../../src/core/behaviours/sprite_render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,SAAS,CAAC,MAAM,CAAC;IACzD,kBAAkB;IAClB,QAAQ,CAAC,IAAI,YAAY;IAEzB,gDAAgD;IAChD,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAuB;IAE3C;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAAa;IAEtC;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAa;IAEhC;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAkB;IAE/B;;;;;OAKG;IACI,MAAM,EAAE,OAAO,CAAkB;IAExC;;;;;;;OAOG;gBACS,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAKxC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAS7B;;;;;OAKG;IACH,IAAI,IAAI,IAAI;IAMZ;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI7B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAwB/B;;;;;;;;OAQG;IACM,MAAM,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI;CA0BrD"}

package/dist/core/camera.d.ts

@@ -1,19 +1,120 @@
 import type { Vector2 } from "../types";
+/**
+ * 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. */
     private x;
+    /** Current Y coordinate of the camera centre. */
     private y;
+    /** Viewport width in pixels. */
     private width;
+    /** Viewport height in pixels. */
     private height;
+    /**
+     * Creates a camera with the given viewport dimensions.
+     *
+     * @param width  - Viewport width in pixels.
+     * @param height - Viewport height in pixels.
+     */
     constructor(width: number, height: number);
+    /**
+     * 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: Vector2): void;
+    /**
+     * 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: Vector2): void;
+    /**
+     * Returns the current centre position of the camera.
+     *
+     * @returns A new {@link Vector2} copy of the camera centre.
+     */
     getPosition(): Vector2;
+    /**
+     * 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(): {
         x: number;
         y: number;
         width: number;
         height: number;
     };
+    /**
+     * 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: number, height: number): void;
 }
 //# sourceMappingURL=camera.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../core/camera.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,OAAO,CAAC,CAAC,CAAa;IACtB,OAAO,CAAC,CAAC,CAAa;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;gBAEX,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAKzC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK7B,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK7B,WAAW,IAAI,OAAO;IAItB,WAAW,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAStE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAI5C"}
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../src/core/camera.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,iDAAiD;IACjD,OAAO,CAAC,CAAC,CAAa;IAEtB,iDAAiD;IACjD,OAAO,CAAC,CAAC,CAAa;IAEtB,gCAAgC;IAChC,OAAO,CAAC,KAAK,CAAS;IAEtB,iCAAiC;IACjC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBACS,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAKzC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK7B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK7B;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAStE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;CAI5C"}