@dryanovski/gamefoo 0.2.3 → 0.2.5

package/src/core/fonts/internal/font_8x8.ts

@@ -0,0 +1,180 @@
+/**
+ * Built-in 8x8 pixel bitmap font.
+ *
+ * Each character is a 8-pixel-wide, 8-pixel-tall glyph stored as an
+ * array of 8 integers. Each integer is a bitmask where bit 7
+ * (MSB) corresponds to the leftmost pixel and bit 0 to the rightmost.
+ *
+ * Chunky square glyphs, ideal at 2× or 4× scale.
+ *
+ * Supported characters: uppercase A–Z, lowercase a–z, digits 0–9,
+ * and common punctuation / special characters.
+ *
+ * @category Fonts
+ * @since 0.2.0
+ * @internal
+ *
+ * @example Reading a glyph
+ * ```ts
+ * import FONT_8x8 from "./font_8x8";
+ *
+ * const letterA = FONT_8x8["A"];
+ * // 24, 36, 66, 66, 126, 66, 66, 0
+ * ```
+ */
+
+/** Catalogue name used by {@link FontBitmap} to look up this font. */
+export const FONT_8x8_NAME = "8x8";
+
+/**
+ * Glyph width in pixels (excluding spacing).
+ * @defaultValue `8`
+ */
+export const FONT_8x8_WIDTH = 8;
+
+/**
+ * Glyph height in pixels.
+ * @defaultValue `8`
+ */
+export const FONT_8x8_HEIGHT = 8;
+
+/**
+ * Horizontal spacing between glyphs in pixels.
+ * @defaultValue `1`
+ */
+export const FONT_8x8_SPACING = 1;
+
+/**
+ * Complete set of supported characters as a single string.
+ */
+export const FONT_8x8_CHARS =
+  "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz !?.,:;-+*/\\()[]{}<>=#%&@^_'\"`~|$";
+
+/**
+ * Glyph data keyed by character.
+ *
+ * Each value is a 8-element `number[]` where each entry is a 8-bit
+ * row bitmask (bit 7 = leftmost pixel, bit 0 = rightmost pixel).
+ *
+ * @see {@link FontBitmap} — consumes this data for rendering
+ */
+export const FONT_8x8: Record<string, number[]> = {
+  "0": [60, 66, 70, 74, 82, 98, 60, 0],
+  "1": [24, 56, 24, 24, 24, 24, 126, 0],
+  "2": [60, 66, 2, 12, 48, 64, 126, 0],
+  "3": [126, 2, 4, 28, 2, 2, 124, 0],
+  "4": [4, 12, 20, 36, 68, 254, 4, 0],
+  "5": [254, 128, 252, 2, 2, 66, 60, 0],
+  "6": [62, 64, 128, 252, 130, 130, 124, 0],
+  "7": [254, 4, 8, 16, 32, 64, 128, 0],
+  "8": [60, 66, 66, 60, 66, 66, 60, 0],
+  "9": [60, 66, 66, 62, 2, 2, 60, 0],
+  A: [24, 36, 66, 66, 126, 66, 66, 0],
+  B: [252, 66, 66, 124, 66, 66, 252, 0],
+  C: [62, 64, 128, 128, 128, 64, 62, 0],
+  D: [248, 68, 66, 66, 66, 68, 248, 0],
+  E: [254, 128, 128, 252, 128, 128, 254, 0],
+  F: [254, 128, 128, 252, 128, 128, 128, 0],
+  G: [62, 64, 128, 142, 130, 66, 62, 0],
+  H: [66, 66, 66, 126, 66, 66, 66, 0],
+  I: [126, 24, 24, 24, 24, 24, 126, 0],
+  J: [62, 4, 4, 4, 132, 136, 112, 0],
+  K: [130, 132, 136, 240, 136, 132, 130, 0],
+  L: [128, 128, 128, 128, 128, 128, 254, 0],
+  M: [130, 198, 170, 146, 130, 130, 130, 0],
+  N: [130, 194, 162, 146, 138, 134, 130, 0],
+  O: [60, 66, 129, 129, 129, 66, 60, 0],
+  P: [252, 130, 130, 252, 128, 128, 128, 0],
+  Q: [60, 66, 129, 129, 133, 66, 61, 0],
+  R: [252, 130, 130, 252, 136, 132, 130, 0],
+  S: [62, 64, 128, 124, 2, 2, 252, 0],
+  T: [254, 16, 16, 16, 16, 16, 16, 0],
+  U: [130, 130, 130, 130, 130, 68, 56, 0],
+  V: [130, 130, 68, 68, 40, 40, 16, 0],
+  W: [130, 130, 130, 146, 170, 198, 130, 0],
+  X: [130, 68, 40, 16, 40, 68, 130, 0],
+  Y: [130, 68, 40, 16, 16, 16, 16, 0],
+  Z: [254, 4, 8, 16, 32, 64, 254, 0],
+  a: [0, 0, 60, 2, 62, 66, 62, 0],
+  b: [64, 64, 124, 66, 66, 66, 124, 0],
+  c: [0, 0, 62, 64, 64, 64, 62, 0],
+  d: [2, 2, 62, 66, 66, 66, 62, 0],
+  e: [0, 0, 60, 66, 126, 64, 62, 0],
+  f: [14, 16, 16, 62, 16, 16, 16, 0],
+  g: [0, 62, 66, 66, 62, 2, 60, 0],
+  h: [64, 64, 124, 66, 66, 66, 66, 0],
+  i: [16, 0, 48, 16, 16, 16, 62, 0],
+  j: [8, 0, 8, 8, 8, 72, 48, 0],
+  k: [64, 68, 72, 112, 72, 68, 66, 0],
+  l: [96, 32, 32, 32, 32, 32, 126, 0],
+  m: [0, 0, 218, 170, 170, 130, 130, 0],
+  n: [0, 0, 124, 66, 66, 66, 66, 0],
+  o: [0, 0, 60, 66, 66, 66, 60, 0],
+  p: [0, 124, 66, 66, 124, 64, 64, 0],
+  q: [0, 62, 66, 66, 62, 2, 2, 0],
+  r: [0, 0, 94, 96, 64, 64, 64, 0],
+  s: [0, 0, 62, 64, 60, 2, 124, 0],
+  t: [32, 32, 126, 32, 32, 34, 28, 0],
+  u: [0, 0, 66, 66, 66, 70, 58, 0],
+  v: [0, 0, 66, 66, 36, 40, 16, 0],
+  w: [0, 0, 130, 130, 146, 170, 68, 0],
+  x: [0, 0, 66, 36, 24, 36, 66, 0],
+  y: [0, 66, 66, 66, 62, 2, 60, 0],
+  z: [0, 0, 254, 4, 24, 96, 254, 0],
+  " ": [0, 0, 0, 0, 0, 0, 0, 0],
+  "!": [24, 24, 24, 24, 24, 0, 24, 0],
+  "?": [60, 66, 2, 4, 8, 0, 8, 0],
+  ".": [0, 0, 0, 0, 0, 48, 48, 0],
+  ",": [0, 0, 0, 0, 48, 48, 96, 0],
+  ":": [0, 24, 24, 0, 24, 24, 0, 0],
+  ";": [0, 24, 24, 0, 24, 24, 48, 0],
+  "-": [0, 0, 0, 254, 0, 0, 0, 0],
+  "+": [0, 16, 16, 254, 16, 16, 0, 0],
+  "*": [0, 130, 68, 56, 68, 130, 0, 0],
+  "/": [2, 4, 8, 16, 32, 64, 128, 0],
+  "\\": [128, 64, 32, 16, 8, 4, 2, 0],
+  "(": [12, 16, 32, 32, 32, 16, 12, 0],
+  ")": [48, 8, 4, 4, 4, 8, 48, 0],
+  "[": [120, 64, 64, 64, 64, 64, 120, 0],
+  "]": [30, 2, 2, 2, 2, 2, 30, 0],
+  "{": [30, 48, 16, 96, 16, 48, 30, 0],
+  "}": [120, 12, 8, 6, 8, 12, 120, 0],
+  "<": [4, 8, 16, 32, 16, 8, 4, 0],
+  ">": [32, 16, 8, 4, 8, 16, 32, 0],
+  "=": [0, 0, 254, 0, 254, 0, 0, 0],
+  "#": [36, 36, 254, 36, 254, 36, 36, 0],
+  "%": [194, 196, 8, 16, 32, 67, 131, 0],
+  "&": [56, 68, 72, 48, 74, 68, 58, 0],
+  "@": [60, 66, 157, 165, 158, 64, 60, 0],
+  "^": [16, 40, 68, 130, 0, 0, 0, 0],
+  _: [0, 0, 0, 0, 0, 0, 254, 0],
+  "'": [24, 24, 48, 0, 0, 0, 0, 0],
+  '"': [72, 72, 0, 0, 0, 0, 0, 0],
+  "`": [48, 24, 8, 0, 0, 0, 0, 0],
+  "~": [0, 70, 137, 144, 0, 0, 0, 0],
+  "|": [24, 24, 24, 24, 24, 24, 24, 0],
+  $: [24, 62, 96, 60, 6, 124, 24, 0],
+};
+
+/**
+ * Complete metadata object for the 8x8 font, used by the
+ * {@link FontBitmap} catalogue at module load time.
+ *
+ * @internal
+ */
+export const metadata = {
+  /** Catalogue name. */
+  name: FONT_8x8_NAME,
+  /** Cell width including spacing (8 + 1 = 9). */
+  width: FONT_8x8_WIDTH + FONT_8x8_SPACING,
+  /** Cell height (8). */
+  height: FONT_8x8_HEIGHT,
+  /** Inter-glyph spacing (1). */
+  spacing: FONT_8x8_SPACING,
+  /** Supported character string. */
+  chars: FONT_8x8_CHARS,
+  /** Glyph bitmask data. */
+  data: FONT_8x8,
+};
+
+export default FONT_8x8;

