@guinetik/gcanvas 1.0.0

package/src/game/objects/scene.js

@@ -0,0 +1,175 @@
+import { Painter } from "../../painter/painter.js";
+import { ZOrderedCollection } from "../../util/zindex.js";
+import { GameObject } from "./go.js";
+
+/**
+ * Scene - A Hierarchical Container for Game Objects
+ *
+ * ### Conceptual Overview
+ *
+ * The Scene class represents a complex spatial management system that goes beyond
+ * simple object containment. It serves as a specialized GameObject that:
+ *
+ * - Creates a local coordinate system
+ * - Manages spatial relationships between game objects
+ * - Provides dynamic bounds calculation
+ * - Handles rendering and updating of child objects
+ *
+ * ### Rendering Pipeline Integration
+ *
+ * The Scene operates as a crucial middleware in the rendering pipeline:
+ * 1. Inherits transformation capabilities from GameObject
+ * 2. Applies collective transformations to child objects
+ * 3. Calculates composite bounds dynamically
+ *
+ * @extends GameObject
+ */
+export class Scene extends GameObject {
+  constructor(game, options = {}) {
+    super(game, options);
+    // Create the z-ordered collection
+    this._collection = new ZOrderedCollection({
+      sortByZIndex: options.sortByZIndex || true,
+    });
+    this._collection._owner = this;
+    // Initialize dimensions and override properties
+    this._width = options.width ?? 0;
+    this._height = options.height ?? 0;
+    this.forceWidth = null; // CRITICAL: Initialize with null
+    this.forceHeight = null; // CRITICAL: Initialize with null
+    // Cache for natural dimensions
+    this._naturalWidth = null;
+    this._naturalHeight = null;
+    this.userDefinedDimensions = false;
+    if (options.width != undefined && options.height != undefined) {
+      this.userDefinedWidth = options.width;
+      this.userDefinedHeight = options.height;
+      this.userDefinedDimensions = true;
+    }
+  }
+
+  // Update method - update children and recalculate natural dimensions
+  update(dt) {
+    this.logger.groupCollapsed(
+      "Scene.update: " +
+        (this.name == undefined ? this.constructor.name : this.name)
+    );
+    // Update all active children
+    for (let i = 0; i < this.children.length; i++) {
+      const child = this.children[i];
+      if (child.active && child.update) {
+        child.update(dt);
+      }
+    }
+    super.update(dt);
+    this.logger.groupEnd();
+  }
+
+  // Add a GameObject to the scene and invalidate dimensions
+  add(go) {
+    if (go == null || go == undefined) {
+      throw new Error("GameObject is null or undefined");
+    }
+    if (go.parent != null) {
+      console.warn(
+        "This GameObject already has a parent. Consider removing it first."
+      );
+    }
+    go.parent = this;
+    this._collection.add(go);
+    this.markBoundsDirty();
+    // if the game object has an init method, call it
+    if (go.init) {
+      go.init();
+    }
+    return go;
+  }
+
+  markBoundsDirty() {
+    super.markBoundsDirty();
+    // Dirty the children's bounds
+    this.children.forEach((child) => {
+      child.markBoundsDirty();
+    });
+  }
+
+  /**
+   * Removes a GameObject from the Scene
+   *
+   * ### Removal Strategy
+   *
+   * #### Why Use Filter?
+   * - Creates a new array (immutable approach)
+   * - Ensures no direct mutation of the children array
+   *
+   * #### Parent Reference Clearing
+   * - Breaks the parent-child relationship
+   * - Allows the object to be re-parented elsewhere
+   *
+   * @param {GameObject} go - Game object to remove
+   */
+  remove(go) {
+    const result = this._collection.remove(go);
+    if (result) {
+      go.parent = null;
+      this.markBoundsDirty();
+    }
+    return result;
+  }
+
+  draw() {
+    super.draw();
+    this.logger.log("Scene.draw chilren:");
+    this._collection
+      .getSortedChildren()
+      .filter((obj) => obj.visible)
+      .map(function (obj) {
+        Painter.save();
+        obj.render();
+        Painter.restore();
+        return obj;
+      });
+  }
+
+  /**
+   * Returns debug bounds in local space (centered at origin).
+   * Used for debug drawing after transforms have been applied.
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  getDebugBounds() {
+    // Return bounds centered at local origin (0, 0)
+    // This works because debug is drawn after translation to scene's position
+    return {
+      width: this.width,
+      height: this.height,
+      x: -this.width / 2,
+      y: -this.height / 2,
+    };
+  }
+
+  bringToFront(go) {
+    return this._collection.bringToFront(go);
+  }
+
+  sendToBack(go) {
+    return this._collection.sendToBack(go);
+  }
+
+  bringForward(go) {
+    return this._collection.bringForward(go);
+  }
+
+  sendBackward(go) {
+    return this._collection.sendBackward(go);
+  }
+
+  clear() {
+    this._collection.children.forEach((go) => this.remove(go));
+    return this._collection.clear();
+  }
+
+  // Getter to access children
+  get children() {
+    return this._collection.children;
+  }
+}

package/src/game/objects/scene3d.js

@@ -0,0 +1,118 @@
+import { Scene } from "./scene.js";
+import { Painter } from "../../painter/painter.js";
+
+/**
+ * Scene3D - A Scene that projects children through Camera3D
+ *
+ * Bridges the GameObject/Scene system with Camera3D, allowing GameObjects
+ * to be positioned in 3D space and automatically projected through the camera.
+ *
+ * Children can have an optional `z` property (defaults to 0 if not present).
+ *
+ * @example
+ * const scene3d = new Scene3D(this, {
+ *   x: this.width / 2,
+ *   y: this.height / 2,
+ *   camera: this.camera,
+ *   depthSort: true,
+ * });
+ *
+ * const box = new MyBox(this, { x: -100, y: 0 });
+ * box.z = -50; // Behind center plane
+ * scene3d.add(box);
+ *
+ * this.pipeline.add(scene3d);
+ *
+ * @extends Scene
+ */
+export class Scene3D extends Scene {
+  /**
+   * @param {Game} game - Game instance
+   * @param {Object} options - Configuration
+   * @param {Camera3D} options.camera - Required Camera3D for projection
+   * @param {boolean} [options.depthSort=true] - Sort children by depth (back-to-front)
+   * @param {boolean} [options.scaleByDepth=true] - Scale children by perspective
+   */
+  constructor(game, options = {}) {
+    super(game, options);
+
+    if (!options.camera) {
+      throw new Error("Scene3D requires a camera option");
+    }
+
+    this.camera = options.camera;
+    this.depthSort = options.depthSort ?? true;
+    this.scaleByDepth = options.scaleByDepth ?? true;
+  }
+
+  /**
+   * Override Scene's draw to project children through Camera3D
+   */
+  render() {
+    // Do NOT call super.render() as it triggers the 2D Scene.draw() pass,
+    // causing double rendering (one 2D, one 3D).
+
+    if (!this.visible) return;
+
+    Painter.save();
+    // Translate to the Scene3D's position (e.g., center of screen)
+    // This defines the "origin" (0,0) of the 3D projection on the 2D canvas.
+    Painter.translateTo(this.x, this.y);
+
+    // Build render list with projections
+    const renderList = [];
+
+    for (const child of this._collection.getSortedChildren()) {
+      if (!child.visible) continue;
+
+      const z = child.z ?? 0;
+      const projected = this.camera.project(child.x, child.y, z);
+
+      // Cull if behind camera
+      if (projected.z < -this.camera.perspective + 10) continue;
+
+      renderList.push({
+        child,
+        x: projected.x,
+        y: projected.y,
+        z: projected.z,
+        scale: projected.scale,
+      });
+    }
+
+    // Sort order: respect zIndex first, then depth for subtle overlap stability.
+    // Higher zIndex should render later (on top).
+    if (this.depthSort) {
+      renderList.sort((a, b) => {
+        const za = a.child.zIndex ?? 0;
+        const zb = b.child.zIndex ?? 0;
+        if (za !== zb) return za - zb;
+        return b.z - a.z; // back-to-front by depth as tie-breaker
+      });
+    }
+
+    // Render each child at projected position
+    for (const item of renderList) {
+      Painter.save();
+
+      // 1. Move to the projected screen position
+      Painter.translateTo(item.x, item.y);
+
+      // 2. Apply perspective scale
+      if (this.scaleByDepth) {
+        Painter.ctx.scale(item.scale, item.scale);
+      }
+
+      // 3. Neutralize the child's own translation logic
+      // GameObject.render() will translate by (child.x, child.y).
+      // By applying (-child.x, -child.y) first (in the scaled context),
+      // we ensure the net visual position is exactly at (item.x, item.y).
+      Painter.translateTo(-item.child.x, -item.child.y);
+
+      item.child.render();
+      Painter.restore();
+    }
+
+    Painter.restore();
+  }
+}

package/src/game/objects/text.js

@@ -0,0 +1,221 @@
+/************************************************************
+ * Text.js
+ *
+ * A simple GameObject for drawing styled text on the canvas.
+ * Supports optional stroke, alignment, and baseline.
+ ************************************************************/
+
+import { GameObject } from "./go.js";
+import { GameObjectShapeWrapper } from "./wrapper.js";
+import { Painter } from "../../painter/painter.js";
+import { TextShape } from "../../shapes/text.js";
+
+/**
+ * Text - Renders a string onto the canvas using the Painter API.
+ * @extends GameObjectShapeWrapper
+ *
+ * Creates a GameObject that wraps a TextShape, providing a convenient API
+ * for text rendering with support for styling, alignment, and measurement.
+ *
+ * @example
+ * ```js
+ * const myText = new Text(game, "Hello World!", {
+ *   x: 100,
+ *   y: 50,
+ *   font: "20px Arial",
+ *   color: "#ff0",
+ *   align: "center",
+ *   baseline: "middle",
+ *   stroke: true,
+ *   strokeColor: "#000",
+ *   lineWidth: 2,
+ * });
+ * game.pipeline.add(myText);
+ * ```
+ */
+export class Text extends GameObjectShapeWrapper {
+  /**
+   * Create a Text component
+   * @param {Game} game - The main game instance
+   * @param {string} text - The text content to display
+   * @param {object} [options={}] - Configuration options
+   * @param {number} [options.x=0] - X-position
+   * @param {number} [options.y=0] - Y-position
+   * @param {string} [options.font="16px monospace"] - CSS-style font string
+   * @param {string} [options.color="#fff"] - Text color
+   * @param {string} [options.align="left"] - Text alignment
+   * @param {string} [options.baseline="top"] - Text baseline
+   * @param {boolean} [options.stroke=false] - Whether to stroke the text
+   * @param {string} [options.strokeColor="#000"] - Stroke color
+   * @param {number} [options.lineWidth=1] - Stroke width
+   * @param {boolean} [options.interactive=false] - Whether the text should be interactive
+   * @param {string} [options.anchor] - Optional anchor position (e.g., "top-left", "center")
+   * @param {number} [options.padding] - Padding when using anchors
+   */
+  constructor(game, text, options = {}) {
+    // Create the TextShape
+    const textShape = new TextShape(text, {
+      font: options.font || "16px monospace",
+      color: options.color || "yellow",
+      align: options.align || "left",
+      baseline: options.baseline || "top",
+      strokeColor: options.strokeColor || "#000",
+      lineWidth: options.lineWidth || 1,
+      debugColor: options.debugColor || "yellow",
+    });
+    // Pass the shape to the parent GameObjectShapeWrapper
+    super(game, textShape, options);
+    // Store reference to text-specific options for direct access
+    this._textOptions = {
+      font: options.font || "16px monospace",
+      color: options.color || "yellow",
+      align: options.align || "left",
+      baseline: options.baseline || "top",
+    };
+  }
+
+  /**
+   * Get the text content
+   * @returns {string} Current text
+   */
+  get text() {
+    return this.shape.text;
+  }
+
+  /**
+   * Set the text content
+   * @param {string} value - New text to display
+   */
+  set text(value) {
+    this.shape.text = value;
+    this.markBoundsDirty();
+  }
+
+  /**
+   * Get the font style
+   * @returns {string} Current font
+   */
+  get font() {
+    return this.shape.font;
+  }
+
+  /**
+   * Set the font style
+   * @param {string} value - New font style
+   */
+  set font(value) {
+    this.shape.font = value;
+    this._textOptions.font = value;
+    this.markBoundsDirty();
+  }
+
+  /**
+   * Get the text color
+   * @returns {string} Current color
+   */
+  get color() {
+    return this.shape.color;
+  }
+
+  /**
+   * Set the text color
+   * @param {string} value - New color
+   */
+  set color(value) {
+    this.shape.color = value;
+    this._textOptions.color = value;
+  }
+
+  /**
+   * Get text alignment
+   * @returns {string} Current alignment
+   */
+  get align() {
+    return this.shape.align;
+  }
+
+  /**
+   * Set text alignment
+   * @param {string} value - New alignment
+   */
+  set align(value) {
+    this.shape.align = value;
+    this._textOptions.align = value;
+    this.markBoundsDirty();
+  }
+
+  /**
+   * Get text baseline
+   * @returns {string} Current baseline
+   */
+  get baseline() {
+    return this.shape.baseline;
+  }
+
+  /**
+   * Set text baseline
+   * @param {string} value - New baseline
+   */
+  set baseline(value) {
+    this.shape.baseline = value;
+    this._textOptions.baseline = value;
+    this.markBoundsDirty();
+  }
+
+  /**
+   * Calculate the width based on the text content
+   * @returns {number} Approximate width of the text
+   */
+  measureWidth() {
+    if (!Painter.ctx) return 0;
+    const width = Painter.text.measureTextWidth(this.text, this.font);
+    return width;
+  }
+
+  /**
+   * Calculate the height based on the font size
+   * @returns {number} Approximate height of the text
+   */
+  measureHeight() {
+    if (!this.font) return 16; // Default font size as fallback
+
+    // Extract font size from font string (e.g., "16px Arial" → 16)
+    const fontSize = parseInt(this.font);
+    return isNaN(fontSize) ? 16 : fontSize;
+  }
+
+  /**
+   * Gets the text bounds accounting for alignment and baseline
+   * @returns {Object} Bounds object with { x, y, width, height }
+   */
+  getBounds() {
+    const bounds = super.getBounds();
+
+    // If the shape has alignment-aware bounds, use those
+    if (this.shape.getTextBounds) {
+      const textBounds = this.shape.getTextBounds();
+      return {
+        x: this.x,
+        y: this.y,
+        width: textBounds.width,
+        height: textBounds.height,
+      };
+    }
+
+    return bounds;
+  }
+
+  /**
+   * Updates the GameObject and the wrapped TextShape
+   * @param {number} dt - Delta time in seconds
+   */
+  update(dt) {
+    super.update(dt);
+
+    // Sync dimensions from the text shape
+    if (this.shape) {
+      this.width = this.shape.width || this.measureWidth();
+      this.height = this.shape.height || this.measureHeight();
+    }
+  }
+}