@guinetik/gcanvas 1.0.0

package/types/common.d.ts

@@ -0,0 +1,155 @@
+/**
+ * GCanvas Common Types
+ * Shared interfaces and types used across all modules.
+ * @module common
+ */
+
+// ==========================================================================
+// Basic Geometric Types
+// ==========================================================================
+
+/** 2D point/position */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** Bounding box representing position and dimensions */
+export interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+// ==========================================================================
+// Animation & Easing Types
+// ==========================================================================
+
+/** Easing function type - takes normalized time (0-1) and returns eased value */
+export type EasingFunction = (t: number) => number;
+
+/** Event callback type */
+export type EventCallback<T = any> = (payload?: T) => void;
+
+/** Callbacks for Motion animation methods */
+export interface MotionCallbacks {
+  /** Called when animation starts */
+  onStart?: () => void;
+  /** Called when animation completes (non-looping only) */
+  onComplete?: () => void;
+  /** Called when animation loops, receives loop count */
+  onLoop?: (loopCount: number) => void;
+  /** Called each frame with current progress */
+  onUpdate?: (progress: number) => void;
+}
+
+/** Internal state tracking for Motion animations */
+export interface MotionState {
+  /** Whether onStart has been called */
+  started: boolean;
+  /** Current loop count */
+  loopCount: number;
+  /** Whether animation has completed */
+  completed?: boolean;
+  /** Animation-specific state data */
+  [key: string]: any;
+}
+
+/** Result object returned by Motion animation methods */
+export interface MotionResult {
+  /** Normalized time (0-1) */
+  t: number;
+  /** Alias for normalized time */
+  progress: number;
+  /** Whether animation is looping */
+  loop: boolean;
+  /** Whether animation has completed (non-looping only) */
+  completed: boolean;
+  /** Internal state for the next call */
+  state: MotionState | null;
+  /** Animation-specific values (x, y, value, etc.) */
+  [key: string]: any;
+}
+
+/** Result with position coordinates */
+export interface MotionPositionResult extends MotionResult {
+  x: number;
+  y: number;
+}
+
+/** Result with a single value */
+export interface MotionValueResult extends MotionResult {
+  value: number;
+}
+
+/** Result from spring animation */
+export interface SpringResult extends MotionResult {
+  value: number;
+  velocity: number;
+}
+
+/** Result from waypoint animation */
+export interface WaypointResult extends MotionPositionResult {
+  /** Whether currently moving between waypoints */
+  moving: boolean;
+  /** Current direction of movement */
+  direction: string;
+  /** Index of current waypoint */
+  waypointIndex: number;
+}
+
+// ==========================================================================
+// Layout Types
+// ==========================================================================
+
+/** Options for layout functions */
+export interface LayoutOptions {
+  /** Horizontal spacing between items */
+  spacing?: number;
+  /** Starting X position */
+  x?: number;
+  /** Starting Y position */
+  y?: number;
+  /** Number of columns (for tile/grid layouts) */
+  columns?: number;
+  /** Number of rows (for grid layout) */
+  rows?: number;
+  /** Cell width (for grid layout) */
+  cellWidth?: number;
+  /** Cell height (for grid layout) */
+  cellHeight?: number;
+}
+
+/** Result returned by layout functions */
+export interface LayoutResult {
+  /** Calculated positions for each object */
+  positions: Point[];
+  /** Total width of the layout */
+  width: number;
+  /** Total height of the layout */
+  height: number;
+}
+
+// ==========================================================================
+// Penrose Tiling Types
+// ==========================================================================
+
+/** RGBA color as 4-element array [R, G, B, A] with values 0-255 */
+export type RGBAColor = [number, number, number, number];
+
+/** Options for Penrose tiling generation */
+export interface PenroseTilingOptions {
+  /** Number of subdivision iterations (default: 5) */
+  divisions?: number;
+  /** Zoom type: "in" or "out" (default: "in") */
+  zoomType?: 'in' | 'out';
+  /** Color for thin rhombi (default: red) */
+  color1?: RGBAColor;
+  /** Color for thick rhombi (default: blue) */
+  color2?: RGBAColor;
+  /** Color for outlines (default: black) */
+  color3?: RGBAColor;
+  /** Background color (default: white) */
+  backgroundColor?: RGBAColor;
+}

package/types/game.d.ts

