@guinetik/gcanvas 1.0.1 → 1.0.2

package/docs/fluid-dynamics.md

@@ -1,97 +1,99 @@
-# Fluid & Gas Dynamics (Math-Only)
-
-Pure math helpers for SPH-style liquids and lightweight gas simulation. The math stays in `src/math/fluid.js`; consumers (games/demos) are responsible for applying forces to their particles.
-
-## What’s Included
-- SPH density, pressure, and viscosity kernels (`computeDensities`, `computePressures`, `computeFluidForces`).
-- Simplified gas mixing with diffusion/pressure/turbulence (`computeGasForces`).
-- Thermal buoyancy coupling (`computeThermalBuoyancy`) that pairs with `src/math/heat.js`.
-- Force blending and pure Euler integration (`blendForces`, `integrateEuler`).
-- Config factory with no magic numbers (`getDefaultFluidConfig`).
-
-## Config
-Defined in `src/math/fluid.js` and merged via `mergeConfig` internally.
-
-```js
-const CONFIG = {
-  kernel: { smoothingRadius: 28 },
-  fluid: {
-    restDensity: 1.1,
-    particleMass: 1,
-    pressureStiffness: 1800,
-    viscosity: 0.18,
-    surfaceTension: 0,
-    maxForce: 6000,
-  },
-  gas: {
-    interactionRadius: 34,
-    pressure: 12,
-    diffusion: 0.08,
-    drag: 0.04,
-    buoyancy: 260,
-    neutralTemperature: 0.5,
-    turbulence: 16,
-  },
-  external: { gravity: { x: 0, y: 820 } },
-};
-```
-
-Override by passing `{ fluid: { … }, gas: { … }, kernel: { … } }` to any helper.
-
-## Particle Shape
-Any object with `{ x, y, vx, vy, size?, mass?, custom? }`. Mass is resolved from:
-`custom.mass` → `mass` → `size` → `config.fluid.particleMass`.
-
-## Core API (pure)
-- `computeDensities(particles, cfg?)` → `Float32Array densities`.
-- `computePressures(densities, cfg?)` → `Float32Array pressures`.
-- `computeFluidForces(particles, cfg?)` → `{ forces, densities, pressures }`.
-- `computeGasForces(particles, cfg?)` → `{ forces }`.
-- `computeThermalBuoyancy(particles, cfg?)` → `forces[]` using `temperature` or `custom.temperature`.
-- `blendForces(a, b, t)` → lerped forces.
-- `integrateEuler(particles, forces, dt, cfg?)` → new `{ x, y, vx, vy }[]` (no mutation).
-
-## Applying in a Game (pattern)
-1) Build forces:
-
-```js
-import { computeFluidForces, computeGasForces, blendForces, computeThermalBuoyancy } from "../../src/math/fluid.js";
-
-const liquid = computeFluidForces(particles, { kernel: { smoothingRadius: 26 } });
-const gas = computeGasForces(particles, { gas: { interactionRadius: 40 } });
-const buoyancy = computeThermalBuoyancy(particles);
-
-// Combine as you see fit (example: mix liquid & gas modes, then add buoyancy)
-const mixed = blendForces(liquid.forces, gas.forces, modeT); // modeT: 0..1
-for (let i = 0; i < particles.length; i++) {
-  mixed[i].x += buoyancy[i].x;
-  mixed[i].y += buoyancy[i].y;
-}
-```
-
-2) Apply to your particles (consumer-controlled):
-
-```js
-// Mutate in your game loop; math module stays pure.
-for (let i = 0; i < particles.length; i++) {
-  const p = particles[i];
-  const f = mixed[i];
-  const mass = p.custom.mass ?? 1;
-  p.vx += (f.x / mass) * dt;
-  p.vy += (f.y / mass) * dt;
-}
-```
-
-3) Let your normal updaters move/render (e.g., `ParticleSystem` velocity updater).
-
-## Heat Coupling
-Assign `p.temperature` or `p.custom.temperature` each frame (e.g., via `heat.zoneTemperature`). Pass the same particles to `computeThermalBuoyancy` and add the resulting forces.
-
-## Notes & Tips
-- Keep `smoothingRadius` proportional to particle spacing (roughly 2–3× average spacing).
-- Clamp velocities in the consumer if you target 10k–20k particles to keep the frame budget.
-- For gases, favor lower `pressure` and higher `diffusion` to avoid jitter.
-- The math never allocates inside the hot path besides output arrays; reuse them between frames if you need fewer allocations (pass your own particles array). 
-
-
-
+# Fluid & Gas Dynamics (Math-Only)
+
+Pure math helpers for SPH-style liquids and lightweight gas simulation. The math stays in `src/math/fluid.js`; consumers (games/demos) are responsible for applying forces to their particles.
+
+## What’s Included
+- SPH density, pressure, and viscosity kernels (`computeDensities`, `computePressures`, `computeFluidForces`).
+- Simplified gas mixing with diffusion/pressure/turbulence (`computeGasForces`).
+- Thermal buoyancy coupling (`computeThermalBuoyancy`) that pairs with `src/math/heat.js`.
+- Force blending and pure Euler integration (`blendForces`, `integrateEuler`).
+- Config factory with no magic numbers (`getDefaultFluidConfig`).
+
+## Config
+Defined in `src/math/fluid.js` and merged via `mergeConfig` internally.
+
+```js
+const CONFIG = {
+  kernel: { smoothingRadius: 28 },
+  fluid: {
+    restDensity: 1.1,
+    particleMass: 1,
+    pressureStiffness: 1800,
+    viscosity: 0.18,
+    surfaceTension: 0,
+    maxForce: 6000,
+  },
+  gas: {
+    interactionRadius: 34,
+    pressure: 12,
+    diffusion: 0.08,
+    drag: 0.04,
+    buoyancy: 260,
+    neutralTemperature: 0.5,
+    turbulence: 16,
+  },
+  external: { gravity: { x: 0, y: 820 } },
+};
+```
+
+Override by passing `{ fluid: { … }, gas: { … }, kernel: { … } }` to any helper.
+
+## Particle Shape
+Any object with `{ x, y, vx, vy, size?, mass?, custom? }`. Mass is resolved from:
+`custom.mass` → `mass` → `size` → `config.fluid.particleMass`.
+
+## Core API (pure)
+- `computeDensities(particles, cfg?)` → `Float32Array densities`.
+- `computePressures(densities, cfg?)` → `Float32Array pressures`.
+- `computeFluidForces(particles, cfg?)` → `{ forces, densities, pressures }`.
+- `computeGasForces(particles, cfg?)` → `{ forces }`.
+- `computeThermalBuoyancy(particles, cfg?)` → `forces[]` using `temperature` or `custom.temperature`.
+- `blendForces(a, b, t)` → lerped forces.
+- `integrateEuler(particles, forces, dt, cfg?)` → new `{ x, y, vx, vy }[]` (no mutation).
+
+## Applying in a Game (pattern)
+1) Build forces:
+
+```js
+import { computeFluidForces, computeGasForces, blendForces, computeThermalBuoyancy } from "../../src/math/fluid.js";
+
+const liquid = computeFluidForces(particles, { kernel: { smoothingRadius: 26 } });
+const gas = computeGasForces(particles, { gas: { interactionRadius: 40 } });
+const buoyancy = computeThermalBuoyancy(particles);
+
+// Combine as you see fit (example: mix liquid & gas modes, then add buoyancy)
+const mixed = blendForces(liquid.forces, gas.forces, modeT); // modeT: 0..1
+for (let i = 0; i < particles.length; i++) {
+  mixed[i].x += buoyancy[i].x;
+  mixed[i].y += buoyancy[i].y;
+}
+```
+
+2) Apply to your particles (consumer-controlled):
+
+```js
+// Mutate in your game loop; math module stays pure.
+for (let i = 0; i < particles.length; i++) {
+  const p = particles[i];
+  const f = mixed[i];
+  const mass = p.custom.mass ?? 1;
+  p.vx += (f.x / mass) * dt;
+  p.vy += (f.y / mass) * dt;
+}
+```
+
+3) Let your normal updaters move/render (e.g., `ParticleSystem` velocity updater).
+
+## Heat Coupling
+Assign `p.temperature` or `p.custom.temperature` each frame (e.g., via `heat.zoneTemperature`). Pass the same particles to `computeThermalBuoyancy` and add the resulting forces.
+
+## Notes & Tips
+- Keep `smoothingRadius` proportional to particle spacing (roughly 2–3× average spacing).
+- Clamp velocities in the consumer if you target 10k–20k particles to keep the frame budget.
+- For gases, favor lower `pressure` and higher `diffusion` to avoid jitter.
+- The math never allocates inside the hot path besides output arrays; reuse them between frames if you need fewer allocations (pass your own particles array). 
+
+
+
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guinetik/gcanvas",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Canvas Utilities and 2d Primitives",
   "main": "index.js",
   "types": "types/index.d.ts",

