@guinetik/gcanvas 1.0.0 → 1.0.2

package/docs/concepts/shapes-vs-gameobjects.md

@@ -0,0 +1,187 @@
+# Shapes vs GameObjects
+
+GCanvas serves two distinct use cases with different abstractions. Understanding when to use each is key to working effectively with the library.
+
+## Overview
+
+| Aspect | Shapes | GameObjects |
+|--------|--------|-------------|
+| Purpose | Direct canvas rendering | Managed game pipeline |
+| Game loop | Not required | Required |
+| Rendering | Call `render()` manually | Automatic via pipeline |
+| State | Stateless between frames | Maintains state |
+| Lifecycle | None | `update(dt)` / `draw()` |
+| Best for | Generative art, static visuals | Games, animations, interactive apps |
+
+## The Two Hierarchies
+
+### Shape Hierarchy (Drawing)
+
+```
+Euclidian → Geometry2d → Renderable → Transformable → Shape
+```
+
+- **Euclidian**: Basic positioning (x, y, width, height)
+- **Geometry2d**: Bounds constraints, bounding box calculations
+- **Renderable**: Visibility, opacity, shadows
+- **Transformable**: Rotation, scaling
+- **Shape**: Styling (fill, stroke, lineWidth)
+
+### GameObject Hierarchy (Pipeline)
+
+```
+GameObject → Scene / Sprite / Text
+```
+
+- **GameObject**: Base class with `update(dt)` and `draw()` lifecycle
+- **Scene**: Container for other GameObjects
+- **Sprite**: Animated GameObject with frame-by-frame timeline
+- **Text**: Text rendering with automatic updates
+
+### Containers
+
+| Container | Holds | Has update()? |
+|-----------|-------|---------------|
+| `Group` | Shapes | No |
+| `Scene` | GameObjects | Yes |
+
+## When to Use What
+
+| Use Case | Use This | Why |
+|----------|----------|-----|
+| Static visualization | `Shape` + `render()` | No update loop needed |
+| Generative art | `Shape`, `Group` | Direct control, no overhead |
+| Game character | `Sprite` (GameObject) | Needs update cycle for animation |
+| UI elements | `Text`, `Scene` | Pipeline handles positioning |
+| Complex scene | `Scene` with children | Hierarchical transforms, lifecycle |
+| Composite shape | `Group` | Transform multiple shapes together |
+
+## Example: Shapes Only (No Game Loop)
+
+You can use GCanvas purely for drawing without any game infrastructure:
+
+```javascript
+import { Circle, Rectangle, Group, Painter } from "gcanvas";
+
+// Get canvas context
+const canvas = document.getElementById("canvas");
+const ctx = canvas.getContext("2d");
+Painter.ctx = ctx;
+
+// Create shapes
+const circle = new Circle(50, { x: 100, y: 100, color: "#0f0" });
+const rect = new Rectangle({ x: 200, y: 100, width: 80, height: 60, color: "#0ff" });
+
+// Render directly - no game loop needed
+circle.render();
+rect.render();
+
+// Group multiple shapes
+const group = new Group({ x: 300, y: 100, rotation: Math.PI / 4 });
+group.add(new Circle(20, { color: "#f0f" }));
+group.add(new Rectangle({ y: 30, width: 40, height: 20, color: "#ff0" }));
+group.render();
+```
+
+> **Note:** This is perfect for one-off drawings, generative art, or when you want full control over the render loop.
+
+## Example: GameObjects with Pipeline
+
+When you need animation, input handling, and managed lifecycles:
+
+```javascript
+import { Game, Scene, Sprite, Text, Circle, Keys } from "gcanvas";
+
+class MyGame extends Game {
+  init() {
+    super.init();
+
+    // Create a scene (GameObject container)
+    this.scene = new Scene(this, { anchor: "center" });
+
+    // Create a sprite with animation (GameObject)
+    this.player = new Sprite(this, { x: 0, y: 0, frameRate: 10 });
+    this.player.addFrame(new Circle(20, { color: "#0f0" }));
+    this.player.addFrame(new Circle(25, { color: "#0ff" }));
+    this.player.play();
+
+    // Add to scene
+    this.scene.add(this.player);
+
+    // Add scene to pipeline - now it's managed
+    this.pipeline.add(this.scene);
+
+    // Input handling
+    this.events.on(Keys.SPACE, () => this.player.pause());
+  }
+
+  update(dt) {
+    super.update(dt);
+    // Player sprite automatically updates via pipeline
+  }
+}
+```
+
+> **Note:** GameObjects get their `update(dt)` called automatically by the pipeline each frame.
+
+## Bridging: Shape to GameObject
+
+Sometimes you have a Shape (or Group of shapes) that you want to add to the pipeline. Use `ShapeGOFactory`:
+
+```javascript
+import { Game, Group, Circle, Rectangle, ShapeGOFactory } from "gcanvas";
+
+class MyGame extends Game {
+  init() {
+    super.init();
+
+    // Create a Group of shapes
+    const avatar = new Group();
+    avatar.add(new Circle(30, { color: "#0f0" }));           // head
+    avatar.add(new Rectangle({ y: 50, width: 40, height: 60, color: "#0f0" })); // body
+
+    // Wrap it as a GameObject so it can join the pipeline
+    const avatarGO = ShapeGOFactory.create(this, avatar, {
+      x: 100,
+      y: 100,
+      interactive: true  // enables click/hover events
+    });
+
+    // Now it's a proper GameObject
+    this.pipeline.add(avatarGO);
+  }
+}
+```
+
+> **Important:** Never put GameObjects inside Groups. Group is a Shape container - it won't call `update()` on its children. Always use Scene for GameObjects.
+
+## Quick Reference
+
+| Class | Type | Container | Has update()? |
+|-------|------|-----------|---------------|
+| `Circle`, `Rectangle`, etc. | Shape | Group | No |
+| `Group` | Shape container | Group | No |
+| `TextShape` | Shape | Group | No |
+| `GameObject` | Base GO | Scene / Pipeline | Yes |
+| `Scene` | GO container | Scene / Pipeline | Yes |
+| `Sprite` | Animated GO | Scene / Pipeline | Yes |
+| `Text` | Text GO | Scene / Pipeline | Yes |
+
+## TL;DR
+
+**Just Drawing?**
+- Use `Shape`, `Group`
+- Call `.render()` yourself
+- No Game class needed
+
+**Building a Game?**
+- Use `GameObject`, `Scene`, `Sprite`
+- Add to `pipeline`
+- Extend `Game` class
+
+## See Also
+
+- [Coordinate System](./coordinate-system.md) - How positioning works (center-based, parent-child, Camera3D)
+- [Rendering Pipeline](./rendering-pipeline.md) - Deep dive into the Shape hierarchy
+- [Architecture Overview](./architecture-overview.md) - High-level system design
+- [Lifecycle](./lifecycle.md) - GameObject lifecycle details

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)