@guinetik/gcanvas 1.0.0

package/docs/modules/isometric.md

@@ -0,0 +1,275 @@
+# IsometricScene
+
+> A Scene subclass for rendering isometric tile-based games and visualizations.
+
+## Overview
+
+`IsometricScene` extends `Scene` to provide automatic isometric projection for child GameObjects. It uses the standard "diamond" isometric projection where grid coordinates (x, y) are transformed to 2D screen positions, with optional z-axis support for height above the ground plane.
+
+## Quick Start
+
+```javascript
+import { Game, IsometricScene, GameObject } from "gcanvas";
+
+class MyGame extends Game {
+  init() {
+    super.init();
+
+    // Create an isometric scene centered on canvas
+    const isoScene = new IsometricScene(this, {
+      x: this.width / 2,
+      y: this.height / 2,
+      tileWidth: 64,
+      tileHeight: 32,
+      gridSize: 10,
+      depthSort: true,
+    });
+
+    // Add objects using grid coordinates
+    const player = new Player(this);
+    player.x = 0;  // Grid X
+    player.y = 0;  // Grid Y
+    player.z = 0;  // Height above ground
+    isoScene.add(player);
+
+    this.pipeline.add(isoScene);
+  }
+}
+```
+
+## Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tileWidth` | number | 64 | Width of a tile in pixels |
+| `tileHeight` | number | tileWidth / 2 | Height of a tile in pixels |
+| `gridSize` | number | 10 | Size of the grid (used for scale calculations) |
+| `depthSort` | boolean | true | Sort children by depth (back-to-front) |
+| `scaleByDepth` | boolean | false | Scale children by perspective distance |
+| `elevationScale` | number | 1 | Multiplier for z-axis visual offset |
+| `camera` | IsometricCamera | null | Optional camera for animated view rotation |
+
+## Coordinate System
+
+IsometricScene uses a diamond-shaped isometric projection:
+
+```
+          Y-
+           \
+            \
+             \
+    X- ------+------ X+
+             /
+            /
+           /
+          Y+
+```
+
+- **Grid coordinates (x, y)**: Position on the isometric grid
+- **Z coordinate**: Height above the ground plane
+- **Screen coordinates**: Calculated automatically via projection
+
+### Projection Formula
+
+```javascript
+// Grid to screen conversion
+screenX = (x - y) * (tileWidth / 2)
+screenY = (x + y) * (tileHeight / 2) - z * elevationScale
+```
+
+## API Reference
+
+### toIsometric(x, y, z?)
+
+Converts grid coordinates to screen coordinates.
+
+```javascript
+const screen = isoScene.toIsometric(5, 3, 0);
+// { x: 64, y: 128, depth: 8 }
+```
+
+**Parameters:**
+- `x` (number): Grid X coordinate
+- `y` (number): Grid Y coordinate
+- `z` (number, optional): Height above ground (default: 0)
+
+**Returns:** `{ x: number, y: number, depth: number }`
+
+### fromIsometric(screenX, screenY)
+
+Converts screen coordinates back to grid coordinates (inverse transform).
+
+```javascript
+const grid = isoScene.fromIsometric(64, 128);
+// { x: 5, y: 3 }
+```
+
+**Parameters:**
+- `screenX` (number): Screen X relative to scene center
+- `screenY` (number): Screen Y relative to scene center
+
+**Returns:** `{ x: number, y: number }`
+
+### getTileAt(screenX, screenY)
+
+Gets the tile coordinates at a screen position (floored to integers).
+
+```javascript
+const tile = isoScene.getTileAt(mouseX - scene.x, mouseY - scene.y);
+// { x: 5, y: 3 }
+```
+
+**Parameters:**
+- `screenX` (number): Screen X relative to scene center
+- `screenY` (number): Screen Y relative to scene center
+
+**Returns:** `{ x: number, y: number }`
+
+### getDepthScale(y)
+
+Calculates scale factor for perspective effect based on Y position.
+
+```javascript
+const scale = isoScene.getDepthScale(5);
+// 1.0 (range: 0.7 to 1.3)
+```
+
+**Parameters:**
+- `y` (number): Grid Y position
+
+**Returns:** `number` (scale factor)
+
+## Depth Sorting
+
+When `depthSort` is enabled (default), children are rendered in back-to-front order based on:
+
+1. **zIndex** (primary): Higher zIndex renders on top
+2. **Isometric depth** (secondary): Calculated as `x + y - z * 0.01`
+
+Objects further back (lower x + y values) render first, allowing closer objects to overlap them correctly.
+
+```javascript
+// Force an object to render behind/in front
+myObject.zIndex = -1;  // Render behind others
+myObject.zIndex = 10;  // Render on top
+```
+
+## Working with Children
+
+### Grid-Based GameObjects
+
+Children added to IsometricScene use grid coordinates:
+
+```javascript
+class Tile extends GameObject {
+  constructor(game, gridX, gridY) {
+    super(game);
+    this.x = gridX;  // Grid coordinate, not pixels
+    this.y = gridY;
+    this.z = 0;      // Ground level
+  }
+
+  render() {
+    // Render at local origin - scene handles projection
+    Painter.shapes.fillRect(-16, -8, 32, 16, "#8B4513");
+  }
+}
+```
+
+### Manual Projection
+
+For complex rendering (shadows, effects), access the scene's projection:
+
+```javascript
+class Ball extends GameObject {
+  render() {
+    // Get projected position for manual drawing
+    const pos = this.parent.toIsometric(this.x, this.y, 0);
+    const elevation = this.z * 0.7;
+
+    // Draw shadow at ground level
+    Painter.shapes.fillCircle(pos.x, pos.y, 10, "rgba(0,0,0,0.3)");
+
+    // Draw ball at elevated position
+    Painter.shapes.fillCircle(pos.x, pos.y - elevation, 10, "blue");
+  }
+}
+```
+
+## Example: Tile Map
+
+```javascript
+class TileMap extends GameObject {
+  constructor(game, isoScene) {
+    super(game);
+    this.isoScene = isoScene;
+    this.tiles = [
+      [1, 1, 1, 1, 1],
+      [1, 0, 0, 0, 1],
+      [1, 0, 2, 0, 1],
+      [1, 0, 0, 0, 1],
+      [1, 1, 1, 1, 1],
+    ];
+    this.colors = {
+      0: "#90EE90",  // Grass
+      1: "#8B4513",  // Wall
+      2: "#4169E1",  // Water
+    };
+    this.zIndex = -1;
+  }
+
+  render() {
+    const size = this.tiles.length;
+    const halfW = this.isoScene.tileWidth / 2;
+    const halfH = this.isoScene.tileHeight / 2;
+
+    for (let y = 0; y < size; y++) {
+      for (let x = 0; x < size; x++) {
+        const tileType = this.tiles[y][x];
+        const pos = this.isoScene.toIsometric(x - size/2, y - size/2);
+
+        // Draw diamond tile
+        Painter.useCtx((ctx) => {
+          ctx.beginPath();
+          ctx.moveTo(pos.x, pos.y - halfH);
+          ctx.lineTo(pos.x + halfW, pos.y);
+          ctx.lineTo(pos.x, pos.y + halfH);
+          ctx.lineTo(pos.x - halfW, pos.y);
+          ctx.closePath();
+          ctx.fillStyle = this.colors[tileType];
+          ctx.fill();
+          ctx.strokeStyle = "#000";
+          ctx.lineWidth = 1;
+          ctx.stroke();
+        });
+      }
+    }
+  }
+}
+```
+
+## Example: Mouse Picking
+
+```javascript
+class PickableGrid extends IsometricScene {
+  constructor(game, options) {
+    super(game, { ...options, interactive: true });
+    this.hoveredTile = null;
+  }
+
+  onMouseMove(e) {
+    // Convert screen position to scene-local coordinates
+    const localX = e.clientX - this.x;
+    const localY = e.clientY - this.y;
+
+    // Get tile at mouse position
+    this.hoveredTile = this.getTileAt(localX, localY);
+  }
+}
+```
+
+## See Also
+
+- [Scene](./scene.md) - Base container class
+- [Scene3D](./scene3d.md) - Camera-based 3D projection
+- [Rendering Pipeline](../concepts/rendering-pipeline.md) - How rendering works

