@guinetik/gcanvas 1.0.0 → 1.0.1

package/docs/api/FluidSystem.md

@@ -0,0 +1,173 @@
+# FluidSystem
+
+High-level fluid simulation system built on `ParticleSystem`.
+
+Integrates SPH physics, collision detection, and boundary handling into a cohesive, configurable fluid simulation.
+
+## Import
+
+```javascript
+import { FluidSystem } from "gcanvas";
+```
+
+## Basic Usage
+
+```javascript
+// Create a liquid simulation
+const fluid = new FluidSystem(game, {
+  maxParticles: 500,
+  particleSize: 20,
+  bounds: { x: 50, y: 50, w: 700, h: 500 },
+  physics: 'liquid',
+});
+
+// Spawn particles
+fluid.spawn(300);
+
+// Add to game pipeline
+game.pipeline.add(fluid);
+```
+
+## Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxParticles` | number | 500 | Maximum particle count |
+| `particleSize` | number | 20 | Base particle diameter |
+| `bounds` | Object | null | Containment bounds `{ x, y, w, h }` |
+| `physics` | string | 'liquid' | Physics mode: `'liquid'`, `'gas'`, or `'blend'` |
+| `gravity` | number | 200 | Gravity strength |
+| `gravityEnabled` | boolean | true | Whether gravity is active |
+| `damping` | number | 0.98 | Velocity damping per frame |
+| `bounce` | number | 0.3 | Bounce factor on collision |
+| `maxSpeed` | number | 400 | Maximum particle speed |
+
+### Fluid Sub-Options (`options.fluid`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `smoothingRadius` | number | particleSize * 2 | SPH smoothing radius |
+| `restDensity` | number | 3.0 | Target density |
+| `pressureStiffness` | number | 80 | Pressure force multiplier |
+| `nearPressureStiffness` | number | 3 | Near pressure multiplier |
+| `viscosity` | number | 0.005 | Viscosity strength |
+
+### Collision Sub-Options (`options.collision`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | true | Enable particle collision |
+| `strength` | number | 5000 | Collision repulsion strength |
+
+### Boundary Sub-Options (`options.boundary`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | true | Enable boundary forces |
+| `strength` | number | 4000 | Boundary repulsion strength |
+| `radius` | number | particleSize * 0.8 | Boundary force range |
+
+## Methods
+
+### spawn(count, options?)
+
+Spawn particles within the bounds or at a specified position.
+
+```javascript
+// Spawn at bounds center (default)
+fluid.spawn(200);
+
+// Spawn at specific position
+fluid.spawn(100, { x: 400, y: 300, spreadX: 50, spreadY: 50 });
+```
+
+### setBounds(bounds)
+
+Update containment bounds.
+
+```javascript
+fluid.setBounds({ x: 100, y: 100, w: 600, h: 400 });
+```
+
+### reset()
+
+Reset all particles to initial spawn positions.
+
+```javascript
+fluid.reset();
+```
+
+### toggleGravity()
+
+Toggle gravity on/off. Returns new state.
+
+```javascript
+const gravityOn = fluid.toggleGravity();
+```
+
+### setPhysicsMode(mode)
+
+Switch physics mode.
+
+```javascript
+fluid.setPhysicsMode('liquid');  // SPH fluid
+fluid.setPhysicsMode('gas');     // Gas dynamics
+fluid.setPhysicsMode(0.5);       // 50% blend
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `particles` | Array | Live particle array |
+| `bounds` | Object | Current bounds `{ x, y, w, h }` |
+| `gravityEnabled` | boolean | Gravity state |
+| `physicsBlend` | number | 0 = liquid, 1 = gas |
+| `config` | Object | Merged configuration |
+
+## Example: Complete Demo
+
+```javascript
+import { Game, FluidSystem, FPSCounter } from "gcanvas";
+
+class FluidDemo extends Game {
+  init() {
+    super.init();
+    
+    // Create fluid system
+    this.fluid = new FluidSystem(this, {
+      maxParticles: 400,
+      particleSize: 25,
+      bounds: { x: 50, y: 50, w: this.width - 100, h: this.height - 100 },
+      physics: 'liquid',
+      gravity: 200,
+    });
+    
+    this.fluid.spawn(400);
+    this.pipeline.add(this.fluid);
+    this.pipeline.add(new FPSCounter(this));
+    
+    // Keyboard controls
+    window.addEventListener('keydown', (e) => {
+      if (e.key === 'g') this.fluid.toggleGravity();
+      if (e.key === 'r') this.fluid.reset();
+    });
+  }
+}
+```
+
+## Integration with Existing Code
+
+FluidSystem reuses existing modules:
+
+- `ParticleSystem` - Base particle management
+- `Collision.applyCircleSeparation()` - Particle-particle collision
+- `computeFluidForces()` - SPH physics from `math/fluid.js`
+- `computeGasForces()` - Gas dynamics from `math/fluid.js`
+
+## Performance Notes
+
+- O(n²) collision detection is used for simplicity
+- For >1000 particles, consider spatial hashing optimization
+- The `blendMode: 'source-over'` default prevents washed-out colors
+

package/docs/concepts/architecture-overview.md

@@ -1,204 +1,204 @@
-# Architecture Overview
-
-> High-level system architecture, module relationships, and design philosophy.
-
-## Overview
-
-GCanvas is a modular 2D rendering and game framework built on top of the HTML5 Canvas API. It follows a layered architecture where each module has a clear responsibility and minimal coupling to other modules.
-
-The library is designed around three core principles:
-
-1. **Modularity** - Use only what you need
-2. **Composability** - Combine simple parts to build complex systems
-3. **Zero Dependencies** - Pure JavaScript, works everywhere
-
-## Module Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                           GCanvas                                │
-│                         (index.js)                               │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │                    Core Modules                           │   │
-│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
-│  │  │   shapes/   │  │   game/     │  │    painter/     │   │   │
-│  │  │  40+ shapes │  │  Game loop  │  │   Canvas API    │   │   │
-│  │  │  hierarchy  │  │  Pipeline   │  │   abstraction   │   │   │
-│  │  │  Group      │  │  GameObject │  │                 │   │   │
-│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │                  Support Modules                          │   │
-│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐  │   │
-│  │  │ motion │ │   io   │ │  math  │ │  util  │ │ mixins │  │   │
-│  │  │ Tween  │ │ Events │ │ Random │ │ Layout │ │Draggable│  │   │
-│  │  │ Easing │ │ Mouse  │ │ Noise  │ │Position│ │ Anchor │  │   │
-│  │  │ Motion │ │ Keys   │ │Fractals│ │ZIndex  │ │        │  │   │
-│  │  │Tweenetik│ │ Touch  │ │Patterns│ │ Tasks  │ │        │  │   │
-│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘  │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                  │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │                  Utility Modules                          │   │
-│  │                    ┌────────┐                             │   │
-│  │                    │ logger │                             │   │
-│  │                    │ Logger │                             │   │
-│  │                    │Loggable│                             │   │
-│  │                    │DebugTab│                             │   │
-│  │                    └────────┘                             │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Module Responsibilities
-
-### Core Modules
-
-| Module | Responsibility | Key Classes |
-|--------|---------------|-------------|
-| **shapes** | Visual primitives and rendering | `Shape`, `Circle`, `Rectangle`, `Group`, `Transformable` |
-| **game** | Game loop, lifecycle, object management | `Game`, `Pipeline`, `GameObject`, `Scene` |
-| **painter** | Canvas context abstraction | `Painter`, `PainterShapes`, `PainterText` |
-
-### Support Modules
-
-| Module | Responsibility | Key Classes |
-|--------|---------------|-------------|
-| **motion** | Animation and tweening | `Motion`, `Tweenetik`, `Easing`, `Tween` |
-| **io** | Input handling | `EventEmitter`, `Mouse`, `Keys`, `Touch`, `Input` |
-| **math** | Mathematical utilities | `Random`, `Noise`, `Complex`, `Fractals`, `Patterns` |
-| **util** | Layout and positioning | `Layout`, `Position`, `ZOrderedCollection` |
-| **mixins** | Composable behaviors | `applyDraggable()`, `applyAnchor()` |
-
-### Utility Modules
-
-| Module | Responsibility | Key Classes |
-|--------|---------------|-------------|
-| **logger** | Debug and logging | `Logger`, `Loggable`, `DebugTab` |
-
-## Data Flow
-
-```
-User Input                     Game Loop
-    │                              │
-    ▼                              ▼
-┌────────┐     events         ┌────────┐
-│   IO   │ ──────────────────►│  Game  │
-└────────┘                    └────────┘
-                                   │
-                    ┌──────────────┼──────────────┐
-                    ▼              ▼              ▼
-              ┌──────────┐  ┌──────────┐   ┌──────────┐
-              │ Pipeline │  │ Tweenetik│   │  Painter │
-              │ update() │  │ update() │   │  clear() │
-              └──────────┘  └──────────┘   └──────────┘
-                    │
-                    ▼
-              ┌──────────┐
-              │GameObject│
-              │ update() │
-              │ render() │
-              └──────────┘
-                    │
-                    ▼
-              ┌──────────┐
-              │  Shape   │
-              │  draw()  │
-              └──────────┘
-                    │
-                    ▼
-              ┌──────────┐
-              │ Painter  │
-              │ Canvas   │
-              └──────────┘
-```
-
-## Design Patterns
-
-### 1. Inheritance Chain (Shapes)
-
-Shapes use a linear inheritance hierarchy where each class adds specific functionality:
-
-```
-Euclidian → Geometry2d → Traceable → Renderable → Transformable → Shape
-```
-
-See: [Rendering Pipeline](./rendering-pipeline.md)
-
-### 2. Static Singleton (Painter)
-
-`Painter` is a static utility class initialized once with the canvas context:
-
-```js
-Painter.init(ctx);
-Painter.shapes.circle(100, 100, 50);
-```
-
-### 3. Component Pattern (GameObject + Shape)
-
-GameObjects compose shapes rather than inheriting from them:
-
-```js
-class Player extends GameObject {
-  constructor(game) {
-    super(game);
-    this.shape = new Circle(40, { color: 'blue' });
-  }
-}
-```
-
-### 4. Mixin Pattern (Behaviors)
-
-Optional behaviors are applied via mixin functions:
-
-```js
-applyDraggable(gameObject, gameObject.shape);
-applyAnchor(gameObject, { anchor: 'top-right' });
-```
-
-### 5. Observer Pattern (Events)
-
-The `EventEmitter` provides pub-sub event handling:
-
-```js
-game.events.on('click', (e) => { ... });
-game.events.emit('custom-event', data);
-```
-
-## Entry Point
-
-The main entry point (`src/index.js`) re-exports all modules:
-
-```js
-export * from "./util";
-export * from "./math";
-export * from "./logger";
-export * from "./painter";
-export * from "./shapes";
-export * from "./io";
-export * from "./game";
-export * from "./motion";
-export * from "./mixins";
-```
-
-This allows importing any component from the main package:
-
-```js
-import { Game, Circle, Painter, Motion } from 'gcanvas';
-```
-
-## Related
-
-- [Two-Layer Architecture](./two-layer-architecture.md) - Shape vs Game layer
-- [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)
-- [Painter Module](../modules/painter/README.md)
+# Architecture Overview
+
+> High-level system architecture, module relationships, and design philosophy.
+
+## Overview
+
+GCanvas is a modular 2D rendering and game framework built on top of the HTML5 Canvas API. It follows a layered architecture where each module has a clear responsibility and minimal coupling to other modules.
+
+The library is designed around three core principles:
+
+1. **Modularity** - Use only what you need
+2. **Composability** - Combine simple parts to build complex systems
+3. **Zero Dependencies** - Pure JavaScript, works everywhere
+
+## Module Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                           GCanvas                                │
+│                         (index.js)                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                    Core Modules                           │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
+│  │  │   shapes/   │  │   game/     │  │    painter/     │   │   │
+│  │  │  40+ shapes │  │  Game loop  │  │   Canvas API    │   │   │
+│  │  │  hierarchy  │  │  Pipeline   │  │   abstraction   │   │   │
+│  │  │  Group      │  │  GameObject │  │                 │   │   │
+│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                  Support Modules                          │   │
+│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐  │   │
+│  │  │ motion │ │   io   │ │  math  │ │  util  │ │ mixins │  │   │
+│  │  │ Tween  │ │ Events │ │ Random │ │ Layout │ │Draggable│  │   │
+│  │  │ Easing │ │ Mouse  │ │ Noise  │ │Position│ │ Anchor │  │   │
+│  │  │ Motion │ │ Keys   │ │Fractals│ │ZIndex  │ │        │  │   │
+│  │  │Tweenetik│ │ Touch  │ │Patterns│ │ Tasks  │ │        │  │   │
+│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘  │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │                  Utility Modules                          │   │
+│  │                    ┌────────┐                             │   │
+│  │                    │ logger │                             │   │
+│  │                    │ Logger │                             │   │
+│  │                    │Loggable│                             │   │
+│  │                    │DebugTab│                             │   │
+│  │                    └────────┘                             │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Module Responsibilities
+
+### Core Modules
+
+| Module | Responsibility | Key Classes |
+|--------|---------------|-------------|
+| **shapes** | Visual primitives and rendering | `Shape`, `Circle`, `Rectangle`, `Group`, `Transformable` |
+| **game** | Game loop, lifecycle, object management | `Game`, `Pipeline`, `GameObject`, `Scene` |
+| **painter** | Canvas context abstraction | `Painter`, `PainterShapes`, `PainterText` |
+
+### Support Modules
+
+| Module | Responsibility | Key Classes |
+|--------|---------------|-------------|
+| **motion** | Animation and tweening | `Motion`, `Tweenetik`, `Easing`, `Tween` |
+| **io** | Input handling | `EventEmitter`, `Mouse`, `Keys`, `Touch`, `Input` |
+| **math** | Mathematical utilities | `Random`, `Noise`, `Complex`, `Fractals`, `Patterns` |
+| **util** | Layout and positioning | `Layout`, `Position`, `ZOrderedCollection` |
+| **mixins** | Composable behaviors | `applyDraggable()`, `applyAnchor()` |
+
+### Utility Modules
+
+| Module | Responsibility | Key Classes |
+|--------|---------------|-------------|
+| **logger** | Debug and logging | `Logger`, `Loggable`, `DebugTab` |
+
+## Data Flow
+
+```
+User Input                     Game Loop
+    │                              │
+    ▼                              ▼
+┌────────┐     events         ┌────────┐
+│   IO   │ ──────────────────►│  Game  │
+└────────┘                    └────────┘
+                                   │
+                    ┌──────────────┼──────────────┐
+                    ▼              ▼              ▼
+              ┌──────────┐  ┌──────────┐   ┌──────────┐
+              │ Pipeline │  │ Tweenetik│   │  Painter │
+              │ update() │  │ update() │   │  clear() │
+              └──────────┘  └──────────┘   └──────────┘
+                    │
+                    ▼
+              ┌──────────┐
+              │GameObject│
+              │ update() │
+              │ render() │
+              └──────────┘
+                    │
+                    ▼
+              ┌──────────┐
+              │  Shape   │
+              │  draw()  │
+              └──────────┘
+                    │
+                    ▼
+              ┌──────────┐
+              │ Painter  │
+              │ Canvas   │
+              └──────────┘
+```
+
+## Design Patterns
+
+### 1. Inheritance Chain (Shapes)
+
+Shapes use a linear inheritance hierarchy where each class adds specific functionality:
+
+```
+Euclidian → Geometry2d → Traceable → Renderable → Transformable → Shape
+```
+
+See: [Rendering Pipeline](./rendering-pipeline.md)
+
+### 2. Static Singleton (Painter)
+
+`Painter` is a static utility class initialized once with the canvas context:
+
+```js
+Painter.init(ctx);
+Painter.shapes.circle(100, 100, 50);
+```
+
+### 3. Component Pattern (GameObject + Shape)
+
+GameObjects compose shapes rather than inheriting from them:
+
+```js
+class Player extends GameObject {
+  constructor(game) {
+    super(game);
+    this.shape = new Circle(40, { color: 'blue' });
+  }
+}
+```
+
+### 4. Mixin Pattern (Behaviors)
+
+Optional behaviors are applied via mixin functions:
+
+```js
+applyDraggable(gameObject, gameObject.shape);
+applyAnchor(gameObject, { anchor: 'top-right' });
+```
+
+### 5. Observer Pattern (Events)
+
+The `EventEmitter` provides pub-sub event handling:
+
+```js
+game.events.on('click', (e) => { ... });
+game.events.emit('custom-event', data);
+```
+
+## Entry Point
+
+The main entry point (`src/index.js`) re-exports all modules:
+
+```js
+export * from "./util";
+export * from "./math";
+export * from "./logger";
+export * from "./painter";
+export * from "./shapes";
+export * from "./io";
+export * from "./game";
+export * from "./motion";
+export * from "./mixins";
+```
+
+This allows importing any component from the main package:
+
+```js
+import { Game, Circle, Painter, Motion } from '@guinetik/gcanvas';
+```
+
+## Related
+
+- [Two-Layer Architecture](./two-layer-architecture.md) - Shape vs Game layer
+- [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)
+- [Painter Module](../modules/painter/README.md)