@guinetik/gcanvas 1.0.0

package/src/shapes/cylinder.js

@@ -0,0 +1,254 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * Cylinder - A 3D-looking isometric cylinder with rotation support.
+ *
+ * Supports:
+ * - Top, bottom and side faces with individual colors
+ * - Full bounding box
+ * - Face visibility control
+ * - Rotation around X, Y, and Z axes
+ * - Adjustable segment count for smoother curves
+ *
+ * Note: This is a 2.5D visual illusion — not actual 3D rendering.
+ */
+export class Cylinder extends Shape {
+  /**
+   * Create a cylinder
+   * @param {number} radius - Radius of the cylinder
+   * @param {number} height - Height of the cylinder
+   * @param {object} options - Customization options
+   * @param {string} [options.topColor] - Color of the top face
+   * @param {string} [options.bottomColor] - Color of the bottom face
+   * @param {string} [options.sideColor] - Color of the side face
+   * @param {number} [options.segments] - Number of segments to approximate the curved surface
+   * @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(radius = 40, options = {}) {
+    super(options);
+    this.radius = radius;
+    this.height = options.height || 80;
+
+    // Number of segments used to approximate the circle
+    this.segments = options.segments || 24;
+
+    // Colors for each face
+    this.topColor = options.topColor || "#FF00FF";
+    this.bottomColor = options.bottomColor || "#FF0FFF";
+    this.sideColor = options.sideColor || "#00FF00";
+
+    this.stroke = options.stroke || "#000000";
+    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'|'side'>} */
+    this.visibleFaces = options.visibleFaces || ["top", "bottom", "side"];
+  }
+
+  /**
+   * 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 cylinder 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 r = this.radius;
+    const h = this.height / 2; // Half height 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, z: 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
+    };
+
+    // Generate points for top and bottom circles
+    const topPoints = [];
+    const bottomPoints = [];
+
+    // Calculate segment angle
+    const angleStep = (Math.PI * 2) / this.segments;
+
+    // Generate circle points
+    for (let i = 0; i < this.segments; i++) {
+      const angle = i * angleStep;
+      const x = Math.cos(angle) * r;
+      const y = Math.sin(angle) * r;
+
+      // Project 3D points to 2D
+      topPoints.push(iso(x, y, h));
+      bottomPoints.push(iso(x, y, -h));
+    }
+
+    // Create side faces (quads between top and bottom points)
+    const sideFaces = [];
+    for (let i = 0; i < this.segments; i++) {
+      const nextIdx = (i + 1) % this.segments;
+      sideFaces.push({
+        points: [
+          bottomPoints[i],
+          bottomPoints[nextIdx],
+          topPoints[nextIdx],
+          topPoints[i],
+        ],
+        // Each segment gets its own depth for proper sorting
+        z:
+          (topPoints[i].z +
+            topPoints[nextIdx].z +
+            bottomPoints[i].z +
+            bottomPoints[nextIdx].z) /
+          4,
+      });
+    }
+
+    // Prepare faces for depth sorting
+    const facesWithDepth = [];
+
+    // Add top face if visible
+    if (this.visibleFaces.includes("top")) {
+      facesWithDepth.push({
+        type: "top",
+        points: topPoints,
+        z: h, // Average Z of top face
+      });
+    }
+
+    // Add bottom face if visible
+    if (this.visibleFaces.includes("bottom")) {
+      facesWithDepth.push({
+        type: "bottom",
+        points: [...bottomPoints].reverse(), // Reverse for correct winding
+        z: -h, // Average Z of bottom face
+      });
+    }
+
+    // Add side faces if visible
+    if (this.visibleFaces.includes("side")) {
+      facesWithDepth.push(
+        ...sideFaces.map((face) => ({
+          type: "side",
+          points: face.points,
+          z: face.z,
+        }))
+      );
+    }
+
+    // Sort faces by depth (back to front)
+    facesWithDepth.sort((a, b) => b.z - a.z);
+
+    // Draw faces in depth order
+    for (const face of facesWithDepth) {
+      let color;
+
+      switch (face.type) {
+        case "top":
+          color = this.topColor;
+          break;
+        case "bottom":
+          color = this.bottomColor;
+          break;
+        case "side":
+          color = this.sideColor;
+          break;
+      }
+
+      Painter.shapes.polygon(
+        face.points,
+        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.radius * 2, this.height);
+    const adjustedSize = maxDimension * projectionFactor;
+
+    return {
+      x: this.x - adjustedSize / 2,
+      y: this.y - adjustedSize / 2,
+      width: adjustedSize,
+      height: adjustedSize,
+    };
+  }
+}

package/src/shapes/diamond.js

@@ -0,0 +1,48 @@
+// Diamond.js
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+/**
+ * Diamond - A drawable diamond-shaped canvas primitive.
+ *
+ * Draws a centered diamond using four points around its bounds.
+ * Uses Painter's polygon rendering under the hood.
+ *
+ * Limitations:
+ * - Not interactive or animated
+ * - For visual use only (wrap in a GameObject for dynamic behavior)
+ */
+export class Diamond extends Shape {
+  /**
+   * @param {number} x - Center X position
+   * @param {number} y - Center Y position
+   * @param {number} width - Total width of the diamond
+   * @param {number} height - Total height of the diamond
+   * @param {Object} [options] - Shape rendering options
+   */
+  constructor(options = {}) {
+    super(options);
+  }
+
+  /**
+   * Renders the diamond using four corner points.
+   */
+  draw() {
+    super.draw();
+    const halfW = this.width / 2;
+    const halfH = this.height / 2;
+
+    const points = [
+      { x: 0, y: -halfH }, // Top
+      { x: halfW, y: 0 }, // Right
+      { x: 0, y: halfH }, // Bottom
+      { x: -halfW, y: 0 }, // Left
+    ];
+
+    Painter.shapes.polygon(
+      points,
+      this.color,
+      this.stroke,
+      this.lineWidth
+    );
+  }
+}

