@guinetik/gcanvas 1.0.0

package/test/util/scene3d.test.js

@@ -0,0 +1,352 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Scene3D } from "../../src/game/objects/scene3d";
+import { Camera3D } from "../../src/util/camera3d";
+import { Painter } from "../../src/painter/painter";
+
+// Mock game object
+const createMockGame = () => ({
+  width: 800,
+  height: 600,
+});
+
+// Mock child game object
+const createMockChild = (options = {}) => ({
+  x: options.x ?? 0,
+  y: options.y ?? 0,
+  z: options.z ?? undefined,
+  visible: options.visible ?? true,
+  draw: vi.fn(),
+});
+
+describe("Scene3D", () => {
+  let mockGame;
+  let camera;
+
+  beforeEach(() => {
+    mockGame = createMockGame();
+    camera = new Camera3D({ perspective: 800 });
+
+    // Reset Painter mocks
+    if (Painter.save) Painter.save.mockClear?.();
+    if (Painter.restore) Painter.restore.mockClear?.();
+    if (Painter.translateTo) Painter.translateTo = vi.fn();
+  });
+
+  describe("constructor", () => {
+    it("should throw if camera is not provided", () => {
+      expect(() => {
+        new Scene3D(mockGame, {});
+      }).toThrow("Scene3D requires a camera option");
+    });
+
+    it("should initialize with camera", () => {
+      const scene = new Scene3D(mockGame, { camera });
+
+      expect(scene.camera).toBe(camera);
+    });
+
+    it("should default depthSort to true", () => {
+      const scene = new Scene3D(mockGame, { camera });
+
+      expect(scene.depthSort).toBe(true);
+    });
+
+    it("should default scaleByDepth to true", () => {
+      const scene = new Scene3D(mockGame, { camera });
+
+      expect(scene.scaleByDepth).toBe(true);
+    });
+
+    it("should accept custom options", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+        scaleByDepth: false,
+        x: 100,
+        y: 200,
+      });
+
+      expect(scene.depthSort).toBe(false);
+      expect(scene.scaleByDepth).toBe(false);
+      expect(scene.x).toBe(100);
+      expect(scene.y).toBe(200);
+    });
+  });
+
+  describe("draw with depth sorting", () => {
+    it("should sort children back-to-front when depthSort is true", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: true,
+        scaleByDepth: false,
+      });
+
+      // Setup Painter mock
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      // Add children at different z depths
+      const front = createMockChild({ x: 0, y: 0, z: -100 });
+      const middle = createMockChild({ x: 0, y: 0, z: 0 });
+      const back = createMockChild({ x: 0, y: 0, z: 100 });
+
+      scene._collection = {
+        children: [front, middle, back],
+      };
+
+      // Call draw
+      scene.draw();
+
+      // Children should be rendered back-to-front
+      // So 'back' should be called before 'front'
+      const callOrder = [];
+      if (back.draw.mock.calls.length) callOrder.push("back");
+      if (middle.draw.mock.calls.length) callOrder.push("middle");
+      if (front.draw.mock.calls.length) callOrder.push("front");
+
+      // All should be called
+      expect(back.draw).toHaveBeenCalled();
+      expect(middle.draw).toHaveBeenCalled();
+      expect(front.draw).toHaveBeenCalled();
+    });
+
+    it("should not sort when depthSort is false", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+        scaleByDepth: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const child1 = createMockChild({ z: 100 });
+      const child2 = createMockChild({ z: -100 });
+
+      scene._collection = {
+        children: [child1, child2],
+      };
+
+      scene.draw();
+
+      // Both should be drawn
+      expect(child1.draw).toHaveBeenCalled();
+      expect(child2.draw).toHaveBeenCalled();
+    });
+  });
+
+  describe("draw with perspective scaling", () => {
+    it("should scale children by perspective when scaleByDepth is true", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+        scaleByDepth: true,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const child = createMockChild({ z: 0 });
+      scene._collection = {
+        children: [child],
+      };
+
+      scene.draw();
+
+      // Scale should be called
+      expect(Painter.ctx.scale).toHaveBeenCalled();
+    });
+
+    it("should not scale when scaleByDepth is false", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+        scaleByDepth: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const child = createMockChild({ z: 0 });
+      scene._collection = {
+        children: [child],
+      };
+
+      scene.draw();
+
+      // Scale should not be called
+      expect(Painter.ctx.scale).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("draw visibility and culling", () => {
+    it("should skip invisible children", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const visible = createMockChild({ visible: true });
+      const hidden = createMockChild({ visible: false });
+
+      scene._collection = {
+        children: [visible, hidden],
+      };
+
+      scene.draw();
+
+      expect(visible.draw).toHaveBeenCalled();
+      expect(hidden.draw).not.toHaveBeenCalled();
+    });
+
+    it("should cull children behind camera", () => {
+      const scene = new Scene3D(mockGame, {
+        camera: new Camera3D({ perspective: 100 }),
+        depthSort: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      // Child far behind camera (z = -200, camera.perspective = 100)
+      // After projection: if z < -perspective + 10, cull it
+      const farBehind = createMockChild({ z: 200 }); // After projection z will be positive
+      const inFront = createMockChild({ z: -50 });
+
+      scene._collection = {
+        children: [farBehind, inFront],
+      };
+
+      scene.draw();
+
+      // Both should be drawn as they're not behind camera
+      expect(inFront.draw).toHaveBeenCalled();
+    });
+
+    it("should default z to 0 for children without z property", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const noZ = createMockChild({ x: 100, y: 100 });
+      delete noZ.z; // No z property
+
+      scene._collection = {
+        children: [noZ],
+      };
+
+      // Should not throw
+      expect(() => scene.draw()).not.toThrow();
+      expect(noZ.draw).toHaveBeenCalled();
+    });
+  });
+
+  describe("draw transformations", () => {
+    it("should save and restore for each child", () => {
+      const scene = new Scene3D(mockGame, {
+        camera,
+        depthSort: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const child1 = createMockChild();
+      const child2 = createMockChild();
+
+      scene._collection = {
+        children: [child1, child2],
+      };
+
+      scene.draw();
+
+      // Should call save/restore for each child
+      expect(Painter.save).toHaveBeenCalledTimes(2);
+      expect(Painter.restore).toHaveBeenCalledTimes(2);
+    });
+
+    it("should translate to projected position", () => {
+      const scene = new Scene3D(mockGame, {
+        camera: new Camera3D(), // No rotation
+        depthSort: false,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const child = createMockChild({ x: 100, y: 50, z: 0 });
+      scene._collection = {
+        children: [child],
+      };
+
+      scene.draw();
+
+      // With no rotation and z=0, projected position should match input
+      expect(Painter.translateTo).toHaveBeenCalledWith(100, 50);
+    });
+  });
+
+  describe("integration with Camera3D projection", () => {
+    it("should use camera projection for positioning", () => {
+      const mockCamera = {
+        project: vi.fn().mockReturnValue({
+          x: 150,
+          y: 75,
+          z: 50,
+          scale: 0.8,
+        }),
+        perspective: 800,
+      };
+
+      const scene = new Scene3D(mockGame, {
+        camera: mockCamera,
+        depthSort: false,
+        scaleByDepth: true,
+      });
+
+      Painter.save = vi.fn();
+      Painter.restore = vi.fn();
+      Painter.translateTo = vi.fn();
+      Painter.ctx = { scale: vi.fn() };
+
+      const child = createMockChild({ x: 100, y: 50, z: 25 });
+      scene._collection = {
+        children: [child],
+      };
+
+      scene.draw();
+
+      // Should call camera.project with child coordinates
+      expect(mockCamera.project).toHaveBeenCalledWith(100, 50, 25);
+
+      // Should use projected values
+      expect(Painter.translateTo).toHaveBeenCalledWith(150, 75);
+      expect(Painter.ctx.scale).toHaveBeenCalledWith(0.8, 0.8);
+    });
+  });
+});

package/types/collision.d.ts

@@ -0,0 +1,249 @@
+/**
+ * GCanvas Collision Detection Types
+ * Collision detection utilities for 2D game development.
+ * @module collision
+ */
+
+import { Bounds } from './common';
+
+// ==========================================================================
+// Collision Shapes
+// ==========================================================================
+
+/** Circle definition for collision detection */
+export interface CollisionCircle {
+  x: number;
+  y: number;
+  radius: number;
+}
+
+/** Line segment definition for collision detection */
+export interface LineSegment {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+/** Sweep collision result */
+export interface SweepResult {
+  /** Time of collision (0-1 within the movement) */
+  time: number;
+  /** X component of collision normal */
+  normalX: number;
+  /** Y component of collision normal */
+  normalY: number;
+}
+
+/** Overlap result between two rectangles */
+export interface OverlapResult {
+  /** Horizontal overlap amount */
+  x: number;
+  /** Vertical overlap amount */
+  y: number;
+}
+
+/** Minimum translation vector to separate colliding objects */
+export interface MTVResult {
+  /** X translation to separate */
+  x: number;
+  /** Y translation to separate */
+  y: number;
+}
+
+// ==========================================================================
+// Collision Static Class
+// ==========================================================================
+
+/**
+ * Static collision detection utilities.
+ * Provides various algorithms for 2D collision detection.
+ */
+export class Collision {
+  /**
+   * Test if two axis-aligned rectangles intersect (AABB collision)
+   */
+  static rectRect(a: Bounds, b: Bounds): boolean;
+
+  /**
+   * Alias for rectRect - matches common naming convention
+   */
+  static intersects(a: Bounds, b: Bounds): boolean;
+
+  /**
+   * Test if a point is inside a rectangle
+   */
+  static pointRect(px: number, py: number, rect: Bounds): boolean;
+
+  /**
+   * Test if two circles intersect
+   */
+  static circleCircle(a: CollisionCircle, b: CollisionCircle): boolean;
+
+  /**
+   * Test if a point is inside a circle
+   */
+  static pointCircle(px: number, py: number, circle: CollisionCircle): boolean;
+
+  /**
+   * Test if a circle and rectangle intersect
+   */
+  static circleRect(circle: CollisionCircle, rect: Bounds): boolean;
+
+  /**
+   * Test if a line segment intersects a rectangle
+   * @param x1 - Line start X
+   * @param y1 - Line start Y
+   * @param x2 - Line end X
+   * @param y2 - Line end Y
+   * @param rect - Target rectangle
+   * @param thickness - Optional line thickness
+   */
+  static lineRect(x1: number, y1: number, x2: number, y2: number, rect: Bounds, thickness?: number): boolean;
+
+  /**
+   * Test if two line segments intersect
+   */
+  static lineLine(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, x4: number, y4: number): boolean;
+
+  /**
+   * Test if multiple line segments intersect a rectangle
+   * Useful for complex shapes like lightning bolts
+   */
+  static segmentsRect(segments: LineSegment[], rect: Bounds, thickness?: number): boolean;
+
+  /**
+   * Get the intersection depth between two rectangles
+   * Returns null if no collision
+   */
+  static getOverlap(a: Bounds, b: Bounds): OverlapResult | null;
+
+  /**
+   * Get the minimum translation vector to separate two rectangles
+   * Returns null if no collision
+   */
+  static getMTV(a: Bounds, b: Bounds): MTVResult | null;
+
+  /**
+   * Check if a moving rectangle will collide with a static one (sweep test)
+   * Useful for fast-moving objects like bullets
+   * @param rect - Moving rectangle
+   * @param vx - Velocity X
+   * @param vy - Velocity Y
+   * @param target - Target rectangle
+   */
+  static sweep(rect: Bounds, vx: number, vy: number, target: Bounds): SweepResult | null;
+}
+
+// ==========================================================================
+// CollisionSystem Class
+// ==========================================================================
+
+/** Object that can participate in collision detection */
+export interface Collidable {
+  getBounds?(): Bounds;
+  bounds?: Bounds;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  active?: boolean;
+  destroyed?: boolean;
+  alive?: boolean;
+}
+
+/** Collision pair callback options */
+export interface CollisionPairOptions {
+  /** If true, only trigger once per pair per frame */
+  once?: boolean;
+}
+
+/** Callback for collision events */
+export type CollisionCallback<A = Collidable, B = Collidable> = (objA: A, objB: B) => void;
+
+/**
+ * Manages collision groups and detection.
+ * Provides an organized way to manage multiple groups of collidable objects
+ * and efficiently check collisions between them.
+ */
+export class CollisionSystem {
+  constructor();
+
+  /**
+   * Create a new collision group
+   * @returns this for chaining
+   */
+  createGroup(name: string): this;
+
+  /**
+   * Add an object to a collision group
+   * @returns this for chaining
+   */
+  add<T extends Collidable>(groupName: string, obj: T): this;
+
+  /**
+   * Remove an object from a collision group
+   * @returns True if object was in the group
+   */
+  remove(groupName: string, obj: Collidable): boolean;
+
+  /**
+   * Remove an object from all groups
+   */
+  removeFromAll(obj: Collidable): void;
+
+  /**
+   * Clear all objects from a group
+   */
+  clearGroup(groupName: string): void;
+
+  /**
+   * Clear all groups
+   */
+  clearAll(): void;
+
+  /**
+   * Get all objects in a group
+   */
+  getGroup<T extends Collidable>(groupName: string): T[];
+
+  /**
+   * Register a collision callback between two groups
+   * @returns this for chaining
+   */
+  onCollision<A extends Collidable, B extends Collidable>(
+    groupA: string,
+    groupB: string,
+    callback: CollisionCallback<A, B>,
+    options?: CollisionPairOptions
+  ): this;
+
+  /**
+   * Remove all collision callbacks for a pair of groups
+   */
+  offCollision(groupA: string, groupB: string): void;
+
+  /**
+   * Check and handle all registered collision pairs
+   * Call this each frame in your update loop
+   */
+  update(): void;
+
+  /**
+   * Check collisions between two specific groups (without callbacks)
+   * @returns Array of [objA, objB] colliding pairs
+   */
+  check<A extends Collidable, B extends Collidable>(groupA: string, groupB: string): [A, B][];
+
+  /**
+   * Check if an object collides with any object in a group
+   * @returns First colliding object, or null
+   */
+  checkAgainstGroup<T extends Collidable>(obj: Collidable, groupName: string): T | null;
+
+  /**
+   * Check if an object collides with any object in a group
+   * @returns All colliding objects
+   */
+  checkAllAgainstGroup<T extends Collidable>(obj: Collidable, groupName: string): T[];
+}