@guinetik/gcanvas 1.0.0 → 1.0.1

package/types/particle.d.ts

@@ -0,0 +1,373 @@
+/// <reference lib="es2015" />
+
+/**
+ * GCanvas Particle System Module
+ * High-performance particle system with optional Camera3D support.
+ * @module particle
+ */
+
+import { GameObject, GameObjectOptions, Game } from './game';
+
+// ==========================================================================
+// Particle Class
+// ==========================================================================
+
+/** RGBA color object */
+export interface ParticleColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** Particle shape type */
+export type ParticleShape = 'circle' | 'square' | 'triangle';
+
+/**
+ * Lightweight data class for particle systems.
+ * Uses object pooling via reset() to minimize garbage collection.
+ *
+ * @example
+ * const p = new Particle();
+ * p.x = 100;
+ * p.y = 200;
+ * p.vx = 5;
+ * p.lifetime = 2;
+ */
+export class Particle {
+  /** X position */
+  x: number;
+  /** Y position */
+  y: number;
+  /** Z position (for 3D systems) */
+  z: number;
+
+  /** X velocity */
+  vx: number;
+  /** Y velocity */
+  vy: number;
+  /** Z velocity */
+  vz: number;
+
+  /** Particle size */
+  size: number;
+  /** Particle color */
+  color: ParticleColor;
+  /** Particle shape */
+  shape: ParticleShape;
+
+  /** Current age in seconds */
+  age: number;
+  /** Maximum lifetime in seconds */
+  lifetime: number;
+  /** Whether particle is alive */
+  alive: boolean;
+
+  /** Custom data for domain-specific behaviors */
+  custom: Record<string, any>;
+
+  /** Progress through lifetime (0 = born, 1 = about to die) */
+  readonly progress: number;
+
+  constructor();
+
+  /** Reset all properties for object pooling */
+  reset(): void;
+}
+
+// ==========================================================================
+// ParticleEmitter Class
+// ==========================================================================
+
+/** Options for ParticleEmitter */
+export interface ParticleEmitterOptions {
+  /** Emission rate (particles per second) */
+  rate?: number;
+  /** Position X */
+  x?: number;
+  /** Position Y */
+  y?: number;
+  /** Position Z */
+  z?: number;
+  /** Position spread (randomness) */
+  spread?: { x?: number; y?: number; z?: number };
+  /** Initial velocity */
+  velocity?: { x?: number; y?: number; z?: number };
+  /** Velocity spread (randomness) */
+  velocitySpread?: { x?: number; y?: number; z?: number };
+  /** Particle size range [min, max] */
+  size?: [number, number];
+  /** Particle lifetime range [min, max] */
+  lifetime?: [number, number];
+  /** Particle color */
+  color?: ParticleColor | ((particle: Particle) => ParticleColor);
+  /** Particle shape */
+  shape?: ParticleShape;
+  /** Custom initializer function */
+  init?: (particle: Particle, emitter: ParticleEmitter) => void;
+}
+
+/**
+ * Emitter that spawns particles with configurable properties.
+ *
+ * @example
+ * const emitter = new ParticleEmitter({
+ *   rate: 50,
+ *   x: 400, y: 300,
+ *   velocity: { x: 0, y: -100 },
+ *   velocitySpread: { x: 50, y: 20 },
+ *   lifetime: [1, 3],
+ *   size: [2, 8],
+ * });
+ */
+export class ParticleEmitter {
+  /** Whether emitter is active */
+  active: boolean;
+  /** Emission rate (particles per second) */
+  rate: number;
+  /** Emitter position X */
+  x: number;
+  /** Emitter position Y */
+  y: number;
+  /** Emitter position Z */
+  z: number;
+
+  constructor(options?: ParticleEmitterOptions);
+
+  /**
+   * Update emitter and return number of particles to spawn.
+   * @param dt - Delta time in seconds
+   * @returns Number of particles to spawn this frame
+   */
+  update(dt: number): number;
+
+  /**
+   * Initialize a particle with this emitter's settings.
+   * @param particle - Particle to initialize
+   */
+  emit(particle: Particle): void;
+
+  /** Start emitting */
+  start(): void;
+
+  /** Stop emitting */
+  stop(): void;
+
+  /** Burst spawn a specific number of particles */
+  burst(count: number): void;
+}
+
+// ==========================================================================
+// ParticleSystem Class
+// ==========================================================================
+
+/** Options for ParticleSystem */
+export interface ParticleSystemOptions extends GameObjectOptions {
+  /** Maximum active particles (default: 5000) */
+  maxParticles?: number;
+  /** Optional Camera3D for 3D projection */
+  camera?: any; // Camera3D
+  /** Enable depth sorting (requires camera) */
+  depthSort?: boolean;
+  /** Canvas blend mode (default: 'source-over') */
+  blendMode?: GlobalCompositeOperation;
+  /** Array of updater functions */
+  updaters?: ParticleUpdater[];
+  /** Position particles in world space */
+  worldSpace?: boolean;
+}
+
+/** Particle updater function signature */
+export type ParticleUpdater = (particle: Particle, dt: number, system: ParticleSystem) => void;
+
+/**
+ * High-performance particle management GameObject.
+ *
+ * @example
+ * const particles = new ParticleSystem(this, {
+ *   camera: this.camera,
+ *   depthSort: true,
+ *   maxParticles: 3000,
+ *   blendMode: 'screen',
+ *   updaters: [Updaters.velocity, Updaters.lifetime, Updaters.gravity(150)],
+ * });
+ * particles.addEmitter('fountain', new ParticleEmitter({ rate: 50 }));
+ * this.pipeline.add(particles);
+ */
+export class ParticleSystem extends GameObject {
+  /** Active particles */
+  particles: Particle[];
+  /** Object pool for recycled particles */
+  pool: Particle[];
+  /** Maximum particles allowed */
+  maxParticles: number;
+  /** Named emitters */
+  emitters: Map<string, ParticleEmitter>;
+  /** Optional Camera3D for 3D projection */
+  camera: any | null;
+  /** Whether to depth sort particles */
+  depthSort: boolean;
+  /** Updater functions */
+  updaters: ParticleUpdater[];
+  /** Canvas blend mode (set via options, not an accessor) */
+  readonly _blendMode: GlobalCompositeOperation;
+  /** Position in world space */
+  worldSpace: boolean;
+
+  /** Current particle count */
+  readonly particleCount: number;
+  /** Pool size (recycled particles ready for reuse) */
+  readonly poolSize: number;
+
+  constructor(game: Game, options?: ParticleSystemOptions);
+
+  /**
+   * Add an emitter to the system.
+   * @param name - Emitter identifier
+   * @param emitter - Emitter instance
+   */
+  addEmitter(name: string, emitter: ParticleEmitter): ParticleSystem;
+
+  /**
+   * Remove an emitter from the system.
+   * @param name - Emitter identifier
+   */
+  removeEmitter(name: string): ParticleSystem;
+
+  /**
+   * Get an emitter by name.
+   * @param name - Emitter identifier
+   */
+  getEmitter(name: string): ParticleEmitter | undefined;
+
+  /**
+   * Acquire a particle from pool or create new.
+   */
+  acquire(): Particle;
+
+  /**
+   * Release a particle back to pool.
+   * @param particle - Particle to release
+   */
+  release(particle: Particle): void;
+
+  /**
+   * Emit particles using an emitter.
+   * @param count - Number of particles to emit
+   * @param emitter - Emitter to use
+   */
+  emitParticles(count: number, emitter: ParticleEmitter): void;
+
+  /**
+   * Burst spawn particles.
+   * @param count - Number of particles
+   * @param emitterOrName - Emitter instance or name
+   */
+  burst(count: number, emitterOrName: ParticleEmitter | string): void;
+
+  /** Clear all particles and return them to pool */
+  clear(): void;
+
+  /**
+   * Draw a single particle (override for custom rendering).
+   * @param ctx - Canvas context
+   * @param p - Particle to draw
+   * @param x - Screen X position
+   * @param y - Screen Y position
+   * @param scale - Size scale factor
+   */
+  drawParticle(ctx: CanvasRenderingContext2D, p: Particle, x: number, y: number, scale: number): void;
+}
+
+// ==========================================================================
+// Updaters
+// ==========================================================================
+
+/**
+ * Collection of composable particle updater functions.
+ *
+ * @example
+ * const system = new ParticleSystem(game, {
+ *   updaters: [
+ *     Updaters.velocity,
+ *     Updaters.lifetime,
+ *     Updaters.gravity(200),
+ *     Updaters.fadeOut,
+ *     Updaters.shrink,
+ *   ]
+ * });
+ */
+export namespace Updaters {
+  /** Apply velocity to position */
+  const velocity: ParticleUpdater;
+
+  /** Update age and kill expired particles */
+  const lifetime: ParticleUpdater;
+
+  /** Fade out alpha over lifetime */
+  const fadeOut: ParticleUpdater;
+
+  /** Shrink size over lifetime */
+  const shrink: ParticleUpdater;
+
+  /** Grow size over lifetime */
+  const grow: ParticleUpdater;
+
+  /**
+   * Apply gravity acceleration.
+   * @param strength - Gravity strength (pixels per second squared)
+   * @param axis - Axis to apply gravity ('y' by default)
+   */
+  function gravity(strength: number, axis?: 'x' | 'y' | 'z'): ParticleUpdater;
+
+  /**
+   * Apply friction/drag.
+   * @param factor - Friction factor (0-1, lower = more friction)
+   */
+  function friction(factor: number): ParticleUpdater;
+
+  /**
+   * Apply wind force.
+   * @param forceX - X force
+   * @param forceY - Y force
+   */
+  function wind(forceX: number, forceY: number): ParticleUpdater;
+
+  /**
+   * Constrain particles to bounds.
+   * @param bounds - Bounding box
+   * @param bounce - Bounce factor (0-1)
+   */
+  function bounds(bounds: { x: number; y: number; width: number; height: number }, bounce?: number): ParticleUpdater;
+
+  /**
+   * Color transition over lifetime.
+   * @param startColor - Starting color
+   * @param endColor - Ending color
+   */
+  function colorTransition(startColor: ParticleColor, endColor: ParticleColor): ParticleUpdater;
+
+  /**
+   * Attract/repel from a point.
+   * @param x - Attractor X position
+   * @param y - Attractor Y position
+   * @param strength - Attraction strength (negative = repel)
+   */
+  function attract(x: number, y: number, strength: number): ParticleUpdater;
+
+  /**
+   * Apply turbulence/noise to velocity.
+   * @param strength - Turbulence strength
+   * @param scale - Noise scale
+   */
+  function turbulence(strength: number, scale?: number): ParticleUpdater;
+
+  /**
+   * Orbital motion around a point.
+   * @param centerX - Center X
+   * @param centerY - Center Y
+   * @param speed - Angular speed
+   */
+  function orbital(centerX: number, centerY: number, speed: number): ParticleUpdater;
+}
+

