@dryanovski/gamefoo 0.2.3 → 0.2.5

package/dist/subsystems/types.d.ts

@@ -1,4 +1,4 @@
-import type Engine from "@/core/engine";
+import type Engine from "../core/engine";
 /**
  * SubSystem is a modular component of the game engine that can be added or removed as needed.
  * It provides hooks for initialization, updating, rendering, and destruction.

package/dist/subsystems/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/subsystems/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC,SAAS,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAChD,MAAM,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC7C,UAAU,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAEjD,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/subsystems/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC,SAAS,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAChD,MAAM,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC7C,UAAU,CAAC,CAAC,GAAG,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAEjD,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared type definitions used throughout the GameFoo engine.
+ *
+ * This module contains the foundational interfaces and type aliases that
+ * form the contract between the engine core, entities, and behaviours.
+ *
+ * @category Types
+ * @module types
+ * @since 0.1.0
+ */

package/package.json

@@ -1,28 +1,38 @@
 {
   "name": "@dryanovski/gamefoo",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "A lightweight 2D game engine with behavior-based component system",
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "README.md"
   ],
   "type": "module",
   "sideEffects": false,
+  "source": "./src/index.ts",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./source": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "dev": "bun --watch demos/server.ts",
-    "build": "rm -rf dist && bun build ./src/index.ts --outdir dist --format esm --target browser --sourcemap=external --no-bundler && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bunx tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "typecheck:watch": "tsc --noEmit --watch",
     "lint": "bunx biome check src/",
@@ -36,7 +46,8 @@
     "docs:collect": "tsx scripts/collect-docs.ts",
     "docs:dev": "npm run docs:generate && astro dev --root ./docs",
     "docs:preview": "astro preview --root ./docs",
-    "docs:watch": "chokidar 'src/**/*.ts' -c 'bun run docs:generate' --initial"
+    "docs:watch": "chokidar 'src/**/*.ts' -c 'bun run docs:generate' --initial",
+    "test:publish": "bun run --cwd publish-test sanity"
   },
   "dependencies": {
     "@microsoft/tsdoc": "^0.16.0",

package/src/core/animate.ts

@@ -0,0 +1,159 @@
+/**
+ * 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"`). */
+  private key: string;
+
+  /** Ordered list of spritesheet cells that make up the animation. */
+  private frames: { col: number; row: number }[];
+
+  /** Width of a single frame in pixels. */
+  private frameW: number;
+
+  /** Height of a single frame in pixels. */
+  private frameH: number;
+
+  /**
+   * Index into {@link Animate.frames} of the frame currently being
+   * displayed.
+   *
+   * @defaultValue `0`
+   */
+  private currentFrame: number = 0;
+
+  /**
+   * Milliseconds accumulated since the last frame advance.
+   *
+   * @defaultValue `0`
+   */
+  private elapsed = 0;
+
+  /** Computed time between frames in milliseconds (`1000 / fps`). */
+  private interval: number;
+
+  /** Playback speed in frames per second. */
+  private fps: number;
+
+  /**
+   * 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: string, frames: { col: number; row: number }[], frameW: number, frameH: number, fps: number) {
+    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);
+   * ```
+   */
+  public update(delta: number) {
+    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.
+   */
+  public draw(_ctx: CanvasRenderingContext2D, _destX: number, _destY: number) {
+    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
+   * ```
+   */
+  public reset() {
+    this.currentFrame = 0;
+    this.elapsed = 0;
+  }
+}

package/src/core/asset.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+   */
+  private static cache: Map<string, HTMLImageElement> = 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: string): Promise<HTMLImageElement> {
+    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/src/core/behaviour.ts

@@ -0,0 +1,145 @@
+import type Entity from "../entities/entity";
+
+/**
+ * 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 abstract class Behaviour<T extends Entity = Entity> {
+  /**
+   * Reference to the entity that owns this behaviour.
+   * Available to subclasses for reading and mutating entity state.
+   */
+  protected owner: T;
+
+  /**
+   * Unique string identifier for this behaviour type.
+   *
+   * Used as the look-up key in {@link Entity.getBehaviour} and
+   * {@link Entity.hasBehaviour}. Must be a compile-time constant
+   * (`readonly`).
+   *
+   * @example
+   * ```ts
+   * class Gravity extends Behaviour {
+   *   readonly type = "gravity";
+   *   // ...
+   * }
+   * ```
+   */
+  abstract readonly type: string;
+
+  /**
+   * Execution priority — lower numbers run first.
+   *
+   * When an entity has multiple behaviours, they are sorted by priority
+   * before each update/render pass.
+   *
+   * @defaultValue `1`
+   */
+  public priority: number = 1;
+
+  /**
+   * Whether this behaviour is currently active.
+   *
+   * Disabled behaviours are skipped during both
+   * {@link Entity.updateBehaviours} and {@link Entity.renderBehaviours}.
+   *
+   * @defaultValue `true`
+   */
+  public enabled: boolean = 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(): string {
+    return this.type.toLowerCase();
+  }
+
+  /**
+   * Creates a new behaviour bound to the given entity.
+   *
+   * @param owner - The entity this behaviour will operate on.
+   */
+  constructor(owner: T) {
+    this.owner = owner;
+  }
+
+  /**
+   * Called once per frame to advance this behaviour's logic.
+   *
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  abstract update(deltaTime: number): void;
+
+  /**
+   * Optional rendering hook invoked after the entity's own
+   * {@link Entity.render} call.
+   *
+   * Override this to draw debug shapes, health bars, status effects, etc.
+   *
+   * @param ctx - The canvas 2-D rendering context.
+   */
+  render?(ctx: CanvasRenderingContext2D): void;
+
+  /**
+   * Lifecycle hook called immediately after the behaviour is attached
+   * to an entity via {@link Entity.attachBehaviour}.
+   *
+   * Use this for one-time setup such as registering with the
+   * collision {@link World}.
+   */
+  onAttach?(): void;
+
+  /**
+   * Lifecycle hook called when the behaviour is removed from an entity
+   * via {@link Entity.detachBehaviour}.
+   *
+   * Use this to unregister from external systems or release resources.
+   */
+  onDetach?(): void;
+}