package/src/game/game.js

@@ -211,12 +211,18 @@ export class Game {
   /**
    * Enables automatic resizing of the canvas to either the window or a given container.
    * @param {HTMLElement} [container=window] - Element to observe for resizing. Defaults to window.
+   * @param {Object} [padding={}] - Optional padding to subtract from the canvas size.
+   * @param {number} [padding.top=0] - Top padding.
+   * @param {number} [padding.right=0] - Right padding.
+   * @param {number} [padding.bottom=0] - Bottom padding.
+   * @param {number} [padding.left=0] - Left padding.
    */
-  enableFluidSize(container = window) {
+  enableFluidSize(container = window, padding = {}) {
+    const { top = 0, right = 0, bottom = 0, left = 0 } = padding;
     if (container === window) {
       const resizeCanvas = () => {
-        this.canvas.width = window.innerWidth;
-        this.canvas.height = window.innerHeight;
+        this.canvas.width = window.innerWidth - left - right;
+        this.canvas.height = window.innerHeight - top - bottom;
         if (
           this.#prevWidth !== this.canvas.width ||
           this.#prevHeight !== this.canvas.height
@@ -240,8 +246,8 @@ export class Game {
       }
       const resizeCanvas = () => {
         const rect = container.getBoundingClientRect();
-        this.canvas.width = rect.width;
-        this.canvas.height = rect.height;
+        this.canvas.width = rect.width - left - right;
+        this.canvas.height = rect.height - top - bottom;
       };
       const observer = new ResizeObserver(() => {
         resizeCanvas();

package/src/game/objects/index.js

@@ -5,6 +5,7 @@
  * This module exports a collection of pre-built GameObject classes that provide
  * specific functionality commonly needed in games:
  * - {@link Scene}: A container for organizing hierarchies of GameObjects
+ * - {@link Sprite}: A MovieClip-style GameObject with frame-by-frame timeline animation
  * - {@link Text}: A GameObject for rendering text with various styling options
  *
  * All classes in this module extend the core {@link GameObject} class and inherit
@@ -48,7 +49,9 @@ export { GameObjectShapeWrapper, ShapeGOFactory } from "./wrapper.js";
 export { Scene } from "./scene.js";
 export { Scene3D } from "./scene3d.js";
 export { IsometricScene } from "./isometric-scene.js";
+export { PlatformerScene } from "./platformer-scene.js";
 export * from "./layoutscene.js";
 // Specialized GameObjects
+export { Sprite } from "./sprite.js";
 export { Text } from "./text.js";
 export { ImageGo } from "./imagego.js";

package/src/game/objects/platformer-scene.js

@@ -0,0 +1,411 @@
+import { Scene } from "./scene.js";
+import { Camera2D } from "../../util/camera2d.js";
+import { Painter } from "../../painter/painter.js";
+import { Keys } from "../../io/keys.js";
+
+/**
+ * PlatformerScene - A scene optimized for side-scrolling platformer games
+ *
+ * Provides:
+ * - Parallax layer support with configurable scroll speeds
+ * - Automatic gravity and input handling for the player
+ * - Camera integration with smooth following
+ * - Viewport clipping
+ * - Override hooks for customization
+ *
+ * @example
+ * // Basic usage
+ * const level = new PlatformerScene(game, {
+ *   player: playerGameObject,
+ *   gravity: 1200,
+ *   groundY: 500,
+ * });
+ *
+ * // Add parallax layers
+ * level.addLayer(background, { speed: 0.3 }); // slow parallax
+ * level.addLayer(platforms, { speed: 1.0 });  // normal
+ * level.addLayer(foreground, { speed: 1.5 }); // fast parallax
+ *
+ * // Add player (not as layer, moves with camera)
+ * level.add(player);
+ *
+ * this.pipeline.add(level);
+ *
+ * @example
+ * // Custom camera behavior (endless runner)
+ * class EndlessRunnerScene extends PlatformerScene {
+ *   updateCamera(dt) {
+ *     // No camera following - fixed viewport
+ *   }
+ *
+ *   getCameraOffset() {
+ *     return { x: 0, y: 0 };
+ *   }
+ * }
+ *
+ * @extends Scene
+ */
+export class PlatformerScene extends Scene {
+  /**
+   * @param {Game} game - Game instance
+   * @param {Object} options - Configuration
+   * @param {GameObject} [options.player=null] - Player GameObject with x, y; will add vx, vy, _grounded
+   * @param {Camera2D} [options.camera] - Optional Camera2D (created automatically if player provided)
+   * @param {number} [options.viewportWidth] - Viewport width (defaults to game width)
+   * @param {number} [options.viewportHeight] - Viewport height (defaults to game height)
+   * @param {number} [options.gravity=1200] - Gravity acceleration (pixels/second^2)
+   * @param {number} [options.groundY=null] - Default ground Y level (null = no default ground)
+   * @param {number} [options.moveSpeed=300] - Horizontal movement speed (pixels/second)
+   * @param {number} [options.jumpVelocity=-500] - Initial jump velocity (negative = up)
+   * @param {boolean} [options.autoInput=true] - Auto-apply WASD/Arrow input
+   * @param {boolean} [options.autoGravity=true] - Auto-apply gravity to player
+   */
+  constructor(game, options = {}) {
+    super(game, options);
+
+    /** @type {GameObject|null} The player GameObject */
+    this.player = options.player ?? null;
+
+    /** @type {Array<{gameObject: GameObject, speed: number, offsetX: number, offsetY: number}>} */
+    this._layers = [];
+
+    // Physics configuration
+    /** @type {number} Gravity acceleration in pixels/second^2 */
+    this.gravity = options.gravity ?? 1200;
+
+    /** @type {number|null} Default ground Y level (null = no ground) */
+    this.groundY = options.groundY ?? null;
+
+    /** @type {number} Horizontal movement speed in pixels/second */
+    this.moveSpeed = options.moveSpeed ?? 300;
+
+    /** @type {number} Initial jump velocity (negative = up) */
+    this.jumpVelocity = options.jumpVelocity ?? -500;
+
+    // Feature toggles
+    /** @type {boolean} Whether to auto-apply WASD/Arrow input */
+    this.autoInput = options.autoInput ?? true;
+
+    /** @type {boolean} Whether to auto-apply gravity to player */
+    this.autoGravity = options.autoGravity ?? true;
+
+    // Viewport dimensions
+    /** @type {number|null} Viewport width (null = use game width) */
+    this._viewportWidth = options.viewportWidth ?? null;
+
+    /** @type {number|null} Viewport height (null = use game height) */
+    this._viewportHeight = options.viewportHeight ?? null;
+
+    // Initialize player physics properties if not present
+    if (this.player) {
+      if (this.player.vx === undefined) this.player.vx = 0;
+      if (this.player.vy === undefined) this.player.vy = 0;
+      if (this.player._grounded === undefined) this.player._grounded = true;
+    }
+
+    // Camera - create default if player provided and no camera given
+    if (options.camera) {
+      this.camera = options.camera;
+    } else if (this.player) {
+      this.camera = new Camera2D({
+        target: this.player,
+        viewportWidth: this._viewportWidth ?? game.width,
+        viewportHeight: this._viewportHeight ?? game.height,
+        lerp: 0.1,
+      });
+    } else {
+      this.camera = null;
+    }
+  }
+
+  // ==================== Layer API ====================
+
+  /**
+   * Add a parallax layer to the scene
+   * @param {GameObject} gameObject - The layer content
+   * @param {Object} options - Layer options
+   * @param {number} [options.speed=1] - Scroll speed multiplier (0=fixed, 0.5=slow, 1=normal, 1.5=fast)
+   * @param {number} [options.offsetX=0] - Fixed X offset
+   * @param {number} [options.offsetY=0] - Fixed Y offset
+   * @returns {GameObject} The added game object
+   */
+  addLayer(gameObject, options = {}) {
+    const layer = {
+      gameObject,
+      speed: options.speed ?? 1,
+      offsetX: options.offsetX ?? 0,
+      offsetY: options.offsetY ?? 0,
+    };
+
+    this._layers.push(layer);
+
+    // Also add to scene's collection for update calls
+    this.add(gameObject);
+
+    return gameObject;
+  }
+
+  /**
+   * Remove a layer from the scene
+   * @param {GameObject} gameObject - The layer to remove
+   * @returns {boolean} True if layer was found and removed
+   */
+  removeLayer(gameObject) {
+    const index = this._layers.findIndex((l) => l.gameObject === gameObject);
+    if (index !== -1) {
+      this._layers.splice(index, 1);
+      this.remove(gameObject);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get all layers
+   * @returns {Array<{gameObject: GameObject, speed: number, offsetX: number, offsetY: number}>}
+   */
+  getLayers() {
+    return [...this._layers];
+  }
+
+  /**
+   * Check if a game object is a layer
+   * @param {GameObject} gameObject
+   * @returns {boolean}
+   */
+  isLayer(gameObject) {
+    return this._layers.some((l) => l.gameObject === gameObject);
+  }
+
+  // ==================== Override Hooks ====================
+
+  /**
+   * Apply gravity to the player
+   * Override this method to customize gravity behavior
+   * @param {GameObject} player - The player object
+   * @param {number} dt - Delta time in seconds
+   */
+  applyGravity(player, dt) {
+    player.vy = (player.vy || 0) + this.gravity * dt;
+  }
+
+  /**
+   * Apply input to the player
+   * Override this method to customize input handling
+   * @param {GameObject} player - The player object
+   * @param {number} dt - Delta time in seconds
+   */
+  applyInput(player, dt) {
+    // Horizontal movement
+    let moveX = 0;
+    if (Keys.isDown(Keys.LEFT) || Keys.isDown(Keys.A)) {
+      moveX = -1;
+    } else if (Keys.isDown(Keys.RIGHT) || Keys.isDown(Keys.D)) {
+      moveX = 1;
+    }
+    player.vx = moveX * this.moveSpeed;
+
+    // Jump
+    const jumpPressed =
+      Keys.isDown(Keys.SPACE) || Keys.isDown(Keys.W) || Keys.isDown(Keys.UP);
+    if (jumpPressed && this.isPlayerGrounded()) {
+      player.vy = this.jumpVelocity;
+      player._grounded = false;
+    }
+  }
+
+  /**
+   * Update the camera
+   * Override this method to customize camera behavior
+   * @param {number} dt - Delta time in seconds
+   */
+  updateCamera(dt) {
+    if (this.camera) {
+      this.camera.update(dt);
+    }
+  }
+
+  /**
+   * Get the current camera offset for rendering
+   * Override this method to customize scroll behavior
+   * @returns {{x: number, y: number}}
+   */
+  getCameraOffset() {
+    if (this.camera) {
+      return this.camera.getOffset();
+    }
+    return { x: 0, y: 0 };
+  }
+
+  /**
+   * Check if player is on the ground
+   * Override for custom ground detection (platforms, etc.)
+   * @returns {boolean}
+   */
+  isPlayerGrounded() {
+    return this.player?._grounded === true;
+  }
+
+  /**
+   * Apply velocity to player position
+   * Override for custom movement physics
+   * @param {GameObject} player - The player object
+   * @param {number} dt - Delta time in seconds
+   */
+  applyVelocity(player, dt) {
+    player.x += (player.vx || 0) * dt;
+    player.y += (player.vy || 0) * dt;
+  }
+
+  /**
+   * Handle ground collision for player
+   * Override for custom ground collision behavior
+   * @param {GameObject} player - The player object
+   */
+  handleGroundCollision(player) {
+    if (this.groundY !== null && player.y >= this.groundY) {
+      player.y = this.groundY;
+      player.vy = 0;
+      player._grounded = true;
+    }
+  }
+
+  // ==================== Update ====================
+
+  /**
+   * Update method - applies physics, input, and camera following
+   * @param {number} dt - Delta time in seconds
+   */
+  update(dt) {
+    if (this.player) {
+      // Apply gravity (if enabled)
+      if (this.autoGravity) {
+        this.applyGravity(this.player, dt);
+      }
+
+      // Apply input (if enabled)
+      if (this.autoInput) {
+        this.applyInput(this.player, dt);
+      }
+
+      // Apply velocity to position
+      this.applyVelocity(this.player, dt);
+
+      // Handle ground collision
+      this.handleGroundCollision(this.player);
+    }
+
+    // Update camera
+    this.updateCamera(dt);
+
+    // Update all children (layers and non-layer children)
+    super.update(dt);
+  }
+
+  // ==================== Rendering ====================
+
+  /**
+   * Draw with viewport clipping and parallax
+   */
+  draw() {
+    // Apply scene transforms (rotation, scale, etc.)
+    this.applyTransforms();
+
+    // Draw debug bounds if enabled
+    this.drawDebug();
+
+    // Get viewport dimensions
+    const viewportW = this._viewportWidth ?? this.game.width;
+    const viewportH = this._viewportHeight ?? this.game.height;
+
+    // Get camera offset
+    const offset = this.getCameraOffset();
+
+    Painter.save();
+
+    // Clip to viewport
+    // Account for scene position - clip in world coordinates
+    Painter.ctx.beginPath();
+    Painter.ctx.rect(-this.x, -this.y, viewportW, viewportH);
+    Painter.ctx.clip();
+    Painter.ctx.beginPath();
+
+    // Translate to world origin so children render at their world positions
+    Painter.ctx.translate(-this.x, -this.y);
+
+    // Render layers with parallax
+    for (const layer of this._layers) {
+      if (!layer.gameObject.visible) continue;
+
+      Painter.save();
+
+      // Apply parallax offset based on layer speed
+      const parallaxX = offset.x * layer.speed + (layer.offsetX || 0);
+      const parallaxY = offset.y * layer.speed + (layer.offsetY || 0);
+
+      Painter.ctx.translate(-parallaxX, -parallaxY);
+
+      // Render the layer
+      layer.gameObject.render();
+
+      Painter.restore();
+    }
+
+    // Render non-layer children (like player, enemies) with full camera offset
+    for (const child of this._collection.getSortedChildren()) {
+      if (!child.visible) continue;
+      // Skip if this child is a layer (already rendered above)
+      if (this._layers.some((l) => l.gameObject === child)) continue;
+
+      Painter.save();
+      // Apply full camera offset
+      Painter.ctx.translate(-offset.x, -offset.y);
+      child.render();
+      Painter.restore();
+    }
+
+    Painter.restore();
+  }
+
+  // ==================== Utilities ====================
+
+  /**
+   * Shake the camera
+   * @param {number} intensity - Shake amount in pixels
+   * @param {number} duration - Shake duration in seconds
+   * @returns {PlatformerScene} this for chaining
+   */
+  shakeCamera(intensity, duration) {
+    if (this.camera) {
+      this.camera.shake(intensity, duration);
+    }
+    return this;
+  }
+
+  /**
+   * Set viewport dimensions
+   * @param {number} width - Viewport width
+   * @param {number} height - Viewport height
+   * @returns {PlatformerScene} this for chaining
+   */
+  setViewport(width, height) {
+    this._viewportWidth = width;
+    this._viewportHeight = height;
+    if (this.camera) {
+      this.camera.viewportWidth = width;
+      this.camera.viewportHeight = height;
+    }
+    return this;
+  }
+
+  /**
+   * Get viewport dimensions
+   * @returns {{width: number, height: number}}
+   */
+  getViewport() {
+    return {
+      width: this._viewportWidth ?? this.game.width,
+      height: this._viewportHeight ?? this.game.height,
+    };
+  }
+}

package/src/game/objects/scene.js

@@ -147,6 +147,20 @@ export class Scene extends GameObject {
     };
   }
 
+  /**
+   * Returns the scene's bounding box.
+   * Required for hit testing when the scene is interactive.
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  getBounds() {
+    return {
+      x: this.x,
+      y: this.y,
+      width: this._width || 0,
+      height: this._height || 0,
+    };
+  }
+
   bringToFront(go) {
     return this._collection.bringToFront(go);
   }