@guinetik/gcanvas 1.0.2 → 1.0.4

package/docs/concepts/two-layer-architecture.md

@@ -1,229 +0,0 @@
-# Two-Layer Architecture
-
-> Understanding when to use the Shape Layer vs the Game Layer.
-
-## Overview
-
-GCanvas provides two complementary approaches to building canvas applications:
-
-1. **Shape Layer** - For declarative, static graphics
-2. **Game Layer** - For interactive, dynamic applications
-
-You can use either layer independently or combine them for complex applications.
-
-## Shape Layer
-
-The Shape Layer is for drawing graphics without a game loop. Shapes are self-contained objects that know how to render themselves.
-
-### When to Use
-
-- Static visualizations
-- Data charts and graphs
-- Decorative graphics
-- Simple animations (manual redraw)
-- Learning canvas fundamentals
-
-### Key Classes
-
-- `Shape` and subclasses (`Circle`, `Rectangle`, `Star`, etc.)
-- `Group` for composing shapes
-- `Painter` for direct canvas control
-
-### Example
-
-```js
-import { Circle, Rectangle, Group, Painter } from '@guinetik/gcanvas';
-
-// Initialize Painter with canvas context
-const canvas = document.getElementById('canvas');
-Painter.init(canvas.getContext('2d'));
-
-// Create shapes
-const circle = new Circle(50, { x: 100, y: 100, color: 'red' });
-const rect = new Rectangle(80, 40, { x: 200, y: 100, color: 'blue' });
-
-// Draw immediately
-Painter.clear();
-circle.draw();
-rect.draw();
-```
-
-### Characteristics
-
-| Aspect | Shape Layer |
-|--------|-------------|
-| Loop | None (manual redraw) |
-| State | Shapes hold their own state |
-| Input | Manual event handling |
-| Animation | Call draw() on each frame manually |
-| Complexity | Simple, direct |
-
-## Game Layer
-
-The Game Layer provides a complete game loop with automatic updates, rendering, and input handling.
-
-### When to Use
-
-- Games and simulations
-- Interactive applications
-- Real-time animations
-- Complex state management
-- Multi-object coordination
-
-### Key Classes
-
-- `Game` - Main loop and canvas management
-- `Pipeline` - Object lifecycle management
-- `GameObject` - Interactive entities
-- `Scene` - Hierarchical organization
-
-### Example
-
-```js
-import { Game, Scene, GameObject, Circle } from '@guinetik/gcanvas';
-
-class Player extends GameObject {
-  constructor(game) {
-    super(game);
-    this.shape = new Circle(40, { color: 'blue' });
-    this.enableInteractivity(this.shape);
-  }
-
-  update(dt) {
-    // Called every frame
-    if (this.game.input.isKeyDown('ArrowRight')) {
-      this.shape.x += 200 * dt;
-    }
-  }
-
-  render() {
-    // Called every frame after update
-    this.shape.draw();
-  }
-
-  onPointerDown(e) {
-    // Automatic input handling
-    console.log('Clicked!');
-  }
-}
-
-class MyGame extends Game {
-  init() {
-    this.enableFluidSize();
-    const scene = new Scene(this);
-    scene.add(new Player(this));
-    this.pipeline.add(scene);
-  }
-}
-
-const game = new MyGame(document.getElementById('canvas'));
-game.start();
-```
-
-### Characteristics
-
-| Aspect | Game Layer |
-|--------|-------------|
-| Loop | Automatic (requestAnimationFrame) |
-| State | Managed by Pipeline |
-| Input | Automatic dispatching to objects |
-| Animation | Built-in with dt (delta time) |
-| Complexity | Full-featured |
-
-## Comparison
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Shape Layer                             │
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
-│  │ Circle  │  │Rectangle│  │  Star   │  ... more shapes    │
-│  └────┬────┘  └────┬────┘  └────┬────┘                      │
-│       │            │            │                            │
-│       └────────────┼────────────┘                            │
-│                    ▼                                         │
-│              ┌──────────┐                                    │
-│              │  Group   │  (optional composition)            │
-│              └────┬─────┘                                    │
-│                   │                                          │
-│                   ▼                                          │
-│              ┌──────────┐                                    │
-│              │  draw()  │  (manual call)                     │
-│              └──────────┘                                    │
-└─────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────┐
-│                      Game Layer                              │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │                       Game                           │    │
-│  │  ┌─────────────────────────────────────────────┐    │    │
-│  │  │                   Pipeline                   │    │    │
-│  │  │  ┌─────────────────────────────────────┐    │    │    │
-│  │  │  │               Scene                  │    │    │    │
-│  │  │  │  ┌───────────┐  ┌───────────┐       │    │    │    │
-│  │  │  │  │GameObject │  │GameObject │  ...  │    │    │    │
-│  │  │  │  │  + Shape  │  │  + Shape  │       │    │    │    │
-│  │  │  │  └───────────┘  └───────────┘       │    │    │    │
-│  │  │  └─────────────────────────────────────┘    │    │    │
-│  │  └─────────────────────────────────────────────┘    │    │
-│  └─────────────────────────────────────────────────────┘    │
-│                            │                                 │
-│                            ▼                                 │
-│                     ┌────────────┐                           │
-│                     │ Game Loop  │  (automatic)              │
-│                     │ update(dt) │                           │
-│                     │ render()   │                           │
-│                     └────────────┘                           │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Mixing Layers
-
-You can use shapes without GameObjects, or combine both approaches:
-
-```js
-class HybridGame extends Game {
-  init() {
-    // Game layer for interactive elements
-    const scene = new Scene(this);
-    scene.add(new Player(this));
-    this.pipeline.add(scene);
-
-    // Shape layer for static background
-    this.background = new Group();
-    this.background.add(new Rectangle(this.width, this.height, { color: '#222' }));
-  }
-
-  render() {
-    // Draw static shapes first
-    this.background.draw();
-
-    // Then let pipeline draw interactive objects
-    super.render();
-  }
-}
-```
-
-## Decision Guide
-
-| If you need... | Use |
-|---------------|-----|
-| Static graphics | Shape Layer |
-| Simple animations | Shape Layer + manual loop |
-| Keyboard/mouse input | Game Layer |
-| Multiple interactive objects | Game Layer |
-| Collision detection | Game Layer |
-| Scene organization | Game Layer |
-| Quick prototype | Shape Layer |
-| Full game | Game Layer |
-
-## Related
-
-- [Architecture Overview](./architecture-overview.md) - Full system architecture
-- [Rendering Pipeline](./rendering-pipeline.md) - Shape inheritance chain
-- [Game Lifecycle](./lifecycle.md) - Update/render cycle
-
-## See Also
-
-- [Shapes Module](../modules/shapes/README.md)
-- [Game Module](../modules/game/README.md)
-- [Getting Started: Hello World](../getting-started/hello-world.md)

