@guinetik/gcanvas 1.0.2 → 1.0.4

package/docs/modules/game/README.md

@@ -1,303 +0,0 @@
-# Game Module
-
-> Core game loop, Pipeline, GameObjects, and Scenes.
-
-## Overview
-
-The game module provides the interactive layer of GCanvas. It manages the game loop, object lifecycle, input handling, and scene organization.
-
-## Quick Start
-
-```js
-import { Game, Scene, GameObject, Circle } from '@guinetik/gcanvas';
-
-class Player extends GameObject {
-  constructor(game) {
-    super(game);
-    this.shape = new Circle(30, { color: 'blue' });
-    this.enableInteractivity(this.shape);
-  }
-
-  update(dt) {
-    if (this.game.input.isKeyDown('ArrowRight')) {
-      this.shape.x += 200 * dt;
-    }
-  }
-
-  render() {
-    this.shape.draw();
-  }
-}
-
-class MyGame extends Game {
-  init() {
-    super.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();
-```
-
-## Core Classes
-
-| Class | Description |
-|-------|-------------|
-| **Game** | Main loop, canvas management, input initialization |
-| **Pipeline** | Manages object collections, update/render dispatch |
-| **GameObject** | Base class for interactive entities |
-| **Scene** | Hierarchical container for GameObjects |
-
-## Game Class
-
-The entry point for interactive applications.
-
-```js
-class MyGame extends Game {
-  constructor(canvas) {
-    super(canvas);
-    this.enableFluidSize();      // Canvas fills viewport
-    this.backgroundColor = '#1a1a2e';
-  }
-
-  init() {
-    super.init();                // Initialize input systems
-    // Create scenes and objects
-  }
-
-  update(dt) {
-    super.update(dt);            // Update pipeline
-    // Custom game logic
-  }
-
-  render() {
-    super.render();              // Render pipeline
-    // Custom rendering
-  }
-}
-
-const game = new MyGame(canvas);
-game.setFPS(60);                 // Set target FPS
-game.start();                    // Begin game loop
-```
-
-### Key Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `canvas` | `HTMLCanvasElement` | The canvas element |
-| `ctx` | `CanvasRenderingContext2D` | 2D context |
-| `pipeline` | `Pipeline` | Object manager |
-| `events` | `EventEmitter` | Event system |
-| `width` | `number` | Canvas width |
-| `height` | `number` | Canvas height |
-| `running` | `boolean` | Is loop running? |
-| `dt` | `number` | Last delta time |
-
-### Key Methods
-
-| Method | Description |
-|--------|-------------|
-| `start()` | Begin the game loop |
-| `stop()` | Stop the game loop |
-| `init()` | Initialize game (override) |
-| `update(dt)` | Update logic (override) |
-| `render()` | Render logic (override) |
-| `enableFluidSize()` | Auto-resize to window |
-| `setFPS(fps)` | Set target frame rate |
-| `enablePauseOnBlur(bool)` | Pause when tab loses focus |
-
-## Pipeline Class
-
-Manages collections of objects for update and render.
-
-```js
-// Add objects
-game.pipeline.add(scene);
-game.pipeline.add(gameObject);
-
-// Remove objects
-game.pipeline.remove(object);
-
-// Clear all
-game.pipeline.clear();
-```
-
-Pipeline automatically:
-- Calls `update(dt)` on active objects
-- Calls `render()` on visible objects
-- Sorts by zIndex
-- Dispatches input events
-
-## GameObject Class
-
-Base class for all interactive entities.
-
-```js
-class Enemy extends GameObject {
-  constructor(game) {
-    super(game);
-    this.shape = new Rectangle({ width: 40, height: 40, color: 'red' });
-    this.enableInteractivity(this.shape);
-    this.speed = 100;
-  }
-
-  update(dt) {
-    this.shape.x += this.speed * dt;
-  }
-
-  render() {
-    this.shape.draw();
-  }
-
-  // Input events
-  onPointerDown(e) { }
-  onPointerUp(e) { }
-  onPointerMove(e) { }
-  onMouseOver() { }
-  onMouseOut() { }
-}
-```
-
-### Lifecycle Methods
-
-| Method | When Called |
-|--------|-------------|
-| `update(dt)` | Every frame (if active) |
-| `render()` | Every frame (if visible) |
-| `destroy()` | When removed from pipeline |
-
-### Input Methods
-
-| Method | Event |
-|--------|-------|
-| `onPointerDown(e)` | Click/tap start |
-| `onPointerUp(e)` | Click/tap end |
-| `onPointerMove(e)` | Pointer movement |
-| `onMouseOver()` | Hover enter |
-| `onMouseOut()` | Hover leave |
-
-## Scene Class
-
-Hierarchical container for GameObjects.
-
-```js
-const gameScene = new Scene(game);
-const uiScene = new Scene(game);
-
-// Add objects to scenes
-gameScene.add(player);
-gameScene.add(enemy);
-
-uiScene.add(healthBar);
-uiScene.add(scoreDisplay);
-
-// Add scenes to pipeline (order matters)
-game.pipeline.add(gameScene);  // Rendered first
-game.pipeline.add(uiScene);    // Rendered on top
-```
-
-Scenes provide:
-- Hierarchical organization
-- Coordinate spaces
-- Z-ordering of children
-- Collective transforms
-
-## UI Components
-
-Built on GameObject and Scene:
-
-| Component | Description |
-|-----------|-------------|
-| `Button` | Clickable with visual states |
-| `ToggleButton` | On/off toggle |
-| `Cursor` | Custom cursor |
-| `FPSCounter` | FPS display |
-
-```js
-import { Button, FPSCounter } from '@guinetik/gcanvas';
-
-const button = new Button(game, 'Click Me', {
-  x: 400,
-  y: 300
-});
-
-button.on('click', () => {
-  console.log('Clicked!');
-});
-
-scene.add(button);
-scene.add(new FPSCounter(game, { anchor: 'bottom-right' }));
-```
-
-## Input Access
-
-```js
-// In GameObject or Game
-update(dt) {
-  // Keyboard
-  if (this.game.input.isKeyDown('ArrowLeft')) { }
-  if (this.game.input.isKeyDown('Space')) { }
-  if (this.game.input.isKeyDown('KeyW')) { }
-
-  // Mouse position
-  const mx = this.game.mouse.x;
-  const my = this.game.mouse.y;
-}
-```
-
-## Events
-
-```js
-// Custom events
-game.events.on('player-died', (data) => {
-  console.log('Player died:', data);
-});
-
-game.events.emit('player-died', { score: 100 });
-
-// Remove listener
-game.events.off('player-died', handler);
-```
-
-## Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                         Game                             │
-│  ┌────────────────────────────────────────────────────┐ │
-│  │                     Pipeline                        │ │
-│  │  ┌──────────────────────────────────────────────┐  │ │
-│  │  │                    Scene                      │  │ │
-│  │  │  ┌────────────┐  ┌────────────┐              │  │ │
-│  │  │  │ GameObject │  │ GameObject │  ...         │  │ │
-│  │  │  │  + Shape   │  │  + Shape   │              │  │ │
-│  │  │  └────────────┘  └────────────┘              │  │ │
-│  │  └──────────────────────────────────────────────┘  │ │
-│  └────────────────────────────────────────────────────┘ │
-│                           │                              │
-│                           ▼                              │
-│                    ┌────────────┐                        │
-│                    │ Game Loop  │                        │
-│                    │ update(dt) │                        │
-│                    │ render()   │                        │
-│                    └────────────┘                        │
-└─────────────────────────────────────────────────────────┘
-```
-
-## Related
-
-- [Game Lifecycle](../../concepts/lifecycle.md) - Update/render cycle
-- [Two-Layer Architecture](../../concepts/two-layer-architecture.md) - Shape vs Game layer
-- [First Game Guide](../../getting-started/first-game.md)
-
-## See Also
-
-- [Shapes Module](../shapes/README.md)
-- [IO Module](../io/README.md) - Input handling
-- [Motion Module](../motion/README.md) - Animation

package/docs/modules/isometric-camera.md

@@ -1,210 +0,0 @@
-# IsometricCamera
-
-A camera for isometric views with step-based rotation and smooth animation.
-
-Unlike `Camera3D` which provides free 3D rotation, `IsometricCamera` is designed for isometric games where the view rotates in fixed increments (e.g., 45° or 90°), similar to classic games like SimCity or Age of Empires.
-
-## Features
-
-- **Step-based rotation** - Rotate in fixed increments (default 45°)
-- **Smooth animation** - Animated transitions between angles with easing
-- **Easy integration** - Works seamlessly with `IsometricScene`
-- **Multiple easing options** - Choose from various easing functions
-- **Callbacks** - Get notified when rotation starts/ends
-
-## Basic Usage
-
-```javascript
-import { IsometricCamera, IsometricScene } from '@guinetik/gcanvas';
-
-// Create camera with 90° rotation steps (recommended for isometric)
-const camera = new IsometricCamera({
-  rotationStep: Math.PI / 2,  // 90 degrees (default)
-  animationDuration: 0.5      // 500ms transition
-});
-
-// Create scene with camera attached
-const scene = new IsometricScene(game, {
-  x: game.width / 2,
-  y: game.height / 2,
-  camera: camera
-});
-
-// Rotate the view
-camera.rotateRight(); // Rotate 45° clockwise
-camera.rotateLeft();  // Rotate 45° counter-clockwise
-```
-
-## Constructor Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `angle` | number | `0` | Initial viewing angle in radians |
-| `rotationStep` | number | `Math.PI / 2` | Rotation step size (default 90°). Use 90° for proper isometric look. |
-| `animationDuration` | number | `0.4` | Transition duration in seconds |
-| `easing` | string | `'easeInOutCubic'` | Easing function name |
-
-> **Note:** 45° rotation steps can cause visual flattening at certain angles due to how isometric projection works. 90° steps are recommended for the best visual results (like SimCity, Age of Empires).
-
-## Available Easing Functions
-
-- `linear` - No easing
-- `easeInQuad`, `easeOutQuad`, `easeInOutQuad` - Quadratic
-- `easeInCubic`, `easeOutCubic`, `easeInOutCubic` - Cubic
-- `easeOutBack` - Overshoot effect
-
-## API Reference
-
-### Methods
-
-#### `rotateRight()`
-Rotate view clockwise by one step. Returns `this` for chaining.
-
-```javascript
-camera.rotateRight(); // Rotate 45° right
-```
-
-#### `rotateLeft()`
-Rotate view counter-clockwise by one step. Returns `this` for chaining.
-
-```javascript
-camera.rotateLeft(); // Rotate 45° left
-```
-
-#### `rotateTo(angle)`
-Rotate to a specific angle (animated).
-
-```javascript
-camera.rotateTo(Math.PI / 2); // Rotate to 90°
-```
-
-#### `setAngle(angle)`
-Set angle immediately (no animation).
-
-```javascript
-camera.setAngle(0); // Jump to 0° instantly
-```
-
-#### `update(dt)`
-Update camera animation. Call each frame with delta time in seconds.
-
-```javascript
-// In your update loop
-camera.update(dt);
-```
-
-> Note: If using with `IsometricScene`, the scene calls this automatically.
-
-#### `isAnimating()`
-Check if camera is currently animating.
-
-```javascript
-if (!camera.isAnimating()) {
-  // Safe to trigger another rotation
-}
-```
-
-#### `getAngleDegrees()`
-Get current angle in degrees (0-360).
-
-#### `getNormalizedAngle()`
-Get angle in radians, normalized to 0-2π range.
-
-#### `reset()`
-Reset camera to angle 0.
-
-### Callbacks
-
-#### `onRotationStart(callback)`
-Set callback for when rotation begins.
-
-```javascript
-camera.onRotationStart((startAngle, targetAngle) => {
-  console.log(`Rotating from ${startAngle} to ${targetAngle}`);
-});
-```
-
-#### `onRotationEnd(callback)`
-Set callback for when rotation completes.
-
-```javascript
-camera.onRotationEnd((finalAngle) => {
-  console.log(`Rotation complete at ${finalAngle}`);
-});
-```
-
-## Integration with IsometricScene
-
-When attached to an `IsometricScene`, the camera's angle is automatically applied to the `toIsometric()` projection:
-
-```javascript
-// Attach camera to scene
-scene.setCamera(camera);
-
-// The scene automatically:
-// 1. Updates the camera each frame
-// 2. Applies camera rotation to all projections
-// 3. Handles depth sorting correctly during rotation
-```
-
-### How It Works
-
-The camera modifies the isometric projection by rotating grid coordinates before projecting:
-
-```javascript
-// Standard isometric projection
-isoX = (x - y) * (tileWidth / 2)
-isoY = (x + y) * (tileHeight / 2)
-
-// With camera rotation
-rotatedX = x * cos(angle) - y * sin(angle)
-rotatedY = x * sin(angle) + y * cos(angle)
-isoX = (rotatedX - rotatedY) * (tileWidth / 2)
-isoY = (rotatedX + rotatedY) * (tileHeight / 2)
-```
-
-## UI Controls Example
-
-Add rotation buttons to your game:
-
-```javascript
-import { Button, Keys } from '@guinetik/gcanvas';
-
-// Arrow buttons
-const leftBtn = new Button(game, {
-  x: 50, y: game.height - 50,
-  width: 50, height: 50,
-  text: "◀",
-  onClick: () => camera.rotateLeft()
-});
-
-const rightBtn = new Button(game, {
-  x: 110, y: game.height - 50,
-  width: 50, height: 50,
-  text: "▶",
-  onClick: () => camera.rotateRight()
-});
-
-game.pipeline.add(leftBtn);
-game.pipeline.add(rightBtn);
-
-// Keyboard controls (Q/E)
-game.events.on(Keys.Q, () => camera.rotateLeft());
-game.events.on(Keys.E, () => camera.rotateRight());
-```
-
-## Why 90° Rotation Steps?
-
-Isometric projection uses the formula:
-- `screenX = (x - y) * tileWidth / 2`
-- `screenY = (x + y) * tileHeight / 2`
-
-At 45° rotation angles (like 45°, 135°, 225°, 315°), the `(x + y)` term can become very small, causing the view to appear flat. At 90° increments (0°, 90°, 180°, 270°), the rotation simply swaps axes, maintaining the proper 3D look.
-
-This is why classic isometric games like SimCity and Age of Empires use 4-direction rotation (90° steps).
-
-## See Also
-
-- [IsometricScene](./isometric.md) - Isometric scene rendering
-- [Camera3D](./camera3d.md) - Free 3D rotation camera
-- [Button](./button.md) - UI buttons