@dryanovski/gamefoo 0.0.1 → 0.2.1

package/dist/core/input.d.ts

@@ -1,15 +1,146 @@
+/**
+ * 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 of currently-pressed mouse button indices.
+     *
+     * Standard mapping: `0` = left, `1` = middle, `2` = right.
+     */
     private mouseButtons;
+    /**
+     * Last known mouse position in **client** (viewport) coordinates.
+     *
+     * @defaultValue `{ x: 0, y: 0 }`
+     */
     private mousePosition;
+    /**
+     * 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();
+    /**
+     * 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;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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;
     };
+    /**
+     * 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;
 }
 //# sourceMappingURL=input.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../core/input.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAO,KAAK;IACxB,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,aAAa,CAA4C;;IAyBjE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI/B,cAAc,IAAI,GAAG,CAAC,MAAM,CAAC;IAI7B,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C,gBAAgB,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAI5C,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/core/input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,OAAO,OAAO,KAAK;IACxB;;;;OAIG;IACH,OAAO,CAAC,IAAI,CAA0B;IAEtC;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAA0B;IAE9C;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAA4C;IAEjE;;;;;;;;OAQG;;IAwBH;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;;;;;;;;;;OAaG;IACH,cAAc,IAAI,GAAG,CAAC,MAAM,CAAC;IAI7B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAI5C;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,IAAI;CAId"}

package/dist/core/sprite.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Describes a single named animation within a {@link Sprite} sheet.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example
+ * ```ts
+ * const walkAnim: AnimationDefinition = {
+ *   frames: [0, 1, 2, 3],
+ *   duration: 0.15,
+ *   loop: true,
+ * };
+ * ```
+ */
+interface AnimationDefinition {
+    /** Ordered frame indices into the spritesheet grid. */
+    frames: (string | number)[];
+    /** Time in seconds each frame is displayed before advancing. */
+    duration: number;
+    /** Whether the animation restarts from frame 0 after the last frame. */
+    loop: boolean;
+}
+/**
+ * Describes the position and size of a single frame within a {@link Sprite}
+ * sheet.
+ *
+ * @category Core
+ * @since 0.2.0
+ *
+ * @example
+ * ```ts
+ * const frame: SpriteFrame = {
+ *  x: 32,
+ *  y: 64,
+ *  width: 32,
+ *  height: 32,
+ *  anchor: { x: 16, y: 16 },
+ *  };
+ *  ```
+ */
+interface SpriteFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Configuration options for slicing a {@link Sprite} sheet into a grid of
+ * frames.
+ *
+ * @category Core
+ * @since 0.2.0
+ *
+ * @example
+ * ```ts
+ * const config: GridConfig = {
+ *  frameWidth: 32,
+ *  frameHeight: 32,
+ *  offsetX: 0,
+ *  offsetY: 0,
+ *  spacingX: 0,
+ *  spacingY: 0,
+ *  count: 16,
+ *  };
+ *  ```
+ */
+interface GridConfig {
+    frameWidth: number;
+    frameHeight: number;
+    offsetX?: number;
+    offsetY?: number;
+    spacingX?: number;
+    spacingY?: number;
+    count?: number;
+}
+/**
+ * Metadata wrapper around an {@link HTMLImageElement} that describes how
+ * it is sliced into a uniform grid of frames and what named animations
+ * are available.
+ *
+ * `Sprite` does **not** handle rendering itself — use
+ * {@link SpriteRender} to play animations on an entity.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Loading and creating a sprite
+ * ```ts
+ * import { Asset } from "gamefoo";
+ *
+ * const image = await Asset.load("hero.png");
+ * const sprite = new Sprite(image, 32, 32, {
+ *   idle: { frames: [0, 1], duration: 0.25, loop: true },
+ *   run:  { frames: [2, 3, 4, 5], duration: 0.1, loop: true },
+ * });
+ * ```
+ *
+ * @example Querying frame coordinates
+ * ```ts
+ * const rect = sprite.getFrameRect(5);
+ * ctx.drawImage(
+ *   sprite.image,
+ *   rect.x, rect.y, rect.width, rect.height,
+ *   destX, destY, rect.width, rect.height,
+ * );
+ * ```
+ *
+ * @see {@link SpriteRender} — behaviour that plays sprite animations
+ * @see {@link Asset}        — image loading utility
+ */
+export default class Sprite {
+    /** The underlying image element containing the full spritesheet. */
+    image: HTMLImageElement;
+    /** Width of a single frame cell in pixels. */
+    readonly width: number;
+    /** Height of a single frame cell in pixels. */
+    readonly height: number;
+    /**
+     * Number of frame columns in the spritesheet, computed as
+     * `Math.floor(image.width / width)`.
+     */
+    readonly columns: number;
+    /**
+     * Number of frame rows in the spritesheet, computed as
+     * `Math.floor(image.height / height)`.
+     */
+    readonly rows: number;
+    /**
+     * Named animation definitions keyed by animation name.
+     *
+     * Populated from the optional `animations` parameter passed to the
+     * constructor.
+     */
+    animations: Map<string, AnimationDefinition>;
+    /**
+     * @since 0.2.0
+     */
+    frames: Map<number | string, SpriteFrame>;
+    /**
+     * Creates a new spritesheet descriptor.
+     *
+     * @param image      - A fully-loaded `HTMLImageElement` containing the
+     *   spritesheet texture.
+     * @param width      - Width of each individual frame in pixels.
+     * @param height     - Height of each individual frame in pixels.
+     * @param animations - Optional map of named animation definitions.
+     *   Keys are animation names (e.g. `"idle"`, `"run"`).
+     *
+     * @example
+     * ```ts
+     * const sprite = new Sprite(img, 64, 64, {
+     *   idle: { frames: [0], duration: 1, loop: false },
+     * });
+     * ```
+     */
+    constructor(image: HTMLImageElement, width: number, height: number, animations?: Record<string, AnimationDefinition>);
+    /**
+     * Alternative constructor for spritesheets that are already sliced into a
+     * uniform grid of frames.
+     *
+     * @since 0.2.0
+     *
+     * @param image      - A fully-loaded `HTMLImageElement` containing the
+     *  spritesheet texture.
+     * @param config     - Configuration options for slicing the image into a
+     *  grid of frames.
+     * @param animations - Optional map of named animation definitions.
+     *  Keys are animation names (e.g. `"idle"`, `"run"`).
+     *
+     * @example
+     *  ```ts
+     *  const sprite = Sprite.fromGrid(img, {
+     *  frameWidth: 64,
+     *
+     *  frameHeight: 64,
+     *  offsetX: 0,
+     *  offsetY: 0,
+     *  spacingX: 0,
+     *  spacingY: 0,
+     *  count: 16,
+     *  }, {
+     *  idle: { frames: [0, 1], duration: 0.25, loop: true },
+     *  run:  { frames: [2, 3, 4, 5], duration: 0.1, loop: true },
+     *  });
+     *  ```
+     */
+    static fromGrid(image: HTMLImageElement, config: GridConfig, animations?: Record<string, AnimationDefinition>): Sprite;
+    /**
+     * Helper method to compute frame rectangles for a spritesheet sliced into a
+     * uniform grid.
+     *
+     * @since 0.2.0
+     *
+     * @param image  - A fully-loaded `HTMLImageElement` containing the
+     * spritesheet texture.
+     * @param config - Configuration options for slicing the image into a grid of
+     * frames.
+     *
+     * @returns A map of frame indices to their corresponding source rectangles.
+     *  Frame indices are zero-based and laid out left-to-right, top-to-bottom.
+     *  The source rectangles are in pixel coordinates relative to the top-left corner
+     *  of the source image.
+     */
+    private static generateGridFrames;
+    static fromAtlas(image: HTMLImageElement, regions: Record<string, SpriteFrame>, animations?: Record<string, AnimationDefinition>): Sprite;
+    static fromAseprite(imagePath: string, jsonPath: string): Promise<Sprite>;
+    /**
+     * Computes the source rectangle for a given frame index within the
+     * spritesheet.
+     *
+     * Frame indices are zero-based and laid out left-to-right,
+     * top-to-bottom.
+     *
+     * @param frame - Zero-based frame index.
+     * @returns An `{ x, y, width, height }` rectangle in pixel coordinates
+     *   relative to the top-left corner of the source image.
+     *
+     * @example
+     * ```ts
+     * // For a 4-column sheet, frame 5 → col 1, row 1
+     * const rect = sprite.getFrameRect(5);
+     * ```
+     */
+    getFrameRect(frame: number | string): SpriteFrame;
+}
+export {};
+//# sourceMappingURL=sprite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sprite.d.ts","sourceRoot":"","sources":["../../src/core/sprite.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,UAAU,mBAAmB;IAC3B,uDAAuD;IACvD,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,UAAU,WAAW;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,oEAAoE;IAC7D,KAAK,EAAE,gBAAgB,CAAC;IAE/B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACI,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAEpD;;OAEG;IACI,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,WAAW,CAAC,CAAC;IAEjD;;;;;;;;;;;;;;;;OAgBG;gBAED,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAgBlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,QAAQ,CACb,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,UAAU,EAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAC/C,MAAM;IAQT;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAqBjC,MAAM,CAAC,SAAS,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAC/C,MAAM;WAQI,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6B/E;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;CAOlD"}