package/docs/modules/painter/README.md

@@ -0,0 +1,328 @@
+# Painter Module
+
+> Low-level canvas drawing abstraction.
+
+## Overview
+
+Painter is a static utility class that wraps the Canvas 2D API. It provides centralized drawing operations and state management, used internally by all shapes.
+
+## Quick Start
+
+```js
+import { Painter } from 'gcanvas';
+
+// Initialize with canvas context
+const canvas = document.getElementById('canvas');
+Painter.init(canvas.getContext('2d'));
+
+// Draw shapes directly
+Painter.shapes.fillCircle(200, 150, 50, 'red');
+Painter.shapes.strokeRect(300, 100, 100, 80, 'blue', 2);
+
+// Draw text
+Painter.text.fill('Hello World', 400, 200, {
+  font: '24px monospace',
+  color: 'white'
+});
+```
+
+## Architecture
+
+Painter is composed of specialized sub-modules:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Painter                              │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   shapes    │  │    text     │  │   lines     │         │
+│  │ fillCircle  │  │    fill     │  │   line      │         │
+│  │ strokeRect  │  │   stroke    │  │  polyline   │         │
+│  │    arc      │  │  measure    │  │   bezier    │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   colors    │  │   opacity   │  │   effects   │         │
+│  │    fill     │  │    push     │  │ setBlendMode│         │
+│  │   stroke    │  │    pop      │  │   shadow    │         │
+│  │  gradient   │  │   current   │  │   filter    │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│                                                             │
+│  ┌─────────────┐                                            │
+│  │    img      │                                            │
+│  │   draw      │                                            │
+│  │   crop      │                                            │
+│  │  pattern    │                                            │
+│  └─────────────┘                                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core API
+
+### Initialization
+
+```js
+Painter.init(ctx);           // Set the canvas context
+const ctx = Painter.ctx;     // Get the context
+```
+
+### Canvas State
+
+```js
+Painter.save();              // Save canvas state
+Painter.restore();           // Restore canvas state
+Painter.clear();             // Clear entire canvas
+Painter.clear(x, y, w, h);   // Clear rectangle
+```
+
+### Transforms
+
+```js
+Painter.translateTo(x, y);   // Move origin
+Painter.rotate(radians);     // Rotate context
+Painter.scale(sx, sy);       // Scale context
+```
+
+## Sub-Modules
+
+### Painter.shapes
+
+Drawing geometric shapes.
+
+```js
+// Circles
+Painter.shapes.fillCircle(x, y, radius, color);
+Painter.shapes.strokeCircle(x, y, radius, color, lineWidth);
+
+// Rectangles
+Painter.shapes.fillRect(x, y, width, height, color);
+Painter.shapes.strokeRect(x, y, width, height, color, lineWidth);
+
+// Rounded rectangles
+Painter.shapes.fillRoundedRect(x, y, w, h, radius, color);
+Painter.shapes.strokeRoundedRect(x, y, w, h, radius, color, lineWidth);
+
+// Arcs
+Painter.shapes.arc(x, y, radius, startAngle, endAngle, color);
+```
+
+### Painter.text
+
+Text rendering and measurement.
+
+```js
+// Fill text
+Painter.text.fill(text, x, y, {
+  font: '16px Arial',
+  color: 'white',
+  align: 'center',      // left, center, right
+  baseline: 'middle'    // top, middle, bottom
+});
+
+// Stroke text
+Painter.text.stroke(text, x, y, {
+  font: '24px Arial',
+  color: 'black',
+  lineWidth: 2
+});
+
+// Measure text
+const metrics = Painter.text.measure(text, font);
+console.log(metrics.width);
+```
+
+### Painter.lines
+
+Line and path drawing.
+
+```js
+// Simple line
+Painter.lines.line(x1, y1, x2, y2, color, lineWidth);
+
+// Polyline
+Painter.lines.polyline([
+  { x: 0, y: 0 },
+  { x: 100, y: 50 },
+  { x: 200, y: 25 }
+], color, lineWidth);
+
+// Bezier curve
+Painter.lines.bezier(
+  x1, y1,           // Start
+  cp1x, cp1y,       // Control point 1
+  cp2x, cp2y,       // Control point 2
+  x2, y2,           // End
+  color, lineWidth
+);
+```
+
+### Painter.colors
+
+Fill and stroke color management.
+
+```js
+// Set fill style
+Painter.colors.fill(color);
+
+// Set stroke style
+Painter.colors.stroke(color, lineWidth);
+
+// Create gradient
+const gradient = Painter.colors.linearGradient(x1, y1, x2, y2, stops);
+// stops: [{ offset: 0, color: 'red' }, { offset: 1, color: 'blue' }]
+
+const radial = Painter.colors.radialGradient(x, y, r1, r2, stops);
+```
+
+### Painter.opacity
+
+Opacity stack management.
+
+```js
+// Push new opacity (multiplies with current)
+Painter.opacity.pushOpacity(0.5);
+
+// Drawing here is 50% transparent
+
+// Pop to restore previous
+Painter.opacity.popOpacity();
+
+// Get current effective opacity
+const current = Painter.opacity.currentOpacity;
+```
+
+### Painter.effects
+
+Visual effects.
+
+```js
+// Blend modes
+Painter.effects.setBlendMode('multiply');
+Painter.effects.setBlendMode('screen');
+Painter.effects.setBlendMode('source-over'); // default
+
+// Shadow
+Painter.effects.shadow(color, blur, offsetX, offsetY);
+Painter.effects.clearShadow();
+```
+
+### Painter.img
+
+Image drawing.
+
+```js
+// Draw image
+Painter.img.draw(image, x, y);
+Painter.img.draw(image, x, y, width, height);
+
+// Draw cropped
+Painter.img.drawCropped(
+  image,
+  sx, sy, sw, sh,   // Source rectangle
+  dx, dy, dw, dh    // Destination rectangle
+);
+
+// Create pattern
+const pattern = Painter.img.createPattern(image, 'repeat');
+```
+
+## Usage Patterns
+
+### Direct Drawing (No Shapes)
+
+```js
+Painter.init(ctx);
+
+function draw() {
+  Painter.clear();
+
+  // Draw background
+  Painter.shapes.fillRect(0, 0, 800, 600, '#1a1a2e');
+
+  // Draw shapes
+  Painter.shapes.fillCircle(400, 300, 50, 'red');
+
+  // Draw text
+  Painter.text.fill('Score: 100', 10, 30, {
+    font: '20px Arial',
+    color: 'white'
+  });
+}
+```
+
+### With State Management
+
+```js
+Painter.save();
+Painter.translateTo(400, 300);
+Painter.rotate(Math.PI / 4);
+Painter.shapes.fillRect(-50, -25, 100, 50, 'blue');
+Painter.restore();
+```
+
+### Opacity Stacking
+
+```js
+Painter.opacity.pushOpacity(0.8);
+  // 80% opacity
+  Painter.shapes.fillCircle(100, 100, 50, 'red');
+
+  Painter.opacity.pushOpacity(0.5);
+    // 40% opacity (0.8 * 0.5)
+    Painter.shapes.fillCircle(150, 100, 50, 'blue');
+  Painter.opacity.popOpacity();
+
+  // Back to 80%
+  Painter.shapes.fillCircle(200, 100, 50, 'green');
+Painter.opacity.popOpacity();
+```
+
+## When to Use Painter Directly
+
+Most of the time, use Shape classes. Use Painter directly when:
+
+- Drawing one-off graphics
+- Custom shape implementations
+- Performance-critical drawing
+- Procedural graphics
+- Effects not supported by shapes
+
+## Example: Custom Shape
+
+```js
+class Diamond extends Shape {
+  draw() {
+    super.draw();  // Apply transforms
+
+    const hw = this.width / 2;
+    const hh = this.height / 2;
+
+    Painter.ctx.beginPath();
+    Painter.ctx.moveTo(0, -hh);
+    Painter.ctx.lineTo(hw, 0);
+    Painter.ctx.lineTo(0, hh);
+    Painter.ctx.lineTo(-hw, 0);
+    Painter.ctx.closePath();
+
+    if (this.color) {
+      Painter.colors.fill(this.color);
+      Painter.ctx.fill();
+    }
+
+    if (this.stroke) {
+      Painter.colors.stroke(this.stroke, this.lineWidth);
+      Painter.ctx.stroke();
+    }
+  }
+}
+```
+
+## Related
+
+- [Shapes Module](../shapes/README.md) - High-level shape classes
+- [Rendering Pipeline](../../concepts/rendering-pipeline.md) - How shapes use Painter
+
+## See Also
+
+- [Hello World](../../getting-started/hello-world.md)
+- [Architecture Overview](../../concepts/architecture-overview.md)