@guinetik/gcanvas 1.0.0

package/src/painter/painter.shapes.js

@@ -0,0 +1,277 @@
+import { Painter } from "./painter";
+
+export class PainterShapes {
+  // =========================================================================
+  // BASIC SHAPES
+  // =========================================================================
+
+  // Drawing functions that ensure opacity is applied
+  static rect(x, y, width, height, color) {
+    // Save current fillStyle
+    const oldFillStyle = Painter.ctx.fillStyle;
+    // Apply fill
+    Painter.colors.fill(color);
+    Painter.ctx.fillRect(x, y, width, height);
+    // Restore fillStyle
+    Painter.ctx.fillStyle = oldFillStyle;
+  }
+
+  static outlineRect(x, y, width, height, color, lineWidth = 1) {
+    // Save current styles
+    const oldStrokeStyle = Painter.ctx.strokeStyle;
+    const oldLineWidth = Painter.ctx.lineWidth;
+    // Apply stroke
+    Painter.ctx.strokeStyle = color;
+    Painter.ctx.lineWidth = lineWidth;
+    Painter.ctx.strokeRect(x, y, width, height);
+    // Restore styles
+    Painter.ctx.strokeStyle = oldStrokeStyle;
+    Painter.ctx.lineWidth = oldLineWidth;
+  }
+
+  /**
+   * Draw a rounded rectangle
+   * @param {number} x - X coordinate (top-left)
+   * @param {number} y - Y coordinate (top-left)
+   * @param {number} width - Width
+   * @param {number} height - Height
+   * @param {number|number[]} radii - Corner radius or array of radii for each corner
+   * @param {string|CanvasGradient} [fillColor] - Fill color
+   * @param {string|CanvasGradient} [strokeColor] - Stroke color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static roundRect(
+    x,
+    y,
+    width,
+    height,
+    radii = 0,
+    fillColor,
+    strokeColor,
+    lineWidth
+  ) {
+    // Handle radius either as a single value or array
+    let radiusArray;
+    if (typeof radii === "number") {
+      radiusArray = [radii, radii, radii, radii]; // [topLeft, topRight, bottomRight, bottomLeft]
+    } else if (Array.isArray(radii)) {
+      // Ensure we have exactly 4 values
+      radiusArray =
+        radii.length === 4
+          ? radii
+          : [
+              radii[0] || 0,
+              radii[1] || radii[0] || 0,
+              radii[2] || radii[0] || 0,
+              radii[3] || radii[1] || radii[0] || 0,
+            ];
+    } else {
+      radiusArray = [0, 0, 0, 0];
+    }
+
+    const [tlRadius, trRadius, brRadius, blRadius] = radiusArray;
+    const right = x + width;
+    const bottom = y + height;
+
+    Painter.lines.beginPath();
+
+    // Start from the top-left corner and draw clockwise
+    Painter.lines.moveTo(x + tlRadius, y);
+
+    // Top edge and top-right corner
+    Painter.lines.lineTo(right - trRadius, y);
+    this.arc(right - trRadius, y + trRadius, trRadius, -Math.PI / 2, 0);
+
+    // Right edge and bottom-right corner
+    Painter.lines.lineTo(right, bottom - brRadius);
+    this.arc(
+      right - brRadius,
+      bottom - brRadius,
+      brRadius,
+      0,
+      Math.PI / 2
+    );
+
+    // Bottom edge and bottom-left corner
+    Painter.lines.lineTo(x + blRadius, bottom);
+    this.arc(
+      x + blRadius,
+      bottom - blRadius,
+      blRadius,
+      Math.PI / 2,
+      Math.PI
+    );
+
+    // Left edge and top-left corner
+    Painter.lines.lineTo(x, y + tlRadius);
+    this.arc(
+      x + tlRadius,
+      y + tlRadius,
+      tlRadius,
+      Math.PI,
+      -Math.PI / 2
+    );
+
+    Painter.lines.closePath();
+
+    if (fillColor) {
+      Painter.fillStyle = fillColor;
+      Painter.colors.fill(fillColor);
+    }
+
+    if (strokeColor) {
+      Painter.colors.stroke(strokeColor, lineWidth);
+    }
+  }
+
+  /**
+   * Draw a filled rounded rectangle
+   * @param {number} x - X coordinate (top-left)
+   * @param {number} y - Y coordinate (top-left)
+   * @param {number} width - Width
+   * @param {number} height - Height
+   * @param {number|number[]} radii - Corner radius or array of radii
+   * @param {string|CanvasGradient} [color] - Fill color
+   * @returns {void}
+   */
+  static fillRoundRect(x, y, width, height, radii = 0, color) {
+    this.roundRect(x, y, width, height, radii, color, null);
+  }
+
+  /**
+   * Draw a stroked rounded rectangle
+   * @param {number} x - X coordinate (top-left)
+   * @param {number} y - Y coordinate (top-left)
+   * @param {number} width - Width
+   * @param {number} height - Height
+   * @param {number|number[]} radii - Corner radius or array of radii
+   * @param {string|CanvasGradient} [color] - Stroke color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static strokeRoundRect(x, y, width, height, radii = 0, color, lineWidth) {
+    this.roundRect(x, y, width, height, radii, null, color, lineWidth);
+  }
+
+  /**
+   * Draw a filled circle
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} radius - Circle radius
+   * @param {string|CanvasGradient} [color] - Fill color
+   * @returns {void}
+   */
+  static fillCircle(x, y, radius, color) {
+    Painter.logger.log("PainterShapes.fillCircle", x, y, radius, color);
+    Painter.lines.beginPath();
+    this.arc(x, y, radius, 0, Math.PI * 2);
+    Painter.colors.fill(color);
+  }
+
+  static arc(x, y, radius, startAngle, endAngle, counterclockwise) {
+    Painter.ctx.arc(x, y, radius, startAngle, endAngle, counterclockwise);
+  }
+
+  /**
+   * Draw a stroked circle
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} radius - Circle radius
+   * @param {string|CanvasGradient} [color] - Stroke color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static strokeCircle(x, y, radius, color, lineWidth) {
+    Painter.lines.beginPath();
+    this.arc(x, y, radius, 0, Math.PI * 2);
+    Painter.colors.stroke(color, lineWidth);
+  }
+
+  /**
+   * Draw a filled ellipse
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} radiusX - X radius
+   * @param {number} radiusY - Y radius
+   * @param {number} [rotation=0] - Rotation in radians
+   * @param {string|CanvasGradient} [color] - Fill color
+   * @returns {void}
+   */
+  static fillEllipse(x, y, radiusX, radiusY, rotation = 0, color) {
+    Painter.lines.beginPath();
+    this.ellipse(x, y, radiusX, radiusY, rotation, 0, Math.PI * 2);
+    if (color) Painter.fillStyle = color;
+    Painter.colors.fill(color);
+  }
+
+  /**
+   * Draw a stroked ellipse
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} radiusX - X radius
+   * @param {number} radiusY - Y radius
+   * @param {number} [rotation=0] - Rotation in radians
+   * @param {string|CanvasGradient} [color] - Stroke color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static strokeEllipse(x, y, radiusX, radiusY, rotation = 0, color, lineWidth) {
+    Painter.lines.beginPath();
+    this.ellipse(x, y, radiusX, radiusY, rotation, 0, Math.PI * 2);
+    if (color) Painter.strokeStyle = color;
+    if (lineWidth !== undefined) Painter.lineWidth = lineWidth;
+    Painter.colors.stroke(color, lineWidth);
+  }
+
+  static ellipse(
+    x,
+    y,
+    radiusX,
+    radiusY,
+    rotation,
+    startAngle,
+    endAngle,
+    counterclockwise
+  ) {
+    Painter.ctx.ellipse(
+      x,
+      y,
+      radiusX,
+      radiusY,
+      rotation,
+      startAngle,
+      endAngle,
+      counterclockwise
+    );
+  }
+
+  /**
+   * Draw a polygon
+   * @param {Array<{x: number, y: number}>} points - Array of points
+   * @param {string|CanvasGradient} [fillColor] - Fill color
+   * @param {string|CanvasGradient} [strokeColor] - Stroke color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static polygon(points, fillColor, strokeColor, lineWidth) {
+    if (points.length < 2) return;
+
+    Painter.lines.beginPath();
+    Painter.lines.moveTo(points[0].x, points[0].y);
+
+    for (let i = 1; i < points.length; i++) {
+      Painter.lines.lineTo(points[i].x, points[i].y);
+    }
+
+    Painter.lines.closePath();
+
+    if (fillColor) {
+      Painter.colors.fill(fillColor);
+    }
+
+    if (strokeColor) {
+      Painter.colors.stroke(strokeColor, lineWidth);
+    }
+  }
+}

package/src/painter/painter.text.js

@@ -0,0 +1,273 @@
+import { Painter } from "./painter";
+export class PainterText {
+
+  static font() {
+    return Painter.ctx.font;
+  }
+
+  /**
+   * Set font for text drawing
+   * @param {string} font - Font specification (e.g. "24px 'Courier New', monospace")
+   * @returns {void}
+   */
+  static setFont(font) {
+    Painter.ctx.font = font;
+  }
+
+  /**
+   * Set text alignment
+   * @param {CanvasTextAlign} align - Text alignment ('left', 'right', 'center', 'start', 'end')
+   * @returns {void}
+   */
+  static setTextAlign(align) {
+    Painter.ctx.textAlign = align;
+  }
+
+  /**
+   * Set text baseline
+   * @param {CanvasTextBaseline} baseline - Text baseline ('top', 'hanging', 'middle', 'alphabetic', 'ideographic', 'bottom')
+   * @returns {void}
+   */
+  static setTextBaseline(baseline) {
+    Painter.ctx.textBaseline = baseline;
+  }
+
+  /**
+   * Draw filled text
+   * @param {string} text - Text to draw
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {string|CanvasGradient} [color] - Text color
+   * @param {string} [font] - Font specification
+   * @returns {void}
+   */
+  static fillText(text, x, y, color, font) {
+    if (color) Painter.ctx.fillStyle = color;
+    if (font) Painter.ctx.font = font;
+    Painter.ctx.fillText(text, x, y);
+  }
+
+  /**
+   * Draw stroked text
+   * @param {string} text - Text to draw
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {string|CanvasGradient} [color] - Text color
+   * @param {number} [lineWidth] - Line width
+   * @param {string} [font] - Font specification
+   * @returns {void}
+   */
+  static strokeText(text, x, y, color, lineWidth, font) {
+    if (color) Painter.ctx.strokeStyle = color;
+    if (lineWidth !== undefined) Painter.ctx.lineWidth = lineWidth;
+    if (font) Painter.ctx.font = font;
+    Painter.ctx.strokeText(text, x, y);
+  }
+
+  /**
+   * Improved text measurement that accounts for baseline adjustments
+   * @param {string} text - Text to measure
+   * @param {string} [font] - Font specification
+   * @param {string} [align="start"] - Text alignment
+   * @param {string} [baseline="alphabetic"] - Text baseline
+   * @returns {{width: number, height: number, verticalAdjustment: number}} Text dimensions with adjustment
+   */
+  static measureTextDimensions(
+    text,
+    font,
+    align = "start",
+    baseline = "alphabetic"
+  ) {
+    if (font) Painter.ctx.font = font;
+    const metrics = Painter.ctx.measureText(text);
+    const width = metrics.width;
+    const height =
+      metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent;
+
+    // Calculate vertical adjustment based on baseline
+    let verticalAdjustment = 0;
+
+    if (baseline === "middle") {
+      // For middle baseline, text is visually slightly higher than the mathematical middle
+      // This small correction factor improves visual alignment
+      verticalAdjustment = -1.5; // Empirically determined adjustment
+    }
+
+    return {
+      width: width,
+      height: height,
+      verticalAdjustment: verticalAdjustment,
+    };
+  }
+
+  /**
+   * Measure text width
+   * @param {string} text - Text to measure
+   * @returns {number} Text width
+   */
+  static measureTextWidth(text, font) {
+    if (font) Painter.ctx.font = font;
+    return Painter.ctx.measureText(text).width;
+  }
+
+  /**
+   * Draw filled and stroked text with outline
+   * @param {string} text - Text to draw
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {string} fillColor - Fill color
+   * @param {string} strokeColor - Stroke color
+   * @param {number} strokeWidth - Stroke width
+   * @param {string} [font] - Font specification
+   * @returns {void}
+   */
+  static outlinedText(text, x, y, fillColor, strokeColor, strokeWidth, font) {
+    if (font) Painter.ctx.font = font;
+
+    // Draw the stroke first
+    Painter.ctx.strokeStyle = strokeColor;
+    Painter.ctx.lineWidth = strokeWidth;
+    Painter.ctx.strokeText(text, x, y);
+
+    // Then draw the fill
+    Painter.ctx.fillStyle = fillColor;
+    Painter.ctx.fillText(text, x, y);
+  }
+
+  /**
+   * Draw text with a maximum width, wrapping to new lines as needed
+   * @param {string} text - Text to draw
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {number} maxWidth - Maximum width before wrapping
+   * @param {number} lineHeight - Line height for wrapped text
+   * @param {string} [color] - Text color
+   * @param {string} [font] - Font specification
+   * @returns {number} Total height of drawn text
+   */
+  static wrappedText(text, x, y, maxWidth, lineHeight, color, font) {
+    if (color) Painter.ctx.fillStyle = color;
+    if (font) Painter.ctx.font = font;
+
+    const words = text.split(" ");
+    let line = "";
+    let testLine = "";
+    let lineCount = 1;
+
+    for (let i = 0; i < words.length; i++) {
+      testLine = line + words[i] + " ";
+      const metrics = Painter.ctx.measureText(testLine);
+      const testWidth = metrics.width;
+
+      if (testWidth > maxWidth && i > 0) {
+        Painter.ctx.fillText(line, x, y);
+        line = words[i] + " ";
+        y += lineHeight;
+        lineCount++;
+      } else {
+        line = testLine;
+      }
+    }
+
+    Painter.ctx.fillText(line, x, y);
+    return lineCount * lineHeight;
+  }
+
+  /**
+   * Draw text along a path (like an arc)
+   * @param {string} text - Text to draw
+   * @param {Array} path - Array of points {x, y} defining the path
+   * @param {string} [color] - Text color
+   * @param {string} [font] - Font specification
+   * @param {boolean} [reverse=false] - Whether to draw text in reverse direction
+   * @returns {void}
+   */
+  static textOnPath(text, path, color, font, reverse = false) {
+    if (path.length < 2) return;
+
+    if (color) Painter.ctx.fillStyle = color;
+    if (font) Painter.ctx.font = font;
+
+    // Get characters and their widths
+    const chars = text.split("");
+    const charWidths = chars.map((char) => Painter.ctx.measureText(char).width);
+
+    if (reverse) {
+      chars.reverse();
+      charWidths.reverse();
+      path.reverse();
+    }
+
+    // Calculate total length of the path
+    let pathLength = 0;
+    for (let i = 1; i < path.length; i++) {
+      const dx = path[i].x - path[i - 1].x;
+      const dy = path[i].y - path[i - 1].y;
+      pathLength += Math.sqrt(dx * dx + dy * dy);
+    }
+
+    // Calculate total width of text
+    const textWidth = charWidths.reduce((total, width) => total + width, 0);
+
+    // Calculate starting offset to center text on path
+    let offset = (pathLength - textWidth) / 2;
+    if (offset < 0) offset = 0;
+
+    // Draw each character
+    let currentOffset = offset;
+    for (let i = 0; i < chars.length; i++) {
+      const charWidth = charWidths[i];
+
+      // Find position and angle on path
+      const { x, y, angle } = getPositionOnPath(path, currentOffset);
+
+      // Draw the character
+      Painter.ctx.save();
+      Painter.ctx.translate(x, y);
+      Painter.ctx.rotate(angle);
+      Painter.ctx.fillText(chars[i], 0, 0);
+      Painter.ctx.restore();
+
+      currentOffset += charWidth;
+    }
+  }
+
+  // Helper function for textOnPath
+  static getPositionOnPath(path, offset) {
+    let currentLength = 0;
+
+    for (let i = 1; i < path.length; i++) {
+      const p1 = path[i - 1];
+      const p2 = path[i];
+      const dx = p2.x - p1.x;
+      const dy = p2.y - p1.y;
+      const segmentLength = Math.sqrt(dx * dx + dy * dy);
+
+      if (currentLength + segmentLength >= offset) {
+        // Calculate position between p1 and p2
+        const t = (offset - currentLength) / segmentLength;
+        const x = p1.x + dx * t;
+        const y = p1.y + dy * t;
+        const angle = Math.atan2(dy, dx);
+
+        return { x, y, angle };
+      }
+
+      currentLength += segmentLength;
+    }
+
+    // If offset is beyond path length, return last point
+    const lastPoint = path[path.length - 1];
+    const secondLastPoint = path[path.length - 2];
+    const angle = Math.atan2(
+      lastPoint.y - secondLastPoint.y,
+      lastPoint.x - secondLastPoint.x
+    );
+
+    return {
+      x: lastPoint.x,
+      y: lastPoint.y,
+      angle,
+    };
+  }
+}

