@guinetik/gcanvas 1.0.0

package/src/game/objects/go.js

@@ -0,0 +1,220 @@
+import { Transformable } from "../../shapes/transformable.js";
+import { EventEmitter } from "../../io/index.js";
+import { applyAnchor } from "../../mixins/anchor.js";
+/**
+ * GameObject
+ * ----------
+ *
+ * A dynamic canvas entity with interactivity, state, and update/render lifecycle.
+ * Builds upon `Transformable` and adds:
+ * - Event handling via `EventEmitter`
+ * - Bounding box-based hit detection
+ * - Game instance linkage
+ * - Parent reference for scene graph traversal
+ *
+ * ### Modernized Interactivity
+ *
+ * Previous versions used a `Shape` for hit testing. This version uses
+ * the object's bounding box (`getBounds()`) for collision/interactivity.
+ *
+ * ### Event Model
+ * Events are managed via the internal emitter. Use:
+ * ```js
+ * obj.on("click", cb)
+ * obj.off("mouseover", cb)
+ * ```
+ *
+ * ### Typical Usage
+ * ```js
+ * const box = new GameObject(game, { x: 100, y: 100, width: 200, height: 80 });
+ * box.on("click", () => console.log("clicked"));
+ * ```
+ *
+ * @abstract
+ * @extends Transformable
+ */
+export class GameObject extends Transformable {
+  /**
+   * @param {Game} game - Game instance reference
+   * @param {Object} [options={}] - Configuration and styling
+   */
+  constructor(game, options = {}) {
+    super(options);
+    this.game = game;
+    this.parent = null;
+    /** @type {EventEmitter} */
+    this.events = new EventEmitter();
+    this._interactive = options.interactive ?? false;
+    this._hovered = false;
+    if (options.anchor) {
+      applyAnchor(this, options);
+    }
+  }
+
+  update(dt) {
+    this.logger.groupCollapsed(
+      "GameObject.update: " +
+        (this.name == undefined ? this.constructor.name : this.name)
+    );
+    super.update(dt);
+    this.logger.groupEnd();
+  }
+
+  /**
+   * Enable or disable hit-testing for this GameObject.
+   * When enabled, _hitTest() will run during interaction checks.
+   * @type {boolean}
+   */
+  get interactive() {
+    return this._interactive;
+  }
+
+  set interactive(value) {
+    const newValue = Boolean(value);
+
+    // Only proceed if there's an actual change
+    if (this._interactive !== newValue) {
+      // Store the new state
+      this._interactive = newValue;
+
+      if (newValue === true) {
+        // Object is becoming interactive
+        this._enableEvents();
+      } else {
+        // Object is becoming non-interactive
+        this._disableEvents();
+
+        // Also reset hover state if it was previously hovered
+        if (this._hovered) {
+          this._hovered = false;
+          this.events.emit("mouseout");
+        }
+      }
+    }
+  }
+
+  /**
+   * Enable event handling for this GameObject.
+   * @private
+   */
+  _enableEvents() {
+    // No need to create event handlers here
+    // The Pipeline class already handles dispatching events to interactive objects
+    // We just need to mark the object as interactive
+    this.logger.log(`${this.constructor.name} is now interactive`);
+  }
+
+  /**
+   * Disable event handling for this GameObject.
+   * @private
+   */
+  _disableEvents() {
+    // Clean up any specific event state
+    this.logger.log(`${this.constructor.name} is no longer interactive`);
+  }
+
+  /**
+   * True if the pointer is currently hovering over the object.
+   * @type {boolean}
+   * @readonly
+   */
+  get hovered() {
+    return this._hovered;
+  }
+
+  set hovered(value) {
+    this._hovered = Boolean(value);
+  }
+
+  /** Internal use by input system */
+  _setHovered(state) {
+    this._hovered = Boolean(state);
+  }
+
+  /**
+   * Test whether a given point lies inside the object's bounds,
+   * taking into account the full transformation hierarchy (position, rotation, scale).
+   *
+   * @param {number} x - X screen coordinate
+   * @param {number} y - Y screen coordinate
+   * @returns {boolean} True if the point is inside this object's bounds
+   */
+  _hitTest(x, y) {
+    if (!this._interactive) return false;
+
+    const bounds = this.getBounds?.();
+    if (!bounds) return false;
+
+    // Transform point from screen space to object's local space
+    let localX = x;
+    let localY = y;
+
+    // Build transform chain (from root to this object)
+    const transformChain = [];
+    let current = this;
+    while (current) {
+      transformChain.unshift(current);
+      current = current.parent;
+    }
+
+    // Apply inverse transforms in sequence (from root to object)
+    for (const obj of transformChain) {
+      // Translation: subtract object position
+      localX -= obj.x || 0;
+      localY -= obj.y || 0;
+
+      // Rotation: apply inverse rotation if needed
+      if (obj.rotation) {
+        const cos = Math.cos(-obj.rotation);
+        const sin = Math.sin(-obj.rotation);
+        const tempX = localX;
+        localX = tempX * cos - localY * sin;
+        localY = tempX * sin + localY * cos;
+      }
+
+      // Scale: apply inverse scale if needed
+      if (obj.scaleX !== undefined && obj.scaleX !== 0) {
+        localX /= obj.scaleX;
+      }
+      if (obj.scaleY !== undefined && obj.scaleY !== 0) {
+        localY /= obj.scaleY;
+      }
+    }
+
+    // Now check if the point is inside our local bounds
+    // Use bounds from getBounds() if available, otherwise fall back to this.width/height
+    const halfW = (bounds.width || this.width || 0) / 2;
+    const halfH = (bounds.height || this.height || 0) / 2;
+
+    return (
+      localX >= -halfW && localX <= halfW && localY >= -halfH && localY <= halfH
+    );
+  }
+
+  /**
+   * Attach an event handler.
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   */
+  on(event, callback) {
+    this.events.on(event, callback);
+  }
+
+  /**
+   * Remove an event handler.
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   */
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+
+  /**
+   * Dispatch an event manually.
+   * @param {string} event - Event name
+   * @param {...any} args - Event arguments
+   */
+  emit(event, ...args) {
+    this.events.emit(event, ...args);
+  }
+}

