@dryanovski/gamefoo 0.2.3 → 0.2.5

package/src/entities/entity.ts

@@ -0,0 +1,322 @@
+import type { Behaviour } from "../core/behaviour";
+import type { Demension, Vector2 } from "../types";
+
+/**
+ * Abstract base class for every game entity in the GameFoo engine.
+ *
+ * `Entity` provides:
+ *
+ * - **Identity** — a unique string {@link Entity.id | id}.
+ * - **Transform** — a 2-D {@link Entity.position | position} and
+ *   {@link Entity.size | size} with convenient `x`/`y` accessors.
+ * - **Behaviour system** — attach, detach, query, and bulk-update
+ *   {@link Behaviour} instances that compose an entity's logic.
+ *
+ * Subclasses must implement {@link Entity.update} and
+ * {@link Entity.render}.
+ *
+ * @category Entities
+ * @since 0.1.0
+ *
+ * @example Subclassing
+ * ```ts
+ * import { Entity } from "gamefoo";
+ *
+ * class Wall extends Entity {
+ *   constructor(x: number, y: number, w: number, h: number) {
+ *     super("wall", x, y, w, h);
+ *   }
+ *
+ *   update(_dt: number) {}
+ *
+ *   render(ctx: CanvasRenderingContext2D) {
+ *     ctx.fillStyle = "#888";
+ *     ctx.fillRect(this.x, this.y, this.size.width, this.size.height);
+ *   }
+ * }
+ * ```
+ *
+ * @example Attaching behaviours
+ * ```ts
+ * const entity = new Wall(0, 0, 100, 20);
+ * entity.attachBehaviour(new Collidable(entity, world, { ... }));
+ *
+ * if (entity.hasBehaviour("collidable")) {
+ *   console.log("Wall has collision!");
+ * }
+ * ```
+ *
+ * @see {@link DynamicEntity} — extends Entity with velocity / speed
+ * @see {@link Player}        — concrete player entity
+ * @see {@link Behaviour}     — composable logic units
+ */
+export default abstract class Entity {
+  /**
+   * Unique identifier for this entity.
+   *
+   * Used as the key in {@link GameObjectRegister} and for
+   * collision-callback identification.
+   */
+  public id: string = "";
+
+  /**
+   * World-space position of the entity's origin (top-left corner).
+   */
+  protected readonly position: Vector2 = { x: 0, y: 0 };
+
+  /**
+   * Bounding dimensions of the entity in pixels.
+   */
+  protected readonly size: Demension = { width: 0, height: 0 };
+
+  /**
+   * Internal map from behaviour key (lowercased type) to
+   * {@link Behaviour} instance.
+   */
+  private behaviorMap: Map<string, Behaviour> = new Map();
+
+  /**
+   * Priority-sorted cache of behaviours. Invalidated (`null`) whenever
+   * a behaviour is attached or detached.
+   */
+  private _sortedBehaviors: Behaviour[] | null = null;
+
+  /**
+   * Horizontal position of the entity (shorthand for
+   * `position.x`).
+   */
+  get x(): number {
+    return this.position.x;
+  }
+
+  /** Sets the horizontal position. */
+  set x(value: number) {
+    this.position.x = value;
+  }
+
+  /**
+   * Vertical position of the entity (shorthand for
+   * `position.y`).
+   */
+  get y(): number {
+    return this.position.y;
+  }
+
+  /** Sets the vertical position. */
+  set y(value: number) {
+    this.position.y = value;
+  }
+
+  /**
+   * Creates a new entity.
+   *
+   * @param id     - Unique string identifier.
+   * @param x      - Initial X position in pixels.
+   * @param y      - Initial Y position in pixels.
+   * @param width  - Width of the entity's bounding box in pixels.
+   * @param height - Height of the entity's bounding box in pixels.
+   *
+   * @example
+   * ```ts
+   * class Crate extends Entity {
+   *   constructor(x: number, y: number) {
+   *     super("crate", x, y, 32, 32);
+   *   }
+   *   // ...
+   * }
+   * ```
+   */
+  constructor(id: string, x: number, y: number, width?: number, height?: number) {
+    this.id = id;
+    this.position = { x, y };
+
+    if (width && height) {
+      this.size = { width, height };
+    }
+  }
+
+  /**
+   * Advances the entity's state by one frame.
+   *
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  abstract update(deltaTime: number): void;
+
+  /**
+   * Draws the entity to the canvas.
+   *
+   * @param ctx - The 2-D rendering context.
+   */
+  abstract render(ctx: CanvasRenderingContext2D): void;
+
+  /**
+   * Returns a **copy** of the entity's current position.
+   *
+   * @returns A new {@link Vector2} with the entity's `x` and `y`.
+   */
+  getPosition(): Vector2 {
+    return this.position;
+  }
+
+  /**
+   * Returns a **copy** of the entity's bounding dimensions.
+   *
+   * @returns An object with `width` and `height`.
+   */
+  getSize(): Demension {
+    return this.size;
+  }
+
+  /**
+   * Set size of the entity
+   *
+   * @since 0.2.0
+   *
+   * @return void
+   */
+  setSize(width: number, height: number): void {
+    this.size.width = width;
+    this.size.height = height;
+  }
+
+  /**
+   * Retrieves a behaviour by its key (case-insensitive).
+   *
+   * @typeParam T - The expected concrete behaviour type.
+   * @param key - The behaviour's {@link Behaviour.type | type} string.
+   * @returns The behaviour cast to `T`, or `undefined` if not found.
+   *
+   * @example
+   * ```ts
+   * const ctrl = entity.getBehaviour<Control>("control");
+   * if (ctrl) ctrl.enabled = false;
+   * ```
+   */
+  getBehaviour<T extends Behaviour>(key: string): T | undefined {
+    return this.behaviorMap.get(key.toLowerCase()) as T | undefined;
+  }
+
+  /**
+   * Returns all attached behaviours that are instances of the given
+   * class.
+   *
+   * @typeParam T - The behaviour subclass to filter by.
+   * @param type - The constructor function to test with `instanceof`.
+   * @returns An array of matching behaviours.
+   *
+   * @example
+   * ```ts
+   * const renderers = entity.getBehavioursByType(SpriteRender);
+   * ```
+   */
+  getBehavioursByType<T extends Behaviour>(type: new (...args: any[]) => T): T[] {
+    return this.behaviors.filter((b) => b instanceof type) as T[];
+  }
+
+  /**
+   * Checks whether a behaviour with the given key is attached.
+   *
+   * @param key - The behaviour's {@link Behaviour.type | type} string
+   *   (case-insensitive).
+   * @returns `true` if the behaviour exists on this entity.
+   */
+  hasBehaviour(key: string): boolean {
+    return this.behaviorMap.has(key.toLowerCase());
+  }
+
+  /**
+   * Attaches a behaviour to this entity.
+   *
+   * If the behaviour defines an {@link Behaviour.onAttach | onAttach}
+   * hook, it is called immediately.  The sorted-behaviour cache is
+   * invalidated.
+   *
+   * @typeParam T - The behaviour type being attached.
+   * @param behavior - The behaviour instance to add.
+   * @returns The same behaviour instance (for chaining).
+   *
+   * @example
+   * ```ts
+   * const hk = entity.attachBehaviour(new HealthKit(entity, 100));
+   * hk.takeDamage(10);
+   * ```
+   */
+  attachBehaviour<T extends Behaviour>(behavior: T): T {
+    this.behaviorMap.set(behavior.key, behavior);
+    this._sortedBehaviors = null;
+
+    if (behavior.onAttach) {
+      behavior.onAttach();
+    }
+    return behavior;
+  }
+
+  /**
+   * Detaches a behaviour by its key and calls
+   * {@link Behaviour.onDetach | onDetach} if defined.
+   *
+   * @param key - The behaviour's {@link Behaviour.type | type} string
+   *   (case-insensitive).
+   *
+   * @example
+   * ```ts
+   * entity.detachBehaviour("collidable");
+   * ```
+   */
+  detachBehaviour(key: string): void {
+    const behavior = this.behaviorMap.get(key.toLowerCase());
+    if (!behavior) return;
+
+    if (behavior.onDetach) {
+      behavior.onDetach();
+    }
+    this.behaviorMap.delete(key.toLowerCase());
+    this._sortedBehaviors = null;
+  }
+
+  /**
+   * Returns all attached behaviours sorted by
+   * {@link Behaviour.priority} (ascending).  The result is cached and
+   * only re-computed when behaviours are added or removed.
+   *
+   * @internal
+   */
+  private get behaviors(): Behaviour[] {
+    if (!this._sortedBehaviors) {
+      this._sortedBehaviors = Array.from(this.behaviorMap.values()).sort((a, b) => a.priority - b.priority);
+    }
+    return this._sortedBehaviors;
+  }
+
+  /**
+   * Calls {@link Behaviour.update | update(deltaTime)} on every
+   * enabled behaviour, in priority order.
+   *
+   * Typically called from a subclass's `update` implementation.
+   *
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  protected updateBehaviours(deltaTime: number): void {
+    for (const behavior of this.behaviors) {
+      if (behavior.enabled) {
+        behavior.update(deltaTime);
+      }
+    }
+  }
+
+  /**
+   * Calls {@link Behaviour.render | render(ctx)} on every enabled
+   * behaviour that defines a render method, in priority order.
+   *
+   * Typically called from a subclass's `render` implementation.
+   *
+   * @param ctx - The canvas 2-D rendering context.
+   */
+  protected renderBehaviours(ctx: CanvasRenderingContext2D): void {
+    for (const behavior of this.behaviors) {
+      if (behavior.enabled && behavior.render) {
+        behavior.render(ctx);
+      }
+    }
+  }
+}

