@guinetik/gcanvas 1.0.0

package/src/game/ui/tooltip.js

@@ -0,0 +1,249 @@
+import { GameObject } from "../objects/go.js";
+import { Rectangle, TextShape, Group } from "../../shapes/index.js";
+
+/**
+ * Tooltip
+ *
+ * A GameObject that displays text near the cursor when shown.
+ * Supports multiline text with automatic word wrapping.
+ *
+ * Usage:
+ *   const tooltip = new Tooltip(game, { ... });
+ *   game.pipeline.add(tooltip);
+ *
+ *   // On hover:
+ *   tooltip.show("Hello world", e.x, e.y);
+ *
+ *   // On mouse out:
+ *   tooltip.hide();
+ */
+export class Tooltip extends GameObject {
+  /**
+   * @param {Game} game - The main game instance.
+   * @param {object} [options={}] - Configuration options.
+   * @param {string} [options.font="12px monospace"] - Font for the text.
+   * @param {string} [options.textColor="#fff"] - Text color.
+   * @param {string} [options.bgColor="rgba(0,0,0,0.85)"] - Background color.
+   * @param {string} [options.borderColor="rgba(255,255,255,0.3)"] - Border color.
+   * @param {number} [options.padding=8] - Padding inside the tooltip.
+   * @param {number} [options.offsetX=15] - X offset from cursor.
+   * @param {number} [options.offsetY=15] - Y offset from cursor.
+   * @param {number} [options.maxWidth=300] - Maximum width before wrapping.
+   * @param {number} [options.lineHeight=1.4] - Line height multiplier.
+   */
+  constructor(game, options = {}) {
+    super(game, { ...options, zIndex: 9999 }); // Always on top
+
+    this.font = options.font || "12px monospace";
+    this.textColor = options.textColor || "#fff";
+    this.bgColor = options.bgColor || "rgba(0,0,0,0.85)";
+    this.borderColor = options.borderColor || "rgba(255,255,255,0.3)";
+    this.padding = options.padding ?? 8;
+    this.offsetX = options.offsetX ?? 15;
+    this.offsetY = options.offsetY ?? 15;
+    this.maxWidth = options.maxWidth ?? 300;
+    this.lineHeightMultiplier = options.lineHeight ?? 1.4;
+
+    // Current text and wrapped lines
+    this._text = "";
+    this._lines = [];
+    this._visible = false;
+
+    // Create background shape
+    this.bg = new Rectangle({
+      width: 100,
+      height: 30,
+      color: this.bgColor,
+      stroke: this.borderColor,
+      lineWidth: 1,
+    });
+
+    // Line shapes will be created dynamically
+    this.lineShapes = [];
+
+    this.group = new Group();
+    this.group.add(this.bg);
+
+    // Follow mouse
+    this.game.events.on("inputmove", (e) => {
+      if (this._visible) {
+        this.updatePosition(e.x, e.y);
+      }
+    });
+  }
+
+  /**
+   * Wrap text into multiple lines based on maxWidth.
+   * @param {string} text - Text to wrap.
+   * @returns {string[]} Array of lines.
+   */
+  wrapText(text) {
+    const ctx = this.game.ctx;
+    ctx.font = this.font;
+
+    const lines = [];
+    // Split by explicit newlines first
+    const paragraphs = text.split("\n");
+
+    for (const paragraph of paragraphs) {
+      const words = paragraph.split(" ");
+      let currentLine = "";
+
+      for (const word of words) {
+        const testLine = currentLine ? `${currentLine} ${word}` : word;
+        const metrics = ctx.measureText(testLine);
+
+        if (metrics.width > this.maxWidth && currentLine) {
+          lines.push(currentLine);
+          currentLine = word;
+        } else {
+          currentLine = testLine;
+        }
+      }
+
+      if (currentLine) {
+        lines.push(currentLine);
+      } else if (paragraph === "") {
+        lines.push(""); // Preserve empty lines
+      }
+    }
+
+    return lines;
+  }
+
+  /**
+   * Show the tooltip with the given text at the specified position.
+   * @param {string} text - Text to display (supports newlines and auto-wrapping).
+   * @param {number} [mouseX] - X position (defaults to current mouse).
+   * @param {number} [mouseY] - Y position (defaults to current mouse).
+   */
+  show(text, mouseX, mouseY) {
+    this._text = text;
+    this._visible = true;
+
+    // Wrap text into lines
+    this._lines = this.wrapText(text);
+
+    // Create/update line shapes
+    this.updateLineShapes();
+
+    // Measure text to size background
+    this.updateSize();
+
+    if (mouseX !== undefined && mouseY !== undefined) {
+      this.updatePosition(mouseX, mouseY);
+    }
+  }
+
+  /**
+   * Create or update TextShape objects for each line.
+   */
+  updateLineShapes() {
+    // Remove old line shapes from group
+    for (const shape of this.lineShapes) {
+      this.group.remove(shape);
+    }
+
+    // Create new line shapes
+    this.lineShapes = this._lines.map(
+      (line) =>
+        new TextShape(line, {
+          font: this.font,
+          color: this.textColor,
+          align: "left",
+          baseline: "top",
+        })
+    );
+
+    // Add to group
+    for (const shape of this.lineShapes) {
+      this.group.add(shape);
+    }
+  }
+
+  /**
+   * Hide the tooltip.
+   */
+  hide() {
+    this._visible = false;
+  }
+
+  /**
+   * Update the tooltip position, keeping it on screen.
+   * Positions tooltip so its top-left is at cursor + offset.
+   * @param {number} mouseX - Mouse X position.
+   * @param {number} mouseY - Mouse Y position.
+   */
+  updatePosition(mouseX, mouseY) {
+    const width = this.bg.width;
+    const height = this.bg.height;
+
+    // Position so top-left corner is at cursor + offset
+    // (since tooltip renders centered, add half width/height)
+    let x = mouseX + this.offsetX + width / 2;
+    let y = mouseY + this.offsetY + height / 2;
+
+    // Keep tooltip on screen - adjust if going off right edge
+    if (x + width / 2 > this.game.width) {
+      x = mouseX - this.offsetX - width / 2;
+    }
+
+    // Adjust if going off bottom edge
+    if (y + height / 2 > this.game.height) {
+      y = mouseY - this.offsetY - height / 2;
+    }
+
+    // Adjust if going off left edge
+    if (x - width / 2 < 0) {
+      x = width / 2 + 5;
+    }
+
+    // Adjust if going off top edge
+    if (y - height / 2 < 0) {
+      y = height / 2 + 5;
+    }
+
+    this.x = x;
+    this.y = y;
+  }
+
+  /**
+   * Update the background size based on wrapped text lines.
+   */
+  updateSize() {
+    const ctx = this.game.ctx;
+    ctx.font = this.font;
+
+    // Find widest line
+    let maxLineWidth = 0;
+    for (const line of this._lines) {
+      const metrics = ctx.measureText(line);
+      maxLineWidth = Math.max(maxLineWidth, metrics.width);
+    }
+
+    const textWidth = Math.min(maxLineWidth, this.maxWidth);
+    const fontSize = parseInt(this.font);
+    const lineHeight = fontSize * this.lineHeightMultiplier;
+    const textHeight = lineHeight * this._lines.length;
+
+    this.bg.width = textWidth + this.padding * 2;
+    this.bg.height = textHeight + this.padding * 2;
+
+    // Position each line inside bg
+    const startX = -this.bg.width / 2 + this.padding;
+    const startY = -this.bg.height / 2 + this.padding;
+
+    for (let i = 0; i < this.lineShapes.length; i++) {
+      this.lineShapes[i].x = startX;
+      this.lineShapes[i].y = startY + i * lineHeight;
+    }
+  }
+
+  /**
+   * Render the tooltip if visible.
+   */
+  draw() {
+    if (!this._visible) return;
+    this.group.render();
+  }
+}

