@dryanovski/gamefoo 0.2.1 → 0.2.5

package/src/core/fonts/font_bitmap.ts

@@ -0,0 +1,232 @@
+import { metadata as FONT_3x5_METADATA } from "./internal/font_3x5";
+import { metadata as FONT_4x6_METADATA } from "./internal/font_4x6";
+import { metadata as FONT_5x5_METADATA } from "./internal/font_5x5";
+import { metadata as FONT_6x8_METADATA } from "./internal/font_6x8";
+import { metadata as FONT_8x8_METADATA } from "./internal/font_8x8";
+import { metadata as FONT_8x13_METADATA } from "./internal/font_8x13";
+
+/**
+ * Internal catalogue of registered bitmap font definitions.
+ *
+ * Fonts are added at module load time. Currently ships with the
+ * built-in {@link FONT_5x5 | 5x5} pixel font.
+ *
+ * @internal
+ */
+const Catalog = new Map<
+  string,
+  {
+    name: string;
+    width: number;
+    height: number;
+    chars: string;
+    spacing: number;
+    data: Record<string, number[]>;
+  }
+>();
+
+Catalog.set(FONT_3x5_METADATA.name, FONT_3x5_METADATA);
+Catalog.set(FONT_4x6_METADATA.name, FONT_4x6_METADATA);
+Catalog.set(FONT_5x5_METADATA.name, FONT_5x5_METADATA);
+Catalog.set(FONT_6x8_METADATA.name, FONT_6x8_METADATA);
+Catalog.set(FONT_8x13_METADATA.name, FONT_8x13_METADATA);
+Catalog.set(FONT_8x8_METADATA.name, FONT_8x8_METADATA);
+
+export type InternalBitmapFontName = "3x5" | "4x6" | "5x5" | "6x8" | "8x13" | "8x8";
+
+/**
+ * Pixel-perfect bitmap font renderer.
+ *
+ * `FontBitmap` looks up a named font from the built-in catalogue,
+ * then renders individual characters or whole strings onto a
+ * `CanvasRenderingContext2D` one pixel at a time using `fillRect`.
+ *
+ * Each character is stored as an array of row bitmasks where each bit
+ * represents a single pixel.
+ *
+ * @category Fonts
+ * @since 0.1.0
+ *
+ * @example Rendering text with the built-in 5x5 font
+ * ```ts
+ * import { FontBitmap } from "gamefoo";
+ *
+ * const font = new FontBitmap("5x5");
+ *
+ * ctx.fillStyle = "#ffffff";
+ * font.renderText("HELLO WORLD", 10, 10, ctx);
+ * ```
+ *
+ * @example Measuring text width
+ * ```ts
+ * const font  = new FontBitmap("5x5");
+ * const width = font.getTextWidth("SCORE 999");
+ * // width === 9 * 6 = 54 (each char is 5px + 1px spacing)
+ * ```
+ *
+ * @see {@link FONT_5x5} — the built-in 5x5 pixel font data
+ */
+export default class FontBitmap {
+  /** The catalogue name of the loaded font (e.g. `"5x5"`). */
+  public readonly name: string;
+
+  /**
+   * Character bitmask data keyed by character string.
+   *
+   * Each value is an array of integers where each integer represents
+   * one row of pixels (MSB = leftmost pixel).
+   */
+  protected readonly data: Record<string, number[]>;
+
+  /**
+   * Character cell width in pixels (including spacing).
+   *
+   * @defaultValue `0` (populated from catalogue on construction)
+   */
+  public width: number = 0;
+
+  /**
+   * Character cell height in pixels.
+   *
+   * @defaultValue `0` (populated from catalogue on construction)
+   */
+  public height: number = 0;
+
+  /**
+   * Horizontal spacing between the drawable area and the full cell
+   * width, in pixels.
+   *
+   * @defaultValue `0`
+   */
+  protected spacing: number = 0;
+
+  /**
+   * Creates a font renderer for the named catalogue entry.
+   *
+   * If the name does not match any registered font the instance will
+   * have empty data and zero dimensions — calls to `renderChar` /
+   * `renderText` will be no-ops.
+   *
+   * @param name - The catalogue key (e.g. `"5x5"`).
+   *
+   * @throws Error if the name is not found in the catalogue.
+   *
+   * @example
+   * ```ts
+   * const font = new FontBitmap("5x5");
+   * ```
+   */
+  constructor(name: InternalBitmapFontName) {
+    this.name = name;
+
+    this.data = {};
+
+    if (Catalog.has(name)) {
+      this.data = Catalog.get(name)!.data;
+    } else {
+      throw new Error(`FontBitmap: No font found for name "${name}".`);
+    }
+
+    this.width = this.metadata?.width || 0;
+    this.height = this.metadata?.height || 0;
+    this.spacing = this.metadata?.spacing || 0;
+  }
+
+  /**
+   * Returns the raw catalogue entry for this font, or `null` if the
+   * font name was not found.
+   *
+   * @returns Font metadata object or `null`.
+   */
+  get metadata() {
+    return Catalog.get(this.name) || null;
+  }
+
+  /**
+   * Retrieves the bitmask rows for a single character.
+   *
+   * @param char - A single character string (e.g. `"A"`).
+   * @returns An array of row bitmasks, or `null` if the character is
+   *   not defined in this font.
+   *
+   * @example
+   * ```ts
+   * const rows = font.getChar("A");
+   * // rows → [14, 17, 31, 17, 17] for the 5x5 font
+   * ```
+   */
+  getChar(char: string): number[] | null {
+    return this.data[char] || null;
+  }
+
+  /**
+   * Computes the pixel width required to render the given text string.
+   *
+   * @param text - The string to measure.
+   * @returns Width in pixels (`text.length * cellWidth`).
+   *
+   * @example
+   * ```ts
+   * const w = font.getTextWidth("HI"); // 12 for the 5x5 font
+   * ```
+   */
+  getTextWidth(text: string): number {
+    return text.length * this.width;
+  }
+
+  /**
+   * Renders a single character at the given pixel position.
+   *
+   * Each set bit in the character's row bitmask produces a 1x1
+   * `fillRect` call using the context's current `fillStyle`.
+   *
+   * @param char - The character to draw.
+   * @param x    - Left edge X coordinate in canvas pixels.
+   * @param y    - Top edge Y coordinate in canvas pixels.
+   * @param ctx  - The 2-D rendering context to draw into.
+   *
+   * @example
+   * ```ts
+   * ctx.fillStyle = "#00ff00";
+   * font.renderChar("G", 20, 40, ctx);
+   * ```
+   */
+  renderChar(char: string, x: number, y: number, ctx: CanvasRenderingContext2D) {
+    const charData = this.getChar(char);
+    if (charData === null) {
+      return;
+    }
+    for (let row = 0; row < charData.length; row++) {
+      const bits = charData[row]!;
+      for (let col = 0; col < this.width - this.spacing; col++) {
+        if ((bits & (1 << (this.width - this.spacing - 1 - col))) !== 0) {
+          ctx.fillRect(x + col, y + row, 1, 1);
+        }
+      }
+    }
+  }
+
+  /**
+   * Renders a full text string by drawing each character sequentially.
+   *
+   * Characters are spaced according to the font's cell width.
+   *
+   * @param text - The string to render.
+   * @param x    - Left edge X coordinate of the first character.
+   * @param y    - Top edge Y coordinate.
+   * @param ctx  - The 2-D rendering context.
+   *
+   * @example
+   * ```ts
+   * ctx.fillStyle = "#ffffff";
+   * font.renderText("GAME OVER", 100, 50, ctx);
+   * ```
+   */
+  renderText(text: string, x: number, y: number, ctx: CanvasRenderingContext2D) {
+    let offsetX = 0;
+    for (const char of text) {
+      this.renderChar(char, x + offsetX, y, ctx);
+      offsetX += this.width;
+    }
+  }
+}