package/src/core/game_object_register.ts

@@ -0,0 +1,146 @@
+import type { GameObject } from "../types";
+
+/**
+ * Central registry that stores and manages all non-player
+ * {@link GameObject | game objects} within the engine.
+ *
+ * Objects are keyed by their `id` property, so each ID must be unique.
+ * The {@link Engine} delegates per-frame `update` and `render` calls to
+ * this register.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Registering and retrieving objects
+ * ```ts
+ * const register = new GameObjectRegister();
+ *
+ * register.register(tree);
+ * register.register(rock);
+ *
+ * const found = register.get("tree"); // Entity | undefined
+ * console.log(register.has("rock"));  // true
+ * ```
+ *
+ * @example Bulk update / render
+ * ```ts
+ * // Called internally by Engine each frame:
+ * register.updateAll(deltaTime);
+ * register.renderAll(ctx);
+ * ```
+ *
+ * @see {@link Engine.attachObjects} — convenience method that delegates here
+ */
+export default class GameObjectRegister {
+  /**
+   * Internal map from entity ID to its {@link GameObject} instance.
+   */
+  private objects: Map<string, GameObject> = new Map();
+
+  private _cache: GameObject[] | null = null;
+
+  /**
+   * Adds a game object to the registry.
+   *
+   * If an object with the same `id` already exists it will be
+   * silently overwritten.
+   *
+   * @param object - The game object to register.
+   *
+   * @example
+   * ```ts
+   * register.register(new Crate("crate_1", 200, 150, 32, 32));
+   * ```
+   */
+  register(object: GameObject) {
+    this.objects.set(object.id, object);
+    this._cache = null;
+  }
+
+  /**
+   * Retrieves a registered object by its unique ID.
+   *
+   * @param id - The ID of the object to find.
+   * @returns The matching {@link GameObject}, or `undefined` if not found.
+   *
+   * @example
+   * ```ts
+   * const crate = register.get("crate_1");
+   * if (crate) crate.x += 10;
+   * ```
+   */
+  get(id: string): GameObject | undefined {
+    return this.objects.get(id);
+  }
+
+  /**
+   * Checks whether an object with the given ID is registered.
+   *
+   * @param id - The ID to look up.
+   * @returns `true` if the registry contains the object.
+   */
+  has(id: string): boolean {
+    return this.objects.has(id);
+  }
+
+  /**
+   * Returns all registered objects as an array.
+   *
+   * Make sure to also cache the objects
+   *
+   * @since 0.2.0
+   *
+   * @returns An array of all {@link GameObject} instances in the registry.
+   */
+  toArray(): GameObject[] {
+    if (!this._cache) {
+      this._cache = Array.from(this.objects.values());
+    }
+
+    return this._cache;
+  }
+
+  /**
+   * Returns all registered objects that pass the supplied filter.
+   *
+   * @param filter - (optional) A predicate function. Return `true` to include the
+   *   object in the result.
+   * @returns An array of matching {@link GameObject} instances.
+   *
+   * @example
+   * ```ts
+   * const enemies = register.getAll(() => true);
+   * ```
+   */
+  getAll(filter?: () => true): GameObject[] {
+    if (typeof filter === "function") {
+      return this.toArray().filter(filter);
+    }
+
+    return this.toArray();
+  }
+
+  /**
+   * Calls {@link GameObject.update | update(deltaTime)} on every
+   * registered object.
+   *
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  updateAll(deltaTime: number): void {
+    for (const obj of this.getAll()) {
+      obj.update(deltaTime);
+    }
+  }
+
+  /**
+   * Calls {@link GameObject.render | render(ctx)} on every registered
+   * object.
+   *
+   * @param ctx - The canvas 2-D rendering context.
+   */
+  renderAll(ctx: CanvasRenderingContext2D): void {
+    for (const obj of this.getAll()) {
+      obj.render(ctx);
+    }
+  }
+}