package/src/index.js

@@ -0,0 +1,25 @@
+export * from "./util";
+export * from "./math";
+export * from "./logger";
+export * from "./painter";
+export * from "./shapes";
+export * from "./io";
+export * from "./game";
+export * from "./motion";
+export * from "./mixins";
+
+// Fluent API
+export * from "./fluent";
+export * from "./sound";
+
+// Collision detection
+export * from "./collision";
+
+// State management
+export * from "./state";
+
+// Particle system
+export * from "./particle";
+
+// WebGL (optional, for shader effects)
+export * from "./webgl";

package/src/io/events.js

@@ -0,0 +1,20 @@
+export class EventEmitter {
+  constructor() {
+    this.listeners = {};
+  }
+
+  on(type, callback) {
+    if (!this.listeners[type]) this.listeners[type] = [];
+    this.listeners[type].push(callback);
+  }
+
+  off(type, callback) {
+    if (!this.listeners[type]) return;
+    this.listeners[type] = this.listeners[type].filter((cb) => cb !== callback);
+  }
+
+  emit(type, payload) {
+    if (!this.listeners[type]) return;
+    this.listeners[type].forEach((cb) => cb(payload));
+  }
+}

package/src/io/index.js

@@ -0,0 +1,86 @@
+/**
+ * @module io
+ * @description Input/Output handling system for user interactions and event management.
+ * 
+ * This module provides a comprehensive set of classes for handling user input across
+ * different devices and input methods:
+ * 
+ * - {@link EventEmitter}: Core event management system for subscribing to and triggering events
+ * - {@link Mouse}: Mouse input tracking and event normalization
+ * - {@link Keys}: Keyboard input with logical key mapping and state tracking
+ * - {@link Touch}: Touch input for mobile devices
+ * - {@link Input}: Unified input system that normalizes mouse and touch events
+ * 
+ * The IO module serves as the intermediary between raw browser events and your game logic,
+ * providing consistent, normalized events regardless of input source.
+ * 
+ * @example
+ * // Basic usage in a game class
+ * import { Game } from './core/game.js';
+ * import { Keys, Mouse } from './core/io';
+ * 
+ * class MyGame extends Game {
+ *   init() {
+ *     super.init();
+ *     
+ *     // Listen for a specific key press
+ *     this.events.on(Keys.SPACE, () => {
+ *       this.player.jump();
+ *     });
+ *     
+ *     // Check mouse position in update loop
+ *     this.events.on("mousemove", () => {
+ *       this.logger.log(`Mouse at ${Mouse.x}, ${Mouse.y}`);
+ *     });
+ *     
+ *     // Listen for unified input events (works with both mouse and touch)
+ *     this.events.on("inputdown", () => {
+ *       this.player.shoot();
+ *     });
+ *   }
+ *   
+ *   update(dt) {
+ *     super.update(dt);
+ *     
+ *     // Check if a key is currently held down
+ *     if (Keys.isDown(Keys.RIGHT)) {
+ *       this.player.moveRight(dt);
+ *     }
+ *   }
+ * }
+ * 
+ * @example
+ * // Creating your own custom event system
+ * import { EventEmitter } from './core/io';
+ * 
+ * class WeaponSystem {
+ *   constructor() {
+ *     this.events = new EventEmitter();
+ *     this.ammo = 10;
+ *   }
+ *   
+ *   fire() {
+ *     if (this.ammo > 0) {
+ *       this.ammo--;
+ *       this.events.emit('fired', { ammo: this.ammo });
+ *       
+ *       if (this.ammo === 0) {
+ *         this.events.emit('empty');
+ *       }
+ *     }
+ *   }
+ * }
+ * 
+ * const weapon = new WeaponSystem();
+ * weapon.events.on('fired', (data) => {
+ *   this.logger.log(`Fired! Ammo remaining: ${data.ammo}`);
+ * });
+ * weapon.events.on('empty', () => {
+ *   this.logger.log('Out of ammo! Reload!');
+ * });
+ */
+export {EventEmitter} from "./events.js";
+export {Input} from "./input.js";
+export {Mouse} from "./mouse.js";
+export {Keys} from "./keys.js";
+export {Touch} from "./touch.js";

