@guinetik/gcanvas 1.0.0

package/docs/modules/game/README.md

@@ -0,0 +1,303 @@
+# 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 '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 '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

@@ -0,0 +1,210 @@
+# 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 '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 '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