@guinetik/gcanvas 1.0.0 → 1.0.1

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

@@ -1,229 +1,229 @@
-# 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 '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 '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)
+# 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

@@ -0,0 +1,97 @@
+# 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). 
+
+
+