package/src/entities/player.ts

@@ -0,0 +1,99 @@
+import type { Control } from "../core/behaviours/control";
+import type { HealthKit } from "../core/behaviours/healtkit";
+import DynamicEntity from "./dynamic_entity";
+
+/**
+ * Default player entity with convenience accessors for common
+ * behaviours.
+ *
+ * `Player` extends {@link DynamicEntity} and automatically delegates
+ * its {@link Player.update | update} and {@link Player.render | render}
+ * calls to all attached {@link Behaviour | behaviours}. It also
+ * provides typed getters for the {@link Control} and
+ * {@link HealthKit} behaviours so game code can access them without
+ * manual casting.
+ *
+ * Subclass `Player` to customise rendering, add game-specific logic,
+ * or bind additional behaviours.
+ *
+ * @category Entities
+ * @since 0.1.0
+ *
+ * @example Basic usage
+ * ```ts
+ * import { Player, Control, HealthKit, Input } from "gamefoo";
+ *
+ * const player = new Player("hero", 400, 300, 50, 50);
+ *
+ * player.attachBehaviour(new Control(player, new Input()));
+ * player.attachBehaviour(new HealthKit(player, 100));
+ *
+ * player.control?.enabled;           // true
+ * player.healthkit?.getHealth();      // 100
+ * ```
+ *
+ * @example Subclassing for custom rendering
+ * ```ts
+ * class Knight extends Player {
+ *   constructor(x: number, y: number) {
+ *     super("knight", x, y, 48, 48);
+ *   }
+ *
+ *   override render(ctx: CanvasRenderingContext2D) {
+ *     ctx.fillStyle = "#c0c0c0";
+ *     ctx.fillRect(this.x, this.y, 48, 48);
+ *     this.renderBehaviours(ctx);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DynamicEntity} — parent class (velocity, speed)
+ * @see {@link Control}       — keyboard movement behaviour
+ * @see {@link HealthKit}     — health-tracking behaviour
+ */
+export default class Player extends DynamicEntity {
+  /**
+   * Convenience getter for the attached {@link Control} behaviour.
+   *
+   * @returns The `Control` instance, or `undefined` if not attached.
+   */
+  get control(): Control | undefined {
+    return this.getBehaviour<Control>("control");
+  }
+
+  /**
+   * Convenience getter for the attached {@link HealthKit} behaviour.
+   *
+   * @returns The `HealthKit` instance, or `undefined` if not attached.
+   */
+  get healthkit(): HealthKit | undefined {
+    return this.getBehaviour<HealthKit>("healthkit");
+  }
+
+  /**
+   * Advances all attached behaviours.
+   *
+   * @inheritDoc
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  update(deltaTime: number): void {
+    this.updateBehaviours(deltaTime);
+  }
+
+  /**
+   * Draws a default blue rectangle and then renders all attached
+   * behaviours (e.g. sprite overlays, health bars).
+   *
+   * Override this in a subclass for custom visuals.
+   *
+   * TODO: write a better default player object
+   *
+   * @inheritDoc
+   * @param ctx - The canvas 2-D rendering context.
+   */
+  render(ctx: CanvasRenderingContext2D): void {
+    ctx.fillStyle = "blue";
+    ctx.fillRect(this.x, this.y, this.size.width, this.size.height);
+    this.renderBehaviours(ctx);
+  }
+}