package/src/game/objects/imagego.js

@@ -0,0 +1,30 @@
+import { ImageShape } from "../../shapes/image";
+import { GameObjectShapeWrapper } from ".";
+
+export class ImageGo extends GameObjectShapeWrapper {
+  /**
+   * Quickly drop a bitmap into the pipeline.
+   *
+   * @param {Game}   game         – the main Game instance
+   * @param {ImageData|HTMLImageElement|HTMLCanvasElement|Uint8ClampedArray} bitmap
+   * @param {object} [options]    – BitmapShape & GO options (x, y, scale, anchor, …)
+   *
+   * The constructor:
+   * 1. creates / re‑uses a BitmapShape,
+   * 2. hands it to GameObjectShapeWrapper,
+   * 3. propagates any extra options (anchor, padding, debug …).
+   */
+  constructor(game, bitmap, options = {}) {
+    // If the user passed an existing BitmapShape we keep it,
+    // otherwise we fabricate one.
+    const shape =
+      bitmap instanceof ImageShape ? bitmap : new ImageShape(bitmap, options);
+    // GameObjectShapeWrapper keeps transform + render in sync with the shape
+    super(game, shape, options);
+    //console.log("imagego", this);
+  }
+
+  reset() {
+    this.shape.reset();
+  }
+}

package/src/game/objects/index.js

@@ -0,0 +1,54 @@
+/**
+ * @module GameObjects
+ * @description Specialized GameObjects providing common functionality for game development.
+ *
+ * This module exports a collection of pre-built GameObject classes that provide
+ * specific functionality commonly needed in games:
+ * - {@link Scene}: A container for organizing hierarchies of GameObjects
+ * - {@link Text}: A GameObject for rendering text with various styling options
+ *
+ * All classes in this module extend the core {@link GameObject} class and inherit
+ * its properties and lifecycle methods while adding specialized behaviors.
+ *
+ * @example
+ * // Using Scene to organize a group of related objects
+ * import { Game } from '../core/game.js';
+ * import { Scene, Text } from '../core/objects';
+ *
+ * class MyGame extends Game {
+ *   init() {
+ *     // Create a UI layer as a Scene
+ *     const uiLayer = new Scene(this, {
+ *       x: 0,
+ *       y: 0
+ *     });
+ *
+ *     // Add text elements to the scene
+ *     const scoreText = new Text(this, "Score: 0", {
+ *       x: 20,
+ *       y: 20,
+ *       font: "24px Arial",
+ *       color: "#ffffff"
+ *     });
+ *
+ *     uiLayer.add(scoreText);
+ *
+ *     // Add the entire scene to the pipeline
+ *     this.pipeline.add(uiLayer);
+ *   }
+ * }
+ *
+ * @see {@link GameObject} The base class for all objects in this module
+ */
+
+// Interactive abstracts
+export { GameObject } from "./go.js";
+export { GameObjectShapeWrapper, ShapeGOFactory } from "./wrapper.js";
+// Interactive Groups
+export { Scene } from "./scene.js";
+export { Scene3D } from "./scene3d.js";
+export { IsometricScene } from "./isometric-scene.js";
+export * from "./layoutscene.js";
+// Specialized GameObjects
+export { Text } from "./text.js";
+export { ImageGo } from "./imagego.js";