package/src/core/input.ts

@@ -0,0 +1,182 @@
+/**
+ * Unified keyboard and mouse input manager.
+ *
+ * `Input` listens to `keydown`, `keyup`, `mousedown`, `mouseup`, and
+ * `mousemove` events on the `window` and exposes a polling API so game
+ * logic can query the current state at any point during a frame rather
+ * than relying on event callbacks.
+ *
+ * All keyboard keys are stored **lowercased** for case-insensitive
+ * look-ups.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Polling keys
+ * ```ts
+ * const input = new Input();
+ *
+ * function update() {
+ *   if (input.isKeyDown("w")) {
+ *     player.y -= speed;
+ *   }
+ * }
+ * ```
+ *
+ * @example Checking mouse state
+ * ```ts
+ * const input = new Input();
+ *
+ * if (input.isMouseButtonDown(0)) {           // left-click
+ *   const { x, y } = input.getMousePosition();
+ *   shoot(x, y);
+ * }
+ * ```
+ *
+ * @see {@link Control} — behaviour that consumes `Input` for player movement
+ */
+export default class Input {
+  /**
+   * Set of currently-pressed keyboard keys (lowercased).
+   *
+   * Populated on `keydown`, cleared on `keyup`.
+   */
+  private keys: Set<string> = new Set();
+
+  /**
+   * Set of currently-pressed mouse button indices.
+   *
+   * Standard mapping: `0` = left, `1` = middle, `2` = right.
+   */
+  private mouseButtons: Set<number> = new Set();
+
+  /**
+   * Last known mouse position in **client** (viewport) coordinates.
+   *
+   * @defaultValue `{ x: 0, y: 0 }`
+   */
+  private mousePosition: { x: number; y: number } = { x: 0, y: 0 };
+
+  /**
+   * Creates a new `Input` instance and attaches global event listeners
+   * to the `window`.
+   *
+   * @remarks
+   * Only one `Input` instance should exist at a time to avoid
+   * duplicate listeners. If you need to tear down, call {@link Input.reset}
+   * to clear tracked state.
+   */
+  constructor() {
+    window.addEventListener("keydown", (e) => {
+      this.keys.add(e.key.toLowerCase());
+    });
+
+    window.addEventListener("keyup", (e) => {
+      this.keys.delete(e.key.toLowerCase());
+    });
+
+    window.addEventListener("mousedown", (e) => {
+      this.mouseButtons.add(e.button);
+    });
+
+    window.addEventListener("mouseup", (e) => {
+      this.mouseButtons.delete(e.button);
+    });
+
+    window.addEventListener("mousemove", (e) => {
+      this.mousePosition.x = e.clientX;
+      this.mousePosition.y = e.clientY;
+    });
+  }
+
+  /**
+   * Checks whether a specific key is currently held down.
+   *
+   * @param key - The key name to check (case-insensitive).
+   *   Uses the standard {@link KeyboardEvent.key} values (e.g. `"a"`,
+   *   `"ArrowLeft"`, `"Shift"`).
+   * @returns `true` if the key is currently pressed.
+   *
+   * @example
+   * ```ts
+   * if (input.isKeyDown("space")) {
+   *   player.jump();
+   * }
+   * ```
+   */
+  isKeyDown(key: string): boolean {
+    return this.keys.has(key.toLowerCase());
+  }
+
+  /**
+   * Returns a snapshot of all keys that are currently held down.
+   *
+   * The returned `Set` is a **copy** — mutating it does not affect
+   * the internal state.
+   *
+   * @returns A new `Set<string>` of pressed key names (lowercased).
+   *
+   * @example
+   * ```ts
+   * const pressed = input.getPressedKeys();
+   * console.log([...pressed]); // e.g. ["w", "shift"]
+   * ```
+   */
+  getPressedKeys(): Set<string> {
+    return new Set(this.keys);
+  }
+
+  /**
+   * Checks whether a specific mouse button is currently held down.
+   *
+   * @param button - The mouse button index (`0` = left, `1` = middle,
+   *   `2` = right).
+   * @returns `true` if the button is currently pressed.
+   *
+   * @example
+   * ```ts
+   * if (input.isMouseButtonDown(2)) {
+   *   openContextMenu();
+   * }
+   * ```
+   */
+  isMouseButtonDown(button: number): boolean {
+    return this.mouseButtons.has(button);
+  }
+
+  /**
+   * Returns the last known mouse position in client (viewport)
+   * coordinates.
+   *
+   * The returned object is a **copy** — mutating it does not affect
+   * the internal state.
+   *
+   * @returns An `{ x, y }` object with the mouse coordinates.
+   *
+   * @example
+   * ```ts
+   * const pos = input.getMousePosition();
+   * ctx.fillRect(pos.x, pos.y, 4, 4); // draw cursor dot
+   * ```
+   */
+  getMousePosition(): { x: number; y: number } {
+    return { ...this.mousePosition };
+  }
+
+  /**
+   * Clears all tracked key and mouse-button state.
+   *
+   * Useful when pausing the game or switching scenes to prevent stale
+   * input from carrying over.
+   *
+   * @example
+   * ```ts
+   * engine.pause();
+   * input.reset();
+   * ```
+   */
+  reset(): void {
+    this.keys.clear();
+    this.mouseButtons.clear();
+  }
+}