@guinetik/gcanvas 1.0.0

package/src/shapes/prism.js

@@ -0,0 +1,226 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * Prism - A 3D-looking isometric triangular prism with rotation support.
+ *
+ * Supports:
+ * - Individual face colors
+ * - Full bounding box
+ * - Face visibility control (top, bottom, left, right, front, back)
+ * - Rotation around X, Y, and Z axes
+ *
+ * Note: This is a 2.5D visual illusion — not actual 3D rendering.
+ */
+export class Prism extends Shape {
+  /**
+   * Create a triangular prism
+   * @param {number} x - X position (center of the prism)
+   * @param {number} y - Y position (center of the prism)
+   * @param {number} width - Width of the prism
+   * @param {number} height - Height of the triangular face
+   * @param {number} depth - Depth/length of the prism
+   * @param {object} options - Customization options
+   * @param {string} [options.faceTopColor] - Color of the top face
+   * @param {string} [options.faceBottomColor] - Color of the bottom face
+   * @param {string} [options.faceLeftColor] - Color of the left face
+   * @param {string} [options.faceRightColor] - Color of the right face
+   * @param {string} [options.faceFrontColor] - Color of the front face
+   * @param {string} [options.faceBackColor] - Color of the back face
+   * @param {Array<string>} [options.visibleFaces] - Array of face keys to render
+   * @param {string} [options.stroke] - Optional stroke around each face
+   * @param {number} [options.lineWidth] - Stroke width
+   * @param {number} [options.rotationX] - Rotation around X axis in radians
+   * @param {number} [options.rotationY] - Rotation around Y axis in radians
+   * @param {number} [options.rotationZ] - Rotation around Z axis in radians
+   */
+  constructor(depth = 100, options = {}) {
+    super(options);
+    this.depth = depth;
+
+    this.faceTopColor = options.faceTopColor || "#eee";
+    this.faceBottomColor = options.faceBottomColor || "#ccc";
+    this.faceLeftColor = options.faceLeftColor || "#aaa";
+    this.faceRightColor = options.faceRightColor || "#888";
+    this.faceFrontColor = options.faceFrontColor || "#666";
+    this.faceBackColor = options.faceBackColor || "#444";
+
+    this.stroke = options.stroke || null;
+    this.lineWidth = options.lineWidth || 1;
+
+    // Rotation angles (in radians)
+    this.rotationX = options.rotationX || 0;
+    this.rotationY = options.rotationY || 0;
+    this.rotationZ = options.rotationZ || 0;
+
+    /** @type {Array<'top'|'bottom'|'left'|'right'|'front'|'back'>} */
+    this.visibleFaces = options.visibleFaces || [
+      "top",
+      "left",
+      "right",
+      "front",
+      "back",
+      "bottom",
+    ];
+  }
+
+  /**
+   * Set rotation angles
+   * @param {number} x - Rotation around X axis in radians
+   * @param {number} y - Rotation around Y axis in radians
+   * @param {number} z - Rotation around Z axis in radians
+   */
+  setRotation(x, y, z) {
+    this.rotationX = x;
+    this.rotationY = y;
+    this.rotationZ = z;
+    return this; // Enable method chaining
+  }
+
+  /**
+   * Rotate the prism incrementally
+   * @param {number} x - Increment for X rotation in radians
+   * @param {number} y - Increment for Y rotation in radians
+   * @param {number} z - Increment for Z rotation in radians
+   */
+  rotate(x, y, z) {
+    this.rotationX += x;
+    this.rotationY += y;
+    this.rotationZ += z;
+    return this; // Enable method chaining
+  }
+
+  /**
+   * Internal draw logic
+   */
+  draw() {
+    super.draw();
+    const w = this.width / 2; // Half width for positioning
+    const h = this.height / 2; // Half height for positioning
+    const d = this.depth / 2; // Half depth for positioning
+
+    /**
+     * Apply 3D rotation to a point
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {{x: number, y: number, z: number}}
+     */
+    const rotate3D = (x, y, z) => {
+      // Apply X-axis rotation
+      let y1 = y;
+      let z1 = z;
+      y = y1 * Math.cos(this.rotationX) - z1 * Math.sin(this.rotationX);
+      z = y1 * Math.sin(this.rotationX) + z1 * Math.cos(this.rotationX);
+
+      // Apply Y-axis rotation
+      let x1 = x;
+      z1 = z;
+      x = x1 * Math.cos(this.rotationY) + z1 * Math.sin(this.rotationY);
+      z = -x1 * Math.sin(this.rotationY) + z1 * Math.cos(this.rotationY);
+
+      // Apply Z-axis rotation
+      x1 = x;
+      y1 = y;
+      x = x1 * Math.cos(this.rotationZ) - y1 * Math.sin(this.rotationZ);
+      y = x1 * Math.sin(this.rotationZ) + y1 * Math.cos(this.rotationZ);
+
+      return { x, y, z };
+    };
+
+    /**
+     * Isometric projection of 3D point
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {{x: number, y: number}}
+     */
+    const iso = (x, y, z) => {
+      // Apply rotations first
+      const rotated = rotate3D(x, y, z);
+
+      // Then apply isometric projection
+      const isoX = (rotated.x - rotated.y) * Math.cos(Math.PI / 6);
+      const isoY = (rotated.x + rotated.y) * Math.sin(Math.PI / 6) - rotated.z;
+      return { x: isoX, y: isoY, z: rotated.z }; // Include z for depth sorting
+    };
+
+    // Define vertices for the triangular prism
+    const p = {
+      // Front triangular face
+      p0: iso(-w, -d, -h), // Front bottom left
+      p1: iso(w, -d, -h), // Front bottom right
+      p2: iso(0, -d, h), // Front top center
+
+      // Back triangular face
+      p3: iso(-w, d, -h), // Back bottom left
+      p4: iso(w, d, -h), // Back bottom right
+      p5: iso(0, d, h), // Back top center
+    };
+
+    // Faces mapped to corner points
+    const faces = {
+      // Triangular front and back faces
+      front: { points: [p.p0, p.p1, p.p2], color: this.faceFrontColor },
+      back: { points: [p.p3, p.p4, p.p5], color: this.faceBackColor },
+
+      // Rectangular side faces
+      bottom: { points: [p.p0, p.p1, p.p4, p.p3], color: this.faceBottomColor },
+      right: { points: [p.p1, p.p2, p.p5, p.p4], color: this.faceRightColor },
+      left: { points: [p.p0, p.p2, p.p5, p.p3], color: this.faceLeftColor },
+    };
+
+    // Calculate visibility based on depth sorting
+    const visibleFacesWithDepth = this.visibleFaces
+      .filter((key) => faces[key])
+      .map((key) => {
+        const face = faces[key];
+
+        // Calculate face center for z-ordering
+        const centerX =
+          face.points.reduce((sum, pt) => sum + pt.x, 0) / face.points.length;
+        const centerY =
+          face.points.reduce((sum, pt) => sum + pt.y, 0) / face.points.length;
+        const centerZ =
+          face.points.reduce((sum, pt) => sum + (pt.z || 0), 0) /
+          face.points.length;
+
+        // Calculate approximate depth
+        // Higher value = farther back
+        const depth = centerX * centerX + centerY * centerY + centerZ * centerZ;
+
+        return { key, face, depth };
+      })
+      .sort((a, b) => b.depth - a.depth); // Sort by depth (back to front)
+
+    // Draw faces in depth order
+    visibleFacesWithDepth.forEach(({ key, face }) => {
+      if (face?.color) {
+        Painter.shapes.polygon(
+          face.points,
+          face.color,
+          this.stroke,
+          this.lineWidth
+        );
+      }
+    });
+  }
+
+  /**
+   * Compute bounding box for interactivity and layout
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  getBounds() {
+    // Calculate actual bounds based on isometric projection
+    const projectionFactor = 1.5; // Approximation for isometric projection
+    const maxDimension = Math.max(this.width, this.height, this.depth);
+    const adjustedSize = maxDimension * projectionFactor;
+
+    return {
+      x: this.x - adjustedSize / 2,
+      y: this.y - adjustedSize / 2,
+      width: adjustedSize,
+      height: adjustedSize,
+    };
+  }
+}

package/src/shapes/rect.js

@@ -0,0 +1,35 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * Rectangle - A drawable centered rectangle using the canvas.
+ *
+ * Draws a rectangle from its center (not top-left) using Painter.
+ */
+export class Rectangle extends Shape {
+  constructor(options = {}) {
+    super(options);
+  }
+
+  /**
+   * Renders the rectangle using Painter.
+   */
+  draw() {
+    super.draw(); // Apply constraints from Shape
+    this.drawRect();
+  }
+
+  drawRect() {
+    // When in a group context, use relative coordinates
+    const x = -this.width / 2;
+    const y = -this.height / 2;
+    
+    if (this.color) {
+      Painter.shapes.rect(x, y, this.width, this.height, this.color);
+    }
+  
+    if (this.stroke) {
+      Painter.shapes.outlineRect(x, y, this.width, this.height, this.stroke, this.lineWidth);
+    }
+  }
+}

package/src/shapes/renderable.js

@@ -0,0 +1,333 @@
+import { Geometry2d } from "./geometry.js";
+import { Painter } from "../painter/painter.js";
+import { Traceable } from "./traceable.js";
+
+/**
+ * Renderable
+ * ----------
+ *
+ * A render-capable spatial object in the gcanvas engine.
+ *
+ * This class introduces the core rendering lifecycle — it knows when to draw,
+ * how to draw, and how to **not draw** when conditions say so (invisible, opacity = 0).
+ *
+ * ### Architectural Role
+ *
+ * - Adds **rendering lifecycle control** (`render()`)
+ * - Supports **canvas state management** (save/restore)
+ * - Exposes **visual props** like opacity, visibility, and debug
+ * - Optional **shadow styling** support
+ *
+ * `Renderable` should be extended by anything that draws visuals:
+ * - Shapes (e.g., `Rectangle`, `Text`)
+ * - Sprites
+ * - UI elements
+ *
+ * @abstract
+ * @extends Geometry2d
+ */
+export class Renderable extends Traceable {
+  /**
+   * @param {Object} [options={}]
+   * @param {boolean} [options.visible=true] - Whether this object should be drawn
+   * @param {number} [options.opacity=1] - Alpha transparency (0–1)
+   * @param {boolean} [options.active=true] - Whether this object receives updates
+   * @param {string} [options.blendMode="source-over"] - Optional blend mode
+   * @param {string} [options.shadowColor] - Optional shadow color
+   * @param {number} [options.shadowBlur=0] - Shadow blur radius
+   * @param {number} [options.shadowOffsetX=0] - Shadow X offset
+   * @param {number} [options.shadowOffsetY=0] - Shadow Y offset
+   * @param {number} [options.zIndex=0] - Z-index for stacking order
+   */
+  constructor(options = {}) {
+    super(options);
+    this._visible = options.visible !== false;
+    this._opacity = typeof options.opacity === "number" ? options.opacity : 1;
+    this._active = options.active !== false;
+    this.zIndex = options.zIndex ?? 0;
+
+    this._shadowColor = options.shadowColor ?? undefined;
+    this._shadowBlur = options.shadowBlur ?? 0;
+    this._shadowOffsetX = options.shadowOffsetX ?? 0;
+    this._shadowOffsetY = options.shadowOffsetY ?? 0;
+
+    // Render caching - when enabled, renders to an offscreen canvas once
+    // and blits the cached bitmap on subsequent frames for better performance.
+    this._cacheRendering = options.cacheRendering ?? false;
+    this._cacheCanvas = null;
+    this._cacheDirty = true;
+    this._cachePadding = options.cachePadding ?? 2; // Extra padding for anti-aliasing/strokes
+
+    this._tick = 0;
+    this.logger.log("Renderable", this.x, this.y, this.width, this.height);
+  }
+
+  /**
+   * Main render method.
+   * Handles visibility, translation, and calls draw() in the transformed context.
+   * If cacheRendering is enabled, renders to an offscreen canvas once and blits it.
+   */
+  render() {
+    if (!this._visible || this._opacity <= 0) return;
+
+    Painter.save();
+    Painter.effects.setBlendMode(this._blendMode);
+
+    if (this.crisp) {
+      Painter.translateTo(Math.round(this.x), Math.round(this.y));
+    } else {
+      Painter.translateTo(this.x, this.y);
+    }
+
+    this.applyShadow(Painter.ctx);
+
+    // If caching IS NOT enabled or we're the base class, render normally
+    if (!this._cacheRendering || this.constructor.name === "Renderable") {
+      Painter.opacity.pushOpacity(this._opacity);
+      this.draw();
+      Painter.opacity.popOpacity();
+    } else {
+      // Caching logic - cache the IDENTITY shape (untransformed)
+      const rawWidth = typeof this.width === "number" ? this.width : 0;
+      const rawHeight = typeof this.height === "number" ? this.height : 0;
+      const padding = this._cachePadding * 2;
+      const cacheWidth = Math.ceil(rawWidth + padding) || 1;
+      const cacheHeight = Math.ceil(rawHeight + padding) || 1;
+
+      // Create or resize cache canvas if needed
+      if (
+        !this._cacheCanvas ||
+        this._cacheCanvas.width !== cacheWidth ||
+        this._cacheCanvas.height !== cacheHeight
+      ) {
+        this._cacheCanvas = document.createElement("canvas");
+        this._cacheCanvas.width = cacheWidth;
+        this._cacheCanvas.height = cacheHeight;
+        this._cacheDirty = true;
+      }
+
+      // Re-render to cache if dirty
+      if (this._cacheDirty) {
+        this._renderToCache(cacheWidth, cacheHeight);
+        this._cacheDirty = false;
+      }
+
+      // Blit cached canvas with current opacity AND transforms
+      // This allows efficient rotation/scaling of the cached bitmap
+      Painter.opacity.pushOpacity(this._opacity);
+
+      // Extract transform properties if they exist
+      const rotation = this.rotation ?? 0;
+      const scaleX = this.scaleX ?? 1;
+      const scaleY = this.scaleY ?? 1;
+
+      Painter.img.draw(this._cacheCanvas, 0, 0, {
+        width: cacheWidth,
+        height: cacheHeight,
+        rotation: rotation,
+        scaleX: scaleX,
+        scaleY: scaleY,
+        anchor: "center",
+      });
+
+      Painter.opacity.popOpacity();
+    }
+
+    Painter.restore();
+  }
+
+  /**
+   * Internal method to render the object to the offscreen cache canvas.
+   * @param {number} width - Cache width
+   * @param {number} height - Cache height
+   * @protected
+   */
+  _renderToCache(width, height) {
+    const cacheCtx = this._cacheCanvas.getContext("2d");
+    cacheCtx.clearRect(0, 0, width, height);
+
+    // Swap to cache context
+    const mainCtx = Painter.ctx;
+    Painter.ctx = cacheCtx;
+
+    // Signal subclasses to skip transforms if they are transform-aware
+    this._isCaching = true;
+
+    cacheCtx.save();
+    // Translate to center of cache so (0,0) draws correctly
+    cacheCtx.translate(width / 2, height / 2);
+
+    // Call draw() to render to the cache at full opacity and identity transform
+    this.draw();
+
+    cacheCtx.restore();
+
+    this._isCaching = false;
+
+    // Restore main context
+    Painter.ctx = mainCtx;
+  }
+
+  /**
+   * Mark the render cache as needing refresh.
+   */
+  invalidateCache() {
+    this._cacheDirty = true;
+  }
+
+  draw() {
+    this.drawDebug();
+  }
+
+  /**
+   * Called once per frame if the object is active.
+   * @param {number} dt - Time delta since last frame (seconds)
+   */
+  update(dt) {
+    this.trace("Renderable.update");
+    this._tick += dt;
+    super.update(dt);
+  }
+
+  /**
+   * Apply shadow styles to the current canvas context.
+   * Only called if `shadowColor` is defined.
+   *
+   * @param {CanvasRenderingContext2D} ctx
+   */
+  applyShadow(ctx) {
+    if (!this._shadowColor) return;
+    ctx.shadowColor = this._shadowColor;
+    ctx.shadowBlur = this._shadowBlur;
+    ctx.shadowOffsetX = this._shadowOffsetX;
+    ctx.shadowOffsetY = this._shadowOffsetY;
+  }
+
+  /**
+   * Gets whether the object is visible (drawn during render).
+   * @type {boolean}
+   */
+  get visible() {
+    return this._visible;
+  }
+
+  set visible(v) {
+    this._visible = Boolean(v);
+  }
+
+  get width() {
+    return super.width;
+  }
+
+  set width(v) {
+    super.width = v;
+    this.invalidateCache();
+  }
+
+  get height() {
+    return super.height;
+  }
+
+  set height(v) {
+    super.height = v;
+    this.invalidateCache();
+  }
+
+  /**
+   * Gets whether the object is active (updated during game loop).
+   * @type {boolean}
+   */
+  get active() {
+    return this._active;
+  }
+
+  set active(v) {
+    this._active = Boolean(v);
+  }
+
+  /**
+   * Gets the object's opacity (0–1).
+   * @type {number}
+   */
+  get opacity() {
+    return this._opacity;
+  }
+
+  set opacity(v) {
+    this._opacity = Math.min(1, Math.max(0, typeof v === "number" ? v : 1));
+  }
+
+  /**
+   * Gets the current shadow color (if any).
+   * @type {string|undefined}
+   */
+  get shadowColor() {
+    return this._shadowColor;
+  }
+
+  set shadowColor(v) {
+    this._shadowColor = v;
+    this.invalidateCache();
+  }
+
+  /**
+   * Gets the blur radius for the drop shadow.
+   * @type {number}
+   */
+  get shadowBlur() {
+    return this._shadowBlur;
+  }
+
+  set shadowBlur(v) {
+    this._shadowBlur = v;
+    this.invalidateCache();
+  }
+
+  /**
+   * Gets the horizontal offset of the drop shadow.
+   * @type {number}
+   */
+  get shadowOffsetX() {
+    return this._shadowOffsetX;
+  }
+
+  set shadowOffsetX(v) {
+    this._shadowOffsetX = v;
+    this.invalidateCache();
+  }
+
+  /**
+   * Gets the vertical offset of the drop shadow.
+   * @type {number}
+   */
+  get shadowOffsetY() {
+    return this._shadowOffsetY;
+  }
+
+  set shadowOffsetY(v) {
+    this._shadowOffsetY = v;
+    this.invalidateCache();
+  }
+
+  /**
+   * Total elapsed time this object has been alive (updated).
+   * @type {number}
+   * @readonly
+   */
+  get tick() {
+    return this._tick;
+  }
+
+  /**
+   * Whether render caching is enabled for this object.
+   * @type {boolean}
+   */
+  get cacheRendering() {
+    return this._cacheRendering;
+  }
+
+  set cacheRendering(v) {
+    this._cacheRendering = Boolean(v);
+    if (v) this.invalidateCache();
+  }
+}

package/src/shapes/ring.js

@@ -0,0 +1,26 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+export class Ring extends Shape {
+  constructor(outerRadius, innerRadius, options = {}) {
+    super(options);
+    this.outerRadius = outerRadius;
+    this.innerRadius = innerRadius;
+  }
+
+  draw() {
+    super.draw();
+    Painter.lines.beginPath();
+    Painter.shapes.arc(0, 0, this.outerRadius, 0, Math.PI * 2);
+    Painter.shapes.arc(0, 0, this.innerRadius, 0, Math.PI * 2, true);
+    Painter.lines.closePath();
+
+    if (this.color) {
+      Painter.colors.fill(this.color);
+    }
+
+    if (this.stroke) {
+      Painter.colors.stroke(this.stroke, this.lineWidth);
+    }
+  }
+}

package/src/shapes/roundrect.js

@@ -0,0 +1,95 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * RoundedRectangle - A drawable centered rectangle with rounded corners.
+ *
+ * Draws a rounded rectangle from its center using Painter.
+ */
+export class RoundedRectangle extends Shape {
+  /**
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} width - Rectangle width
+   * @param {number} height - Rectangle height
+   * @param {number|number[]} radii - Corner radius or array of radii for each corner
+   * @param {Object} [options] - Shape rendering options
+   */
+  constructor(radii = 0, options = {}) {
+    super(options);
+    // Handle radius either as a single value or array of 4 values
+    if (typeof radii === "number") {
+      this.radii = [radii, radii, radii, radii]; // [topLeft, topRight, bottomRight, bottomLeft]
+    } else if (Array.isArray(radii)) {
+      // Ensure we have exactly 4 values
+      this.radii =
+        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 {
+      this.radii = [0, 0, 0, 0];
+    }
+  }
+
+  /**
+   * Renders the rounded rectangle using Painter's roundRect method.
+   */
+  draw() {
+    super.draw();
+    const x = -this.width / 2;
+    const y = -this.height / 2;
+    // Use the Painter's roundRect utility methods
+    if (this.color && this.stroke) {
+      // If both fill and stroke are needed
+      Painter.shapes.roundRect(
+        x,
+        y,
+        this.width,
+        this.height,
+        this.radii,
+        this.color,
+        this.stroke,
+        this.lineWidth
+      );
+    } else if (this.color) {
+      // If only fill is needed
+      Painter.shapes.fillRoundRect(
+        x,
+        y,
+        this.width,
+        this.height,
+        this.radii,
+        this.color
+      );
+    } else if (this.stroke) {
+      // If only stroke is needed
+      Painter.shapes.strokeRoundRect(
+        x,
+        y,
+        this.width,
+        this.height,
+        this.radii,
+        this.stroke,
+        this.lineWidth
+      );
+    }
+  }
+
+  /**
+   * Returns the bounding box for the rounded rectangle
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  getBounds() {
+    return {
+      x: this.x,
+      y: this.y,
+      width: this.width,
+      height: this.height,
+    };
+  }
+}