package/src/entities/text.ts

@@ -0,0 +1,72 @@
+import FontBitmap, { type InternalBitmapFontName } from "../core/fonts/font_bitmap";
+import Entity from "./entity";
+
+/**
+ * Abstract base class for Text and Label alike objects
+ *
+ * `Text` extends {@link Entity} and could also get all behaviors attach to it but
+ * most likely there will be no need for that. Its primary design use case is to
+ * keep track of text objects and interact with them
+ *
+ * @category Entities
+ * @since 0.2.0
+ *
+ * @see {@link Entity} - parent class
+ */
+export default abstract class Text extends Entity {
+  /** Bitmap font name to load internally */
+  protected fontName: string;
+
+  /** BitmapFont instance used to manipulate the font */
+  protected font: FontBitmap;
+
+  /** Internal state of the text needed to be update */
+  protected text: string = "";
+
+  /**
+   * Create new Text object that could be placed and render on the screen
+   *
+   * @param fontName - the FontBitmap valid name to load
+   *
+   * @example
+   * ```ts
+   * const Label = new Text('CustomLabel', '5x5');
+   * ```
+   */
+  constructor(id: string, fontName: InternalBitmapFontName) {
+    super(id, 0, 0);
+
+    this.fontName = fontName;
+
+    this.font = new FontBitmap(fontName);
+  }
+
+  /**
+   * Set internal state value
+   *
+   * @param text - any content that should be render
+   *
+   * @return void
+   */
+  setText(text: string) {
+    this.text = text;
+
+    this.setSize(this.font.width * this.text.length, this.font.height);
+  }
+
+  /**
+   * Get the internal state of the object
+   *
+   * @return string
+   */
+  getText(): string {
+    return this.text;
+  }
+
+  /**
+   * Render the text to the canvas using the BitmapFont instance
+   */
+  override render(ctx: CanvasRenderingContext2D): void {
+    this.font.renderText(this.getText(), this.x, this.y, ctx);
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * GameFoo — a lightweight 2-D canvas game engine.
+ *
+ * This barrel module re-exports every public class, behaviour, utility,
+ * and type so consumers can import from a single entry point:
+ *
+ * ```ts
+ * import { Engine, Player, Input, Collidable } from "gamefoo";
+ * ```
+ *
+ * @category Core
+ * @module gamefoo
+ * @since 0.1.0
+ */
+
+// --- Assets / Rendering ───────────────────────────────────────────────
+export { default as Asset } from "./core/asset";
+// ── Core ────────────────────────────────────────────────────────────
+export { Behaviour } from "./core/behaviour";
+export { Collidable } from "./core/behaviours/collidable";
+export { Control } from "./core/behaviours/control";
+export { HealthKit } from "./core/behaviours/healtkit";
+export { default as SpriteRender } from "./core/behaviours/sprite_render";
+export { default as Camera } from "./core/camera";
+export { default as Engine } from "./core/engine";
+export { default as FontBitmap } from "./core/fonts/font_bitmap";
+export { default as FontBitmapPrebuild } from "./core/fonts/font_bitmap_prebuild";
+export { default as GameObjectRegister } from "./core/game_object_register";
+export { default as Input } from "./core/input";
+export { default as Sprite } from "./core/sprite";
+// ── Utilities ───────────────────────────────────────────────────────
+export { PerlinNoise } from "./core/utils/perlin_noise";
+// ── World / Physics ─────────────────────────────────────────────────
+export { default as World } from "./core/world";
+// -- Debug -----
+export { default as Monitor } from "./debug/monitor";
+// ── Decorators ───────────────────────────────────────────────────────
+export { log } from "./decorators/index";
+// ── Entities ────────────────────────────────────────────────────────
+export { default as DynamicEntity } from "./entities/dynamic_entity";
+export { default as Entity } from "./entities/entity";
+export { default as Player } from "./entities/player";
+export { default as Text } from "./entities/text";
+export { CameraSystem } from "./subsystems/camera_system";
+// ── Subsystems ───────────────────────────────────────────────────
+export { CollisionSystem } from "./subsystems/collision_system";
+export { MonitorSystem } from "./subsystems/monitor_system";
+export { ObjectSystem } from "./subsystems/object_system";
+export type { SubSystem } from "./subsystems/types";
+// ── Type-only exports ───────────────────────────────────────────────
+export type { ColliderShape, CollisionInfo, Demension, GameObject, Vector2 } from "./types";

package/src/subsystems/camera_system.ts

@@ -0,0 +1,52 @@
+import Camera from "../core/camera";
+import type { Vector2 } from "../types";
+import type { SubSystem } from "./types";
+
+/**
+ * CameraSystem is responsible for managing the camera's position and view.
+ * It can follow a target (like a player) and adjust the view accordingly.
+ *
+ * @since 0.2.0
+ *
+ * @category SubSystems
+ */
+export class CameraSystem implements SubSystem {
+  /**
+   * The unique identifier for this subsystem.
+   */
+  id = "camera";
+  order = 10;
+
+  camera: Camera;
+
+  private target: () => Vector2 | null = () => null;
+
+  constructor(width: number, height: number, target: () => Vector2 | null) {
+    this.camera = new Camera(width, height);
+
+    if (target) {
+      this.target = target;
+    }
+  }
+
+  update() {
+    let v = null;
+    if (this.target) {
+      v = this.target();
+    }
+
+    if (v !== null) {
+      this.camera.follow(v);
+    }
+  }
+
+  preRender(ctx: CanvasRenderingContext2D) {
+    const v = this.camera.getViewRect();
+    ctx.save();
+    ctx.translate(-v.x, -v.y);
+  }
+
+  postRender(ctx: CanvasRenderingContext2D) {
+    ctx.restore();
+  }
+}

package/src/subsystems/collision_system.ts

@@ -0,0 +1,21 @@
+import World from "../core/world";
+import type { SubSystem } from "./types";
+
+/**
+ * CollisionSystem is responsible for detecting collisions between game objects.
+ * It uses the World class to manage and detect collisions based on registered collidable objects.
+ *
+ * @since 0.2.0
+ *
+ * @category SubSystems
+ */
+export class CollisionSystem implements SubSystem {
+  id = "collision";
+  order = 30;
+
+  private world = new World();
+
+  update() {
+    this.world.detect();
+  }
+}

package/src/subsystems/monitor_system.ts

@@ -0,0 +1,26 @@
+import Monitor from "../debug/monitor";
+import type { SubSystem } from "./types";
+
+/**
+ * MonitorSystem is responsible for displaying debug information on the screen.
+ * It uses the Monitor class to track and render various performance metrics,
+ *
+ * @since 0.2.0
+ *
+ * @category SubSystems
+ */
+export class MonitorSystem implements SubSystem {
+  id = "monitor";
+
+  order = 100;
+
+  private monitor = new Monitor();
+
+  update(deltaTime: number) {
+    this.monitor.update(deltaTime);
+  }
+
+  render(ctx: CanvasRenderingContext2D) {
+    this.monitor.render(ctx);
+  }
+}

package/src/subsystems/object_system.ts

@@ -0,0 +1,37 @@
+import GameObjectRegister from "../core/game_object_register";
+import type { GameObject } from "../types";
+import type { SubSystem } from "./types";
+
+/**
+ * ObjectSystem is responsible for managing all non-player game objects within the engine.
+ * It maintains a central registry of game objects and delegates per-frame update and render calls to them.
+ *
+ * @since 0.2.0
+ * @category SubSystems
+ */
+export class ObjectSystem implements SubSystem {
+  id = "objects";
+
+  order = 20;
+
+  private objects: GameObjectRegister = new GameObjectRegister();
+
+  constructor(objects: GameObject[] = []) {
+    for (const obj of objects) {
+      this.objects.register(obj);
+    }
+  }
+
+  update(deltaTime: number) {
+    if (this.objects) {
+      console.time("ObjectSystem Update");
+      this.objects.updateAll(deltaTime);
+    }
+  }
+
+  render(ctx: CanvasRenderingContext2D) {
+    if (this.objects) {
+      this.objects.renderAll(ctx);
+    }
+  }
+}