@guinetik/gcanvas 1.0.0

package/src/fluent/fluent-layer.js

@@ -0,0 +1,152 @@
+/**
+ * @module FluentLayer
+ * @description Builder class for layer (z-indexed group) operations within a scene
+ *
+ * Layers are implemented as GameObjects containing Groups, allowing for
+ * z-indexed sub-grouping within a scene.
+ */
+
+import { GameObject } from "../game/objects/go.js";
+import { FluentGO } from "./fluent-go.js";
+
+/**
+ * FluentLayer - Builder for layer (z-indexed group) within a scene
+ */
+export class FluentLayer {
+  /** @type {import('./fluent-scene.js').FluentScene} */
+  #parent;
+  /** @type {GameObject} */
+  #layerGO;
+  /** @type {import('../shapes/group.js').Group} */
+  #group;
+  /** @type {Object} */
+  #refs;
+  /** @type {Object} */
+  #state;
+
+  /**
+   * @param {import('./fluent-scene.js').FluentScene} parent - Parent FluentScene
+   * @param {GameObject} layerGO - The GameObject holding the layer
+   * @param {import('../shapes/group.js').Group} group - The Group for the layer
+   * @param {Object} refs - Shared refs object
+   * @param {Object} state - Shared state object
+   */
+  constructor(parent, layerGO, group, refs, state) {
+    this.#parent = parent;
+    this.#layerGO = layerGO;
+    this.#group = group;
+    this.#refs = refs;
+    this.#state = state;
+  }
+
+  /**
+   * Create a GameObject in this layer
+   * @param {Object} [opts] - GameObject options
+   * @param {Function} [builderFn] - Optional builder callback
+   * @returns {FluentGO|FluentLayer}
+   */
+  go(opts = {}, builderFn) {
+    const {
+      name,
+      x = 0,
+      y = 0,
+      visible = true,
+      ...rest
+    } = opts;
+
+    const go = new GameObject({ x, y, visible, ...rest });
+
+    // Set game reference from parent
+    if (this.#parent.parent?.game) {
+      go.game = this.#parent.parent.game;
+    }
+
+    // Add to the layer's group
+    this.#group.add(go);
+
+    // Register in refs if named
+    if (name) {
+      go.name = name;
+      this.#refs[name] = go;
+    }
+
+    const fluentGO = new FluentGO(this, go, this.#refs, this.#state);
+
+    if (builderFn) {
+      builderFn(fluentGO);
+      return this;
+    }
+
+    return fluentGO;
+  }
+
+  /**
+   * Set layer visibility
+   * @param {boolean} visible - Visibility state
+   * @returns {FluentLayer}
+   */
+  visible(visible) {
+    this.#layerGO.visible = visible;
+    return this;
+  }
+
+  /**
+   * Set layer opacity
+   * @param {number} value - Opacity (0-1)
+   * @returns {FluentLayer}
+   */
+  opacity(value) {
+    this.#group.opacity = value;
+    return this;
+  }
+
+  /**
+   * End layer context and return to scene
+   * @returns {import('./fluent-scene.js').FluentScene}
+   */
+  endLayer() {
+    return this.#parent;
+  }
+
+  /**
+   * Navigate back to parent (same as endLayer)
+   * @returns {import('./fluent-scene.js').FluentScene}
+   */
+  end() {
+    return this.#parent;
+  }
+
+  /**
+   * Switch to another scene
+   * @param {string} name - Scene name
+   * @param {Object} [opts] - Scene options
+   * @returns {import('./fluent-scene.js').FluentScene}
+   */
+  scene(name, opts) {
+    return this.#parent.scene(name, opts);
+  }
+
+  /**
+   * Start the game
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  start() {
+    return this.#parent.start();
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // ACCESSORS
+  // ─────────────────────────────────────────────────────────
+
+  /** @returns {GameObject} The layer's wrapper GameObject */
+  get layerGO() { return this.#layerGO; }
+
+  /** @returns {import('../shapes/group.js').Group} The layer's Group */
+  get group() { return this.#group; }
+
+  /** @returns {Object} Named object references */
+  get refs() { return this.#refs; }
+
+  /** @returns {Object} Shared state */
+  get state() { return this.#state; }
+}

package/src/fluent/fluent-scene.js

@@ -0,0 +1,291 @@
+/**
+ * @module FluentScene
+ * @description Builder class for Scene operations in the fluent API
+ *
+ * Provides chainable methods for creating and managing GameObjects within a scene.
+ */
+
+import { GameObject } from "../game/objects/go.js";
+import { Group } from "../shapes/group.js";
+import { FluentGO } from "./fluent-go.js";
+import { FluentLayer } from "./fluent-layer.js";
+
+/**
+ * FluentScene - Builder class for Scene operations
+ */
+export class FluentScene {
+  /** @type {import('./fluent-game.js').FluentGame} */
+  #parent;
+  /** @type {import('../game/objects/scene.js').Scene} */
+  #scene;
+  /** @type {Object} */
+  #refs;
+  /** @type {Object} */
+  #state;
+  /** @type {GameObject|null} */
+  #lastGO = null;
+
+  /**
+   * @param {import('./fluent-game.js').FluentGame} parent - Parent FluentGame
+   * @param {import('../game/objects/scene.js').Scene} scene - Wrapped Scene instance
+   * @param {Object} refs - Shared refs object
+   * @param {Object} state - Shared state object
+   */
+  constructor(parent, scene, refs, state) {
+    this.#parent = parent;
+    this.#scene = scene;
+    this.#refs = refs;
+    this.#state = state;
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // GAMEOBJECT CREATION
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * Create a GameObject in this scene
+   *
+   * Supports multiple signatures:
+   * - go() - Create plain GameObject at origin
+   * - go(options) - Create plain GameObject with options
+   * - go(CustomClass) - Create custom GameObject class
+   * - go(CustomClass, options) - Custom class with options
+   * - go(options, builderFn) - Plain GO with builder callback
+   * - go(CustomClass, options, builderFn) - Custom class with builder
+   *
+   * @param {Object|Function} [optionsOrClass] - GameObject options or custom class
+   * @param {Object|Function} [optionsOrBuilder] - Options or builder function
+   * @param {Function} [builderFn] - Optional builder callback
+   * @returns {FluentGO|FluentScene}
+   */
+  go(optionsOrClass, optionsOrBuilder, builderFn) {
+    // Parse flexible arguments
+    let GOClass, options, builder;
+
+    if (typeof optionsOrClass === 'function' && optionsOrClass.prototype) {
+      // go(CustomClass) or go(CustomClass, options) or go(CustomClass, options, builder)
+      GOClass = optionsOrClass;
+      if (typeof optionsOrBuilder === 'function') {
+        options = {};
+        builder = optionsOrBuilder;
+      } else {
+        options = optionsOrBuilder || {};
+        builder = builderFn;
+      }
+    } else {
+      // go() or go(options) or go(options, builder)
+      GOClass = GameObject;
+      options = optionsOrClass || {};
+      builder = optionsOrBuilder;
+    }
+
+    const {
+      name,
+      x = 0,
+      y = 0,
+      visible = true,
+      ...rest
+    } = options;
+
+    // Instantiate the GO class (custom or default)
+    // GameObject constructor signature is (game, options)
+    const go = new GOClass(this.#parent.game, { x, y, visible, ...rest });
+    this.#scene.add(go);
+    this.#lastGO = go;
+
+    // Register in refs if named
+    if (name) {
+      go.name = name;
+      this.#refs[name] = go;
+    }
+
+    const fluentGO = new FluentGO(this, go, this.#refs, this.#state);
+
+    // If builder function provided, execute and return scene context
+    if (builder) {
+      builder(fluentGO);
+      return this;
+    }
+
+    return fluentGO;
+  }
+
+  /**
+   * Create multiple GOs with a builder
+   * @param {string|Function} groupNameOrFn - Group name or builder function
+   * @param {Function} [builderFn] - Builder function if name provided
+   * @returns {FluentScene}
+   */
+  group(groupNameOrFn, builderFn) {
+    const groupName = typeof groupNameOrFn === 'string' ? groupNameOrFn : null;
+    const fn = typeof groupNameOrFn === 'function' ? groupNameOrFn : builderFn;
+
+    const groupGOs = [];
+
+    const groupApi = {
+      go: (opts) => {
+        const fluentGO = this.go(opts);
+        groupGOs.push(fluentGO.goInstance);
+        return fluentGO;
+      }
+    };
+
+    fn(groupApi);
+
+    if (groupName) {
+      this.#refs[groupName] = groupGOs;
+    }
+
+    return this;
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // LAYER MANAGEMENT (sub-grouping within scene)
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * Create a layer (z-indexed group) within the scene
+   * @param {string} name - Layer name
+   * @param {number} [zIndex=0] - Layer z-index (relative to scene)
+   * @returns {FluentLayer}
+   */
+  layer(name, zIndex = 0) {
+    // Layers are implemented as Groups with zIndex
+    const layerGroup = new Group({ zIndex });
+    layerGroup.name = name;
+
+    // Create a wrapper GO to hold the group
+    // GameObject constructor signature is (game, options)
+    const layerGO = new GameObject(this.#parent.game, { x: 0, y: 0 });
+    layerGO._fluentShape = layerGroup;
+    layerGO.renderable = layerGroup;
+    layerGO.zIndex = zIndex;
+
+    // Hook into draw to render the group
+    const originalDraw = layerGO.draw?.bind(layerGO) || (() => {});
+    layerGO.draw = function() {
+      originalDraw();
+      if (this._fluentShape && this.visible) {
+        this._fluentShape.render();
+      }
+    };
+
+    this.#scene.add(layerGO);
+
+    if (name) {
+      this.#refs[`${this.#scene.name}_${name}`] = layerGO;
+    }
+
+    return new FluentLayer(this, layerGO, layerGroup, this.#refs, this.#state);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // SCENE LIFECYCLE HOOKS
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * Register scene enter callback
+   * @param {Function} handler
+   * @returns {FluentScene}
+   */
+  onEnter(handler) {
+    this.#scene._onEnter = handler;
+    return this;
+  }
+
+  /**
+   * Register scene exit callback
+   * @param {Function} handler
+   * @returns {FluentScene}
+   */
+  onExit(handler) {
+    this.#scene._onExit = handler;
+    return this;
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // NAVIGATION
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * Switch to another scene (creates if needed)
+   * @param {string} name - Scene name
+   * @param {Object} [options] - Scene options
+   * @returns {FluentScene}
+   */
+  scene(name, options) {
+    return this.#parent.scene(name, options);
+  }
+
+  /**
+   * Return to game context
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  end() {
+    return this.#parent;
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // SHORTCUTS (delegate to parent)
+  // ─────────────────────────────────────────────────────────
+
+  /**
+   * Start the game
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  start() {
+    return this.#parent.start();
+  }
+
+  /**
+   * Stop the game
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  stop() {
+    return this.#parent.stop();
+  }
+
+  /**
+   * Register event handler
+   * @param {string} event - Event name
+   * @param {Function} handler - Handler function
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  on(event, handler) {
+    return this.#parent.on(event, handler);
+  }
+
+  /**
+   * Use a plugin
+   * @param {Function} plugin - Plugin function
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  use(plugin) {
+    return this.#parent.use(plugin);
+  }
+
+  /**
+   * Set state
+   * @param {Object} stateObj - State object
+   * @returns {import('./fluent-game.js').FluentGame}
+   */
+  state(stateObj) {
+    return this.#parent.state(stateObj);
+  }
+
+  // ─────────────────────────────────────────────────────────
+  // ACCESSORS
+  // ─────────────────────────────────────────────────────────
+
+  /** @returns {import('../game/objects/scene.js').Scene} Underlying Scene instance */
+  get sceneInstance() { return this.#scene; }
+
+  /** @returns {Object} Named object references */
+  get refs() { return this.#refs; }
+
+  /** @returns {Object} Shared state */
+  get state() { return this.#state; }
+
+  /** @returns {import('./fluent-game.js').FluentGame} Parent FluentGame */
+  get parent() { return this.#parent; }
+}

package/src/fluent/index.js

@@ -0,0 +1,98 @@
+/**
+ * @module Fluent
+ * @description Declarative fluent builder API for GCanvas
+ *
+ * This module provides a chainable, declarative API layer on top of GCanvas's
+ * object-oriented architecture. It enables rapid creative coding while maintaining
+ * full access to the underlying power.
+ *
+ * ## Entry Points
+ *
+ * - **gcanvas(options)** - Full fluent API for building games and interactive apps
+ * - **sketch(w, h, bg)** - Ultra-simple mode for quick creative coding prototypes
+ *
+ * ## Quick Start
+ *
+ * @example
+ * // Full fluent API
+ * import { gcanvas } from 'gcanvas';
+ *
+ * gcanvas({ bg: 'black' })
+ *   .scene('game')
+ *     .go({ x: 400, y: 300, name: 'player' })
+ *       .circle({ radius: 30, fill: 'lime' })
+ *       .pulse({ min: 0.9, max: 1.1, duration: 1 })
+ *   .scene('ui', { zIndex: 100 })
+ *     .go({ x: 20, y: 20 })
+ *       .text('SCORE: 0', { font: '24px monospace', fill: 'white' })
+ *   .on('update', (dt, ctx) => {
+ *     // Game logic
+ *   })
+ *   .start();
+ *
+ * @example
+ * // Sketch mode for quick prototypes
+ * import { sketch } from 'gcanvas';
+ *
+ * sketch(800, 600, '#1a1a1a')
+ *   .grid(10, 10, 80, (s, x, y, i, j) => {
+ *     s.circle(x, y, 20, `hsl(${(i + j) * 20}, 70%, 60%)`);
+ *   })
+ *   .update((dt, ctx) => {
+ *     ctx.shapes.forEach((shape, i) => {
+ *       shape.y += Math.sin(ctx.time * 2 + i * 0.1) * 0.5;
+ *     });
+ *   })
+ *   .start();
+ *
+ * @example
+ * // Class injection - use custom classes with fluent API
+ * import { gcanvas } from 'gcanvas';
+ * import { SpaceScene } from './scenes/space-scene';
+ * import { Player, Alien, Boss } from './entities';
+ *
+ * gcanvas({ bg: 'black' })
+ *   // Pass custom scene class
+ *   .scene(SpaceScene)
+ *   // Or with name: .scene('game', SpaceScene, { zIndex: 0 })
+ *
+ *   // Pass custom GameObject classes
+ *   .go(Player, { x: 400, y: 500, name: 'player' })
+ *   .go(Alien, { x: 100, y: 100, type: 0 })
+ *   .go(Boss, { x: 400, y: 150, bossType: 2 })
+ *
+ *   .start();
+ *
+ * @example
+ * // Composable scene modules
+ * // scenes/player.js
+ * export const playerScene = (g) => g
+ *   .inScene('game')
+ *     .go({ x: 400, y: 300, name: 'player' })
+ *       .circle({ radius: 25, fill: '#00ff88' });
+ *
+ * // main.js
+ * import { gcanvas } from 'gcanvas';
+ * import { playerScene } from './scenes/player';
+ *
+ * gcanvas({ bg: 'black' })
+ *   .scene('game')
+ *   .use(playerScene)
+ *   .start();
+ */
+
+// Main entry points
+export { gcanvas, FluentGame } from "./fluent-game.js";
+export { sketch } from "./sketch.js";
+
+// Builder classes (for advanced usage/extension)
+export { FluentScene } from "./fluent-scene.js";
+export { FluentGO } from "./fluent-go.js";
+export { FluentLayer } from "./fluent-layer.js";
+
+// Re-export commonly used items for convenience
+export { Motion } from "../motion/motion.js";
+export { Easing } from "../motion/easing.js";
+export { Tweenetik } from "../motion/tweenetik.js";
+export { Keys } from "../io/keys.js";
+export { Mouse } from "../io/mouse.js";