package/src/shapes/euclidian.js

@@ -0,0 +1,111 @@
+import { Loggable } from "../logger/loggable";
+import { Painter } from "../painter/painter";
+/**
+ * Euclidian
+ * ----------
+ *
+ * The root of all drawable objects in the gcanvas engine.
+ *
+ * This class defines the fundamental spatial contract:
+ * - A 2D position in Euclidean space (`x`, `y`)
+ * - A size (`width`, `height`)
+ * - Optional debug rendering via `draw()` and `drawDebug()`
+ *
+ * ### Why This Exists
+ *
+ * Before something becomes a shape, a renderable, or a transformable object,
+ * it first **exists in space**. This class introduces that concept of space,
+ * without yet concerning itself with rendering pipelines, transformations,
+ * or bounding box calculations.
+ *
+ * ### Core Characteristics
+ *
+ * - Provides visual presence on the canvas by exposing spatial dimensions
+ * - Supports debug drawing for bounding boxes (green by default)
+ * - Serves as the base class for all shape, UI, and layout components
+ *
+ * This class is intended to be subclassed and never used directly.
+ *
+ * @abstract
+ * @extends Loggable
+ */
+export class Euclidian extends Loggable {
+  /**
+   * @param {Object} [options={}]
+   * @param {number} [options.x=0] - X position (center-based)
+   * @param {number} [options.y=0] - Y position (center-based)
+   * @param {number} [options.width=0] - Width in pixels
+   * @param {number} [options.height=0] - Height in pixels
+   * @param {boolean} [options.debug=false] - Enables visual debug overlay
+   * @param {string} [options.debugColor="#0f0"] - Outline color for debug box
+   */
+  constructor(options = {}) {
+    super(options);
+    this._x = typeof options.x === "number" ? options.x : 0;
+    this._y = typeof options.y === "number" ? options.y : 0;
+    this._width = typeof options.width === "number" ? options.width : 0;
+    this._height = typeof options.height === "number" ? options.height : 0;
+    this.logger.log("Euclidian", this._x, this._y, this._width, this._height);
+  }
+
+  /** @type {number} X center position in canvas space */
+  get x() {
+    return this._x;
+  }
+  set x(v) {
+    this.validateProp(v, "x");
+    this._x = v;
+  }
+
+  /** @type {number} Y center position in canvas space */
+  get y() {
+    return this._y;
+  }
+  set y(v) {
+    this.validateProp(v, "y");
+    this._y = v;
+  }
+
+  /** @type {number} Width of the object (must be ≥ 0) */
+  get width() {
+    return this._width;
+  }
+  set width(v) {
+    this.validateProp(v, "width");
+    this._width = Math.max(0, v);
+  }
+
+  /** @type {number} Height of the object (must be ≥ 0) */
+  get height() {
+    return this._height;
+  }
+  set height(v) {
+    this.validateProp(v, "height");
+    this._height = Math.max(0, v);
+  }
+
+  /** @type {boolean} Whether to draw the debug box outline */
+  get debug() {
+    return this._debug;
+  }
+  set debug(v) {
+    this.validateProp(v, "debug");
+    this._debug = Boolean(v);
+  }
+
+  /** @type {string} Color of the debug box (e.g. "#0f0" or "red") */
+  get debugColor() {
+    return this._debugColor;
+  }
+  set debugColor(v) {
+    this.validateProp(v, "debugColor");
+    this._debugColor = v;
+  }
+
+  validateProp(v, prop) {
+    //this.trace("Euclidian.validateProp " + prop + " = " + v);
+    if (v === undefined || v === null) {
+      throw new Error("Invalid property value: " + prop + " " + v);
+    }
+  }
+}

