@guinetik/gcanvas 1.0.2 → 1.0.4

package/docs/modules/isometric.md

@@ -1,275 +0,0 @@
-# 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 "@guinetik/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

@@ -1,328 +0,0 @@
-# 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 '@guinetik/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)