package/docs/fluid-dynamics.md

@@ -1,99 +0,0 @@
-# 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/docs/getting-started/first-game.md

@@ -1,354 +0,0 @@
-# First Game
-
-> Create an interactive game with the Game layer.
-
-## Overview
-
-This guide shows how to use the Game layer to create interactive applications. We'll build a simple game with keyboard input, collision detection, and animations.
-
-## Basic Game Setup
-
-```js
-import { Game, Scene, GameObject, Circle, Group, Rectangle, TextShape } from '@guinetik/gcanvas';
-
-class MyGame extends Game {
-  constructor(canvas) {
-    super(canvas);
-    this.enableFluidSize();  // Canvas fills window
-    this.backgroundColor = '#1a1a2e';
-  }
-
-  init() {
-    super.init();  // Initialize input systems
-
-    // Create a scene
-    this.scene = new Scene(this);
-    this.pipeline.add(this.scene);
-
-    // Add game objects
-    this.scene.add(new Player(this));
-  }
-}
-
-// Start the game
-const canvas = document.getElementById('game');
-const game = new MyGame(canvas);
-game.start();
-```
-
-## Creating a Player
-
-```js
-class Player extends GameObject {
-  constructor(game) {
-    super(game);
-
-    // Create the player shape
-    this.shape = new Circle(30, {
-      color: '#4ecdc4',
-      stroke: '#fff',
-      lineWidth: 2
-    });
-
-    // Position at center
-    this.shape.x = game.width / 2;
-    this.shape.y = game.height / 2;
-
-    // Movement speed (pixels per second)
-    this.speed = 300;
-
-    // Enable mouse/touch input on this shape
-    this.enableInteractivity(this.shape);
-  }
-
-  update(dt) {
-    // Handle keyboard input
-    const input = this.game.input;
-
-    if (input.isKeyDown('ArrowLeft') || input.isKeyDown('KeyA')) {
-      this.shape.x -= this.speed * dt;
-    }
-    if (input.isKeyDown('ArrowRight') || input.isKeyDown('KeyD')) {
-      this.shape.x += this.speed * dt;
-    }
-    if (input.isKeyDown('ArrowUp') || input.isKeyDown('KeyW')) {
-      this.shape.y -= this.speed * dt;
-    }
-    if (input.isKeyDown('ArrowDown') || input.isKeyDown('KeyS')) {
-      this.shape.y += this.speed * dt;
-    }
-
-    // Keep player on screen
-    this.shape.x = Math.max(30, Math.min(this.game.width - 30, this.shape.x));
-    this.shape.y = Math.max(30, Math.min(this.game.height - 30, this.shape.y));
-  }
-
-  render() {
-    this.shape.draw();
-  }
-
-  // Called when player is clicked
-  onPointerDown(e) {
-    console.log('Player clicked!');
-  }
-}
-```
-
-## Adding Enemies
-
-```js
-class Enemy extends GameObject {
-  constructor(game, x, y) {
-    super(game);
-
-    this.shape = new Rectangle({
-      x: x,
-      y: y,
-      width: 40,
-      height: 40,
-      color: '#ff6b6b'
-    });
-
-    // Random direction
-    this.vx = (Math.random() - 0.5) * 200;
-    this.vy = (Math.random() - 0.5) * 200;
-  }
-
-  update(dt) {
-    // Move
-    this.shape.x += this.vx * dt;
-    this.shape.y += this.vy * dt;
-
-    // Bounce off walls
-    if (this.shape.x < 20 || this.shape.x > this.game.width - 20) {
-      this.vx *= -1;
-    }
-    if (this.shape.y < 20 || this.shape.y > this.game.height - 20) {
-      this.vy *= -1;
-    }
-
-    // Rotate
-    this.shape.rotation += dt * 2;
-  }
-
-  render() {
-    this.shape.draw();
-  }
-}
-```
-
-## Complete Game Example
-
-Here's a complete game from `demos/js/basic.js`:
-
-```js
-import {
-  Game,
-  GameObject,
-  Scene,
-  Circle,
-  Rectangle,
-  TextShape,
-  Group,
-  Motion,
-  Easing,
-  FPSCounter
-} from '@guinetik/gcanvas';
-
-/**
- * HelloWorldBox - A simple animated text box
- */
-class HelloWorldBox extends GameObject {
-  constructor(game) {
-    super(game);
-
-    // Create a group to hold shapes
-    this.group = new Group({});
-
-    // Background box
-    this.box = new Rectangle({
-      width: 200,
-      height: 80,
-      color: '#333'
-    });
-
-    // Text label
-    this.label = new TextShape('Hello World!', {
-      font: '18px monospace',
-      color: '#0f0',
-      align: 'center',
-      baseline: 'middle'
-    });
-
-    // Add to group
-    this.group.add(this.box);
-    this.group.add(this.label);
-
-    // Animation time
-    this.animTime = 0;
-  }
-
-  update(dt) {
-    this.animTime += dt;
-
-    // Pulse the text opacity
-    const pulse = Motion.pulse(
-      0, 1,           // min, max opacity
-      this.animTime,
-      2,              // 2 second cycle
-      true,           // loop
-      false,          // no yoyo
-      Easing.easeInOutSine
-    );
-    this.label.opacity = pulse.value;
-
-    // Float the group
-    const float = Motion.float(
-      { x: 0, y: 0 },
-      this.animTime,
-      5,              // 5 second cycle
-      0.5,            // speed
-      0.5,            // randomness
-      50,             // radius
-      true,
-      Easing.easeInOutSine
-    );
-    this.group.x = float.x;
-    this.group.y = float.y;
-
-    super.update(dt);
-  }
-
-  render() {
-    this.group.render();
-  }
-}
-
-/**
- * DemoGame - Main game class
- */
-class DemoGame extends Game {
-  constructor(canvas) {
-    super(canvas);
-    this.enableFluidSize();
-    this.backgroundColor = 'black';
-  }
-
-  init() {
-    super.init();
-
-    // Create main scene
-    this.gameScene = new Scene(this);
-    this.gameScene.add(new HelloWorldBox(this));
-    this.pipeline.add(this.gameScene);
-
-    // Add orbiting circle
-    this.floatingCircle = new Circle(30, {
-      x: this.width / 2 + 200,
-      y: this.height / 2,
-      color: '#0f0'
-    });
-    this.floatingCircle.animTime = 0;
-    this.pipeline.add(this.floatingCircle);
-
-    // Add FPS counter
-    this.pipeline.add(new FPSCounter(this, {
-      anchor: 'bottom-right'
-    }));
-  }
-
-  update(dt) {
-    super.update(dt);
-
-    // Center the scene
-    this.gameScene.x = this.width / 2;
-    this.gameScene.y = this.height / 2;
-
-    // Orbit the circle
-    this.floatingCircle.animTime += dt;
-    const orbit = Motion.orbit(
-      this.width / 2, this.height / 2,
-      200, 200,       // radius X, Y
-      0,              // start angle
-      this.floatingCircle.animTime,
-      8,              // 8 second orbit
-      true,           // loop
-      true            // clockwise
-    );
-    this.floatingCircle.x = orbit.x;
-    this.floatingCircle.y = orbit.y;
-  }
-}
-
-// Run the game
-window.addEventListener('load', () => {
-  const canvas = document.getElementById('game');
-  const game = new DemoGame(canvas);
-  game.start();
-});
-```
-
-## HTML Template
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <title>My First Game</title>
-  <style>
-    body { margin: 0; overflow: hidden; }
-    canvas { display: block; }
-  </style>
-</head>
-<body>
-  <canvas id="game"></canvas>
-  <script type="module" src="./game.js"></script>
-</body>
-</html>
-```
-
-## Key Concepts
-
-| Concept | Description |
-|---------|-------------|
-| `Game` | Main class managing loop, canvas, input |
-| `Scene` | Container for GameObjects |
-| `GameObject` | Interactive entity with update/render |
-| `enableInteractivity(shape)` | Enable click/hover on a shape |
-| `dt` | Delta time in seconds |
-| `game.input.isKeyDown(key)` | Check if key is pressed |
-| `Motion.*` | Animation helper functions |
-| `FPSCounter` | Built-in FPS display |
-
-## Input Reference
-
-```js
-// Keyboard
-game.input.isKeyDown('ArrowUp')
-game.input.isKeyDown('KeyW')
-game.input.isKeyDown('Space')
-
-// Mouse position
-game.mouse.x
-game.mouse.y
-
-// GameObject events
-onPointerDown(e) { }
-onPointerUp(e) { }
-onPointerMove(e) { }
-onMouseOver() { }
-onMouseOut() { }
-```
-
-## Next Steps
-
-- [Game Module](../modules/game/README.md) - Full Game API reference
-- [Motion Patterns](../modules/motion/README.md) - Animation functions
-- [Input Handling](../modules/io/README.md) - Mouse, keyboard, touch
-
-## Related
-
-- [Hello World](./hello-world.md)
-- [Two-Layer Architecture](../concepts/two-layer-architecture.md)
-- [Game Lifecycle](../concepts/lifecycle.md)