package/src/io/input.js

@@ -0,0 +1,70 @@
+export class Input {
+  static init(game) {
+    Input.game = game;
+    Input.x = 0;
+    Input.y = 0;
+    Input.down = false;
+    game.events.on("mousedown", Input._onDown);
+    game.events.on("mouseup", Input._onUp);
+    game.events.on("mousemove", Input._onMove);
+    game.events.on("touchstart", Input._onTouchStart);
+    game.events.on("touchend", Input._onTouchEnd);
+    game.events.on("touchmove", Input._onTouchMove);
+  }
+
+  static _setPosition(x, y) {
+    Input.x = x;
+    Input.y = y;
+  }
+
+  static _onDown = (e) => {
+    Input.down = true;
+    Input._setPosition(e.offsetX, e.offsetY);
+    Object.defineProperty(e, "x", { value: e.offsetX, configurable: true });
+    Object.defineProperty(e, "y", { value: e.offsetY, configurable: true });
+    Input.game.events.emit("inputdown", e);
+  };
+
+  static _onUp = (e) => {
+    Input.down = false;
+    Input._setPosition(e.offsetX, e.offsetY);
+    Object.defineProperty(e, "x", { value: e.offsetX, configurable: true });
+    Object.defineProperty(e, "y", { value: e.offsetY, configurable: true });
+    Input.game.events.emit("inputup", e);
+  };
+
+  static _onMove = (e) => {
+    Input._setPosition(e.offsetX, e.offsetY);
+    Object.defineProperty(e, "x", { value: e.offsetX, configurable: true });
+    Object.defineProperty(e, "y", { value: e.offsetY, configurable: true });
+    Input.game.events.emit("inputmove", e);
+  };
+
+  static _onTouchStart = (e) => {
+    const touch = e.touches[0];
+    const rect = Input.game.canvas.getBoundingClientRect();
+    Input.down = true;
+    const x = touch.clientX - rect.left;
+    const y = touch.clientY - rect.top;
+    Input._setPosition(x, y);
+    Object.defineProperty(e, "x", { value: x, configurable: true });
+    Object.defineProperty(e, "y", { value: y, configurable: true });
+    Input.game.events.emit("inputdown", e);
+  };
+
+  static _onTouchEnd = (e) => {
+    Input.down = false;
+    Input.game.events.emit("inputup", e);
+  };
+
+  static _onTouchMove = (e) => {
+    const touch = e.touches[0];
+    const rect = Input.game.canvas.getBoundingClientRect();
+    const x = touch.clientX - rect.left;
+    const y = touch.clientY - rect.top;
+    Input._setPosition(x, y);
+    Object.defineProperty(e, "x", { value: x, configurable: true });
+    Object.defineProperty(e, "y", { value: y, configurable: true });
+    Input.game.events.emit("inputmove", e);
+  };
+}

