@dryanovski/gamefoo 0.0.1 → 0.2.1

package/dist/core/engine.d.ts

@@ -1,39 +1,401 @@
-import type Player from "../entities/player";
-import type { GameObject } from "../types";
-import World from "./world";
+import type { SubSystem } from "@/subsystems/types";
+/**
+ * Configuration options for the {@link Engine}.
+ *
+ * Passed to the `Engine` constructor to customise visual defaults.
+ * Every property is optional; sensible defaults are applied internally.
+ *
+ * @example
+ * ```ts
+ * const config: EngineConfig = {
+ *   backgroundColor: "#1a1a2e",
+ * };
+ *
+ * const engine = new Engine("game", 800, 600, config);
+ * ```
+ */
 interface EngineConfig {
+    /**
+     * The CSS colour string used to clear the canvas each frame.
+     *
+     * Accepts any value valid for {@link CanvasRenderingContext2D.fillStyle}
+     * (hex, `rgb()`, `hsl()`, named colours, etc.).
+     *
+     * @defaultValue `"#000000"`
+     */
     backgroundColor?: string;
+    /**
+     * Global scale factor applied to the canvas via CSS transforms.
+     *
+     * @defaultValue `1` (no scaling)
+     */
+    gameScale?: number;
 }
 /**
- * Game Engine - the main class that manages the game loop, rendering, and overall game state.
+ * Core game engine responsible for the game loop, rendering pipeline,
+ * entity management, collision detection, and camera tracking.
+ *
+ * `Engine` owns a single HTML `<canvas>` element and drives a
+ * `requestAnimationFrame`-based loop that, on every tick:
+ *
+ * 1. Computes **deltaTime** (seconds since the previous frame).
+ * 2. Calls {@link Engine.update | update} — advances all entities and runs
+ *    collision detection via the internal {@link World}.
+ * 3. Calls {@link Engine.render | render} — clears the canvas and draws every
+ *    registered entity.
+ *
+ * ---
+ *
+ * ### Lifecycle
+ *
+ * ```text
+ * new Engine()          — creates canvas context, camera, object register, world
+ *      │
+ *      ▼
+ *   setup(fn)           — runs the user-supplied initialiser, then starts the loop
+ *      │
+ *      ▼
+ *  ┌─► loop(timestamp)  — called every frame via requestAnimationFrame
+ *  │     ├─ update(dt)
+ *  │     └─ render()
+ *  │         │
+ *  └─────────┘
+ *      │
+ *   pause() / clear() / destroy()  — stops or tears down the engine
+ * ```
+ *
+ * ---
+ *
+ * ### Minimal example
+ *
+ * ```ts
+ * import { Engine, Player } from "gamefoo";
+ *
+ * const engine = new Engine("game", 800, 600, {
+ *   backgroundColor: "#1a1a2e",
+ * });
+ *
+ * const player = new Player("hero", 400, 300, 50, 50);
+ * engine.player = player;
+ *
+ * engine.setup(() => {
+ *   console.log("Game started!");
+ * });
+ * ```
+ *
+ * ### Adding game objects
+ *
+ * ```ts
+ * import { Engine, DynamicEntity } from "gamefoo";
+ *
+ * const engine = new Engine("game", 800, 600, {});
+ *
+ * class Crate extends DynamicEntity {
+ *   constructor(x: number, y: number) {
+ *     super("crate", x, y, 32, 32);
+ *   }
+ *   override update(_dt: number) {}
+ *   override render(ctx: CanvasRenderingContext2D) {
+ *     ctx.fillStyle = "#8B4513";
+ *     ctx.fillRect(this.x, this.y, 32, 32);
+ *   }
+ * }
+ *
+ * engine.attachObjects(new Crate(200, 150));
+ *
+ * engine.setup(() => {
+ *   console.log("Crate placed!");
+ * });
+ * ```
+ *
+ * @see {@link Camera}            — viewport tracking
+ * @see {@link GameObjectRegister} — entity storage
+ * @see {@link World}             — collision detection
  */
 export default class Engine {
+    /**
+     * The underlying `<canvas>` DOM element retrieved by its `id` during
+     * construction.
+     */
     private canvas;
+    /**
+     * The 2-D rendering context obtained from {@link Engine.canvas}.
+     * Used by {@link Engine.render} and exposed indirectly to game objects.
+     */
     private ctx;
+    /**
+     * Timestamp (in milliseconds) of the previous animation frame.
+     * Used internally to calculate `deltaTime` between frames.
+     *
+     * Reset to `0` when the engine is set up via {@link Engine.setup}.
+     */
     private lastTime;
+    /**
+     * The logical width of the game world (and the canvas), in pixels.
+     *
+     * Set once during construction and also used by the {@link Camera}.
+     */
     private width;
+    /**
+     * The logical height of the game world (and the canvas), in pixels.
+     *
+     * Set once during construction and also used by the {@link Camera}.
+     */
     private height;
+    /**
+     * Guards against calling {@link Engine.setup} more than once.
+     * Flipped to `true` after the first successful setup invocation.
+     */
     private _initialized;
+    /**
+     * Whether the game loop is actively requesting new frames.
+     *
+     * - Set to `true` inside {@link Engine.setup}.
+     * - Set to `false` by {@link Engine.pause} or {@link Engine.clear}.
+     */
     private running;
+    /**
+     * Merged engine configuration. Combines user-supplied values with internal
+     * defaults (`backgroundColor: "#000000"`).
+     */
     private cnf;
-    private _player?;
-    private engine;
+    /**
+     * Global scale factor applied to the canvas via CSS transforms.
+     *
+     * This does not affect the internal resolution (`width` / `height`) or the
+     * camera viewport, but simply scales the rendered output for display.
+     *
+     */
+    gameScale: number;
+    /**
+     * The main subsystems of the engine, responsible for core functionalities
+     * like rendering, object management, collision detection, and monitoring.
+     *
+     * Subsystems are executed in a specific order determined by their `order` property
+     */
+    private subsystems;
+    /**
+     * Creates a new `Engine` instance, binds it to a `<canvas>` element,
+     * and initialises the camera, object register, and collision world.
+     *
+     * @param canvasId - The DOM `id` attribute of the `<canvas>` element to
+     *   render into. Must already exist in the document.
+     * @param width    - Logical width of the game area in pixels. Sets both
+     *   `canvas.width` and the camera viewport width.
+     * @param height   - Logical height of the game area in pixels. Sets both
+     *   `canvas.height` and the camera viewport height.
+     * @param config   - Optional overrides for engine-level settings.
+     *   See {@link EngineConfig}.
+     *
+     * @throws {Error} If no 2-D rendering context can be obtained from the
+     *   canvas (e.g. the browser does not support Canvas 2D).
+     *
+     * @example
+     * ```ts
+     * const engine = new Engine("game", 800, 600, {
+     *   backgroundColor: "#1a1a2e",
+     * });
+     * ```
+     */
     constructor(canvasId: string, width: number, height: number, config: EngineConfig);
-    set player(player: Player);
-    get player(): Player | undefined;
-    get collisions(): World;
-    attachObjects(objects: GameObject): void;
+    /**
+     * Attaches a subsystem to the engine, making it part of the update and render cycles.
+     *
+     * Subsystems are executed in a specific order determined by their `order` property (lower values run first).
+     *
+     * @since 0.2.0
+     *
+     * @param subsystem - The subsystem instance to attach. Must implement the {@link SubSystem} interface.
+     *
+     * @returns The engine instance, allowing for method chaining.
+     *
+     * @example
+     * ```ts
+     * engine.use(new ObjectSystem());
+     * engine.use(new CollisionSystem());
+     * ```
+     */
+    use(subsystem: SubSystem): this;
+    /**
+     * Runs a specific lifecycle hook on all enabled subsystems that implement it.
+     *
+     * This method is used internally by the game loop to delegate update and render calls to subsystems.
+     *
+     * @param hook - The name of the lifecycle method to invoke (e.g. "update", "render").
+     * @param args - Arguments to pass to the subsystem methods (e.g. `deltaTime` for updates, `ctx` for rendering).
+     *
+     * @remarks
+     * The method iterates over all subsystems, checks if they are enabled, and if they implement the specified hook. If so, it calls the hook method with the provided arguments.
+     * This allows for a flexible and modular architecture where subsystems can independently implement the lifecycle methods they need without being tightly coupled to the engine's core logic.
+     *
+     * @example
+     * ```ts
+     * // During the update phase of the game loop:
+     * this.run("update", deltaTime);
+     *
+     * // During the render phase of the game loop:
+     * this.run("render", ctx);
+     * ```
+     */
+    private run;
+    /**
+     * Resizes the canvas via CSS transforms so it fits within its parent
+     * container while preserving the original aspect ratio.
+     *
+     * Call this in a `window` `resize` event listener to keep the game
+     * centred and properly scaled in responsive layouts.
+     *
+     * @remarks
+     * The method calculates the uniform scale factor from the container
+     * dimensions and centres the canvas with a CSS `translate + scale`
+     * transform. The internal resolution (`width` / `height`) remains
+     * unchanged.
+     *
+     * @example
+     * ```ts
+     * window.addEventListener("resize", () => engine.handleResize());
+     * ```
+     */
     handleResize(): void;
+    /**
+     * Directly sets the canvas pixel dimensions.
+     *
+     * Unlike {@link Engine.handleResize}, this changes the **actual**
+     * resolution of the canvas (clearing its contents in the process).
+     *
+     * @param width  - New canvas width in pixels.
+     * @param height - New canvas height in pixels.
+     *
+     * @example
+     * ```ts
+     * engine.resize(1024, 768);
+     * ```
+     */
     resize(width: number, height: number): void;
+    /**
+     * Binds the `loop` method to the current `this` context so it can be passed directly to
+     * `requestAnimationFrame` without losing the correct reference to the engine instance.
+     *
+     * Also prevent the need of GC to create a new function on each frame, which could lead to performance issues over time.
+     */
+    private boundLoop;
+    /**
+     * The core animation loop driven by `requestAnimationFrame`.
+     *
+     * Each iteration:
+     * 1. Computes **deltaTime** (seconds since the last frame).
+     * 2. Delegates to {@link Engine.update} and {@link Engine.render}.
+     * 3. Schedules itself for the next frame (unless `running` is `false`).
+     *
+     * @param timestamp - The high-resolution timestamp provided by
+     *   `requestAnimationFrame`, in milliseconds.
+     *
+     * @internal
+     */
     private loop;
     /**
-     * Public - cause I'm old school
+     * Initialises the engine and starts the game loop.
+     *
+     * The supplied `setupFn` callback is invoked **synchronously** before the
+     * first frame. Use it to perform any last-minute setup that depends on
+     * the engine being ready (e.g. spawning initial entities, binding UI).
+     *
+     * Calling `setup` more than once is a no-op — a warning is logged to the
+     * console and the method returns immediately.
+     *
+     * @param setupFn - (optional) A synchronous callback executed once before the loop
+     *   begins. Typically used for scene initialisation.
+     *
+     * @example
+     * ```ts
+     * engine.setup(() => {
+     *   console.log("Engine initialised — first frame incoming!");
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Attempting a second setup is safely ignored:
+     * engine.setup(() => {}); // warns: "Engine is already initialized."
+     * ```
+     */
+    setup(setupFn?: () => void): Promise<void>;
+    /**
+     * Advances the game state by one tick.
+     *
+     * Called automatically by the game loop, but is `public` so it can be
+     * invoked manually for deterministic / test-driven updates.
+     *
+     *
+     * @param deltaTime - Time elapsed since the last frame, **in seconds**.
+     *
+     * @example
+     * ```ts
+     * // Manual update (useful for unit testing):
+     * engine.update(1 / 60); // simulate a single 60 FPS tick
+     * ```
+     */
+    update(_deltaTime: number): void;
+    /**
+     * Draws one complete frame to the canvas.
+     *
+     * Called automatically after {@link Engine.update} in the game loop, but
+     * is `public` for manual / debug rendering.
+     *
+     * @example
+     * ```ts
+     * // Force a single frame repaint:
+     * engine.render((ctx) => {
+     *   ctx.fillStyle = "red";
+     * });
+     * ```
+     */
+    render(_ctx: CanvasRenderingContext2D): void;
+    /**
+     * Pauses the game loop.
+     *
+     * The current frame finishes, but no further frames are scheduled.
+     * The canvas retains its last rendered state.
+     *
+     * Resume by calling {@link Engine.setup} on a **new** engine instance
+     * (the current instance cannot be restarted after pausing because
+     * `_initialized` remains `true`).
+     *
+     * @example
+     * ```ts
+     * document.addEventListener("visibilitychange", () => {
+     *   if (document.hidden) engine.pause();
+     * });
+     * ```
      */
-    setup(setupFn: () => void): Promise<void>;
-    update(deltaTime: number): void;
-    render(): void;
     pause(): void;
-    clear(): void;
+    /**
+     * Clear the screen and set default background colour.
+     *
+     * @example
+     * ```ts
+     * engine.clearScrean();
+     * // Canvas is now blank; loop is stopped.
+     * ```
+     */
+    clearScrean(): void;
+    /**
+     * Tears down the engine and releases resources.
+     *
+     * Use this to perform any cleanup such as removing event listeners or
+     * releasing external references when the engine is no longer needed.
+     *
+     * @remarks
+     * Currently a no-op placeholder. Extend this method when the engine
+     * acquires resources that need explicit cleanup (e.g. `ResizeObserver`,
+     * `WebSocket`, audio contexts).
+     *
+     * @example
+     * ```ts
+     * // When leaving the game screen:
+     * engine.destroy();
+     * ```
+     */
     destroy(): void;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,KAAK,MAAM,SAAS,CAAC;AAE5B,UAAU,YAAY;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,GAAG,CAA2B;IAEtC,OAAO,CAAC,QAAQ,CAAa;IAE7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,GAAG,CAET;IAEF,OAAO,CAAC,OAAO,CAAC,CAAS;IAEzB,OAAO,CAAC,MAAM,CAIZ;gBAEU,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;IA6BjF,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAExB;IAED,IAAI,MAAM,IAAI,MAAM,GAAG,SAAS,CAE/B;IAED,IAAI,UAAU,IAAI,KAAK,CAEtB;IAEM,aAAa,CAAC,OAAO,EAAE,UAAU;IAIxC,YAAY;IAkBZ,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK3C,OAAO,CAAC,IAAI;IAiBZ;;OAEG;IAEU,KAAK,CAAC,OAAO,EAAE,MAAM,IAAI;IAiB/B,MAAM,CAAC,SAAS,EAAE,MAAM;IAoBxB,MAAM;IAcN,KAAK;IAIL,KAAK;IAKL,OAAO;CAGf"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIpD;;;;;;;;;;;;;;GAcG;AACH,UAAU,YAAY;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAoB;IAElC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAA2B;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAkB;IAEtC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAkB;IAEjC;;;OAGG;IACH,OAAO,CAAC,GAAG,CAOT;IAEF;;;;;;OAMG;IACI,SAAS,EAAE,MAAM,CAAsB;IAE9C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAmB;IAErC;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;IA2BjF;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAgB/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,GAAG;IAeX;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY;IAkBZ;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK3C;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAwB;IAEzC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI;IA+DZ;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI;IA8BvC;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM;IAEhC;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,IAAI,EAAE,wBAAwB;IAE5C;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK;IAIZ;;;;;;;;OAQG;IACI,WAAW;IAMlB;;;;;;;;;;;;;;;;OAgBG;IACI,OAAO;CAQf"}