@@ -0,0 +1,497 @@
+/**
+ * GCanvas Game Module
+ * Core game loop, pipeline, game objects, scenes, and UI components.
+ * @module game
+ */
+
+import { Bounds, Point, EventCallback } from './common';
+import { Logger } from './logger';
+import { Transformable, TransformableOptions, Shape } from './shapes';
+import { EventEmitter } from './io';
+
+// ==========================================================================
+// Game Class
+// ==========================================================================
+
+/**
+ * Core game class providing game loop, pipeline, and input management.
+ * Entry point for creating interactive canvas applications.
+ *
+ * @example
+ * const canvas = document.getElementById('game');
+ * const game = new Game(canvas);
+ * game.init();
+ * game.start();
+ */
+export class Game {
+  /** The canvas element */
+  canvas: HTMLCanvasElement;
+  /** The 2D rendering context */
+  ctx: CanvasRenderingContext2D;
+  /** Event emitter for game events */
+  events: EventEmitter;
+  /** Pipeline for managing game objects */
+  pipeline: Pipeline;
+  /** Whether the game loop is running */
+  running: boolean;
+  /** Delta time since last frame (seconds) */
+  dt: number;
+  /** Target frames per second */
+  targetFPS: number;
+  /** Actual measured FPS */
+  actualFps: number;
+  /** Logger instance */
+  logger: Logger;
+
+  /**
+   * Create a new Game instance.
+   * @param canvas - The canvas element to render to
+   */
+  constructor(canvas: HTMLCanvasElement);
+
+  /** Canvas width */
+  get width(): number;
+  /** Canvas height */
+  get height(): number;
+  /** Background color (set only) */
+  set backgroundColor(color: string);
+  /** Custom cursor (get/set) */
+  get cursor(): Cursor;
+  set cursor(cursor: Cursor);
+  /** Whether bounds need recalculation */
+  get boundsDirty(): boolean;
+  set boundsDirty(dirty: boolean);
+
+  /** Initialize the game (called automatically by constructor) */
+  init(): void;
+  /** Start the game loop */
+  start(): void;
+  /** Stop the game loop */
+  stop(): void;
+  /** Restart the game (stop and start) */
+  restart(): void;
+  /** Clear the canvas */
+  clear(): void;
+  /** Update game state (called each frame) */
+  update(dt: number): void;
+  /** Render the game (called each frame) */
+  render(): void;
+
+  // Input initialization
+  /** Initialize mouse input */
+  initMouse(): void;
+  /** Initialize touch input */
+  initTouch(): void;
+  /** Initialize unified input (mouse + touch) */
+  initInput(): void;
+  /** Initialize keyboard input */
+  initKeyboard(): void;
+  /** Initialize all input systems */
+  initIO(): void;
+  /** Initialize motion/animation system */
+  initMotion(): void;
+  /** Initialize logging */
+  initLogging(): void;
+
+  /** Enable debug logging */
+  enableLogging(): void;
+  /** Disable debug logging */
+  disableLogging(): void;
+
+  /**
+   * Enable fluid canvas sizing (resizes with container).
+   * @param container - Container element (default: window)
+   */
+  enableFluidSize(container?: HTMLElement | Window): void;
+  /** Disable fluid sizing */
+  disableFluidSize(): void;
+
+  /**
+   * Enable/disable pausing when window loses focus.
+   * @param enabled - Whether to pause on blur
+   */
+  enablePauseOnBlur(enabled: boolean): void;
+
+  /**
+   * Set target frame rate.
+   * @param fps - Target FPS
+   */
+  setFPS(fps: number): void;
+
+  /** Mark that bounds need recalculation */
+  markBoundsDirty(): void;
+  /** Reset to default cursor */
+  resetCursor(): void;
+
+  /** Override for custom resize handling */
+  onResize?(): void;
+}
+
+// ==========================================================================
+// Pipeline
+// ==========================================================================
+
+/**
+ * Pipeline for managing GameObjects lifecycle.
+ * Handles update and render cycles for all registered objects.
+ */
+export class Pipeline {
+  /**
+   * Create a new Pipeline.
+   * @param game - The game instance
+   */
+  constructor(game: Game);
+
+  /**
+   * Add a game object to the pipeline.
+   * @param object - GameObject to add
+   */
+  add(object: GameObject): void;
+
+  /**
+   * Remove a game object from the pipeline.
+   * @param object - GameObject to remove
+   */
+  remove(object: GameObject): void;
+
+  /** Remove all objects from the pipeline */
+  clear(): void;
+
+  /**
+   * Update all objects.
+   * @param dt - Delta time
+   */
+  update(dt: number): void;
+
+  /** Render all objects */
+  render(): void;
+}
+
+// ==========================================================================
+// GameObject
+// ==========================================================================
+
+/** Options for GameObject */
+export interface GameObjectOptions extends TransformableOptions {
+  /** Whether object responds to input events */
+  interactive?: boolean;
+  /** Screen anchor position (e.g., "top-left", "center") */
+  anchor?: string | Point;
+}
+
+/**
+ * Base class for interactive game entities.
+ * Extends Transformable with events and hit testing.
+ *
+ * @example
+ * const player = new GameObject(game, {
+ *   x: 100, y: 100,
+ *   width: 50, height: 50,
+ *   interactive: true
+ * });
+ * player.on('click', () => console.log('Player clicked!'));
+ */
+export class GameObject extends Transformable {
+  /** Reference to the game instance */
+  game: Game;
+  /** Event emitter for this object */
+  events: EventEmitter;
+
+  /**
+   * Create a new GameObject.
+   * @param game - The game instance
+   * @param options - Configuration options
+   */
+  constructor(game: Game, options?: GameObjectOptions);
+
+  /** Whether object responds to input */
+  get interactive(): boolean;
+  set interactive(value: boolean);
+  /** Whether pointer is over this object */
+  get hovered(): boolean;
+  set hovered(value: boolean);
+
+  /** Update the object (override in subclasses) */
+  update(dt: number): void;
+
+  /**
+   * Subscribe to an event.
+   * @param event - Event name
+   * @param callback - Handler function
+   */
+  on<T = any>(event: string, callback: EventCallback<T>): void;
+
+  /**
+   * Unsubscribe from an event.
+   * @param event - Event name
+   * @param callback - Handler function
+   */
+  off<T = any>(event: string, callback: EventCallback<T>): void;
+
+  /**
+   * Emit an event.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  emit<T = any>(event: string, ...args: any[]): void;
+
+  /** @internal Test if point is inside object bounds */
+  _hitTest(x: number, y: number): boolean;
+  /** @internal Set hover state */
+  _setHovered(state: boolean): void;
+}
+
+// ==========================================================================
+// Scene
+// ==========================================================================
+
+/** Options for Scene */
+export interface SceneOptions extends GameObjectOptions {
+  /** Sort children by zIndex before rendering */
+  sortByZIndex?: boolean;
+}
+
+/**
+ * Hierarchical container for GameObjects with z-ordering.
+ * Use scenes to group related objects and manage their lifecycle.
+ *
+ * @example
+ * const uiScene = new Scene(game, { x: 0, y: 0 });
+ * uiScene.add(new Button(game, { label: 'Start' }));
+ * game.pipeline.add(uiScene);
+ */
+export class Scene extends GameObject {
+  /**
+   * Create a new Scene.
+   * @param game - The game instance
+   * @param options - Configuration options
+   */
+  constructor(game: Game, options?: SceneOptions);
+
+  /** Get all child objects */
+  get children(): GameObject[];
+
+  /**
+   * Add a child object.
+   * @param object - GameObject to add
+   * @returns The added object
+   */
+  add(object: GameObject): GameObject;
+
+  /**
+   * Remove a child object.
+   * @param object - GameObject to remove
+   * @returns Whether object was found and removed
+   */
+  remove(object: GameObject): boolean;
+
+  /** Remove all children */
+  clear(): void;
+
+  /** Move object to front (highest z-order) */
+  bringToFront(object: GameObject): void;
+
+  /** Move object to back (lowest z-order) */
+  sendToBack(object: GameObject): void;
+}
+
+// ==========================================================================
+// Shape Wrappers
+// ==========================================================================
+
+/**
+ * Wraps a Shape as a GameObject for use in the pipeline.
+ * Allows using pure shapes in the game object system.
+ */
+export class GameObjectShapeWrapper extends GameObject {
+  /** The wrapped shape */
+  shape: Shape;
+
+  /**
+   * Create a wrapper for a shape.
+   * @param game - The game instance
+   * @param shape - Shape to wrap
+   * @param options - Additional options
+   */
+  constructor(game: Game, shape: Shape, options?: GameObjectOptions);
+}
+
+/**
+ * Factory for quickly creating GameObject wrappers for shapes.
+ */
+export class ShapeGOFactory {
+  /**
+   * Wrap a shape as a GameObject.
+   * @param game - The game instance
+   * @param shape - Shape to wrap
+   * @param options - Additional options
+   */
+  static wrap(game: Game, shape: Shape, options?: GameObjectOptions): GameObjectShapeWrapper;
+}
+
+// ==========================================================================
+// Text GameObject
+// ==========================================================================
+
+/** Options for Text GameObject */
+export interface TextGameObjectOptions extends GameObjectOptions {
+  /** CSS font string */
+  font?: string;
+  /** Text alignment */
+  align?: CanvasTextAlign;
+  /** Text baseline */
+  baseline?: CanvasTextBaseline;
+  /** Text color */
+  color?: string;
+}
+
+/**
+ * Text rendering as a GameObject.
+ */
+export class Text extends GameObject {
+  /** The text content */
+  text: string;
+
+  /**
+   * Create a Text object.
+   * @param game - The game instance
+   * @param text - Text to display
+   * @param options - Text options
+   */
+  constructor(game: Game, text: string, options?: TextGameObjectOptions);
+}
+
+// ==========================================================================
+// Image GameObject
+// ==========================================================================
+
+/**
+ * Image rendering as a GameObject.
+ */
+export class ImageGo extends GameObject {
+  /**
+   * Create an Image object.
+   * @param game - The game instance
+   * @param src - Image source URL or HTMLImageElement
+   * @param options - GameObject options
+   */
+  constructor(game: Game, src: string | HTMLImageElement, options?: GameObjectOptions);
+}
+
+// ==========================================================================
+// Layout Scenes
+// ==========================================================================
+
+/**
+ * Base layout container with automatic child positioning.
+ */
+export class LayoutScene extends Scene {
+  constructor(game: Game, options?: SceneOptions);
+}
+
+/**
+ * Horizontal layout - children arranged left to right.
+ */
+export class HorizontalLayout extends LayoutScene {
+  constructor(game: Game, options?: SceneOptions);
+}
+
+/**
+ * Vertical layout - children arranged top to bottom.
+ */
+export class VerticalLayout extends LayoutScene {
+  constructor(game: Game, options?: SceneOptions);
+}
+
+/**
+ * Tile layout - children arranged in a grid.
+ */
+export class TileLayout extends LayoutScene {
+  constructor(game: Game, options?: SceneOptions);
+}
+
+/**
+ * Flexible grid layout with configurable rows and columns.
+ */
+export class GridLayout extends LayoutScene {
+  constructor(game: Game, options?: SceneOptions);
+}
+
+// ==========================================================================
+// UI Components
+// ==========================================================================
+
+/** Options for Button */
+export interface ButtonOptions extends GameObjectOptions {
+  /** Button text */
+  label?: string;
+  /** CSS font string */
+  font?: string;
+  /** Padding around text */
+  padding?: number;
+  /** Background color (normal state) */
+  backgroundColor?: string;
+  /** Background color (hover state) */
+  hoverColor?: string;
+  /** Background color (pressed state) */
+  pressedColor?: string;
+  /** Text color */
+  textColor?: string;
+}
+
+/**
+ * Interactive button component.
+ *
+ * @example
+ * const btn = new Button(game, {
+ *   x: 100, y: 100,
+ *   label: 'Click Me',
+ *   backgroundColor: '#3498db'
+ * });
+ * btn.on('click', () => console.log('Button clicked!'));
+ */
+export class Button extends GameObject {
+  /** Button label text */
+  label: string;
+
+  constructor(game: Game, options?: ButtonOptions);
+}
+
+/**
+ * Toggle button component (on/off state).
+ */
+export class ToggleButton extends Button {
+  /** Current toggle state */
+  toggled: boolean;
+
+  constructor(game: Game, options?: ButtonOptions);
+}
+
+/** Options for Cursor */
+export interface CursorOptions extends GameObjectOptions {
+  /** Cursor image */
+  image?: HTMLImageElement | string;
+  /** Hotspot offset from cursor position */
+  hotspot?: Point;
+}
+
+/**
+ * Custom cursor component.
+ * Hides the system cursor and renders a custom one.
+ */
+export class Cursor extends GameObject {
+  constructor(game: Game, options?: CursorOptions);
+
+  /** Activate this cursor (hide system cursor) */
+  activate(): void;
+  /** Destroy and restore system cursor */
+  destroy(): void;
+}
+
+/**
+ * FPS counter display component.
+ * Shows real-time frame rate.
+ */
+export class FPSCounter extends GameObject {
+  constructor(game: Game, options?: GameObjectOptions);
+}