package/src/shapes/figure.js

@@ -0,0 +1,115 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+/**
+ * StickFigure - A simple humanoid stick figure composed of circles and lines.
+ * Good for demos, games, and jokes about bad posture.
+ */
+export class StickFigure extends Shape {
+  /**
+   * @param {number} x - X position (center of figure)
+   * @param {number} y - Y position (center of figure)
+   * @param {number} scale - Scale multiplier for size
+   * @param {object} options - Style options
+   * @param {string} [options.stroke="#000"] - Line color
+   * @param {string} [options.headColor] - Fill color of the head
+   * @param {string} [options.jointColor] - Fill color of joint circles
+   * @param {number} [options.lineWidth=2] - Line width
+   * @param {boolean} [options.showJoints=true] - Whether to draw joints
+   */
+  constructor(scale = 1, options = {}) {
+    super(options);
+    this.scale = scale;
+
+    this.stroke = options.stroke || "#000";
+    this.headColor = options.headColor || this.stroke;
+    this.jointColor = options.jointColor || this.stroke;
+    this.lineWidth = options.lineWidth || 2;
+    this.showJoints = options.showJoints !== false; // default to true
+  }
+
+  draw() {
+    super.draw();
+    const s = this.scale;
+    // Layout
+    const headR = 10 * s;
+    const headCenterY = -30 * s;
+    const neckY = headCenterY + headR;
+    const torsoTop = neckY;
+    const torsoBottom = torsoTop + 40 * s;
+    const armY = torsoTop + 10 * s;
+    const shoulderX = 15 * s;
+    const hipX = 10 * s;
+    const legY = torsoBottom + 40 * s;
+    const jointR = 3 * s;
+    // Head
+    Painter.shapes.fillCircle(0, headCenterY, headR, this.headColor);
+    Painter.shapes.strokeCircle(
+      0,
+      headCenterY,
+      headR,
+      this.stroke,
+      this.lineWidth
+    );
+    // Torso
+    Painter.lines.line(
+      0,
+      torsoTop,
+      0,
+      torsoBottom,
+      this.stroke,
+      this.lineWidth
+    );
+    // Arms
+    Painter.lines.line(
+      -shoulderX,
+      armY,
+      shoulderX,
+      armY,
+      this.stroke,
+      this.lineWidth
+    );
+    // Legs
+    Painter.lines.line(
+      0,
+      torsoBottom,
+      -hipX,
+      legY,
+      this.stroke,
+      this.lineWidth
+    );
+    Painter.lines.line(
+      0,
+      torsoBottom,
+      hipX,
+      legY,
+      this.stroke,
+      this.lineWidth
+    );
+    // Joints (optional)
+    if (this.showJoints) {
+      const joints = [
+        [0, torsoTop],
+        [-shoulderX, armY],
+        [shoulderX, armY],
+        [0, torsoBottom],
+        [-hipX, legY],
+        [hipX, legY],
+      ];
+      joints.forEach(([jx, jy]) =>
+        Painter.shapes.fillCircle(jx, jy, jointR, this.jointColor)
+      );
+    }
+  }
+
+  getBounds() {
+    const h = 100 * this.scale;
+    const w = 40 * this.scale;
+    return {
+      x: this.x,
+      y: this.y,
+      width: w,
+      height: h,
+    };
+  }
+}