@guinetik/gcanvas 1.0.0

package/docs/getting-started/first-game.md

@@ -0,0 +1,354 @@
+# First Game
+
+> Create an interactive game with the Game layer.
+
+## Overview
+
+This guide shows how to use the Game layer to create interactive applications. We'll build a simple game with keyboard input, collision detection, and animations.
+
+## Basic Game Setup
+
+```js
+import { Game, Scene, GameObject, Circle, Group, Rectangle, TextShape } from 'gcanvas';
+
+class MyGame extends Game {
+  constructor(canvas) {
+    super(canvas);
+    this.enableFluidSize();  // Canvas fills window
+    this.backgroundColor = '#1a1a2e';
+  }
+
+  init() {
+    super.init();  // Initialize input systems
+
+    // Create a scene
+    this.scene = new Scene(this);
+    this.pipeline.add(this.scene);
+
+    // Add game objects
+    this.scene.add(new Player(this));
+  }
+}
+
+// Start the game
+const canvas = document.getElementById('game');
+const game = new MyGame(canvas);
+game.start();
+```
+
+## Creating a Player
+
+```js
+class Player extends GameObject {
+  constructor(game) {
+    super(game);
+
+    // Create the player shape
+    this.shape = new Circle(30, {
+      color: '#4ecdc4',
+      stroke: '#fff',
+      lineWidth: 2
+    });
+
+    // Position at center
+    this.shape.x = game.width / 2;
+    this.shape.y = game.height / 2;
+
+    // Movement speed (pixels per second)
+    this.speed = 300;
+
+    // Enable mouse/touch input on this shape
+    this.enableInteractivity(this.shape);
+  }
+
+  update(dt) {
+    // Handle keyboard input
+    const input = this.game.input;
+
+    if (input.isKeyDown('ArrowLeft') || input.isKeyDown('KeyA')) {
+      this.shape.x -= this.speed * dt;
+    }
+    if (input.isKeyDown('ArrowRight') || input.isKeyDown('KeyD')) {
+      this.shape.x += this.speed * dt;
+    }
+    if (input.isKeyDown('ArrowUp') || input.isKeyDown('KeyW')) {
+      this.shape.y -= this.speed * dt;
+    }
+    if (input.isKeyDown('ArrowDown') || input.isKeyDown('KeyS')) {
+      this.shape.y += this.speed * dt;
+    }
+
+    // Keep player on screen
+    this.shape.x = Math.max(30, Math.min(this.game.width - 30, this.shape.x));
+    this.shape.y = Math.max(30, Math.min(this.game.height - 30, this.shape.y));
+  }
+
+  render() {
+    this.shape.draw();
+  }
+
+  // Called when player is clicked
+  onPointerDown(e) {
+    console.log('Player clicked!');
+  }
+}
+```
+
+## Adding Enemies
+
+```js
+class Enemy extends GameObject {
+  constructor(game, x, y) {
+    super(game);
+
+    this.shape = new Rectangle({
+      x: x,
+      y: y,
+      width: 40,
+      height: 40,
+      color: '#ff6b6b'
+    });
+
+    // Random direction
+    this.vx = (Math.random() - 0.5) * 200;
+    this.vy = (Math.random() - 0.5) * 200;
+  }
+
+  update(dt) {
+    // Move
+    this.shape.x += this.vx * dt;
+    this.shape.y += this.vy * dt;
+
+    // Bounce off walls
+    if (this.shape.x < 20 || this.shape.x > this.game.width - 20) {
+      this.vx *= -1;
+    }
+    if (this.shape.y < 20 || this.shape.y > this.game.height - 20) {
+      this.vy *= -1;
+    }
+
+    // Rotate
+    this.shape.rotation += dt * 2;
+  }
+
+  render() {
+    this.shape.draw();
+  }
+}
+```
+
+## Complete Game Example
+
+Here's a complete game from `demos/js/basic.js`:
+
+```js
+import {
+  Game,
+  GameObject,
+  Scene,
+  Circle,
+  Rectangle,
+  TextShape,
+  Group,
+  Motion,
+  Easing,
+  FPSCounter
+} from 'gcanvas';
+
+/**
+ * HelloWorldBox - A simple animated text box
+ */
+class HelloWorldBox extends GameObject {
+  constructor(game) {
+    super(game);
+
+    // Create a group to hold shapes
+    this.group = new Group({});
+
+    // Background box
+    this.box = new Rectangle({
+      width: 200,
+      height: 80,
+      color: '#333'
+    });
+
+    // Text label
+    this.label = new TextShape('Hello World!', {
+      font: '18px monospace',
+      color: '#0f0',
+      align: 'center',
+      baseline: 'middle'
+    });
+
+    // Add to group
+    this.group.add(this.box);
+    this.group.add(this.label);
+
+    // Animation time
+    this.animTime = 0;
+  }
+
+  update(dt) {
+    this.animTime += dt;
+
+    // Pulse the text opacity
+    const pulse = Motion.pulse(
+      0, 1,           // min, max opacity
+      this.animTime,
+      2,              // 2 second cycle
+      true,           // loop
+      false,          // no yoyo
+      Easing.easeInOutSine
+    );
+    this.label.opacity = pulse.value;
+
+    // Float the group
+    const float = Motion.float(
+      { x: 0, y: 0 },
+      this.animTime,
+      5,              // 5 second cycle
+      0.5,            // speed
+      0.5,            // randomness
+      50,             // radius
+      true,
+      Easing.easeInOutSine
+    );
+    this.group.x = float.x;
+    this.group.y = float.y;
+
+    super.update(dt);
+  }
+
+  render() {
+    this.group.render();
+  }
+}
+
+/**
+ * DemoGame - Main game class
+ */
+class DemoGame extends Game {
+  constructor(canvas) {
+    super(canvas);
+    this.enableFluidSize();
+    this.backgroundColor = 'black';
+  }
+
+  init() {
+    super.init();
+
+    // Create main scene
+    this.gameScene = new Scene(this);
+    this.gameScene.add(new HelloWorldBox(this));
+    this.pipeline.add(this.gameScene);
+
+    // Add orbiting circle
+    this.floatingCircle = new Circle(30, {
+      x: this.width / 2 + 200,
+      y: this.height / 2,
+      color: '#0f0'
+    });
+    this.floatingCircle.animTime = 0;
+    this.pipeline.add(this.floatingCircle);
+
+    // Add FPS counter
+    this.pipeline.add(new FPSCounter(this, {
+      anchor: 'bottom-right'
+    }));
+  }
+
+  update(dt) {
+    super.update(dt);
+
+    // Center the scene
+    this.gameScene.x = this.width / 2;
+    this.gameScene.y = this.height / 2;
+
+    // Orbit the circle
+    this.floatingCircle.animTime += dt;
+    const orbit = Motion.orbit(
+      this.width / 2, this.height / 2,
+      200, 200,       // radius X, Y
+      0,              // start angle
+      this.floatingCircle.animTime,
+      8,              // 8 second orbit
+      true,           // loop
+      true            // clockwise
+    );
+    this.floatingCircle.x = orbit.x;
+    this.floatingCircle.y = orbit.y;
+  }
+}
+
+// Run the game
+window.addEventListener('load', () => {
+  const canvas = document.getElementById('game');
+  const game = new DemoGame(canvas);
+  game.start();
+});
+```
+
+## HTML Template
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>My First Game</title>
+  <style>
+    body { margin: 0; overflow: hidden; }
+    canvas { display: block; }
+  </style>
+</head>
+<body>
+  <canvas id="game"></canvas>
+  <script type="module" src="./game.js"></script>
+</body>
+</html>
+```
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| `Game` | Main class managing loop, canvas, input |
+| `Scene` | Container for GameObjects |
+| `GameObject` | Interactive entity with update/render |
+| `enableInteractivity(shape)` | Enable click/hover on a shape |
+| `dt` | Delta time in seconds |
+| `game.input.isKeyDown(key)` | Check if key is pressed |
+| `Motion.*` | Animation helper functions |
+| `FPSCounter` | Built-in FPS display |
+
+## Input Reference
+
+```js
+// Keyboard
+game.input.isKeyDown('ArrowUp')
+game.input.isKeyDown('KeyW')
+game.input.isKeyDown('Space')
+
+// Mouse position
+game.mouse.x
+game.mouse.y
+
+// GameObject events
+onPointerDown(e) { }
+onPointerUp(e) { }
+onPointerMove(e) { }
+onMouseOver() { }
+onMouseOut() { }
+```
+
+## Next Steps
+
+- [Game Module](../modules/game/README.md) - Full Game API reference
+- [Motion Patterns](../modules/motion/README.md) - Animation functions
+- [Input Handling](../modules/io/README.md) - Mouse, keyboard, touch
+
+## Related
+
+- [Hello World](./hello-world.md)
+- [Two-Layer Architecture](../concepts/two-layer-architecture.md)
+- [Game Lifecycle](../concepts/lifecycle.md)

package/docs/getting-started/hello-world.md

@@ -0,0 +1,269 @@
+# Hello World
+
+> Draw your first shape with GCanvas.
+
+## Overview
+
+This guide shows the simplest way to draw a shape on canvas using GCanvas. We'll start with the Shape Layer (no game loop) and progress to a simple animation.
+
+## Basic Setup
+
+Create an HTML file with a canvas:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>GCanvas Hello World</title>
+  <style>
+    body { margin: 0; background: #000; }
+    canvas { display: block; }
+  </style>
+</head>
+<body>
+  <canvas id="canvas" width="800" height="600"></canvas>
+  <script type="module">
+    // Your code here
+  </script>
+</body>
+</html>
+```
+
+## Step 1: Draw a Circle
+
+```js
+import { Circle, Painter } from './dist/gcanvas.es.min.js';
+
+// Get canvas and initialize Painter
+const canvas = document.getElementById('canvas');
+Painter.init(canvas.getContext('2d'));
+
+// Create a circle
+const circle = new Circle(50, {
+  x: 400,
+  y: 300,
+  color: 'red'
+});
+
+// Draw it
+circle.draw();
+```
+
+**Result:** A red circle with radius 50, centered at (400, 300).
+
+## Step 2: Add More Shapes
+
+```js
+import { Circle, Rectangle, Star, Painter } from './dist/gcanvas.es.min.js';
+
+const canvas = document.getElementById('canvas');
+Painter.init(canvas.getContext('2d'));
+
+// Circle
+const circle = new Circle(50, {
+  x: 200,
+  y: 300,
+  color: '#ff6b6b'
+});
+
+// Rectangle
+const rect = new Rectangle({
+  x: 400,
+  y: 300,
+  width: 120,
+  height: 80,
+  color: '#4ecdc4',
+  stroke: '#fff',
+  lineWidth: 2
+});
+
+// Star
+const star = new Star(40, 5, {
+  x: 600,
+  y: 300,
+  color: '#ffe66d',
+  rotation: Math.PI / 10
+});
+
+// Draw all shapes
+circle.draw();
+rect.draw();
+star.draw();
+```
+
+## Step 3: Group Shapes Together
+
+```js
+import { Circle, Rectangle, TextShape, Group, Painter } from './dist/gcanvas.es.min.js';
+
+const canvas = document.getElementById('canvas');
+Painter.init(canvas.getContext('2d'));
+
+// Create a group
+const group = new Group({ x: 400, y: 300 });
+
+// Add shapes to the group (positions relative to group)
+group.add(new Rectangle({
+  width: 200,
+  height: 80,
+  color: '#333',
+  stroke: '#0f0',
+  lineWidth: 2
+}));
+
+group.add(new TextShape('Hello World!', {
+  font: '24px monospace',
+  color: '#0f0',
+  align: 'center',
+  baseline: 'middle'
+}));
+
+// Draw the group
+group.draw();
+
+// Rotate the entire group
+group.rotation = Math.PI / 12;  // 15 degrees
+Painter.clear();
+group.draw();
+```
+
+## Step 4: Simple Animation
+
+Add a render loop for animation:
+
+```js
+import { Circle, Painter } from './dist/gcanvas.es.min.js';
+
+const canvas = document.getElementById('canvas');
+const ctx = canvas.getContext('2d');
+Painter.init(ctx);
+
+// Create a circle
+const circle = new Circle(50, {
+  x: 400,
+  y: 300,
+  color: '#4ecdc4'
+});
+
+// Animation variables
+let time = 0;
+
+function animate() {
+  // Clear canvas
+  Painter.clear();
+
+  // Update circle position (oscillate)
+  time += 0.02;
+  circle.x = 400 + Math.sin(time) * 200;
+  circle.y = 300 + Math.cos(time * 0.5) * 100;
+
+  // Pulse the opacity
+  circle.opacity = 0.5 + Math.sin(time * 2) * 0.5;
+
+  // Draw
+  circle.draw();
+
+  // Next frame
+  requestAnimationFrame(animate);
+}
+
+// Start animation
+animate();
+```
+
+## Complete Example
+
+Here's a complete example with multiple animated shapes:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>GCanvas Hello World</title>
+  <style>
+    body { margin: 0; background: #1a1a2e; overflow: hidden; }
+    canvas { display: block; }
+  </style>
+</head>
+<body>
+  <canvas id="canvas"></canvas>
+  <script type="module">
+    import { Circle, Rectangle, Star, Group, Painter } from './dist/gcanvas.es.min.js';
+
+    // Setup
+    const canvas = document.getElementById('canvas');
+    canvas.width = window.innerWidth;
+    canvas.height = window.innerHeight;
+    Painter.init(canvas.getContext('2d'));
+
+    const centerX = canvas.width / 2;
+    const centerY = canvas.height / 2;
+
+    // Create shapes
+    const circle = new Circle(60, { color: '#ff6b6b' });
+    const rect = new Rectangle({ width: 100, height: 60, color: '#4ecdc4' });
+    const star = new Star(40, 5, { color: '#ffe66d' });
+
+    let time = 0;
+
+    function animate() {
+      Painter.clear();
+      time += 0.016;
+
+      // Orbit the shapes around center
+      const radius = 150;
+
+      circle.x = centerX + Math.cos(time) * radius;
+      circle.y = centerY + Math.sin(time) * radius;
+
+      rect.x = centerX + Math.cos(time + Math.PI * 0.66) * radius;
+      rect.y = centerY + Math.sin(time + Math.PI * 0.66) * radius;
+      rect.rotation = time;
+
+      star.x = centerX + Math.cos(time + Math.PI * 1.33) * radius;
+      star.y = centerY + Math.sin(time + Math.PI * 1.33) * radius;
+      star.rotation = -time * 2;
+
+      // Draw
+      circle.draw();
+      rect.draw();
+      star.draw();
+
+      requestAnimationFrame(animate);
+    }
+
+    animate();
+
+    // Handle resize
+    window.addEventListener('resize', () => {
+      canvas.width = window.innerWidth;
+      canvas.height = window.innerHeight;
+    });
+  </script>
+</body>
+</html>
+```
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| `Painter.init(ctx)` | Initialize the drawing system with canvas context |
+| `Painter.clear()` | Clear the entire canvas |
+| `shape.draw()` | Draw a shape at its current position |
+| `shape.x`, `shape.y` | Position (center of shape) |
+| `shape.rotation` | Rotation in radians |
+| `shape.opacity` | Transparency (0 to 1) |
+| `Group` | Container for multiple shapes |
+
+## Next Steps
+
+- [First Game](./first-game.md) - Add interactivity with the Game layer
+- [Rendering Pipeline](../concepts/rendering-pipeline.md) - Understand the shape hierarchy
+- [Shapes Module](../modules/shapes/README.md) - Explore all available shapes
+
+## Related
+
+- [Installation](./installation.md)
+- [Two-Layer Architecture](../concepts/two-layer-architecture.md)
+- [Shapes Module](../modules/shapes/README.md)