package/src/core/fonts/font_bitmap_prebuild.ts

@@ -0,0 +1,141 @@
+import FontBitmap from "./font_bitmap";
+
+/**
+ * Bitmap font renderer that pre-builds character paths for faster rendering and
+ * reduced CPU usage at the cost of increased memory usage.
+ *
+ * GC pressure is reduced by pre-building `Path2D` objects for each character,
+ * which are then reused on subsequent renders. This can significantly improve
+ * performance when rendering the same characters multiple times, such as in a
+ * game UI or repeated text elements.
+ *
+ * Build on top of {@link FontBitmap}, `FontBitmapPrebuild` overrides the character rendering
+ *
+ * @category Fonts
+ * @since 0.2.0
+ *
+ * @example Pre-building glyphs for a menu
+ *
+ * ```ts
+ * import { FontBitmapPrebuild } from "gamefoo";
+ *
+ * const font = new FontBitmapPrebuild("5x5");
+ * font.prebuildGlyphs("PLAY SETTINGS EXIT".split(""));
+ *
+ * // Later in the render loop
+ * ctx.fillStyle = "#ffffff";
+ * font.renderText("PLAY", 10, 10, ctx);
+ * font.renderText("SETTINGS", 10, 20, ctx);
+ * font.renderText("EXIT", 10, 30, ctx);
+ * ```
+ *
+ * @example Performance comparison
+ *
+ * ```ts
+ * import { FontBitmap, FontBitmapPrebuild } from "gamefoo";
+ *
+ * const fontStandard = new FontBitmap("5x5");
+ * const fontPrebuild = new FontBitmapPrebuild("5x5");
+ * fontPrebuild.prebuildGlyphs("ABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""));
+ *
+ * // In the render loop, measure time taken to render a string multiple times
+ * console.time("Standard Bitmap");
+ * for (let i = 0; i < 1000; i++) {
+ *  fontStandard.renderText("HELLO WORLD", 10, 10, ctx);
+ * }
+ * console.timeEnd("Standard Bitmap");
+ *
+ * console.time("Prebuilt Bitmap");
+ * for (let i = 0; i < 1000; i++) {
+ *  fontPrebuild.renderText("HELLO WORLD", 10, 10, ctx);
+ * }
+ * console.timeEnd("Prebuilt Bitmap");
+ * ```
+ *
+ * @remarks
+ *
+ * Pre-building glyphs can significantly improve rendering performance when
+ * the same characters are rendered multiple times, as it avoids the overhead
+ * of constructing `Path2D` objects on each render. However, it does increase
+ * memory usage, especially if a large number of unique characters are pre-built.
+ * Use this class when you have a known set of characters that will be rendered
+ * frequently, such as in a game UI or static text elements.
+ *
+ * @see FontBitmap for a more memory-efficient alternative that builds paths on demand.
+ *
+ */
+export default class FontBitmapPrebuild extends FontBitmap {
+  /**
+   * Map of pre-built `Path2D` objects for each character. Keys are characters,
+   * values are their corresponding paths.
+   * This cache is used to store pre-built paths for characters that have been
+   * rendered at least once, allowing for faster rendering on subsequent calls.
+   */
+  private glyphPaths: Map<string, Path2D> = new Map();
+
+  /**
+   * Builds a `Path2D` object for the specified character based on its bitmap data.
+   * This method reads the character's bitmap data and constructs a path that
+   * represents the filled pixels of the character.
+   *
+   * @param char The character to build a path for.
+   *
+   * @returns A `Path2D` object representing the character's shape, or `null` if the character is not found in the font data.
+   *
+   * @remarks
+   * This method is called internally when a character is rendered for the first time
+   * or when pre-building glyphs. It converts the bitmap representation of the character
+   * into a vector path that can be efficiently rendered using `CanvasRenderingContext2D`.
+   * The resulting `Path2D` object is cached in the `glyphPaths` map for future use, reducing the overhead of path construction on subsequent renders.
+   */
+  private buildGlyphPath(char: string): Path2D | null {
+    const charData = this.getChar(char);
+    if (!charData) return null;
+
+    const path = new Path2D();
+    const w = this.width - this.spacing;
+    for (let row = 0; row < charData.length; row++) {
+      const bits = charData[row]!;
+      for (let col = 0; col < w; col++) {
+        if ((bits & (1 << (w - 1 - col))) !== 0) {
+          path.rect(col, row, 1, 1);
+        }
+      }
+    }
+    return path;
+  }
+
+  /**
+   * Pre-builds `Path2D` objects for a set of characters, storing them in the `glyphPaths`
+   * cache. This method can be called with a list of characters that are expected to
+   * be rendered frequently,
+   */
+  public prebuildGlyphs(chars: string[] = []): void {
+    for (const char of chars) {
+      if (!this.glyphPaths.has(char)) {
+        const built = this.buildGlyphPath(char);
+        if (built) {
+          this.glyphPaths.set(char, built);
+        }
+      }
+    }
+  }
+
+  /**
+   * Renders a single character at the given pixel position using a pre-built `Path2D` object.
+   * If the character's path has not been pre-built, it will be built on demand and cached for future use.
+   */
+  override renderChar(char: string, x: number, y: number, ctx: CanvasRenderingContext2D) {
+    let path = this.glyphPaths.get(char);
+    if (path === undefined) {
+      const built = this.buildGlyphPath(char);
+      if (!built) return;
+      path = built;
+      this.glyphPaths.set(char, path);
+    }
+
+    ctx.translate(x, y);
+    ctx.fill(path);
+    ctx.translate(-x, -y);
+  }
+}

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