package/src/particle/emitter.js

@@ -0,0 +1,124 @@
+/**
+ * ParticleEmitter - Configuration and spawning logic for particles
+ *
+ * Defines spawn position, velocity, lifetime, and appearance properties.
+ * Supports continuous emission (rate) and burst spawning.
+ */
+export class ParticleEmitter {
+  /**
+   * @param {Object} options - Emitter configuration
+   * @param {number} [options.rate=10] - Particles per second (continuous emission)
+   * @param {Object} [options.position] - Spawn position { x, y, z }
+   * @param {Object} [options.spread] - Position randomization { x, y, z }
+   * @param {Object} [options.velocity] - Initial velocity { x, y, z }
+   * @param {Object} [options.velocitySpread] - Velocity randomization { x, y, z }
+   * @param {Object} [options.lifetime] - Particle lifetime { min, max } in seconds
+   * @param {Object} [options.size] - Particle size { min, max }
+   * @param {Object} [options.color] - Base color { r, g, b, a }
+   * @param {string} [options.shape] - Particle shape: "circle", "square", "triangle"
+   */
+  constructor(options = {}) {
+    // Emission rate (particles per second)
+    this.rate = options.rate ?? 10;
+
+    // Spawn position and spread
+    this.position = { x: 0, y: 0, z: 0, ...options.position };
+    this.spread = { x: 0, y: 0, z: 0, ...options.spread };
+
+    // Initial velocity and spread
+    this.velocity = { x: 0, y: 0, z: 0, ...options.velocity };
+    this.velocitySpread = { x: 0, y: 0, z: 0, ...options.velocitySpread };
+
+    // Particle lifetime range (seconds)
+    this.lifetime = { min: 1, max: 2, ...options.lifetime };
+
+    // Particle size range
+    this.size = { min: 1, max: 1, ...options.size };
+
+    // Base color
+    this.color = { r: 255, g: 255, b: 255, a: 1, ...options.color };
+
+    // Particle shape
+    this.shape = options.shape ?? "circle";
+
+    // Emitter state
+    this.active = options.active !== false;
+    this._timer = 0;
+  }
+
+  /**
+   * Random value in range [-spread, spread].
+   * @private
+   */
+  _spread(spread) {
+    return (Math.random() - 0.5) * 2 * spread;
+  }
+
+  /**
+   * Random value in range [min, max].
+   * @private
+   */
+  _range(min, max) {
+    return min + Math.random() * (max - min);
+  }
+
+  /**
+   * Initialize a particle with emitter settings.
+   * @param {Particle} p - Particle to initialize
+   */
+  emit(p) {
+    // Position with spread
+    p.x = this.position.x + this._spread(this.spread.x);
+    p.y = this.position.y + this._spread(this.spread.y);
+    p.z = this.position.z + this._spread(this.spread.z);
+
+    // Velocity with spread
+    p.vx = this.velocity.x + this._spread(this.velocitySpread.x);
+    p.vy = this.velocity.y + this._spread(this.velocitySpread.y);
+    p.vz = this.velocity.z + this._spread(this.velocitySpread.z);
+
+    // Lifetime
+    p.lifetime = this._range(this.lifetime.min, this.lifetime.max);
+    p.age = 0;
+    p.alive = true;
+
+    // Size
+    p.size = this._range(this.size.min, this.size.max);
+
+    // Color (copy to avoid shared reference)
+    p.color.r = this.color.r;
+    p.color.g = this.color.g;
+    p.color.b = this.color.b;
+    p.color.a = this.color.a;
+
+    // Shape
+    p.shape = this.shape;
+  }
+
+  /**
+   * Update emitter and return number of particles to spawn.
+   * @param {number} dt - Delta time in seconds
+   * @returns {number} Number of particles to spawn this frame
+   */
+  update(dt) {
+    if (!this.active || this.rate <= 0) return 0;
+
+    this._timer += dt;
+    const interval = 1 / this.rate;
+    let count = 0;
+
+    while (this._timer >= interval) {
+      this._timer -= interval;
+      count++;
+    }
+
+    return count;
+  }
+
+  /**
+   * Reset emission timer.
+   */
+  reset() {
+    this._timer = 0;
+  }
+}

package/src/particle/index.js

@@ -0,0 +1,11 @@
+/**
+ * Particle System Module
+ *
+ * High-performance particle system with optional Camera3D support.
+ *
+ * @module particle
+ */
+export { Particle } from "./particle.js";
+export { ParticleEmitter } from "./emitter.js";
+export { ParticleSystem } from "./particle-system.js";
+export { Updaters } from "./updaters.js";