package/src/io/keys.js

@@ -0,0 +1,152 @@
+/**
+ * Keys.js
+ *
+ * Provides an abstraction layer over keyboard input. Instead of dealing with
+ * raw "KeyA" / "Space" codes, you can subscribe to logical names like Keys.W,
+ * Keys.SPACE, Keys.LEFT, etc.
+ *
+ * Example usage:
+ *   // Initialization (usually in your Game constructor):
+ *   Keys.init(this);
+ *
+ *   // Listen for a press:
+ *   this.events.on(Keys.W, (evt) => {
+ *     this.logger.log("W pressed!", evt);
+ *   });
+ *
+ *   // Listen for release:
+ *   this.events.on(Keys.W + "_up", (evt) => {
+ *     this.logger.log("W released!");
+ *   });
+ *
+ *   // Check if pressed in your update(dt):
+ *   if (Keys.isDown(Keys.SPACE)) {
+ *     // Spacebar is currently held
+ *   }
+ */
+export class Keys {
+  // Named constants for common game keys you might use:
+  static W = "W";
+  static A = "A";
+  static S = "S";
+  static D = "D";
+  static Q = "Q";
+  static E = "E";
+  static UP = "UP";
+  static DOWN = "DOWN";
+  static LEFT = "LEFT";
+  static RIGHT = "RIGHT";
+  static SPACE = "SPACE";
+  static SHIFT = "SHIFT";
+  static ENTER = "ENTER";
+  static ESC = "ESC";
+
+  /**
+   * Mapping from DOM event.code to one of the above Keys.* constants.
+   * Customize this list as needed for your game.
+   */
+  static _codeMap = {
+    // WASD + QE
+    KeyW: Keys.W,
+    KeyA: Keys.A,
+    KeyS: Keys.S,
+    KeyD: Keys.D,
+    KeyQ: Keys.Q,
+    KeyE: Keys.E,
+
+    // Arrows
+    ArrowUp: Keys.UP,
+    ArrowDown: Keys.DOWN,
+    ArrowLeft: Keys.LEFT,
+    ArrowRight: Keys.RIGHT,
+
+    // Space, Shift, Enter, Esc
+    Space: Keys.SPACE,
+    ShiftLeft: Keys.SHIFT,
+    ShiftRight: Keys.SHIFT,
+    Enter: Keys.ENTER,
+    NumpadEnter: Keys.ENTER,
+    Escape: Keys.ESC,
+  };
+
+  /**
+   * A Set of logical key names (Keys.W, Keys.SPACE, etc.) that are currently held down.
+   * @type {Set<string>}
+   * @private
+   */
+  static _down = new Set();
+
+  /**
+   * A reference to the main game instance. We store it so we can emit events
+   * via game.events whenever a key is pressed or released.
+   * @type {Game}
+   * @private
+   */
+  static game = null;
+
+  /**
+   * Initialize keyboard event handling. This attaches global listeners on the
+   * window so that whenever a key is pressed or released, we can map it to
+   * one of our Keys.* constants and emit the corresponding events on the game's
+   * EventEmitter.
+   *
+   * @param {Game} game - Your main Game instance, which has a central event emitter.
+   */
+  static init(game) {
+    Keys.game = game;
+
+    // Attach global keydown/keyup listeners
+    window.addEventListener("keydown", Keys._onKeyDown);
+    window.addEventListener("keyup", Keys._onKeyUp);
+  }
+
+  /**
+   * Returns true if the specified logical key (e.g. Keys.W) is currently held down.
+   *
+   * @param {string} logicalKey - One of the Keys.* constants.
+   * @returns {boolean} - True if that key is in the "down" set, false otherwise.
+   */
+  static isDown(logicalKey) {
+    return Keys._down.has(logicalKey);
+  }
+
+  /**
+   * Internal method called whenever a key is pressed. We look up which
+   * logical key constant it corresponds to, add it to our _down set,
+   * and emit an event on the game (e.g. game.events.emit(Keys.W, e)).
+   *
+   * @param {KeyboardEvent} e - The raw DOM event.
+   * @private
+   */
+  static _onKeyDown(e) {
+    const mappedKey = Keys._codeMap[e.code];
+    if (mappedKey) {
+      if (!Keys._down.has(mappedKey)) {
+        // Only emit this event the moment the key transitions from 'up' to 'down'
+        Keys._down.add(mappedKey);
+        Keys.game.events.emit(mappedKey, e);
+      }
+    }
+    // Dispatch the raw event as well, in case anyone cares about that.
+    Keys.game.events.emit(e.type, e);
+  }
+
+  /**
+   * Internal method called whenever a key is released. If it was one of our
+   * mapped keys, remove it from the _down set and emit an "_up" event.
+   *
+   * @param {KeyboardEvent} e - The raw DOM event.
+   * @private
+   */
+  static _onKeyUp(e) {
+    const mappedKey = Keys._codeMap[e.code];
+    if (mappedKey) {
+      if (Keys._down.has(mappedKey)) {
+        Keys._down.delete(mappedKey);
+        Keys.game.events.emit(mappedKey + "_up", e);
+      }
+    }
+    // Dispatch the raw event as well, in case anyone cares about that.
+    Keys.game.events.emit(e.type, e);
+  }
+}

