@guinetik/gcanvas 1.0.0 → 1.0.1

package/src/util/camera3d.js

@@ -32,6 +32,9 @@ export class Camera3D {
    * @param {number} [options.rotationX=0] - Initial X rotation (tilt up/down) in radians
    * @param {number} [options.rotationY=0] - Initial Y rotation (spin left/right) in radians
    * @param {number} [options.rotationZ=0] - Initial Z rotation (roll) in radians
+   * @param {number} [options.x=0] - Initial X position in world space
+   * @param {number} [options.y=0] - Initial Y position in world space
+   * @param {number} [options.z=0] - Initial Z position in world space
    * @param {number} [options.perspective=800] - Perspective distance (higher = less distortion)
    * @param {number} [options.sensitivity=0.005] - Mouse drag sensitivity
    * @param {number} [options.minRotationX=-1.5] - Minimum X rotation limit
@@ -49,10 +52,18 @@ export class Camera3D {
     this.rotationY = options.rotationY ?? 0;
     this.rotationZ = options.rotationZ ?? 0;
 
+    // Position state (camera location in world space)
+    this.x = options.x ?? 0;
+    this.y = options.y ?? 0;
+    this.z = options.z ?? 0;
+
     // Store initial values for reset
     this._initialRotationX = this.rotationX;
     this._initialRotationY = this.rotationY;
     this._initialRotationZ = this.rotationZ;
+    this._initialX = this.x;
+    this._initialY = this.y;
+    this._initialZ = this.z;
 
     // Perspective
     this.perspective = options.perspective ?? 800;
@@ -86,6 +97,20 @@ export class Camera3D {
     this._lastMouseY = 0;
     this._canvas = null;
     this._boundHandlers = null;
+
+    // Follow target state
+    this._followTarget = null;
+    this._followOffset = { x: 0, y: 0, z: 0 };
+    this._followLookAt = true;  // Auto-orient to look at target's forward direction
+    this._followLerp = 0.1;     // Interpolation speed (0-1, higher = snappier)
+
+    // Position animation state
+    this._targetX = null;
+    this._targetY = null;
+    this._targetZ = null;
+    this._targetRotationX = null;
+    this._targetRotationY = null;
+    this._positionLerp = 0.05;  // Default smooth movement speed
   }
 
   /**
@@ -96,6 +121,12 @@ export class Camera3D {
    * @returns {{x: number, y: number, z: number, scale: number}} Projected 2D coordinates and depth info
    */
   project(x, y, z) {
+    // Translate world relative to camera position
+    // (Moving camera right = moving world left)
+    x -= this.x;
+    y -= this.y;
+    z -= this.z;
+
     // Rotate around Z axis (roll)
     if (this.rotationZ !== 0) {
       const cosZ = Math.cos(this.rotationZ);
@@ -141,12 +172,78 @@ export class Camera3D {
   }
 
   /**
-   * Update camera for auto-rotation and inertia (call in update loop)
+   * Update camera for auto-rotation, inertia, and follow mode (call in update loop)
    * @param {number} dt - Delta time in seconds
    */
   update(dt) {
-    // Apply inertia when not dragging
-    if (this.inertia && !this._isDragging) {
+    // Follow target mode - position camera relative to target
+    if (this._followTarget) {
+      const target = this._followTarget;
+      const targetX = (target.x ?? 0) + this._followOffset.x;
+      const targetY = (target.y ?? 0) + this._followOffset.y;
+      const targetZ = (target.z ?? 0) + this._followOffset.z;
+
+      // Smooth interpolation to target position
+      this.x += (targetX - this.x) * this._followLerp;
+      this.y += (targetY - this.y) * this._followLerp;
+      this.z += (targetZ - this.z) * this._followLerp;
+
+      // Auto-orient to look toward origin (or specified look target)
+      if (this._followLookAt) {
+        const lookX = this._followLookAtTarget?.x ?? 0;
+        const lookY = this._followLookAtTarget?.y ?? 0;
+        const lookZ = this._followLookAtTarget?.z ?? 0;
+
+        // Calculate direction from camera to look target
+        const dx = lookX - this.x;
+        const dy = lookY - this.y;
+        const dz = lookZ - this.z;
+        const distXZ = Math.sqrt(dx * dx + dz * dz);
+
+        // Target rotation to face the look target
+        const targetRotY = Math.atan2(dx, dz);
+        const targetRotX = Math.atan2(-dy, distXZ);
+
+        // Smooth rotation interpolation
+        this.rotationY += this._angleDiff(this.rotationY, targetRotY) * this._followLerp;
+        this.rotationX += (targetRotX - this.rotationX) * this._followLerp;
+      }
+    }
+    // Animated position movement (moveTo)
+    else if (this._targetX !== null) {
+      const lerp = this._positionLerp;
+
+      // Interpolate position
+      this.x += (this._targetX - this.x) * lerp;
+      this.y += (this._targetY - this.y) * lerp;
+      this.z += (this._targetZ - this.z) * lerp;
+
+      // Interpolate rotation if targets set
+      if (this._targetRotationX !== null) {
+        this.rotationX += (this._targetRotationX - this.rotationX) * lerp;
+      }
+      if (this._targetRotationY !== null) {
+        this.rotationY += this._angleDiff(this.rotationY, this._targetRotationY) * lerp;
+      }
+
+      // Check if we've arrived (close enough)
+      const posDist = Math.abs(this._targetX - this.x) +
+                      Math.abs(this._targetY - this.y) +
+                      Math.abs(this._targetZ - this.z);
+      if (posDist < 0.1) {
+        this.x = this._targetX;
+        this.y = this._targetY;
+        this.z = this._targetZ;
+        this._targetX = null;
+        this._targetY = null;
+        this._targetZ = null;
+        this._targetRotationX = null;
+        this._targetRotationY = null;
+      }
+    }
+
+    // Apply inertia when not dragging and not following
+    if (this.inertia && !this._isDragging && !this._followTarget) {
       // Apply velocity to rotation
       if (Math.abs(this._velocityX) > 0.0001 || Math.abs(this._velocityY) > 0.0001) {
         this.rotationY += this._velocityY;
@@ -167,8 +264,8 @@ export class Camera3D {
       }
     }
 
-    // Auto-rotate when not dragging and no significant velocity
-    if (this.autoRotate && !this._isDragging) {
+    // Auto-rotate when not dragging, not following, and no significant velocity
+    if (this.autoRotate && !this._isDragging && !this._followTarget) {
       const hasVelocity = Math.abs(this._velocityX) > 0.001 || Math.abs(this._velocityY) > 0.001;
       if (!hasVelocity) {
         const delta = this.autoRotateSpeed * dt;
@@ -187,6 +284,17 @@ export class Camera3D {
     }
   }
 
+  /**
+   * Calculate shortest angle difference (handles wraparound)
+   * @private
+   */
+  _angleDiff(from, to) {
+    let diff = to - from;
+    while (diff > Math.PI) diff -= Math.PI * 2;
+    while (diff < -Math.PI) diff += Math.PI * 2;
+    return diff;
+  }
+
   /**
    * Enable mouse/touch drag rotation on a canvas
    * @param {HTMLCanvasElement} canvas - The canvas element to attach controls to
@@ -360,15 +468,22 @@ export class Camera3D {
   }
 
   /**
-   * Reset rotation to initial values and stop inertia
+   * Reset rotation and position to initial values, stop inertia and following
    * @returns {Camera3D} Returns this for chaining
    */
   reset() {
     this.rotationX = this._initialRotationX;
     this.rotationY = this._initialRotationY;
     this.rotationZ = this._initialRotationZ;
+    this.x = this._initialX;
+    this.y = this._initialY;
+    this.z = this._initialZ;
     this._velocityX = 0;
     this._velocityY = 0;
+    this._followTarget = null;
+    this._targetX = null;
+    this._targetY = null;
+    this._targetZ = null;
     return this;
   }
 
@@ -382,6 +497,91 @@ export class Camera3D {
     return this;
   }
 
+  /**
+   * Set camera position in world space
+   * @param {number} x - X position
+   * @param {number} y - Y position
+   * @param {number} z - Z position
+   * @returns {Camera3D} Returns this for chaining
+   */
+  setPosition(x, y, z) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    return this;
+  }
+
+  /**
+   * Animate camera to a new position (and optionally rotation)
+   * @param {number} x - Target X position
+   * @param {number} y - Target Y position
+   * @param {number} z - Target Z position
+   * @param {object} [options] - Animation options
+   * @param {number} [options.rotationX] - Target X rotation
+   * @param {number} [options.rotationY] - Target Y rotation
+   * @param {number} [options.lerp=0.05] - Interpolation speed (0-1)
+   * @returns {Camera3D} Returns this for chaining
+   */
+  moveTo(x, y, z, options = {}) {
+    this._targetX = x;
+    this._targetY = y;
+    this._targetZ = z;
+    this._targetRotationX = options.rotationX ?? null;
+    this._targetRotationY = options.rotationY ?? null;
+    this._positionLerp = options.lerp ?? 0.05;
+    return this;
+  }
+
+  /**
+   * Follow a target object (position camera relative to target)
+   * @param {object} target - Object with x, y, z properties to follow
+   * @param {object} [options] - Follow options
+   * @param {number} [options.offsetX=0] - X offset from target
+   * @param {number} [options.offsetY=0] - Y offset from target
+   * @param {number} [options.offsetZ=0] - Z offset from target
+   * @param {boolean} [options.lookAt=true] - Auto-orient to look at lookAtTarget
+   * @param {object} [options.lookAtTarget=null] - Point to look at (default: origin)
+   * @param {number} [options.lerp=0.1] - Interpolation speed (0-1, higher = snappier)
+   * @returns {Camera3D} Returns this for chaining
+   */
+  follow(target, options = {}) {
+    this._followTarget = target;
+    this._followOffset = {
+      x: options.offsetX ?? 0,
+      y: options.offsetY ?? 0,
+      z: options.offsetZ ?? 0,
+    };
+    this._followLookAt = options.lookAt ?? true;
+    this._followLookAtTarget = options.lookAtTarget ?? null;
+    this._followLerp = options.lerp ?? 0.1;
+    return this;
+  }
+
+  /**
+   * Stop following target and optionally reset to initial position
+   * @param {boolean} [resetPosition=false] - Whether to animate back to initial position
+   * @returns {Camera3D} Returns this for chaining
+   */
+  unfollow(resetPosition = false) {
+    this._followTarget = null;
+    if (resetPosition) {
+      this.moveTo(this._initialX, this._initialY, this._initialZ, {
+        rotationX: this._initialRotationX,
+        rotationY: this._initialRotationY,
+        lerp: 0.05,
+      });
+    }
+    return this;
+  }
+
+  /**
+   * Check if camera is currently following a target
+   * @returns {boolean} True if following a target
+   */
+  isFollowing() {
+    return this._followTarget !== null;
+  }
+
   /**
    * Set rotation angles
    * @param {number} x - X rotation in radians
@@ -424,15 +624,21 @@ export class Camera3D {
   }
 
   /**
-   * Look at a specific point (sets rotation to face that direction)
-   * @param {number} x - Target X
-   * @param {number} y - Target Y
-   * @param {number} z - Target Z
+   * Look at a specific point (sets rotation to face that direction from current position)
+   * @param {number} x - Target X in world space
+   * @param {number} y - Target Y in world space
+   * @param {number} z - Target Z in world space
    * @returns {Camera3D} Returns this for chaining
    */
   lookAt(x, y, z) {
-    this.rotationY = Math.atan2(x, z);
-    this.rotationX = Math.atan2(y, Math.sqrt(x * x + z * z));
+    // Calculate direction from camera position to target
+    const dx = x - this.x;
+    const dy = y - this.y;
+    const dz = z - this.z;
+    const distXZ = Math.sqrt(dx * dx + dz * dz);
+
+    this.rotationY = Math.atan2(dx, dz);
+    this.rotationX = Math.atan2(-dy, distXZ);
     return this;
   }
 }

package/types/fluent.d.ts

@@ -0,0 +1,361 @@
+/// <reference lib="es2015" />
+
+/**
+ * GCanvas Fluent API Module
+ * Declarative, chainable API for rapid game and creative coding development.
+ * @module fluent
+ */
+
+import { Game, Scene, GameObject, GameObjectOptions, SceneOptions } from './game';
+import { Shape } from './shapes';
+import { Easing, Motion, Tweenetik } from './motion';
+import { Keys, Mouse } from './io';
+
+// ==========================================================================
+// Main Entry Points
+// ==========================================================================
+
+/**
+ * Main entry point for the fluent API.
+ * Creates a FluentGame instance with automatic canvas setup.
+ *
+ * @param options - Game configuration
+ * @returns FluentGame builder instance
+ *
+ * @example
+ * gcanvas({ bg: 'black' })
+ *   .scene('game')
+ *     .go({ x: 400, y: 300, name: 'player' })
+ *       .circle({ radius: 30, fill: 'lime' })
+ *   .start();
+ */
+export function gcanvas(options?: FluentGameOptions): FluentGame;
+
+/**
+ * Ultra-simple sketch mode for quick creative coding prototypes.
+ *
+ * @param w - Canvas width (default: 800)
+ * @param h - Canvas height (default: 600)
+ * @param bg - Background color (default: 'black')
+ * @returns SketchAPI builder instance
+ *
+ * @example
+ * sketch(800, 600, 'black')
+ *   .circle(400, 300, 50, 'lime')
+ *   .update((dt, ctx) => {
+ *     ctx.shapes[0].x += Math.sin(ctx.time) * 2;
+ *   })
+ *   .start();
+ */
+export function sketch(w?: number, h?: number, bg?: string): SketchAPI;
+
+// ==========================================================================
+// FluentGame Options
+// ==========================================================================
+
+/** Options for FluentGame constructor */
+export interface FluentGameOptions {
+  /** Canvas element to use (auto-creates if not provided) */
+  canvas?: HTMLCanvasElement;
+  /** Canvas width when auto-creating (default: 800) */
+  width?: number;
+  /** Canvas height when auto-creating (default: 600) */
+  height?: number;
+  /** Background color */
+  bg?: string;
+  /** Enable fluid/responsive sizing (default: true for auto-created canvas) */
+  fluid?: boolean;
+  /** Container for auto-created canvas (default: document.body) */
+  container?: HTMLElement;
+  /** Target FPS (default: 60) */
+  fps?: number;
+  /** Pixel ratio for HiDPI displays */
+  pixelRatio?: number;
+}
+
+// ==========================================================================
+// FluentGame Class
+// ==========================================================================
+
+/**
+ * Root builder class for the fluent API.
+ * Wraps the Game class with a declarative, chainable interface.
+ */
+export class FluentGame {
+  constructor(options?: FluentGameOptions);
+
+  // Scene Management
+  /**
+   * Create or switch to a scene.
+   * @param name - Scene identifier
+   * @param options - Scene options
+   */
+  scene(name: string, options?: FluentSceneOptions): FluentScene;
+  /**
+   * Create scene with custom Scene class.
+   * @param name - Scene identifier
+   * @param sceneClass - Custom Scene class
+   * @param options - Scene options
+   */
+  scene(name: string, sceneClass: new (...args: any[]) => Scene, options?: FluentSceneOptions): FluentScene;
+  /**
+   * Create scene with custom Scene class (name derived from class).
+   * @param sceneClass - Custom Scene class
+   * @param options - Scene options
+   */
+  scene(sceneClass: new (...args: any[]) => Scene, options?: FluentSceneOptions): FluentScene;
+
+  /**
+   * Switch context to an existing scene (does not create).
+   * @param name - Scene name
+   */
+  inScene(name: string): FluentScene;
+
+  /**
+   * Shortcut: create GameObject in current/default scene.
+   * @param options - GameObject options
+   */
+  go(options?: GameObjectOptions): FluentGO;
+  /**
+   * Create GameObject with custom class.
+   * @param goClass - Custom GameObject class
+   * @param options - GameObject options
+   */
+  go(goClass: new (...args: any[]) => GameObject, options?: GameObjectOptions): FluentGO;
+
+  // Scene Visibility
+  /** Show a scene by name */
+  showScene(name: string): FluentGame;
+  /** Hide a scene by name */
+  hideScene(name: string): FluentGame;
+  /** Transition between scenes */
+  transition(from: string, to: string, options?: TransitionOptions): FluentGame;
+
+  // State Management
+  /** Set initial state */
+  state(initialState: Record<string, any>): FluentGame;
+  /** Get a state value */
+  getState<T = any>(key: string): T;
+  /** Set a state value */
+  setState(key: string, value: any): FluentGame;
+
+  // Events & Lifecycle
+  /**
+   * Register event handler.
+   * @param event - Event name (update, keydown:escape, click, etc.)
+   * @param handler - Handler function
+   */
+  on(event: string, handler: (ctx: FluentContext, e?: any) => void): FluentGame;
+  on(event: 'update', handler: (dt: number, ctx: FluentContext) => void): FluentGame;
+
+  // Plugins
+  /** Use a plugin or scene builder function */
+  use(plugin: (game: FluentGame) => void): FluentGame;
+
+  // Lifecycle
+  /** Start the game loop */
+  start(): FluentGame;
+  /** Stop the game loop */
+  stop(): FluentGame;
+  /** Restart the game */
+  restart(): FluentGame;
+
+  // Accessors
+  /** Underlying Game instance */
+  readonly game: Game;
+  /** Named object references */
+  readonly refs: Record<string, GameObject>;
+  /** All scenes */
+  readonly scenes: Map<string, Scene>;
+  /** Canvas element */
+  readonly canvas: HTMLCanvasElement;
+  /** Canvas width */
+  readonly width: number;
+  /** Canvas height */
+  readonly height: number;
+}
+
+// ==========================================================================
+// FluentScene Class
+// ==========================================================================
+
+/** Options for fluent scene creation */
+export interface FluentSceneOptions extends SceneOptions {
+  /** Scene z-index (default: 0) */
+  zIndex?: number;
+  /** Whether scene is visible (default: true) */
+  active?: boolean;
+  /** Scene enter callback */
+  onEnter?: (ctx: FluentContext) => void;
+  /** Scene exit callback */
+  onExit?: (ctx: FluentContext) => void;
+}
+
+/** Transition options */
+export interface TransitionOptions {
+  /** Fade duration in seconds */
+  fade?: number;
+  /** Completion callback */
+  onComplete?: () => void;
+}
+
+/**
+ * Scene builder for the fluent API.
+ */
+export class FluentScene {
+  /**
+   * Create a GameObject in this scene.
+   * @param options - GameObject options
+   */
+  go(options?: GameObjectOptions): FluentGO;
+  /**
+   * Create GameObject with custom class.
+   * @param goClass - Custom GameObject class
+   * @param options - GameObject options
+   */
+  go(goClass: new (...args: any[]) => GameObject, options?: GameObjectOptions): FluentGO;
+
+  /** Return to FluentGame context */
+  end(): FluentGame;
+
+  /** Access the underlying scene */
+  readonly sceneInstance: Scene;
+}
+
+// ==========================================================================
+// FluentGO Class
+// ==========================================================================
+
+/**
+ * GameObject builder for the fluent API.
+ * Provides chainable methods for adding shapes and behaviors.
+ */
+export class FluentGO {
+  // Shape methods
+  circle(options?: { radius?: number; fill?: string; stroke?: string }): FluentGO;
+  rect(options?: { width?: number; height?: number; fill?: string; stroke?: string }): FluentGO;
+  square(options?: { size?: number; fill?: string; stroke?: string }): FluentGO;
+  star(options?: { points?: number; radius?: number; innerRadius?: number; fill?: string }): FluentGO;
+  triangle(options?: { size?: number; fill?: string }): FluentGO;
+  hexagon(options?: { radius?: number; fill?: string }): FluentGO;
+  line(options?: { x2?: number; y2?: number; stroke?: string; lineWidth?: number }): FluentGO;
+  ring(options?: { innerRadius?: number; outerRadius?: number; fill?: string }): FluentGO;
+  text(content: string, options?: { fill?: string; font?: string }): FluentGO;
+
+  // Motion methods (apply behaviors)
+  pulse(options?: { min?: number; max?: number; duration?: number }): FluentGO;
+  orbit(options?: { radius?: number; speed?: number; centerX?: number; centerY?: number }): FluentGO;
+  oscillate(options?: { axis?: 'x' | 'y'; amplitude?: number; frequency?: number }): FluentGO;
+  bounce(options?: { height?: number; duration?: number }): FluentGO;
+  shake(options?: { intensity?: number; duration?: number }): FluentGO;
+  float(options?: { amplitude?: number; frequency?: number }): FluentGO;
+  spin(options?: { speed?: number }): FluentGO;
+
+  /** Return to FluentScene context */
+  end(): FluentScene;
+
+  /** Access the underlying GameObject */
+  readonly goInstance: GameObject;
+}
+
+// ==========================================================================
+// FluentLayer Class
+// ==========================================================================
+
+/**
+ * Layer builder for organizing GameObjects at different z-levels.
+ */
+export class FluentLayer {
+  /** Add a GameObject to this layer */
+  go(options?: GameObjectOptions): FluentGO;
+  /** Return to parent context */
+  end(): FluentScene;
+}
+
+// ==========================================================================
+// Sketch API
+// ==========================================================================
+
+/** Context passed to sketch update function */
+export interface SketchContext {
+  /** All created GameObjects */
+  shapes: GameObject[];
+  /** Elapsed time in seconds */
+  time: number;
+  /** Current frame number */
+  frame: number;
+  /** Canvas width */
+  width: number;
+  /** Canvas height */
+  height: number;
+  /** Mouse position */
+  mouse: { x: number; y: number };
+  /** Named object references */
+  refs: Record<string, GameObject>;
+  /** Underlying Game instance */
+  game: Game;
+}
+
+/**
+ * Ultra-simple sketch API for quick prototypes.
+ */
+export interface SketchAPI {
+  // Shapes
+  circle(x: number, y: number, r: number, fill?: string): SketchAPI;
+  rect(x: number, y: number, w: number, h: number, fill?: string): SketchAPI;
+  square(x: number, y: number, size: number, fill?: string): SketchAPI;
+  star(x: number, y: number, points: number, r: number, fill?: string): SketchAPI;
+  triangle(x: number, y: number, size: number, fill?: string): SketchAPI;
+  hexagon(x: number, y: number, r: number, fill?: string): SketchAPI;
+  line(x1: number, y1: number, x2: number, y2: number, stroke?: string, lineWidth?: number): SketchAPI;
+  ring(x: number, y: number, innerRadius: number, outerRadius: number, fill?: string): SketchAPI;
+  text(content: string, x: number, y: number, opts?: { fill?: string; font?: string }): SketchAPI;
+
+  // Bulk creation
+  grid(cols: number, rows: number, spacing: number, shapeFn: (api: SketchAPI, x: number, y: number, col: number, row: number) => void): SketchAPI;
+  repeat(count: number, shapeFn: (api: SketchAPI, index: number, total: number) => void): SketchAPI;
+  radial(cx: number, cy: number, radius: number, count: number, shapeFn: (api: SketchAPI, x: number, y: number, angle: number, index: number) => void): SketchAPI;
+
+  // Lifecycle
+  setup(fn: (api: SketchAPI) => void): SketchAPI;
+  update(fn: (dt: number, ctx: SketchContext) => void): SketchAPI;
+  start(): FluentGame;
+
+  // Accessors
+  readonly width: number;
+  readonly height: number;
+  readonly game: FluentGame | null;
+}
+
+// ==========================================================================
+// Fluent Context
+// ==========================================================================
+
+/** Context object passed to event handlers */
+export interface FluentContext {
+  /** Named object references */
+  refs: Record<string, GameObject>;
+  /** Game state */
+  state: Record<string, any>;
+  /** All scenes by name */
+  scenes: Record<string, Scene>;
+  /** Underlying Game instance */
+  game: Game;
+  /** Canvas width */
+  width: number;
+  /** Canvas height */
+  height: number;
+  /** Show a scene */
+  showScene: (name: string) => void;
+  /** Hide a scene */
+  hideScene: (name: string) => void;
+  /** Transition between scenes */
+  transition: (from: string, to: string, opts?: TransitionOptions) => void;
+}
+
+// ==========================================================================
+// Re-exports for convenience
+// ==========================================================================
+
+export { Motion, Easing, Tweenetik, Keys, Mouse };
+