@dryanovski/gamefoo 0.2.3 → 0.2.5

package/dist/core/world.js

@@ -0,0 +1,304 @@
+/**
+ * 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.
+     */
+    colliders = new Set();
+    /**
+     * 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) {
+        this.colliders.add(collider);
+    }
+    /**
+     * Removes a collider from the world.
+     *
+     * Called automatically by {@link Collidable.onDetach}.
+     *
+     * @param collider - The collidable behaviour to remove.
+     */
+    unregister(collider) {
+        this.colliders.delete(collider);
+    }
+    /**
+     * 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() {
+        /**
+         * Note: this naive O(n^2) approach is fine for small numbers of colliders
+         * (e.g. <100) but will degrade rapidly as that grows. For larger games,
+         * consider implementing spatial partitioning (e.g. quad-trees) to reduce
+         * the number of pairwise checks.
+         * In the meantime, users can mitigate performance issues by carefully
+         * managing which colliders are active and using layers/tags to minimize
+         * unnecessary checks.
+         * This method is intentionally straightforward for clarity and ease of
+         * extension (e.g. adding new shapes or filters) in the early stages of
+         * development.
+         *
+         * Future optimizations could include:
+         * - Spatial partitioning (quad-trees, grids)
+         *   - Sweep and prune (sorting by axis)
+         *   - Early-out checks (e.g. bounding circles)
+         *   - Parallel processing (Web Workers)
+         *   - Configurable broad-phase strategies
+         *   - Caching world bounds and only updating when necessary
+         *   - Object pooling for collision data structures
+         *   - Profiling and optimizing hot paths (e.g. intersection tests)
+         *   - Allowing users to provide custom collision filters or callbacks
+         *   - Supporting more complex shapes (polygons, capsules) with appropriate tests
+         *   - Providing debug visualization tools to help users understand collisions
+         *   - Documenting best practices for performance (e.g. using layers/tags effectively)
+         *   - Providing warnings or profiling tools when performance degrades due to too many colliders
+         *   - etc.
+         */
+        if (this.colliders.size === 0)
+            return;
+        const list = Array.from(this.colliders);
+        const len = list.length;
+        for (let i = 0; i < len; i++) {
+            const obj = list[i];
+            if (!obj?.enabled)
+                continue;
+            for (let j = i + 1; j < len; j++) {
+                const other = list[j];
+                if (!other?.enabled)
+                    continue;
+                if (obj.layer !== other.layer)
+                    continue;
+                const objWantOther = this.tagsOverlap(obj.collidesWith, other.tags);
+                const otherWantObj = this.tagsOverlap(other.collidesWith, obj.tags);
+                const boundsObj = obj.getWorldBounds();
+                const boundsOther = other.getWorldBounds();
+                if (!this.intersects(obj, boundsObj, other, boundsOther))
+                    continue;
+                if (obj.solid && other.solid) {
+                    this.resolveOverlap(obj, boundsObj, other, boundsOther);
+                }
+                if (objWantOther && obj.onCollision) {
+                    obj.onCollision({
+                        self: obj.getOwner(),
+                        other: other.getOwner(),
+                        selfTags: obj.tags,
+                        otherTags: other.tags,
+                    });
+                }
+                if (otherWantObj && other.onCollision) {
+                    other.onCollision({
+                        self: other.getOwner(),
+                        other: obj.getOwner(),
+                        selfTags: other.tags,
+                        otherTags: obj.tags,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * 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
+     */
+    tagsOverlap(wants, has) {
+        for (const tag of wants) {
+            if (has.has(tag))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * 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
+     */
+    intersects(a, boundsA, b, boundsB) {
+        const shapeA = a.shape;
+        const shapeB = b.shape;
+        if (shapeA.type === "aabb" && shapeB.type === "aabb") {
+            return this.aabbVSAabb(boundsA, boundsB);
+        }
+        if (shapeA.type === "circle" && shapeB.type === "circle") {
+            return this.circleVSCircle(a, boundsA, b, boundsB);
+        }
+        const [circle, circleBounds, rect] = shapeA.type === "circle" ? [a, boundsA, boundsB] : [b, boundsB, boundsA];
+        return this.circleVSAAabb(circle, circleBounds, rect);
+    }
+    /**
+     * AABB-vs-AABB overlap test.
+     *
+     * @param a - First bounding rectangle.
+     * @param b - Second bounding rectangle.
+     * @returns `true` if the rectangles overlap.
+     *
+     * @internal
+     */
+    aabbVSAabb(a, b) {
+        return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+    }
+    /**
+     * 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
+     */
+    circleVSCircle(a, boundsA, b, boundsB) {
+        if (a.shape.type !== "circle" || b.shape.type !== "circle")
+            return false;
+        const cx1 = boundsA.x + a.shape.radius;
+        const cy1 = boundsA.y + a.shape.radius;
+        const cx2 = boundsB.x + b.shape.radius;
+        const cy2 = boundsB.y + b.shape.radius;
+        const dx = cx2 - cx1;
+        const dy = cy2 - cy1;
+        const distSq = dx * dx + dy * dy;
+        const radSum = a.shape.radius + b.shape.radius;
+        return distSq <= radSum * radSum;
+    }
+    /**
+     * 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
+     */
+    circleVSAAabb(circle, circleBounds, rect) {
+        if (circle.shape.type !== "circle")
+            return false;
+        const cx = circleBounds.x + circle.shape.radius;
+        const cy = circleBounds.y + circle.shape.radius;
+        const closestX = Math.max(rect.x, Math.min(cx, rect.x + rect.width));
+        const closestY = Math.max(rect.y, Math.min(cy, rect.y + rect.height));
+        const dx = cx - closestX;
+        const dy = cy - closestY;
+        return dx * dx + dy * dy <= circle.shape.radius * circle.shape.radius;
+    }
+    /**
+     * 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
+     */
+    resolveOverlap(a, boundsA, b, boundsB) {
+        const overlapX = Math.min(boundsA.x + boundsA.width - boundsB.x, boundsB.x + boundsB.width - boundsA.x);
+        const overlapY = Math.min(boundsA.y + boundsA.height - boundsB.y, boundsB.y + boundsB.height - boundsA.y);
+        let pushX = 0;
+        let pushY = 0;
+        if (overlapX < overlapY) {
+            pushX = boundsA.x < boundsB.x ? -overlapX : overlapX;
+        }
+        else {
+            pushY = boundsA.y < boundsB.y ? -overlapY : overlapY;
+        }
+        const ownerA = a.getOwner();
+        const ownerB = b.getOwner();
+        if (a.fixed && b.fixed) {
+            return;
+        }
+        if (a.fixed) {
+            ownerB.x -= pushX;
+            ownerB.y -= pushY;
+        }
+        else if (b.fixed) {
+            ownerA.x += pushX;
+            ownerA.y += pushY;
+        }
+        else {
+            ownerA.x += pushX / 2;
+            ownerA.y += pushY / 2;
+            ownerB.x -= pushX / 2;
+            ownerB.y -= pushY / 2;
+        }
+    }
+}

package/dist/debug/monitor.js

@@ -0,0 +1,47 @@
+import FontBitmap from "../core/fonts/font_bitmap";
+const font = new FontBitmap("5x5");
+export default class Monitor {
+    fps = 0;
+    timer = 0;
+    frameCount = 0;
+    memory = 0;
+    frames = [0];
+    x = 8;
+    y = 8;
+    update(delta) {
+        this.frameCount++;
+        this.timer += delta;
+        if (this.timer >= 1.0) {
+            this.fps = this.frameCount / this.timer;
+            this.frameCount = 0;
+            this.timer = 0;
+            this.frames.push(this.fps);
+            if (this.frames.length > 60) {
+                this.frames.shift();
+            }
+        }
+        if (performance.memory) {
+            const mem = performance.memory;
+            this.memory = mem.usedJSHeapSize / 1048576;
+        }
+    }
+    render(ctx) {
+        ctx.save();
+        ctx.fillStyle = "#fff";
+        ctx.strokeStyle = "#fff";
+        font.renderText(`FPS: ${this.fps.toFixed(1)}`, this.x, this.y, ctx);
+        if (this.memory) {
+            font.renderText(`MEM: ${this.memory.toFixed(1)} MB`, this.x, this.y + font.height + 3, ctx);
+        }
+        if (this.frames.length >= 1) {
+            ctx.beginPath();
+            for (let i = 0; i < this.frames.length; i++) {
+                const x = this.x + i;
+                const y = this.x + font.height * 2 + 80 - (this.frames[i] ?? 0);
+                ctx.lineTo(x, y);
+            }
+            ctx.stroke();
+        }
+        ctx.restore();
+    }
+}

package/dist/decorators/index.js

@@ -0,0 +1 @@
+export * from "./log";

package/dist/decorators/log.js

@@ -0,0 +1,42 @@
+/**
+ * A method decorator that logs the method name, arguments, and return value.
+ *
+ * Uses the legacy (experimental) decorator protocol for compatibility with
+ * Bun's browser bundler.
+ *
+ * @category Decorators
+ * @since 0.2.0
+ *
+ * @param target    - The prototype of the class (instance method) or the constructor (static method).
+ * @param propertyKey - The name of the decorated method.
+ * @param descriptor  - The property descriptor for the method.
+ *
+ * @returns The modified property descriptor with logging behaviour.
+ *
+ * @example
+ * ```typescript
+ * class Example {
+ *  @log
+ *  myMethod(arg1: string, arg2: number) {
+ *   return `${arg1} - ${arg2}`;
+ *  }
+ * }
+ *
+ * const example = new Example();
+ * example.myMethod('test', 42);
+ *  Output:
+ *  ▶ myMethod(["test", 42])
+ *  ◀ myMethod → "test - 42"
+ * ```
+ */
+export function log(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    const prefix = `${target.constructor.name || "anonymous"}.${String(propertyKey)}`;
+    descriptor.value = function (...args) {
+        console.log(`▶ ${prefix}(${JSON.stringify(args)})`);
+        const result = originalMethod.apply(this, args);
+        console.log(`◀ ${prefix} →`, result);
+        return result;
+    };
+    return descriptor;
+}

package/dist/entities/dynamic_entity.js

@@ -0,0 +1,99 @@
+import Entity from "./entity";
+/**
+ * Abstract entity with built-in velocity and speed, suitable for any
+ * game object that moves (players, NPCs, projectiles, etc.).
+ *
+ * `DynamicEntity` extends {@link Entity} with a {@link Vector2}
+ * velocity and a scalar speed, plus getter/setter pairs for each.
+ * Subclasses are responsible for applying the velocity to position
+ * inside their {@link Entity.update | update} implementation.
+ *
+ * @category Entities
+ * @since 0.1.0
+ *
+ * @example Subclassing
+ * ```ts
+ * import { DynamicEntity } from "gamefoo";
+ *
+ * class Bullet extends DynamicEntity {
+ *   constructor(x: number, y: number) {
+ *     super("bullet", x, y, 4, 4);
+ *     this.setSpeed(600);
+ *     this.setVelocity({ x: 1, y: 0 });
+ *   }
+ *
+ *   update(dt: number) {
+ *     this.x += this.velocity.x * this.speed * dt;
+ *     this.y += this.velocity.y * this.speed * dt;
+ *   }
+ *
+ *   render(ctx: CanvasRenderingContext2D) {
+ *     ctx.fillStyle = "#ff0";
+ *     ctx.fillRect(this.x, this.y, 4, 4);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Entity} — parent class (identity, transform, behaviours)
+ * @see {@link Player} — concrete dynamic entity for the player
+ */
+export default class DynamicEntity extends Entity {
+    /**
+     * Directional velocity vector.
+     *
+     * Represents the normalised (or raw) direction of movement. Multiply
+     * by {@link DynamicEntity.speed | speed} and `deltaTime` to get the
+     * per-frame displacement.
+     *
+     * @defaultValue `{ x: 0, y: 0 }`
+     */
+    velocity = { x: 0, y: 0 };
+    /**
+     * Scalar movement speed in pixels per second.
+     *
+     * @defaultValue `0`
+     */
+    speed = 0;
+    /**
+     * Replaces the current velocity vector.
+     *
+     * @param velocity - The new velocity.
+     *
+     * @example
+     * ```ts
+     * entity.setVelocity({ x: -1, y: 0 }); // moving left
+     * ```
+     */
+    setVelocity(velocity) {
+        this.velocity = velocity;
+    }
+    /**
+     * Returns a **copy** of the current velocity vector.
+     *
+     * @returns A new {@link Vector2}.
+     */
+    getVelocity() {
+        return { ...this.velocity };
+    }
+    /**
+     * Sets the scalar movement speed.
+     *
+     * @param speed - Speed in pixels per second.
+     *
+     * @example
+     * ```ts
+     * entity.setSpeed(200);
+     * ```
+     */
+    setSpeed(speed) {
+        this.speed = speed;
+    }
+    /**
+     * Returns the current movement speed.
+     *
+     * @returns Speed in pixels per second.
+     */
+    getSpeed() {
+        return this.speed;
+    }
+}