package/src/io/mouse.js

@@ -0,0 +1,61 @@
+export class Mouse {
+  static init(game) {
+    Mouse.game = game;
+    Mouse.canvas = game.canvas;
+    Mouse.x = 0;
+    Mouse.y = 0;
+    Mouse.leftDown = false;
+    Mouse.middleDown = false;
+    Mouse.rightDown = false;
+
+    Mouse.canvas.addEventListener("mousemove", Mouse._onMove);
+    Mouse.canvas.addEventListener("mousedown", Mouse._onDown);
+    Mouse.canvas.addEventListener("mouseup", Mouse._onUp);
+    Mouse.canvas.addEventListener("click", Mouse._onClick);
+    Mouse.canvas.addEventListener("wheel", Mouse._onWheel);
+  }
+
+  static _updatePosition(e) {
+    const rect = Mouse.canvas.getBoundingClientRect();
+    Mouse.x = e.clientX - rect.left;
+    Mouse.y = e.clientY - rect.top;
+  }
+
+  static _onMove = (e) => {
+    Mouse._updatePosition(e);
+    Mouse.game.events.emit("mousemove", e);
+  };
+
+  static _onDown = (e) => {
+    Mouse._updatePosition(e);
+    if (e.button === 0) Mouse.leftDown = true;
+    if (e.button === 1) Mouse.middleDown = true;
+    if (e.button === 2) Mouse.rightDown = true;
+    Mouse.game.events.emit("mousedown", e);
+  };
+
+  static _onUp = (e) => {
+    Mouse._updatePosition(e);
+    if (e.button === 0) Mouse.leftDown = false;
+    if (e.button === 1) Mouse.middleDown = false;
+    if (e.button === 2) Mouse.rightDown = false;
+    Mouse.game.events.emit("mouseup", e);
+  };
+
+  static _onClick = (e) => {
+    Mouse._updatePosition(e);
+    // Emit enhanced event with canvas-relative coordinates
+    // Note: e is a MouseEvent, add canvas-relative x/y directly
+    e.canvasX = Mouse.x;
+    e.canvasY = Mouse.y;
+    // Also set x/y for convenience (matches expected fluent API)
+    Object.defineProperty(e, 'x', { value: Mouse.x, writable: false });
+    Object.defineProperty(e, 'y', { value: Mouse.y, writable: false });
+    Mouse.game.events.emit("click", e);
+  };
+
+  static _onWheel = (e) => {
+    Mouse._updatePosition(e);
+    Mouse.game.events.emit("wheel", e);
+  };
+}