package/dist/core/utils/perlin_noise.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Deterministic 2-D Perlin noise generator with fractal Brownian motion
+ * (fBm) support.
+ *
+ * Produces smooth, continuous noise suitable for terrain heightmaps,
+ * cloud textures, procedural vegetation placement, and other organic
+ * patterns. The output is fully reproducible for a given seed.
+ *
+ * The implementation uses a 256-entry permutation table shuffled by a
+ * seeded linear congruential generator (LCG) and Ken Perlin's improved
+ * 5th-order fade curve \( 6t^5 - 15t^4 + 10t^3 \).
+ *
+ * @category Utilities
+ * @since 0.1.0
+ *
+ * @example Basic noise sampling
+ * ```ts
+ * import { PerlinNoise } from "gamefoo";
+ *
+ * const noise = new PerlinNoise(42);
+ * const value = noise.noise2d(1.5, 2.3); // returns a value in [-1, 1]
+ * ```
+ *
+ * @example Generating a heightmap with fBm
+ * ```ts
+ * const noise = new PerlinNoise(12345);
+ * const map: number[][] = [];
+ *
+ * for (let y = 0; y < 128; y++) {
+ *   map[y] = [];
+ *   for (let x = 0; x < 128; x++) {
+ *     map[y][x] = noise.fbm(x * 0.05, y * 0.05, 6, 2, 0.5);
+ *   }
+ * }
+ * ```
+ *
+ * @example Seeded reproducibility
+ * ```ts
+ * const a = new PerlinNoise(7);
+ * const b = new PerlinNoise(7);
+ * console.log(a.noise2d(3, 4) === b.noise2d(3, 4)); // true
+ * ```
+ */
+export declare class PerlinNoise {
+    /**
+     * Doubled permutation table (512 entries) used for gradient hashing.
+     * Built from a 256-entry shuffle of `[0..255]` seeded by the LCG.
+     */
+    private perm;
+    /**
+     * Creates a new noise generator with the given seed.
+     *
+     * @param seed - An integer seed for the internal LCG. Identical seeds
+     *   produce identical noise fields.
+     *
+     * @defaultValue `0`
+     */
+    constructor(seed?: number);
+    /**
+     * Ken Perlin's improved 5th-order fade (smoothstep) curve:
+     * \( 6t^5 - 15t^4 + 10t^3 \).
+     *
+     * @param t - Value in `[0, 1]`.
+     * @returns Smoothed value in `[0, 1]`.
+     *
+     * @internal
+     */
+    private fade;
+    /**
+     * Standard linear interpolation.
+     *
+     * @param a - Start value.
+     * @param b - End value.
+     * @param t - Interpolant in `[0, 1]`.
+     * @returns Interpolated value.
+     *
+     * @internal
+     */
+    private lerp;
+    /**
+     * Computes a pseudo-random gradient dot product from a hash and
+     * 2-D offset.
+     *
+     * Uses the bottom 2 bits of `hash` to select one of four gradient
+     * directions.
+     *
+     * @param hash - Permutation table entry.
+     * @param x    - X offset from the grid point.
+     * @param y    - Y offset from the grid point.
+     * @returns Dot product of the gradient and offset vectors.
+     *
+     * @internal
+     */
+    private grad;
+    /**
+     * Samples 2-D Perlin noise at the given coordinates.
+     *
+     * @param x - X coordinate (any real number).
+     * @param y - Y coordinate (any real number).
+     * @returns A noise value in the range `[-1, 1]`.
+     *
+     * @example
+     * ```ts
+     * const n = noise.noise2d(0.5, 0.5);
+     * // n is a smooth, deterministic value in [-1, 1]
+     * ```
+     */
+    noise2d(x: number, y: number): number;
+    /**
+     * Computes fractal Brownian motion (fBm) by layering multiple
+     * octaves of {@link PerlinNoise.noise2d} with increasing frequency
+     * and decreasing amplitude.
+     *
+     * The result is normalised to `[-1, 1]`.
+     *
+     * @param x           - X coordinate.
+     * @param y           - Y coordinate.
+     * @param octaves     - Number of noise layers to sum.
+     * @param lacunarity  - Frequency multiplier per octave.
+     * @param persistence - Amplitude multiplier per octave (controls
+     *   roughness).
+     * @returns A noise value in `[-1, 1]`.
+     *
+     * @defaultValue octaves = `4`
+     * @defaultValue lacunarity = `2`
+     * @defaultValue persistence = `0.5`
+     *
+     * @example
+     * ```ts
+     * // 6 octaves for high detail:
+     * const height = noise.fbm(x * 0.01, y * 0.01, 6, 2.0, 0.5);
+     * ```
+     */
+    fbm(x: number, y: number, octaves?: number, lacunarity?: number, persistence?: number): number;
+}
+//# sourceMappingURL=perlin_noise.d.ts.map