package/dist/core/fonts/font_bitmap.d.ts

@@ -0,0 +1,156 @@
+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"`). */
+    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)
+     */
+    width: number;
+    /**
+     * Character cell height in pixels.
+     *
+     * @defaultValue `0` (populated from catalogue on construction)
+     */
+    height: number;
+    /**
+     * Horizontal spacing between the drawable area and the full cell
+     * width, in pixels.
+     *
+     * @defaultValue `0`
+     */
+    protected spacing: number;
+    /**
+     * 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);
+    /**
+     * 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(): {
+        name: string;
+        width: number;
+        height: number;
+        chars: string;
+        spacing: number;
+        data: Record<string, number[]>;
+    } | 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;
+    /**
+     * 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;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+}
+//# sourceMappingURL=font_bitmap.d.ts.map

package/dist/core/fonts/font_bitmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font_bitmap.d.ts","sourceRoot":"","sources":["../../../src/core/fonts/font_bitmap.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,4DAA4D;IAC5D,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAElD;;;;OAIG;IACI,KAAK,EAAE,MAAM,CAAK;IAEzB;;;;OAIG;IACI,MAAM,EAAE,MAAM,CAAK;IAE1B;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,CAAK;IAE9B;;;;;;;;;;;;;;;OAeG;gBACS,IAAI,EAAE,sBAAsB;IAgBxC;;;;;OAKG;IACH,IAAI,QAAQ;cA1HJ,MAAM;eACL,MAAM;gBACL,MAAM;eACP,MAAM;iBACJ,MAAM;cACT,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;aAuH/B;IAED;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAItC;;;;;;;;;;OAUG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIlC;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB;IAe5E;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB;CAO7E"}

package/dist/core/fonts/font_bitmap_prebuild.d.ts

@@ -0,0 +1,102 @@
+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;
+    /**
+     * 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;
+    /**
+     * 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,
+     */
+    prebuildGlyphs(chars?: string[]): void;
+    /**
+     * 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.
+     */
+    renderChar(char: string, x: number, y: number, ctx: CanvasRenderingContext2D): void;
+}
+//# sourceMappingURL=font_bitmap_prebuild.d.ts.map

package/dist/core/fonts/font_bitmap_prebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font_bitmap_prebuild.d.ts","sourceRoot":"","sources":["../../../src/core/fonts/font_bitmap_prebuild.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,eAAe,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,UAAU;IACxD;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAkC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;;OAIG;IACI,cAAc,CAAC,KAAK,GAAE,MAAM,EAAO,GAAG,IAAI;IAWjD;;;OAGG;IACM,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB;CAatF"}