@guinetik/gcanvas 1.0.0

package/demos/js/blackhole/index.js

@@ -0,0 +1,409 @@
+/**
+ * Black Hole - Cinematic Visualization
+ *
+ * Particle-based accretion disk with:
+ * - Camera-space gravitational lensing
+ * - Doppler beaming
+ * - Depth-sorted rendering
+ * - Hawking radiation
+ *
+ * Refactored into modular components:
+ * - StarField: Background starfield with parallax
+ * - AccretionDisk: Particle management and formation
+ * - BlackHole: Event horizon and Hawking radiation
+ */
+
+import { Game, Painter, Camera3D, StateMachine, Button } from "../../../src/index.js";
+import { applyAnchor } from "../../../src/mixins/anchor.js";
+import { Position } from "../../../src/util/position.js";
+
+import { LensedStarfield } from "../tde/lensedstarfield.js";
+import { AccretionDisk } from "./accretiondisk.obj.js";
+import { BlackHole } from "./blackhole.obj.js";
+
+// Configuration
+const CONFIG = {
+  // Black hole (as fraction of screen)
+  bhRadiusRatio: 0.08,
+  diskInnerRatio: 0.12,
+  diskOuterRatio: 0.35,
+
+  // Disk tilt (radians)
+  diskTilt: (0 * Math.PI) / 180,
+
+  particleCount: 2500,
+
+  // Colors (white-hot inner to deep red outer)
+  colors: {
+    inner: [255, 250, 220],
+    mid: [255, 160, 50],
+    outer: [180, 40, 40],
+  },
+
+  // Formation phases (durations in seconds)
+  formation: {
+    infall: 4.0,
+    collapse: 1.2,
+    circularize: 2.5,
+  },
+
+  // Stars
+  starCount: 3000,
+
+  // Visual
+  backgroundColor: "#050505",
+};
+
+class BlackHoleDemo extends Game {
+  constructor(canvas) {
+    super(canvas);
+    this.backgroundColor = CONFIG.backgroundColor;
+    this.enableFluidSize();
+  }
+
+  init() {
+    super.init();
+    this.time = 0;
+
+    // Calculate scaled sizes
+    this.updateScaledSizes();
+
+    // Setup Camera3D with inertia
+    this.camera = new Camera3D({
+      rotationX: 0.1,
+      rotationY: 0,
+      perspective: this.baseScale * 0.6,
+      autoRotate: true,
+      autoRotateSpeed: 0.2,
+      // Inertia for smooth camera drag
+      inertia: true,
+      friction: 0.94,
+      velocityScale: 1.2,
+    });
+    this.camera.enableMouseControl(this.canvas);
+
+    // Black hole reference for lensed starfield occlusion
+    this.bhRef = { currentRadius: 0 };
+
+    // Lensed starfield with gravitational lensing
+    // Use smaller distanceScale (0.33) because camera perspective is 0.6x vs TDE's 1.8x
+    this.starField = new LensedStarfield(this, {
+      camera: this.camera,
+      blackHole: this.bhRef,
+      starCount: CONFIG.starCount,
+      distanceScale: 0.33,
+      lensingStrength: 1.0,
+    });
+    this.starField.init();
+    this.pipeline.add(this.starField);
+
+    // Create AccretionDisk
+    this.accretionDisk = new AccretionDisk(this, {
+      camera: this.camera,
+      baseScale: this.baseScale,
+      bhRadius: this.bhRadius,
+      diskInner: this.diskInner,
+      diskOuter: this.diskOuter,
+      diskTilt: CONFIG.diskTilt,
+      particleCount: CONFIG.particleCount,
+      colors: CONFIG.colors,
+    });
+    this.accretionDisk.initParticles();
+    this.pipeline.add(this.accretionDisk);
+
+    // Create BlackHole
+    this.blackHole = new BlackHole(this, {
+      camera: this.camera,
+      baseScale: this.baseScale,
+      bhRadius: this.bhRadius,
+      diskOuter: this.diskOuter,
+    });
+    this.pipeline.add(this.blackHole);
+
+    // Initialize formation state machine (after components exist, as FSM triggers infall immediately)
+    this.initFormationStateMachine();
+
+    // Set FSM reference on components
+    this.accretionDisk.formationFSM = this.formationFSM;
+    this.blackHole.formationFSM = this.formationFSM;
+
+    // Replay button (bottom left)
+    this.replayButton = new Button(this, {
+      width: 120,
+      height: 32,
+      text: "▶ Replay",
+      font: "14px monospace",
+      colorDefaultBg: "rgba(0, 0, 0, 0.6)",
+      colorDefaultStroke: "#666",
+      colorDefaultText: "#888",
+      colorHoverBg: "rgba(40, 40, 40, 0.8)",
+      colorHoverStroke: "#aaa",
+      colorHoverText: "#fff",
+      colorPressedBg: "rgba(60, 40, 20, 0.8)",
+      colorPressedStroke: "#ffaa66",
+      colorPressedText: "#ffaa66",
+      onClick: () => this.formNewBlackHole(),
+    });
+    applyAnchor(this.replayButton, {
+      anchor: Position.BOTTOM_LEFT,
+      anchorMargin: 20,
+      anchorOffsetY: -30,
+    });
+    this.replayButton.zIndex = 100;
+    this.replayButton.visible = false; // Hidden until stable
+    this.pipeline.add(this.replayButton);
+  }
+
+  initFormationStateMachine() {
+    this.formationFSM = StateMachine.fromSequence(
+      [
+        {
+          name: "infall",
+          duration: CONFIG.formation.infall,
+          enter: () => {
+            this.accretionDisk.initParticlesForInfall();
+          },
+        },
+        {
+          name: "collapse",
+          duration: CONFIG.formation.collapse,
+        },
+        {
+          name: "circularize",
+          duration: CONFIG.formation.circularize,
+        },
+        {
+          name: "stable",
+          duration: Infinity,
+          enter: () => {
+            // Show replay button when stable
+            if (this.replayButton) this.replayButton.visible = true;
+          },
+        },
+      ],
+      { context: this },
+    );
+  }
+
+  formNewBlackHole() {
+    // Hide replay button
+    if (this.replayButton) this.replayButton.visible = false;
+
+    this.blackHole.reset();
+    this.formationFSM.setState("infall");
+  }
+
+  updateScaledSizes() {
+    this.baseScale = Math.min(this.width, this.height);
+    this.bhRadius = this.baseScale * CONFIG.bhRadiusRatio;
+    this.diskInner = this.baseScale * CONFIG.diskInnerRatio;
+    this.diskOuter = this.baseScale * CONFIG.diskOuterRatio;
+  }
+
+  onResize() {
+    this.updateScaledSizes();
+    if (this.camera) {
+      this.camera.perspective = this.baseScale * 0.6;
+    }
+    if (this.accretionDisk) {
+      this.accretionDisk.updateSizing(
+        this.baseScale,
+        this.bhRadius,
+        this.diskInner,
+        this.diskOuter,
+      );
+      this.accretionDisk.initParticles();
+    }
+    if (this.blackHole) {
+      this.blackHole.updateSizing(
+        this.baseScale,
+        this.bhRadius,
+        this.diskOuter,
+      );
+    }
+  }
+
+  update(dt) {
+    super.update(dt);
+    this.time += dt;
+
+    // Update camera
+    this.camera.update(dt);
+
+    // Update formation state machine
+    this.formationFSM.update(dt);
+
+    // Components update via pipeline
+  }
+
+  render() {
+    const w = this.width;
+    const h = this.height;
+    const cx = w / 2;
+    const cy = h / 2;
+
+    // Calculate formation visibility
+    const lambda = this.blackHole.getFormationLambda(
+      this.accretionDisk.particlesConsumed,
+      this.accretionDisk.totalParticleMass,
+    );
+
+    // Update black hole reference for lensed starfield occlusion
+    this.bhRef.currentRadius = this.bhRadius * lambda;
+
+    // Adjust starfield lensing strength based on formation phase
+    if (this.starField) {
+      const state = this.formationFSM.state;
+      if (state === "stable") {
+        this.starField.lensingStrength = 1.0;
+      } else if (state === "circularize") {
+        this.starField.lensingStrength = 0.4 + this.formationFSM.progress * 0.6;
+      } else if (state === "collapse") {
+        this.starField.lensingStrength = this.formationFSM.progress * 0.4;
+      } else {
+        // infall - subtle lensing as BH forms
+        this.starField.lensingStrength = lambda * 0.3;
+      }
+    }
+
+    // Clear and draw starfield (via pipeline)
+    super.render();
+
+    // Draw formation collapse flash
+    if (lambda < 0.3 && lambda > 0) {
+      Painter.useCtx((ctx) => {
+        this.blackHole.drawFormationFlash(ctx, cx, cy, lambda, this.time);
+      });
+    }
+
+    // Build combined render list from components
+    const renderList = [
+      ...this.accretionDisk.buildRenderList(),
+      ...this.blackHole.buildRenderList(lambda),
+    ];
+
+    // Sort by depth (back to front)
+    renderList.sort((a, b) => b.z - a.z);
+
+    // Draw everything
+    Painter.useCtx((ctx) => {
+      ctx.save();
+      ctx.translate(cx, cy);
+
+      for (const item of renderList) {
+        if (item.type === "hole") {
+          BlackHole.drawHole(ctx, item, this.bhRadius);
+        } else if (item.type === "particle") {
+          this.drawParticle(ctx, item);
+        } else if (item.type === "hawking") {
+          BlackHole.drawHawkingParticle(ctx, item, this.baseScale);
+        }
+      }
+
+      ctx.restore();
+    });
+
+    // Info HUD
+    this.drawInfo(w, h);
+  }
+
+  drawParticle(ctx, item) {
+    const size = this.baseScale * 0.003 * item.scale;
+    if (size < 0.1) return;
+
+    let { r, g, b, a } = item.color;
+    const state = this.formationFSM.state;
+    const isInfalling = state === "infall" || state === "collapse";
+
+    // Gravitational redshift for particles falling into the black hole
+    // As they approach the event horizon, light shifts to red and dims (time dilation)
+    if (item.isFalling && item.horizonProximity < 3) {
+      const redshift = 1 - (item.horizonProximity - 0.5) / 2.5;
+      const rs = Math.max(0, Math.min(1, redshift));
+
+      // Shift toward deep red (reduce green/blue more than red)
+      r = Math.floor(r * (1 - rs * 0.2));
+      g = Math.floor(g * (1 - rs * 0.85));
+      b = Math.floor(b * (1 - rs * 0.95));
+
+      // Time dilation dimming - particles appear to freeze and fade
+      a *= 1 - rs * 0.8;
+    } else if (isInfalling) {
+      // Non-falling particles during infall: cooler (bluer) transitioning to hot
+      const heatProgress = 1 - item.z / (this.baseScale * 0.5);
+      const coolFactor = Math.max(0, 1 - heatProgress);
+      r = Math.floor(r * (0.6 + heatProgress * 0.4));
+      g = Math.floor(g * (0.7 + heatProgress * 0.3));
+      b = Math.min(255, Math.floor(b + coolFactor * 80));
+    }
+
+    const finalAlpha = Math.max(
+      0,
+      Math.min(1, a * item.doppler * item.diskAlpha),
+    );
+
+    // Core particle (circle)
+    ctx.fillStyle = `rgba(${r},${g},${b},${finalAlpha})`;
+    ctx.beginPath();
+    ctx.arc(item.x, item.y, size / 2, 0, Math.PI * 2);
+    ctx.fill();
+
+    // Additive glow for bright/close particles
+    if (
+      (item.doppler > 1.1 && item.diskAlpha > 0.5) ||
+      (isInfalling && item.z < 0)
+    ) {
+      ctx.globalCompositeOperation = "screen";
+      ctx.fillStyle = `rgba(${r},${g},${b},${finalAlpha * 0.4})`;
+      ctx.beginPath();
+      ctx.arc(item.x, item.y, size, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.globalCompositeOperation = "source-over";
+    }
+  }
+
+  drawInfo(w, h) {
+    Painter.useCtx((ctx) => {
+      ctx.font = "11px monospace";
+      ctx.textAlign = "left";
+
+      const state = this.formationFSM.state;
+      const progress = this.formationFSM.progress;
+
+      const stateLabels = {
+        infall: "Matter Infall",
+        collapse: "Gravitational Collapse",
+        circularize: "Disk Circularization",
+        stable: "Stable Orbit",
+      };
+
+      const stateColors = {
+        infall: "#88f",
+        collapse: "#f88",
+        circularize: "#fa8",
+        stable: "#8a8",
+      };
+
+      ctx.fillStyle = stateColors[state] || "#888";
+      if (state === "stable") {
+        ctx.fillText(stateLabels[state], 15, h - 30);
+      } else {
+        ctx.fillText(
+          `${stateLabels[state]}: ${(progress * 100).toFixed(0)}%`,
+          15,
+          h - 30,
+        );
+      }
+
+      ctx.textAlign = "right";
+      ctx.fillStyle = "#444";
+      ctx.fillText("drag to orbit", w - 15, h - 15);
+    });
+  }
+}
+
+window.addEventListener("load", () => {
+  const canvas = document.getElementById("game");
+  const demo = new BlackHoleDemo(canvas);
+  demo.start();
+});

package/demos/js/blackhole/particle.js

@@ -0,0 +1,56 @@
+/**
+ * Particle - Lightweight data class for accretion disk particles
+ *
+ * NOT a GameObject - plain objects for performance (2500+ items)
+ * Creating GameObjects for each particle would add massive overhead.
+ */
+export class Particle {
+  constructor(options = {}) {
+    // Current animated position
+    this.angle = options.angle ?? 0;
+    this.distance = options.distance ?? 0;
+    this.yOffset = options.yOffset ?? 0;
+
+    // Target (final disk orbit)
+    this.targetAngle = options.targetAngle ?? this.angle;
+    this.targetDistance = options.targetDistance ?? this.distance;
+    this.targetYOffset = options.targetYOffset ?? this.yOffset;
+
+    // Starting position (for infall animation)
+    this.startAngle = options.startAngle ?? this.angle;
+    this.startDistance = options.startDistance ?? this.distance;
+    this.startYOffset = options.startYOffset ?? 0;
+
+    // Physics
+    this.speed = options.speed ?? 0;
+    this.baseColor = options.baseColor ?? { r: 255, g: 255, b: 255, a: 1 };
+
+    // Formation state
+    this.infallDelay = options.infallDelay ?? 0;
+    this.circularizeSpeed = options.circularizeSpeed ?? 1;
+    this.streamOffset = options.streamOffset ?? 0;
+    this.spiralTurns = options.spiralTurns ?? 1.5;
+    this.willFallIn = options.willFallIn ?? false;
+    this.consumed = options.consumed ?? false;
+    this.isFalling = options.isFalling ?? false;
+  }
+
+  /**
+   * Factory method for creating disk particles at final positions
+   */
+  static createForDisk(angle, distance, yOffset, speed, baseColor) {
+    return new Particle({
+      angle,
+      distance,
+      yOffset,
+      speed,
+      baseColor,
+      targetAngle: angle,
+      targetDistance: distance,
+      targetYOffset: yOffset,
+      startAngle: angle,
+      startDistance: distance,
+      circularizeSpeed: 0.8 + Math.random() * 0.4,
+    });
+  }
+}

package/demos/js/blackhole/starfield.obj.js

@@ -0,0 +1,218 @@
+/**
+ * StarField - 3D volumetric starfield
+ * 
+ * Features:
+ * - Prerendered sprites for high performance (5000+ stars).
+ * - Scientific spectral color distribution (O, B, A, F, G, K, M).
+ * - Authentic twinkle animation.
+ * - Spherical distribution for consistent background density.
+ */
+import { GameObject, Painter } from "../../../src/index.js";
+
+// Spectral types: Color and "Aesthetic" rarity (skewed slightly from reality for better visuals)
+const SPECTRAL_TYPES = [
+  { type: 'O', color: '#9bb0ff', weight: 0.01, baseSize: 5.0 }, // Blue (Hot/Big)
+  { type: 'B', color: '#aabfff', weight: 0.05, baseSize: 4.0 },
+  { type: 'A', color: '#cad7ff', weight: 0.15, baseSize: 3.5 },
+  { type: 'F', color: '#f8f7ff', weight: 0.20, baseSize: 3.0 },
+  { type: 'G', color: '#fff4ea', weight: 0.20, baseSize: 2.8 }, // Sun-like
+  { type: 'K', color: '#ffd2a1', weight: 0.25, baseSize: 2.5 },
+  { type: 'M', color: '#ffcc6f', weight: 0.14, baseSize: 2.2 } // Red (Cool/Small)
+];
+
+const CONFIG = {
+  starCount: 5000,
+  minDist: 4000,
+  maxDist: 10000,
+  // Global size multiplier (applied to spectral baseSize)
+  scaleMultiplier: 2.0
+};
+
+export class StarField extends GameObject {
+  /**
+   * @param {Game} game
+   * @param {Object} options
+   * @param {Camera3D} options.camera
+   * @param {number} [options.starCount] - Number of stars
+   * @param {number} [options.distanceScale=1.0] - Scale factor for star distances (lower = closer stars)
+   */
+  constructor(game, options = {}) {
+    super(game, options);
+    this.camera = options.camera;
+    this.zIndex = -1000;
+
+    this.starCount = options.starCount || CONFIG.starCount;
+    this.distanceScale = options.distanceScale ?? 1.0;
+    this.stars = [];
+
+    // Cache for pre-rendered star sprites
+    // Map<Color, HTMLCanvasElement>
+    this.sprites = new Map();
+  }
+
+  init() {
+    this.preRenderSprites();
+    this.generateStarfield();
+  }
+
+  /**
+   * Pre-render star sprites for each spectral type.
+   * Drawing images is much faster than running context state changes and arc() commands per star.
+   */
+  preRenderSprites() {
+    for (const type of SPECTRAL_TYPES) {
+      const size = 32; // Texture size (enough for glow)
+      const center = size / 2;
+      const radius = size / 4; // Actual core radius
+
+      const canvas = document.createElement('canvas');
+      canvas.width = size;
+      canvas.height = size;
+      const ctx = canvas.getContext('2d');
+
+      // Soft glow
+      const grad = ctx.createRadialGradient(center, center, 0, center, center, size / 2);
+      grad.addColorStop(0, type.color);
+      grad.addColorStop(0.2, type.color); // Solid core
+      grad.addColorStop(0.5, this.adjustAlpha(type.color, 0.3)); // Glow
+      grad.addColorStop(1, this.adjustAlpha(type.color, 0)); // Fade out
+
+      ctx.fillStyle = grad;
+      ctx.beginPath();
+      ctx.arc(center, center, size / 2, 0, Math.PI * 2);
+      ctx.fill();
+
+      // Store sprite associated with this spectral type index
+      this.sprites.set(type.type, canvas);
+    }
+  }
+
+  // Helper to add alpha to hex color
+  adjustAlpha(hex, alpha) {
+    // rudimentary hex to rgba conversion
+    // Assuming hex is #RRGGBB
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  generateStarfield() {
+    this.stars = [];
+
+    // Create cumulative weights for random selection
+    const totalWeight = SPECTRAL_TYPES.reduce((sum, t) => sum + t.weight, 0);
+
+    // Apply distance scale for different camera perspectives
+    const minDist = CONFIG.minDist * this.distanceScale;
+    const maxDist = CONFIG.maxDist * this.distanceScale;
+
+    for (let i = 0; i < this.starCount; i++) {
+      // distribute stars in a spherical shell
+      const theta = Math.random() * Math.PI * 2;
+      const phi = Math.acos(2 * Math.random() - 1);
+      const r = minDist + Math.random() * (maxDist - minDist);
+
+      const x = r * Math.sin(phi) * Math.cos(theta);
+      const y = r * Math.sin(phi) * Math.sin(theta);
+      const z = r * Math.cos(phi);
+
+      // Pick spectral type
+      const rand = Math.random() * totalWeight;
+      let accum = 0;
+      let selectedType = SPECTRAL_TYPES[SPECTRAL_TYPES.length - 1]; // Default
+      for (const t of SPECTRAL_TYPES) {
+        accum += t.weight;
+        if (rand < accum) {
+          selectedType = t;
+          break;
+        }
+      }
+
+      // Twinkle properties
+      const twinkleSpeed = 0.5 + Math.random() * 2.0;    // How fast it pulses
+      const twinklePhase = Math.random() * Math.PI * 2;  // Offset so they don't pulse in sync
+
+      this.stars.push({
+        x, y, z,
+        type: selectedType,
+        twinkleSpeed,
+        twinklePhase,
+        // Random slight variations in size even within same class
+        baseScale: (0.8 + Math.random() * 0.4) * CONFIG.scaleMultiplier
+      });
+    }
+  }
+
+  render() {
+    super.render();
+    if (!this.camera) return;
+
+    const cx = this.game.width / 2;
+    const cy = this.game.height / 2;
+    const time = performance.now() / 1000;
+
+    Painter.useCtx((ctx) => {
+      // Use efficient composition
+      // 'lighter' gives a nice additive look for stars overlapping, or 'source-over' for standard
+      ctx.globalCompositeOperation = 'source-over';
+
+      for (const star of this.stars) {
+        // Project
+        const p = this.camera.project(star.x, star.y, star.z);
+
+        // Cull (behind camera)
+        if (p.z < -this.camera.perspective + 50) continue;
+
+        // Viewport cull (loose bounds)
+        const x = cx + p.x;
+        const y = cy + p.y;
+        if (x < -30 || x > this.game.width + 30 || y < -30 || y > this.game.height + 30) continue;
+
+        // Calculate Twinkle
+        // Sine wave mapped to [0.3, 1.0] range mainly, occasionally dipping lower
+        const val = Math.sin(time * star.twinkleSpeed + star.twinklePhase);
+        const alpha = 0.6 + 0.4 * val; // Min brightness 0.2
+
+        // Don't draw invisible stars
+        if (alpha < 0.1) continue;
+
+        // Visual Size
+        // p.scale is usually around 0.1-0.2 for distant stars
+        // star.baseScale is ~2.0
+        // Resulting size ~ 0.2 * 2.0 * 32 (sprite size) which is huge. 
+        // We want the *drawn size* to be small, but the sprite is high quality.
+        // Let's say we want a star to be 6px on screen.
+        // 6px / 32px (sprite) = 0.18 draw scale
+
+        const finalSize = star.type.baseSize * star.baseScale * p.scale;
+
+        const sprite = this.sprites.get(star.type.type);
+        if (!sprite) continue;
+
+        // Center the sprite
+        // Determine draw dimension. 
+        // We used 32px sprite.
+        // We want final visual size to be `finalSize`.
+
+        // Optimization: if tiny, skip drawImage and justfillRect?
+        // With 5000 stars, drawImage is fast enough if not scaling huge images.
+
+        ctx.globalAlpha = alpha;
+
+        // Draw centered
+        ctx.drawImage(
+          sprite,
+          x - finalSize * 2,
+          y - finalSize * 2,
+          finalSize * 4, // Make sprite larger than "size" to account for glow
+          finalSize * 4
+        );
+      }
+
+      // Reset
+      ctx.globalAlpha = 1.0;
+    });
+  }
+}
+