package/dist/core/utils/perlin_noise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perlin_noise.d.ts","sourceRoot":"","sources":["../../../src/core/utils/perlin_noise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,IAAI,CAAa;IAEzB;;;;;;;OAOG;gBACS,IAAI,GAAE,MAAU;IAgB5B;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI;IAIZ;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI;IAIZ;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI;IAOZ;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAoBrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,SAAI,EAAE,UAAU,SAAI,EAAE,WAAW,SAAM,GAAG,MAAM;CAelF"}

package/dist/core/world.d.ts

@@ -1,14 +1,161 @@
 import type { Collidable } from "./behaviours/collidable";
+/**
+ * Spatial collision-detection world.
+ *
+ * `World` maintains a set of {@link Collidable} behaviours and, each
+ * frame, performs an **O(n^2)** broad-phase + narrow-phase pass via
+ * {@link World.detect}.  It supports:
+ *
+ * - **Layer filtering** — only colliders on the same layer are tested.
+ * - **Tag-based interest** — a collider only receives callbacks for
+ *   tags it has opted into via `collidesWith`.
+ * - **Shape combinations** — AABB vs AABB, circle vs circle, and
+ *   circle vs AABB.
+ * - **Solid overlap resolution** — when both colliders are marked
+ *   `solid`, entities are pushed apart along the axis of least
+ *   penetration.
+ * - **Fixed bodies** — colliders flagged `fixed` are immovable; the
+ *   other body absorbs the full push.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Registering colliders
+ * ```ts
+ * const world = new World();
+ *
+ * const collidable = new Collidable(entity, world, {
+ *   shape: { type: "aabb", width: 32, height: 32 },
+ *   layer: 0,
+ *   tags: new Set(["enemy"]),
+ *   solid: true,
+ *   collidesWith: new Set(["player", "bullet"]),
+ * });
+ *
+ * entity.attachBehaviour(collidable); // calls world.register internally
+ * ```
+ *
+ * @example Running detection manually
+ * ```ts
+ * world.detect(); // typically called by Engine.update each frame
+ * ```
+ *
+ * @see {@link Collidable} — the behaviour that plugs into this world
+ * @see {@link Engine}     — calls {@link World.detect} every frame
+ */
 export default class World {
+    /**
+     * The live set of all registered {@link Collidable} behaviours.
+     */
     private colliders;
+    /**
+     * Adds a collider to the world so it participates in future
+     * {@link World.detect} passes.
+     *
+     * Called automatically by {@link Collidable.onAttach}.
+     *
+     * @param collider - The collidable behaviour to register.
+     */
     register(collider: Collidable): void;
+    /**
+     * Removes a collider from the world.
+     *
+     * Called automatically by {@link Collidable.onDetach}.
+     *
+     * @param collider - The collidable behaviour to remove.
+     */
     unregister(collider: Collidable): void;
+    /**
+     * Runs one full collision-detection pass over every registered
+     * collider.
+     *
+     * **Algorithm:**
+     *
+     * 1. Iterate all unique pairs `(i, j)` where `i < j`.
+     * 2. Skip disabled colliders or mismatched layers.
+     * 3. Check tag interest in both directions.
+     * 4. Compute world bounds and test intersection.
+     * 5. If both are `solid`, resolve the overlap.
+     * 6. Fire `onCollision` callbacks on interested sides.
+     *
+     * @since 0.1.0
+     */
     detect(): void;
+    /**
+     * Returns `true` if any tag in `wants` exists in `has`.
+     *
+     * @param wants - Tags the collider is interested in.
+     * @param has   - Tags the other collider owns.
+     * @returns Whether at least one tag overlaps.
+     *
+     * @internal
+     */
     private tagsOverlap;
+    /**
+     * Dispatches to the correct narrow-phase test based on collider
+     * shape types.
+     *
+     * Supports AABB-vs-AABB, circle-vs-circle, and circle-vs-AABB.
+     *
+     * @param a       - First collidable.
+     * @param boundsA - World bounds of `a`.
+     * @param b       - Second collidable.
+     * @param boundsB - World bounds of `b`.
+     * @returns `true` if the two shapes overlap.
+     *
+     * @internal
+     */
     private intersects;
+    /**
+     * AABB-vs-AABB overlap test.
+     *
+     * @param a - First bounding rectangle.
+     * @param b - Second bounding rectangle.
+     * @returns `true` if the rectangles overlap.
+     *
+     * @internal
+     */
     private aabbVSAabb;
+    /**
+     * Circle-vs-circle overlap test using squared-distance comparison
+     * (avoids `Math.sqrt`).
+     *
+     * @param a       - First collidable (must have `circle` shape).
+     * @param boundsA - World bounds of `a`.
+     * @param b       - Second collidable (must have `circle` shape).
+     * @param boundsB - World bounds of `b`.
+     * @returns `true` if the circles overlap.
+     *
+     * @internal
+     */
     private circleVSCircle;
+    /**
+     * Circle-vs-AABB overlap test. Finds the closest point on the
+     * rectangle to the circle centre and checks the squared distance.
+     *
+     * @param circle       - The collidable with a `circle` shape.
+     * @param circleBounds - World bounds of the circle collider.
+     * @param rect         - World bounds of the AABB collider.
+     * @returns `true` if the circle and rectangle overlap.
+     *
+     * @internal
+     */
     private circleVSAAabb;
+    /**
+     * Resolves positional overlap between two solid colliders by pushing
+     * their owning entities apart along the axis of minimum penetration.
+     *
+     * Respects the `fixed` flag: if one collider is fixed the other
+     * absorbs the full displacement; if both are fixed, no resolution
+     * occurs.
+     *
+     * @param a       - First collidable.
+     * @param boundsA - World bounds of `a`.
+     * @param b       - Second collidable.
+     * @param boundsB - World bounds of `b`.
+     *
+     * @internal
+     */
     private resolveOverlap;
 }
 //# sourceMappingURL=world.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../core/world.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,CAAC,OAAO,OAAO,KAAK;IACxB,OAAO,CAAC,SAAS,CAA8B;IAE/C,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAIpC,UAAU,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAItC,MAAM,IAAI,IAAI;IA+Cd,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,UAAU;IAsBlB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,cAAc;CA4CvB"}
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/core/world.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,OAAO,OAAO,KAAK;IACxB;;OAEG;IACH,OAAO,CAAC,SAAS,CAA8B;IAE/C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAIpC;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAItC;;;;;;;;;;;;;;OAcG;IACH,MAAM,IAAI,IAAI;IA6Ed;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAOnB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,UAAU;IAiBlB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAIlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,cAAc;CAiCvB"}