package/types/shapes.d.ts

@@ -713,21 +713,56 @@ export class PatternRectangle extends Rectangle {
 
 /** Options for ImageShape */
 export interface ImageShapeOptions extends ShapeOptions {
-  /** Image source URL */
-  src?: string;
-  /** Image element */
-  image?: HTMLImageElement;
+  /** Anchor point for positioning (e.g., "center", "top-left") */
+  anchor?: string;
+  /** Enable image smoothing (default: true) */
+  smoothing?: boolean;
 }
 
+/** Type for bitmap sources that ImageShape accepts */
+export type BitmapSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | HTMLVideoElement | ImageData;
+
 /**
- * Image shape.
+ * Image shape for rendering arbitrary pixel buffers.
+ * Supports HTMLImageElement, HTMLCanvasElement, ImageBitmap, HTMLVideoElement, and ImageData.
+ *
+ * @example
+ * const data = Painter.img.getImageData(0, 0, 320, 200);
+ * const shape = new ImageShape(data, { x: 100, y: 50, anchor: "center" });
+ * scene.add(shape);
  */
 export class ImageShape extends Shape {
-  constructor(options?: ImageShapeOptions);
+  /**
+   * Create an ImageShape.
+   * @param bitmap - Image source (HTMLImageElement, HTMLCanvasElement, ImageBitmap, HTMLVideoElement, or ImageData)
+   * @param options - Shape options including anchor and smoothing
+   */
+  constructor(bitmap: BitmapSource | null, options?: ImageShapeOptions);
+
+  /** The internal bitmap */
+  get bitmap(): BitmapSource | null;
+  set bitmap(v: BitmapSource | null);
+
+  /** Anchor position (e.g., "center", "top-left") */
+  anchor: string;
 
-  /** The image element */
-  get image(): HTMLImageElement | null;
-  set image(v: HTMLImageElement | null);
+  /** Whether image smoothing is enabled */
+  smoothing: boolean;
+
+  /**
+   * Update the canvas buffer for ImageData sources.
+   * @param bitmap - ImageData to buffer
+   */
+  buffer(bitmap: ImageData): void;
+
+  /** Reset the image to an empty state */
+  reset(): void;
+
+  /**
+   * Set the anchor point.
+   * @param anchor - Anchor position string
+   */
+  setAnchor(anchor: string): void;
 }
 
 // ==========================================================================
@@ -801,6 +836,69 @@ export class Sphere extends Shape {
   constructor(radius: number, options?: ShapeOptions);
 }
 
+/** Options for Sphere3D */
+export interface Sphere3DOptions extends ShapeOptions {
+  /** Sphere radius */
+  radius?: number;
+  /** Number of latitude segments */
+  latSegments?: number;
+  /** Number of longitude segments */
+  lonSegments?: number;
+  /** Base color */
+  color?: string;
+  /** Light direction [x, y, z] */
+  lightDirection?: [number, number, number];
+  /** Ambient light intensity (0-1) */
+  ambientLight?: number;
+  /** Whether to use glow effect */
+  glow?: boolean;
+  /** Glow color */
+  glowColor?: string;
+  /** Glow intensity */
+  glowIntensity?: number;
+  /** Whether to use wireframe */
+  wireframe?: boolean;
+  /** Wireframe color */
+  wireframeColor?: string;
+}
+
+/**
+ * 3D sphere with Camera3D projection support.
+ * Renders a proper 3D sphere with lighting and optional effects.
+ *
+ * @example
+ * const sphere = new Sphere3D({
+ *   x: 0, y: 0, z: 0,
+ *   radius: 100,
+ *   color: '#ff6600',
+ *   glow: true
+ * });
+ */
+export class Sphere3D extends Shape {
+  /** Sphere radius */
+  radius: number;
+  /** Z position in 3D space */
+  z: number;
+  /** Camera3D instance for projection */
+  camera: any;
+
+  constructor(options?: Sphere3DOptions);
+
+  /**
+   * Set the camera for 3D projection.
+   * @param camera - Camera3D instance
+   */
+  setCamera(camera: any): Sphere3D;
+
+  /**
+   * Set position in 3D space.
+   * @param x - X position
+   * @param y - Y position
+   * @param z - Z position
+   */
+  setPosition(x: number, y: number, z: number): Sphere3D;
+}
+
 // ==========================================================================
 // Text Shapes
 // ==========================================================================