@@ -0,0 +1,178 @@
+/**
+ * Built-in 3x5 pixel bitmap font.
+ *
+ * Each character is a 3-pixel-wide, 5-pixel-tall glyph stored as an
+ * array of 5 integers. Each integer is a bitmask where bit 2
+ * (MSB) corresponds to the leftmost pixel and bit 0 to the rightmost.
+ *
+ * Ultra-compact, great for HUDs and tiny labels.
+ *
+ * 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_3x5 from "./font_3x5";
+ *
+ * const letterA = FONT_3x5["A"];
+ * // 2, 5, 7, 5, 5
+ * ```
+ */
+
+/** Catalogue name used by {@link FontBitmap} to look up this font. */
+export const FONT_3x5_NAME = "3x5";
+
+/**
+ * Glyph width in pixels (excluding spacing).
+ * @defaultValue `3`
+ */
+export const FONT_3x5_WIDTH = 3;
+
+/**
+ * Glyph height in pixels.
+ * @defaultValue `5`
+ */
+export const FONT_3x5_HEIGHT = 5;
+
+/**
+ * Horizontal spacing between glyphs in pixels.
+ * @defaultValue `1`
+ */
+export const FONT_3x5_SPACING = 1;
+
+/**
+ * Complete set of supported characters as a single string.
+ */
+export const FONT_3x5_CHARS =
+  "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz !?.,:;-+*/\\()[]<>=#%&@^_'\"`~|$";
+
+/**
+ * Glyph data keyed by character.
+ *
+ * Each value is a 5-element `number[]` where each entry is a 3-bit
+ * row bitmask (bit 2 = leftmost pixel, bit 0 = rightmost pixel).
+ *
+ * @see {@link FontBitmap} — consumes this data for rendering
+ */
+export const FONT_3x5: Record<string, number[]> = {
+  "0": [2, 5, 5, 5, 2],
+  "1": [2, 6, 2, 2, 7],
+  "2": [6, 1, 2, 4, 7],
+  "3": [6, 1, 2, 1, 6],
+  "4": [5, 5, 7, 1, 1],
+  "5": [7, 4, 6, 1, 6],
+  "6": [3, 4, 6, 5, 2],
+  "7": [7, 1, 2, 2, 2],
+  "8": [2, 5, 2, 5, 2],
+  "9": [2, 5, 3, 1, 6],
+  A: [2, 5, 7, 5, 5],
+  B: [6, 5, 6, 5, 6],
+  C: [3, 4, 4, 4, 3],
+  D: [6, 5, 5, 5, 6],
+  E: [7, 4, 6, 4, 7],
+  F: [7, 4, 6, 4, 4],
+  G: [3, 4, 5, 5, 3],
+  H: [5, 5, 7, 5, 5],
+  I: [7, 2, 2, 2, 7],
+  J: [7, 1, 1, 5, 2],
+  K: [5, 5, 6, 5, 5],
+  L: [4, 4, 4, 4, 7],
+  M: [5, 7, 7, 5, 5],
+  N: [5, 7, 7, 5, 5],
+  O: [2, 5, 5, 5, 2],
+  P: [6, 5, 6, 4, 4],
+  Q: [2, 5, 5, 3, 1],
+  R: [6, 5, 6, 5, 5],
+  S: [3, 4, 2, 1, 6],
+  T: [7, 2, 2, 2, 2],
+  U: [5, 5, 5, 5, 7],
+  V: [5, 5, 5, 5, 2],
+  W: [5, 5, 5, 7, 5],
+  X: [5, 5, 2, 5, 5],
+  Y: [5, 5, 2, 2, 2],
+  Z: [7, 1, 2, 4, 7],
+  a: [0, 3, 5, 7, 5],
+  b: [4, 6, 5, 5, 6],
+  c: [0, 3, 4, 4, 3],
+  d: [1, 3, 5, 5, 3],
+  e: [0, 2, 5, 6, 3],
+  f: [3, 4, 6, 4, 4],
+  g: [0, 3, 5, 3, 6],
+  h: [4, 6, 5, 5, 5],
+  i: [0, 2, 0, 2, 3],
+  j: [0, 1, 0, 1, 6],
+  k: [4, 5, 6, 5, 5],
+  l: [2, 2, 2, 2, 3],
+  m: [0, 7, 7, 5, 5],
+  n: [0, 6, 5, 5, 5],
+  o: [0, 2, 5, 5, 2],
+  p: [0, 6, 5, 6, 4],
+  q: [0, 3, 5, 3, 1],
+  r: [0, 3, 4, 4, 4],
+  s: [0, 3, 2, 1, 6],
+  t: [2, 7, 2, 2, 3],
+  u: [0, 5, 5, 5, 3],
+  v: [0, 5, 5, 5, 2],
+  w: [0, 5, 5, 7, 5],
+  x: [0, 5, 2, 2, 5],
+  y: [0, 5, 3, 1, 6],
+  z: [0, 7, 2, 4, 7],
+  " ": [0, 0, 0, 0, 0],
+  "!": [2, 2, 2, 0, 2],
+  "?": [6, 1, 2, 0, 2],
+  ".": [0, 0, 0, 0, 2],
+  ",": [0, 0, 0, 2, 4],
+  ":": [0, 2, 0, 2, 0],
+  ";": [0, 2, 0, 2, 4],
+  "-": [0, 0, 7, 0, 0],
+  "+": [0, 2, 7, 2, 0],
+  "*": [0, 5, 2, 5, 0],
+  "/": [1, 1, 2, 4, 4],
+  "\\": [4, 4, 2, 1, 1],
+  "(": [1, 2, 2, 2, 1],
+  ")": [4, 2, 2, 2, 4],
+  "[": [3, 2, 2, 2, 3],
+  "]": [6, 2, 2, 2, 6],
+  "<": [1, 2, 4, 2, 1],
+  ">": [4, 2, 1, 2, 4],
+  "=": [0, 7, 0, 7, 0],
+  "#": [5, 7, 5, 7, 5],
+  "%": [5, 1, 2, 4, 5],
+  "&": [2, 5, 2, 5, 3],
+  "@": [2, 5, 7, 4, 3],
+  "^": [2, 5, 0, 0, 0],
+  _: [0, 0, 0, 0, 7],
+  "'": [2, 2, 0, 0, 0],
+  '"': [5, 5, 0, 0, 0],
+  "`": [4, 2, 0, 0, 0],
+  "~": [0, 2, 5, 4, 0],
+  "|": [2, 2, 2, 2, 2],
+  $: [2, 3, 6, 3, 2],
+};
+
+/**
+ * Complete metadata object for the 3x5 font, used by the
+ * {@link FontBitmap} catalogue at module load time.
+ *
+ * @internal
+ */
+export const metadata = {
+  /** Catalogue name. */
+  name: FONT_3x5_NAME,
+  /** Cell width including spacing (3 + 1 = 4). */
+  width: FONT_3x5_WIDTH + FONT_3x5_SPACING,
+  /** Cell height (5). */
+  height: FONT_3x5_HEIGHT,
+  /** Inter-glyph spacing (1). */
+  spacing: FONT_3x5_SPACING,
+  /** Supported character string. */
+  chars: FONT_3x5_CHARS,
+  /** Glyph bitmask data. */
+  data: FONT_3x5,
+};
+
+export default FONT_3x5;