package/src/game/objects/isometric-scene.js

@@ -0,0 +1,260 @@
+import { Scene } from "./scene.js";
+import { Painter } from "../../painter/painter.js";
+
+/**
+ * IsometricScene - A Scene that projects children using isometric projection
+ *
+ * Bridges the GameObject/Scene system with isometric rendering, allowing GameObjects
+ * to be positioned in 3D grid space (x, y, z) and automatically projected to 2D
+ * isometric view using diamond projection.
+ *
+ * Children can have an optional `z` property for height above the ground plane.
+ * The scene handles depth sorting automatically based on isometric depth (x + y).
+ *
+ * Supports optional IsometricCamera for animated view rotation.
+ *
+ * @example
+ * // Basic usage
+ * const isoScene = new IsometricScene(this, {
+ *   x: this.width / 2,
+ *   y: this.height / 2,
+ *   tileWidth: 64,
+ *   tileHeight: 32,
+ *   depthSort: true,
+ * });
+ *
+ * // With camera for rotatable view
+ * const camera = new IsometricCamera({ rotationStep: Math.PI / 4 });
+ * isoScene.setCamera(camera);
+ * camera.rotateRight(); // Rotate view 45°
+ *
+ * const box = new IsometricBox(this, { x: 2, y: 3 });
+ * box.z = 0; // ground level
+ * isoScene.add(box);
+ *
+ * this.pipeline.add(isoScene);
+ *
+ * @extends Scene
+ */
+export class IsometricScene extends Scene {
+  /**
+   * @param {Game} game - Game instance
+   * @param {Object} options - Configuration
+   * @param {number} [options.tileWidth=64] - Width of a tile in the isometric grid (pixels)
+   * @param {number} [options.tileHeight] - Height of a tile (defaults to tileWidth / 2)
+   * @param {boolean} [options.depthSort=true] - Sort children by depth (back-to-front)
+   * @param {boolean} [options.scaleByDepth=false] - Scale children by perspective distance
+   * @param {number} [options.gridSize=10] - Size of the grid in tiles (used for scale calculations)
+   * @param {number} [options.elevationScale=1] - Multiplier for z-axis visual offset
+   * @param {IsometricCamera} [options.camera=null] - Optional camera for view rotation
+   */
+  constructor(game, options = {}) {
+    super(game, options);
+
+    /** @type {number} Width of a tile in pixels */
+    this.tileWidth = options.tileWidth ?? 64;
+
+    /** @type {number} Height of a tile in pixels (typically tileWidth / 2 for standard isometric) */
+    this.tileHeight = options.tileHeight ?? this.tileWidth / 2;
+
+    /** @type {boolean} Whether to sort children by depth (back-to-front) */
+    this.depthSort = options.depthSort ?? true;
+
+    /** @type {boolean} Whether to scale children by perspective distance */
+    this.scaleByDepth = options.scaleByDepth ?? false;
+
+    /** @type {number} Size of the grid in tiles (for scale calculations) */
+    this.gridSize = options.gridSize ?? 10;
+
+    /** @type {number} Multiplier for z-axis visual offset */
+    this.elevationScale = options.elevationScale ?? 1;
+
+    /** @type {IsometricCamera|null} Camera for view rotation */
+    this.camera = options.camera ?? null;
+  }
+
+  /**
+   * Set or update the camera reference
+   * @param {IsometricCamera} camera - Camera instance
+   * @returns {IsometricScene} this for chaining
+   */
+  setCamera(camera) {
+    this.camera = camera;
+    return this;
+  }
+
+  /**
+   * Convert 3D grid coordinates (x, y, z) to 2D isometric screen position.
+   *
+   * Uses the standard "diamond" isometric projection with camera rotation.
+   * Note: For best visual results, use 90° rotation steps (Math.PI/2).
+   * 45° rotations can cause visual flattening at certain angles.
+   *
+   * @param {number} x - Grid X coordinate
+   * @param {number} y - Grid Y coordinate
+   * @param {number} [z=0] - Height above ground plane
+   * @returns {{x: number, y: number, depth: number}} Screen position and depth for sorting
+   */
+  toIsometric(x, y, z = 0) {
+    // Apply camera rotation if present
+    let rotatedX = x;
+    let rotatedY = y;
+
+    if (this.camera) {
+      const angle = this.camera.angle;
+      const cos = Math.cos(angle);
+      const sin = Math.sin(angle);
+      rotatedX = x * cos - y * sin;
+      rotatedY = x * sin + y * cos;
+    }
+
+    const isoX = (rotatedX - rotatedY) * (this.tileWidth / 2);
+    const isoY = (rotatedX + rotatedY) * (this.tileHeight / 2) - z * this.elevationScale;
+
+    // Depth for sorting
+    const depth = rotatedX + rotatedY - z * 0.01;
+
+    return { x: isoX, y: isoY, depth };
+  }
+
+  /**
+   * Convert screen coordinates back to grid coordinates.
+   *
+   * Useful for mouse picking and tile selection.
+   * Note: This assumes z = 0 (ground plane).
+   * If a camera is attached, the inverse rotation is applied.
+   *
+   * @param {number} screenX - Screen X relative to scene center
+   * @param {number} screenY - Screen Y relative to scene center
+   * @returns {{x: number, y: number}} Grid coordinates
+   */
+  fromIsometric(screenX, screenY) {
+    // Inverse of the isometric transform (assuming z = 0)
+    const halfTileW = this.tileWidth / 2;
+    const halfTileH = this.tileHeight / 2;
+
+    // Get rotated grid coordinates
+    let rotatedX = (screenX / halfTileW + screenY / halfTileH) / 2;
+    let rotatedY = (screenY / halfTileH - screenX / halfTileW) / 2;
+
+    // Apply inverse camera rotation if present
+    if (this.camera) {
+      const angle = -this.camera.angle; // Negative for inverse
+      const cos = Math.cos(angle);
+      const sin = Math.sin(angle);
+      const x = rotatedX * cos - rotatedY * sin;
+      const y = rotatedX * sin + rotatedY * cos;
+      return { x, y };
+    }
+
+    return { x: rotatedX, y: rotatedY };
+  }
+
+  /**
+   * Update method - updates camera if attached
+   * @param {number} dt - Delta time in seconds
+   */
+  update(dt) {
+    super.update(dt);
+    
+    // Update camera animation
+    if (this.camera) {
+      this.camera.update(dt);
+    }
+  }
+
+  /**
+   * Get the tile coordinates at a given screen position (floored to integers).
+   *
+   * @param {number} screenX - Screen X relative to scene center
+   * @param {number} screenY - Screen Y relative to scene center
+   * @returns {{x: number, y: number}} Tile coordinates (integers)
+   */
+  getTileAt(screenX, screenY) {
+    const grid = this.fromIsometric(screenX, screenY);
+    return {
+      x: Math.floor(grid.x),
+      y: Math.floor(grid.y),
+    };
+  }
+
+  /**
+   * Calculate scale factor based on Y position (for perspective effect).
+   *
+   * Objects further "back" (higher y in grid) appear smaller.
+   *
+   * @param {number} y - Grid Y position
+   * @returns {number} Scale factor (0.7 to 1.3 range)
+   */
+  getDepthScale(y) {
+    const distanceFromCenter = Math.abs(y);
+    const maxDistance = this.gridSize;
+    // Range from 0.7 (far) to 1.3 (near)
+    return 0.7 + (distanceFromCenter / maxDistance) * 0.6;
+  }
+
+  /**
+   * Override Scene's render to provide isometric coordinate system.
+   *
+   * This method:
+   * 1. Translates to the scene's position (center of projection)
+   * 2. Depth-sorts children back-to-front by their grid position
+   * 3. Renders each child (children use toIsometric() for their own projection)
+   *
+   * Note: Children are responsible for calling toIsometric() in their render()
+   * method. This gives them full control over complex rendering (shadows, etc).
+   */
+  render() {
+    if (!this.visible) return;
+
+    Painter.save();
+
+    // Translate to the IsometricScene's position (e.g., center of screen)
+    // This defines the origin (0,0) of the isometric projection on the 2D canvas
+    Painter.translateTo(this.x, this.y);
+
+    // Build render list with depth info for sorting
+    const renderList = [];
+
+    for (const child of this._collection.getSortedChildren()) {
+      if (!child.visible) continue;
+
+      // Use custom isoDepth if available, otherwise calculate
+      let depth;
+      if (child.isoDepth !== undefined) {
+        depth = child.isoDepth;
+      } else {
+        // For moving objects, use z as height
+        const height = child.z ?? 0;
+        // Higher (x + y) = closer to viewer = higher depth = render later
+        // Higher z = on top = higher depth = render later
+        depth = (child.x + child.y) + height * 0.05;
+      }
+
+      renderList.push({
+        child,
+        depth,
+      });
+    }
+
+    // Depth sort: respect zIndex first, then isometric depth
+    // Lower depth (back) renders first, higher depth (front) renders last
+    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 a.depth - b.depth; // back-to-front by position
+      });
+    }
+
+    // Render each child - they handle their own projection via toIsometric()
+    for (const item of renderList) {
+      Painter.save();
+      item.child.render();
+      Painter.restore();
+    }
+
+    Painter.restore();
+  }
+}