package/src/io/touch.js

@@ -0,0 +1,39 @@
+export class Touch {
+  static init(game) {
+    Touch.game = game;
+    Touch.canvas = game.canvas;
+    Touch.x = 0;
+    Touch.y = 0;
+    Touch.active = false;
+
+    Touch.canvas.addEventListener("touchstart", Touch._onStart);
+    Touch.canvas.addEventListener("touchend", Touch._onEnd);
+    Touch.canvas.addEventListener("touchmove", Touch._onMove);
+  }
+
+  static _updatePosition(touch) {
+    const rect = Touch.canvas.getBoundingClientRect();
+    Touch.x = touch.clientX - rect.left;
+    Touch.y = touch.clientY - rect.top;
+  }
+
+  static _onStart = (e) => {
+    if (e.touches.length > 0) {
+      Touch.active = true;
+      Touch._updatePosition(e.touches[0]);
+      Touch.game.events.emit("touchstart", e);
+    }
+  };
+
+  static _onEnd = (e) => {
+    Touch.active = false;
+    Touch.game.events.emit("touchend", e);
+  };
+
+  static _onMove = (e) => {
+    if (e.touches.length > 0) {
+      Touch._updatePosition(e.touches[0]);
+      Touch.game.events.emit("touchmove", e);
+    }
+  };
+}