@guinetik/gcanvas 1.0.5 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guinetik/gcanvas",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "description": "A batteries-included 2D canvas framework for games and generative art",
   "main": "dist/gcanvas.es.js",
   "types": "types/index.d.ts",

package/readme.md

@@ -235,7 +235,7 @@ game.start(); // Start the game loop
 
 - `update(dt)` — Run game logic each frame
 - `render()` — Optional custom rendering 
-- Event handling through `enableInteractivity(shape)`
+- Event handling through the event emitter pattern
 
 This is the base class for all interactive entities:
 
@@ -244,7 +244,14 @@ class Player extends GameObject {
   constructor(game) {
     super(game);
     this.shape = new Circle(100, 100, 40, { fillColor: "blue" });
-    this.enableInteractivity(this.shape);
+    
+    // Enable interactivity
+    this.interactive = true;
+    
+    // Listen for input events
+    this.on('inputdown', (e) => {
+      console.log('Player clicked!');
+    });
   }
   
   update(dt) {
@@ -257,10 +264,6 @@ class Player extends GameObject {
   render() {
     this.shape.draw();
   }
-  
-  onPointerDown(e) {
-    console.log('Player clicked!');
-  }
 }
 ```
 
@@ -396,21 +399,26 @@ The `Tweenetik` system animates object properties directly over time using easin
 
 ```js
 // Animate a button when pressed
-onPointerDown() {
-  Tweenetik.to(this.shape, 
-    { scaleX: 1.2, scaleY: 1.2 }, 
-    0.2, 
-    Easing.easeOutBack,
-    {
-      onComplete: () => {
-        Tweenetik.to(this.shape, 
-          { scaleX: 1.0, scaleY: 1.0 }, 
-          0.3, 
-          Easing.easeInOutQuad
-        );
+constructor(game) {
+  super(game);
+  this.interactive = true;
+  
+  this.on('inputdown', () => {
+    Tweenetik.to(this.shape, 
+      { scaleX: 1.2, scaleY: 1.2 }, 
+      0.2, 
+      Easing.easeOutBack,
+      {
+        onComplete: () => {
+          Tweenetik.to(this.shape, 
+            { scaleX: 1.0, scaleY: 1.0 }, 
+            0.3, 
+            Easing.easeInBack
+          );
+        }
       }
-    }
-  );
+    );
+  });
 }
 ```
 
@@ -545,7 +553,7 @@ class Bob extends GameObject {
   constructor(game) {
     super(game);
     this.shape = new Circle(100, 100, 40, { fillColor: "tomato" });
-    this.enableInteractivity(this.shape);
+    this.interactive = true;
   }
 
   update(dt) {
@@ -575,7 +583,7 @@ class SpinningShape extends GameObject {
   constructor(game) {
     super(game);
     this.shape = new Circle(200, 200, 50, { fillColor: 'cyan' });
-    this.enableInteractivity(this.shape);
+    this.interactive = true;
     this.hovered = false;
 
     this.on('mouseover', () => this.hovered = true);

package/src/game/objects/go.js

@@ -163,6 +163,13 @@ export class GameObject extends Transformable {
       localX -= obj.x || 0;
       localY -= obj.y || 0;
 
+      // Apply additional hit test offset (e.g., scroll offset from LayoutScene)
+      if (obj.getHitTestOffset) {
+        const offset = obj.getHitTestOffset();
+        localX -= offset.x || 0;
+        localY -= offset.y || 0;
+      }
+
       // Rotation: apply inverse rotation if needed
       if (obj.rotation) {
         const cos = Math.cos(-obj.rotation);

package/src/game/objects/index.js

@@ -56,3 +56,5 @@ export { Sprite } from "./sprite.js";
 export { SpriteSheet } from "./spritesheet.js";
 export { Text } from "./text.js";
 export { ImageGo } from "./imagego.js";
+// Utilities
+export { Mask } from "./mask.js";

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

@@ -178,6 +178,46 @@ export class IsometricScene extends Scene {
     };
   }
 
+  /**
+   * Compute depth value for sorting, accounting for camera rotation.
+   * Use this when implementing custom isoDepth getters for box-like objects.
+   *
+   * For a rectangular object, pass all 4 corners and this will return
+   * the depth of the "front" corner (highest rotated x+y) at the current camera angle.
+   *
+   * @param {Array<{x: number, y: number}>} corners - Array of corner positions in grid coords
+   * @param {number} [height=0] - Height of object for z-ordering
+   * @returns {number} Depth value for sorting
+   *
+   * @example
+   * // In a custom GameObject with grid position and size:
+   * get isoDepth() {
+   *   const corners = [
+   *     { x: this.gridX, y: this.gridY },
+   *     { x: this.gridX + this.width, y: this.gridY },
+   *     { x: this.gridX, y: this.gridY + this.depth },
+   *     { x: this.gridX + this.width, y: this.gridY + this.depth },
+   *   ];
+   *   return this.isoScene.getRotatedDepth(corners, this.height);
+   * }
+   */
+  getRotatedDepth(corners, height = 0) {
+    const angle = this.camera ? this.camera.angle : 0;
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+
+    let maxDepth = -Infinity;
+    for (const c of corners) {
+      const rotatedX = c.x * cos - c.y * sin;
+      const rotatedY = c.x * sin + c.y * cos;
+      const depth = rotatedX + rotatedY;
+      if (depth > maxDepth) maxDepth = depth;
+    }
+
+    // Height factor of 0.5 matches demo for proper depth sorting
+    return maxDepth + height * 0.5;
+  }
+
   /**
    * Calculate scale factor based on Y position (for perspective effect).
    *
@@ -219,16 +259,26 @@ export class IsometricScene extends Scene {
     for (const child of this._collection.getSortedChildren()) {
       if (!child.visible) continue;
 
-      // Use custom isoDepth if available, otherwise calculate
+      // Use custom isoDepth if available, otherwise calculate using rotated coords
       let depth;
       if (child.isoDepth !== undefined) {
         depth = child.isoDepth;
       } else {
+        // Apply camera rotation to get correct depth at all angles
+        let rotatedX = child.x;
+        let rotatedY = child.y;
+        if (this.camera) {
+          const angle = this.camera.angle;
+          const cos = Math.cos(angle);
+          const sin = Math.sin(angle);
+          rotatedX = child.x * cos - child.y * sin;
+          rotatedY = child.x * sin + child.y * cos;
+        }
         // For moving objects, use z as height
         const height = child.z ?? 0;
-        // Higher (x + y) = closer to viewer = higher depth = render later
+        // Higher (rotatedX + rotatedY) = closer to viewer = higher depth = render later
         // Higher z = on top = higher depth = render later
-        depth = (child.x + child.y) + height * 0.05;
+        depth = (rotatedX + rotatedY) + height * 0.05;
       }
 
       renderList.push({

package/src/game/objects/layoutscene.js

@@ -431,6 +431,63 @@ export class LayoutScene extends Scene {
     this._scrollOffset = { x: 0, y: 0 };
     this._scrollVelocity = { x: 0, y: 0 };
   }
+
+  /**
+   * Returns scroll offset for hit testing coordinate transformation.
+   * @returns {{x: number, y: number}} Scroll offset to apply
+   */
+  getHitTestOffset() {
+    if (!this.scrollable) {
+      return { x: 0, y: 0 };
+    }
+    return {
+      x: this._scrollOffset?.x || 0,
+      y: this._scrollOffset?.y || 0,
+    };
+  }
+
+  /**
+   * Checks if a child is within the visible viewport and should be hittable.
+   * @param {GameObject} child - The child to check
+   * @returns {boolean} True if child is within viewport
+   */
+  isChildHittable(child) {
+    // If not scrollable or doesn't need scrolling, all children are hittable
+    if (!this.scrollable || !this._needsScrolling()) {
+      return true;
+    }
+
+    const axis = this.getScrollAxis();
+    const vpW = this._viewportWidth ?? this.width;
+    const vpH = this._viewportHeight ?? this.height;
+    const scrollX = this._scrollOffset?.x || 0;
+    const scrollY = this._scrollOffset?.y || 0;
+
+    // Child position with scroll applied (relative to viewport center)
+    const childScrolledX = child.x + scrollX;
+    const childScrolledY = child.y + scrollY;
+
+    // Get child dimensions (use half for centered bounds check)
+    const childHalfW = (child.width || 0) / 2;
+    const childHalfH = (child.height || 0) / 2;
+
+    // Check if child overlaps with viewport
+    if (axis.horizontal) {
+      // Child right edge must be past viewport left, child left edge must be before viewport right
+      if (childScrolledX + childHalfW < -vpW / 2 || childScrolledX - childHalfW > vpW / 2) {
+        return false;
+      }
+    }
+
+    if (axis.vertical) {
+      // Child bottom edge must be past viewport top, child top edge must be before viewport bottom
+      if (childScrolledY + childHalfH < -vpH / 2 || childScrolledY - childHalfH > vpH / 2) {
+        return false;
+      }
+    }
+
+    return true;
+  }
 }
 
 // HorizontalLayout with clean implementation

package/src/game/objects/mask.js

@@ -0,0 +1,241 @@
+/**
+ * Mask - Clipping mask for scenes and game objects
+ *
+ * Supports multiple shapes with animatable properties:
+ * - circle: radius
+ * - rectangle: width, height, cornerRadius
+ * - ellipse: radiusX, radiusY
+ * - path: custom path function
+ *
+ * @example
+ * // Create a circular mask that grows
+ * const mask = new Mask({
+ *   shape: 'circle',
+ *   x: game.width / 2,
+ *   y: game.height / 2,
+ *   radius: 0,
+ * });
+ *
+ * // Animate the radius
+ * mask.radius = 100;
+ *
+ * // Apply to context
+ * mask.apply(ctx);
+ * // ... render masked content ...
+ * mask.remove(ctx);
+ */
+export class Mask {
+  constructor(options = {}) {
+    // Shape type
+    this.shape = options.shape || 'circle';
+
+    // Position (center point)
+    this.x = options.x ?? 0;
+    this.y = options.y ?? 0;
+
+    // Scale (multiplies dimensions)
+    this.scaleX = options.scaleX ?? 1;
+    this.scaleY = options.scaleY ?? 1;
+
+    // Circle properties
+    this.radius = options.radius ?? 100;
+
+    // Rectangle properties
+    this.width = options.width ?? 200;
+    this.height = options.height ?? 200;
+    this.cornerRadius = options.cornerRadius ?? 0;
+
+    // Ellipse properties
+    this.radiusX = options.radiusX ?? 100;
+    this.radiusY = options.radiusY ?? 100;
+
+    // Custom path function: (ctx, mask) => void
+    this.pathFn = options.pathFn ?? null;
+
+    // Invert the mask (show outside, hide inside)
+    this.invert = options.invert ?? false;
+
+    // Track if currently applied (for safety)
+    this._applied = false;
+  }
+
+  /**
+   * Apply the mask to a canvas context
+   * @param {CanvasRenderingContext2D} ctx - The canvas context
+   */
+  apply(ctx) {
+    if (this._applied) {
+      console.warn('Mask already applied. Call remove() first.');
+      return;
+    }
+
+    ctx.save();
+    ctx.beginPath();
+
+    if (this.invert) {
+      // For inverted mask, draw full canvas then cut out the shape
+      // This requires knowing the canvas size, so we use a large rect
+      ctx.rect(-10000, -10000, 20000, 20000);
+      this._drawPath(ctx);
+      // evenodd fill rule creates the "hole"
+      ctx.clip('evenodd');
+    } else {
+      this._drawPath(ctx);
+      ctx.clip();
+    }
+
+    this._applied = true;
+  }
+
+  /**
+   * Remove the mask (restore context)
+   * @param {CanvasRenderingContext2D} ctx - The canvas context
+   */
+  remove(ctx) {
+    if (!this._applied) {
+      return;
+    }
+    ctx.restore();
+    this._applied = false;
+  }
+
+  /**
+   * Draw the mask path (internal)
+   * @param {CanvasRenderingContext2D} ctx
+   */
+  _drawPath(ctx) {
+    const sx = this.scaleX;
+    const sy = this.scaleY;
+
+    switch (this.shape) {
+      case 'circle':
+        // Use average scale for circle
+        const scale = (sx + sy) / 2;
+        ctx.arc(this.x, this.y, this.radius * scale, 0, Math.PI * 2);
+        break;
+
+      case 'rectangle':
+        const w = this.width * sx;
+        const h = this.height * sy;
+        const cr = this.cornerRadius * Math.min(sx, sy);
+
+        if (cr > 0) {
+          // Rounded rectangle
+          this._roundedRect(ctx, this.x - w/2, this.y - h/2, w, h, cr);
+        } else {
+          // Simple rectangle
+          ctx.rect(this.x - w/2, this.y - h/2, w, h);
+        }
+        break;
+
+      case 'ellipse':
+        ctx.ellipse(this.x, this.y, this.radiusX * sx, this.radiusY * sy, 0, 0, Math.PI * 2);
+        break;
+
+      case 'path':
+        if (this.pathFn) {
+          this.pathFn(ctx, this);
+        }
+        break;
+
+      default:
+        console.warn(`Unknown mask shape: ${this.shape}`);
+    }
+  }
+
+  /**
+   * Draw a rounded rectangle path
+   * @param {CanvasRenderingContext2D} ctx
+   * @param {number} x
+   * @param {number} y
+   * @param {number} w
+   * @param {number} h
+   * @param {number} r - Corner radius
+   */
+  _roundedRect(ctx, x, y, w, h, r) {
+    // Clamp corner radius to half of smallest dimension
+    r = Math.min(r, w / 2, h / 2);
+
+    ctx.moveTo(x + r, y);
+    ctx.lineTo(x + w - r, y);
+    ctx.arcTo(x + w, y, x + w, y + r, r);
+    ctx.lineTo(x + w, y + h - r);
+    ctx.arcTo(x + w, y + h, x + w - r, y + h, r);
+    ctx.lineTo(x + r, y + h);
+    ctx.arcTo(x, y + h, x, y + h - r, r);
+    ctx.lineTo(x, y + r);
+    ctx.arcTo(x, y, x + r, y, r);
+    ctx.closePath();
+  }
+
+  /**
+   * Set position
+   * @param {number} x
+   * @param {number} y
+   * @returns {Mask} this for chaining
+   */
+  setPosition(x, y) {
+    this.x = x;
+    this.y = y;
+    return this;
+  }
+
+  /**
+   * Set uniform scale
+   * @param {number} scale
+   * @returns {Mask} this for chaining
+   */
+  setScale(scale) {
+    this.scaleX = scale;
+    this.scaleY = scale;
+    return this;
+  }
+
+  /**
+   * Set non-uniform scale
+   * @param {number} sx
+   * @param {number} sy
+   * @returns {Mask} this for chaining
+   */
+  setScaleXY(sx, sy) {
+    this.scaleX = sx;
+    this.scaleY = sy;
+    return this;
+  }
+
+  /**
+   * Create a circle mask
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} radius
+   * @returns {Mask}
+   */
+  static circle(x, y, radius) {
+    return new Mask({ shape: 'circle', x, y, radius });
+  }
+
+  /**
+   * Create a rectangle mask
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} width
+   * @param {number} height
+   * @param {number} cornerRadius - Optional rounded corners
+   * @returns {Mask}
+   */
+  static rectangle(x, y, width, height, cornerRadius = 0) {
+    return new Mask({ shape: 'rectangle', x, y, width, height, cornerRadius });
+  }
+
+  /**
+   * Create an ellipse mask
+   * @param {number} x - Center X
+   * @param {number} y - Center Y
+   * @param {number} radiusX
+   * @param {number} radiusY
+   * @returns {Mask}
+   */
+  static ellipse(x, y, radiusX, radiusY) {
+    return new Mask({ shape: 'ellipse', x, y, radiusX, radiusY });
+  }
+}

package/src/game/objects/scene.js

@@ -186,4 +186,23 @@ export class Scene extends GameObject {
   get children() {
     return this._collection.children;
   }
+
+  /**
+   * Returns additional offset to apply during hit testing.
+   * Override in subclasses (e.g., LayoutScene) to account for scroll offset.
+   * @returns {{x: number, y: number}} Additional offset for hit test coordinate transform
+   */
+  getHitTestOffset() {
+    return { x: 0, y: 0 };
+  }
+
+  /**
+   * Checks if a child should be hittable (receive input events).
+   * Override in subclasses (e.g., LayoutScene) to implement viewport culling.
+   * @param {GameObject} child - The child to check
+   * @returns {boolean} True if child should be hittable
+   */
+  isChildHittable(child) {
+    return true;
+  }
 }

package/src/game/objects/wrapper.js

@@ -68,7 +68,13 @@ export class GameObjectShapeWrapper extends GameObject {
    * @param {Object} options - Configuration options
    */
   constructor(game, shape, options = {}) {
-    super(game, options);
+    // IMPORTANT: Strip 'anchor' from options passed to GameObject
+    // In shape context, 'anchor' means "image rendering anchor" (center, top-left, etc.)
+    // In GameObject, 'anchor' triggers applyAnchor mixin for auto-positioning
+    // These are different concepts - don't let shape anchor trigger positioning
+    const { anchor: _shapeAnchor, ...goOptions } = options;
+
+    super(game, goOptions);
 
     // Validate shape
     if (!shape || shape == null || shape == undefined) {
@@ -224,9 +230,15 @@ export class GameObjectShapeWrapper extends GameObject {
 
   /**
    * Draw method to render the shape
+   *
+   * IMPORTANT: Call shape.draw() NOT shape.render()!
+   * The wrapper's render() has already translated to (this.x, this.y).
+   * Calling shape.render() would call Painter.translateTo(shape.x, shape.y)
+   * which OVERWRITES (not adds to) the current translation.
+   * By calling shape.draw() directly, we render at the wrapper's position.
    */
   draw() {
     super.draw();
-    this.shape.render();
+    this.shape.draw();
   }
 }

package/src/game/pipeline.js

@@ -78,6 +78,17 @@ export class Pipeline extends Loggable {
     if (scene.children && scene.children.length > 0) {
       for (let i = scene.children.length - 1; i >= 0; i--) {
         const child = scene.children[i];
+
+        // Check if child is hittable (e.g., within viewport for scrollable layouts)
+        if (scene.isChildHittable && !scene.isChildHittable(child)) {
+          // Force mouseout if child was hovered but is now outside viewport
+          if (child._hovered) {
+            child._hovered = false;
+            child.events.emit("mouseout", e);
+          }
+          continue;
+        }
+
         if (child instanceof Scene) {
           this._hoverScene(child, e); // recurse into nested scenes
         } else {
@@ -152,6 +163,12 @@ export class Pipeline extends Loggable {
     // First check children (they render on top, so should get priority)
     for (let i = scene.children.length - 1; i >= 0; i--) {
       const child = scene.children[i];
+
+      // Check if child is hittable (e.g., within viewport for scrollable layouts)
+      if (scene.isChildHittable && !scene.isChildHittable(child)) {
+        continue;
+      }
+
       if (child instanceof Scene) {
         // Recurse deeper if child is also a Scene
         const hit = this._dispatchToScene(child, type, e);