@guinetik/gcanvas 1.0.0

package/demos/js/tde/blackhole.js

@@ -0,0 +1,219 @@
+import { GameObject, Sphere3D, Painter, Easing } from "../../../src/index.js";
+import { CONFIG } from "./config.js";
+
+export class BlackHole extends GameObject {
+    constructor(game, options = {}) {
+        super(game, options);
+        this.mass = options.initialMass ?? CONFIG.blackHole.initialMass;
+        this.baseRadius = game.baseScale ? game.baseScale * CONFIG.bhRadiusRatio : 50;
+        this.currentRadius = this.baseRadius;
+
+        // Awakening state - BH starts dormant, wakes up as it feeds
+        this.awakeningLevel = 0;    // 0 = dormant (pure black), 1 = fully awake
+        this.feedingPulse = 0;      // Temporary glow boost when consuming
+        this.totalConsumed = 0;     // Track total mass consumed
+
+        // Dynamic growth animation
+        this.growthSpurt = 0;       // Overshoot when consuming (decays to 0)
+        this.breathPhase = 0;       // Oscillation phase for breathing effect
+        this.targetRadius = this.baseRadius;  // Smooth radius target
+
+        // Rotation - black holes spin!
+        this.rotation = 0;
+        this.rotationSpeed = options.rotationSpeed ?? 2.9; // Slow, ominous spin
+
+        // Use WebGL shaders for rendering
+        this.useShader = options.useShader ?? true;
+    }
+
+    init() {
+        this.updateVisual();
+    }
+
+    /**
+     * Add mass from consumed particles - triggers awakening and pulse
+     *
+     * @param {number} amount - Amount of mass to add
+     *
+     * Note: Feeding pulse is only triggered before the stable phase.
+     * Once stabilizing, particles can still be consumed but won't
+     * cause the visual pulse effect.
+     */
+    addConsumedMass(amount) {
+        this.totalConsumed += amount;
+
+        // Skip pulse effects if we're in the stable phase
+        if (this.isStabilizing) {
+            return;
+        }
+
+        // Awakening increases as BH feeds (slow ramp up)
+        const awakeningProgress = Math.min(1, this.totalConsumed * 0.1);
+        this.awakeningLevel = Math.max(this.awakeningLevel, awakeningProgress);
+
+        // Feeding pulse - temporary glow boost
+        this.feedingPulse = Math.min(1, this.feedingPulse + amount * 0.2);
+
+        // Growth spurt - overshoot effect when consuming
+        // More dramatic spurts as awakening increases
+        const spurtIntensity = 0.03 + this.awakeningLevel * 0.05;
+        this.growthSpurt = Math.min(0.15, this.growthSpurt + amount * spurtIntensity);
+    }
+
+    /**
+     * Reset to dormant state
+     */
+    resetAwakening() {
+        this.awakeningLevel = 0;
+        this.feedingPulse = 0;
+        this.totalConsumed = 0;
+        this.rotation = 0;
+        this.growthSpurt = 0;
+        this.breathPhase = 0;
+        this.isStabilizing = false;  // Reset stabilization state
+    }
+
+    updateVisual() {
+        // Calculate how much mass has been absorbed (0 = none, 1 = full star)
+        const massAbsorbed = Math.max(0, this.mass - CONFIG.blackHole.initialMass);
+        const absorptionProgress = massAbsorbed / CONFIG.star.initialMass;
+
+        // Apply easing to make growth feel more organic
+        // easeOutCubic: rapid initial growth that slows as it fills
+        const easedProgress = Easing.easeOutCubic(absorptionProgress);
+
+        // Base radius from absorption with easing
+        const baseScale = this.baseRadius / CONFIG.bhRadiusRatio;
+        const radiusFraction = CONFIG.bhRadiusRatio +
+            easedProgress * (CONFIG.bhFinalRadiusRatio - CONFIG.bhRadiusRatio);
+        this.targetRadius = baseScale * radiusFraction;
+
+        // Breathing oscillation - subtle when dormant, stronger when awake
+        const breathAmplitude = 0.01 + this.awakeningLevel * 0.02 + this.feedingPulse * 0.03;
+        const breathSpeed = 1.5 + this.awakeningLevel * 0.5;  // Faster when active
+        const breathOffset = Math.sin(this.breathPhase * breathSpeed) * breathAmplitude;
+
+        // Growth spurt overshoot effect (elastic rebound)
+        const spurtOffset = this.growthSpurt * (1 + Math.sin(this.breathPhase * 8) * 0.3);
+
+        // Combine all effects
+        this.currentRadius = this.targetRadius * (1 + breathOffset + spurtOffset);
+
+        if (this.currentRadius <= 0) {
+            this.currentRadius = this.baseRadius;
+        }
+
+        // Edge brightness increases with awakening
+        const awakeFactor = this.awakeningLevel;
+        const pulseFactor = this.feedingPulse;
+
+        // For Canvas 2D fallback - gradient rendering
+        // Dormant: pure black edges (#101010)
+        // Awake: warmer edges with hint of orange/red glow
+        const edgeBase = 16 + Math.round(awakeFactor * 24 + pulseFactor * 16); // 16-56
+        const edgeR = Math.min(255, edgeBase + Math.round(awakeFactor * 40 + pulseFactor * 60));
+        const edgeG = Math.min(255, edgeBase + Math.round(awakeFactor * 20 + pulseFactor * 30));
+        const edgeB = edgeBase;
+
+        const midBase = 8 + Math.round(awakeFactor * 12 + pulseFactor * 8);
+        const midR = Math.min(255, midBase + Math.round(awakeFactor * 20 + pulseFactor * 30));
+        const midG = Math.min(255, midBase + Math.round(awakeFactor * 10 + pulseFactor * 15));
+        const midB = midBase;
+
+        const gradient = Painter.colors.radialGradient(
+            0, 0, 0.01 * this.currentRadius,
+            0, 0, this.currentRadius,
+            [
+                { offset: 0, color: "#000" },
+                { offset: 0.5, color: "#000" },
+                { offset: 0.85, color: `rgb(${midR}, ${midG}, ${midB})` },
+                { offset: 1, color: `rgb(${edgeR}, ${edgeG}, ${edgeB})` },
+            ]
+        );
+
+        if (!this.core) {
+            this.core = new Sphere3D(this.currentRadius, {
+                color: gradient,
+                camera: this.game.camera,
+                stroke: null,   // No wireframe
+                debug: false,
+                segments: 32,   // Smoother sphere
+                // WebGL shader options
+                useShader: this.useShader,
+                shaderType: "blackHole",
+                shaderUniforms: {
+                    uAwakeningLevel: awakeFactor,
+                    uFeedingPulse: pulseFactor,
+                    uRotation: this.rotation,
+                },
+            });
+        } else {
+            this.core.radius = this.currentRadius;
+            this.core.color = gradient;  // Keep gradient for Canvas 2D fallback
+            // Update shader uniforms
+            if (this.core.useShader) {
+                this.core.setShaderUniforms({
+                    uAwakeningLevel: awakeFactor,
+                    uFeedingPulse: pulseFactor,
+                    uRotation: this.rotation,
+                });
+            }
+            this.core._generateGeometry();
+        }
+    }
+
+    update(dt) {
+        super.update(dt);
+
+        // Animate breathing phase
+        this.breathPhase += dt * Math.PI * 2;  // Full cycle per second
+
+        // Spin the black hole - rotation speeds up when feeding
+        const spinMultiplier = 1 + this.feedingPulse * 2 + this.awakeningLevel * 0.5;
+        this.rotation += this.rotationSpeed * spinMultiplier * dt;
+
+        // Decay feeding pulse over time
+        if (this.feedingPulse > 0) {
+            this.feedingPulse = Math.max(0, this.feedingPulse - dt * 1.5);
+        }
+
+        // Decay growth spurt with elastic damping
+        if (this.growthSpurt > 0) {
+            // Fast initial decay, slows down (feels like elastic settling)
+            const decayRate = 3 + this.growthSpurt * 5;  // Faster when larger
+            this.growthSpurt = Math.max(0, this.growthSpurt - dt * decayRate);
+        }
+
+        // Decay awakening level when stabilizing (slow cool-down)
+        // Minimum level is 0.3 - never goes fully dormant after feeding
+        if (this.isStabilizing && this.awakeningLevel > 0.3) {
+            this.awakeningLevel = Math.max(0.3, this.awakeningLevel - dt * 0.15);
+        }
+
+        this.updateVisual();
+    }
+
+    /**
+     * Start the stabilization phase - black hole calms down
+     */
+    startStabilizing() {
+        this.isStabilizing = true;
+    }
+
+    /**
+     * Reset stabilization state
+     */
+    resetStabilizing() {
+        this.isStabilizing = false;
+    }
+
+    onResize(baseRadius) {
+        this.baseRadius = baseRadius;
+        this.updateVisual();
+    }
+
+    render() {
+        super.render();
+        this.core.render();
+    }
+}

package/demos/js/tde/blackholescene.js

@@ -0,0 +1,209 @@
+import { Scene3D } from "../../../src/index.js";
+import { BlackHole } from "./blackhole.js";
+import { Star } from "./tdestar.js";
+import { TidalStream } from "./tidalstream.js";
+import { AccretionDisk } from "./accretiondisk.js";
+import { RelativisticJets } from "./jets.js";
+import { CONFIG } from "./config.js";
+
+/**
+ * BlackHoleScene - Main 3D scene containing the TDE visualization
+ *
+ * Z-Order Rendering Rules:
+ * 1. BlackHole renders at the back (dark shadow)
+ * 2. AccretionDisk renders over the black hole (particles curve around)
+ * 3. TidalStream always on top of star and black hole
+ * 4. Star position relative to BlackHole changes based on camera depth
+ *
+ * Z-Index Buckets (lower = renders first = behind):
+ * - starBack: 10 (star when behind BH)
+ * - blackHole: 15 (dark shadow at back)
+ * - disk: 20 (accretion disk over BH)
+ * - starFront: 25 (star when in front of BH)
+ * - stream: 30 (particles - always on top)
+ * - jets: 40 (always on top)
+ *
+ * @extends Scene3D
+ */
+export class BlackHoleScene extends Scene3D {
+    constructor(game, options = {}) {
+        super(game, options);
+        // Camera is passed via options and handled by Scene3D
+
+        /**
+         * Z-index buckets for render ordering
+         * Scene3D sorts by zIndex first (lower renders first/behind),
+         * then uses camera depth as tie-breaker
+         *
+         * Layering (simple):
+         * - BlackHole at back (dark shadow)
+         * - Disk renders over BH (particles curve around it)
+         * - Stream always on top of star and BH
+         * - Star moves in front of/behind BH based on camera view
+         */
+        this.Z = {
+            starBack: 10,    // Star when behind BH
+            blackHole: 15,   // BlackHole: dark shadow at back
+            disk: 20,        // AccretionDisk: over the black hole
+            starFront: 25,   // Star when in front of BH
+            stream: 30,      // TidalStream: always on top of star and BH
+            jets: 40,        // Jets: always on top
+        };
+    }
+
+    init() {
+        // Z-order buckets: lower draws first, equal uses depth
+        // IMPORTANT: Set zIndex AFTER add() because ZOrderedCollection.add()
+        // overwrites zIndex with array index
+
+        // Add BlackHole at (0,0,0)
+        this.bh = new BlackHole(this.game);
+        this.add(this.bh);
+        this.bh.zIndex = this.Z.blackHole;  // Set AFTER add()
+
+        // Add a Star orbiting the black hole
+        this.star = new Star(this.game);
+        this.add(this.star);
+        this.star.zIndex = this.Z.starFront;  // Set AFTER add(), will be updated per-frame
+
+        // Add accretion disk (starts inactive)
+        this.disk = new AccretionDisk(this.game, {
+            camera: this.game.camera,
+            bhRadius: this.game.baseScale * CONFIG.bhRadiusRatio,
+            bhMass: CONFIG.blackHole.initialMass,
+            onParticleConsumed: () => {
+                this.bh.addConsumedMass(0.1); // Disk particles worth more
+            },
+        });
+        this.add(this.disk);
+        this.disk.zIndex = this.Z.disk;  // Set AFTER add()
+
+        // Add tidal stream for particles
+        // When particles are consumed, feed the black hole
+        // When particles circularize, transfer to accretion disk
+        this.stream = new TidalStream(this.game, {
+            camera: this.game.camera,
+            scene: this,  // Pass scene reference for screen center
+            bhRadius: this.game.baseScale * CONFIG.bhRadiusRatio,
+            diskInnerRadius: this.disk.innerRadius,
+            diskOuterRadius: this.disk.outerRadius,
+            onParticleConsumed: () => {
+                this.bh.addConsumedMass(0.05); // Each particle adds small amount
+            },
+            onParticleCaptured: (p) => {
+                this.disk.captureParticle(p);
+            },
+        });
+        this.add(this.stream);
+        this.stream.zIndex = this.Z.stream;  // Set AFTER add()
+
+        // Add relativistic jets (activated during flare phase)
+        this.jets = new RelativisticJets(this.game, {
+            camera: this.game.camera,
+            bhRadius: this.game.baseScale * CONFIG.bhRadiusRatio,
+        });
+        this.add(this.jets);
+        this.jets.zIndex = this.Z.jets;  // Set AFTER add()
+
+        // Mark z-order as dirty to ensure initial sort
+        if (this._collection) {
+            this._collection._zOrderDirty = true;
+        }
+    }
+
+    update(dt) {
+        super.update(dt);
+
+        // Sync all particle systems with current BH radius (grows as it feeds)
+        if (this.bh) {
+            if (this.stream) {
+                this.stream.updateBHRadius(this.bh.currentRadius);
+            }
+            if (this.disk) {
+                this.disk.updateBHRadius(this.bh.currentRadius);
+                // Also sync stream's disk bounds for capture detection
+                if (this.stream) {
+                    this.stream.updateDiskBounds(this.disk.innerRadius, this.disk.outerRadius);
+                }
+            }
+            if (this.jets) {
+                this.jets.updateBHRadius(this.bh.currentRadius);
+            }
+        }
+
+        // Note: Z-order update is called from TDEDemo.update() AFTER star position
+        // is updated, to ensure we use the current frame's position, not the previous frame's.
+    }
+
+    /**
+     * Update star's z-index based on its depth relative to the black hole
+     *
+     * Dynamic z-ordering:
+     * - When star in front of BH: star renders on top of BH
+     * - When star behind BH: BH renders on top of star
+     * - Stream (particles) always stays on top of both
+     *
+     * Camera3D.project() returns z as depth after rotation:
+     * - Lower z = closer to camera
+     * - Higher z = farther from camera
+     *
+     * IMPORTANT: Must be called AFTER star position is updated each frame.
+     */
+    updateStarZOrder() {
+        if (!this.star || !this.bh || !this.game?.camera) {
+            return;
+        }
+
+        const camera = this.game.camera;
+
+        // Project star position to get its depth after camera rotation
+        const projStar = camera.project(
+            this.star.x || 0,
+            this.star.y || 0,
+            this.star.z || 0
+        );
+
+        // Black hole is always at origin (0, 0, 0)
+        const projBH = camera.project(0, 0, 0);
+
+        // Star is "in front" if its depth is LESS than BH's depth
+        const starInFront = projStar.z < projBH.z;
+
+        // Update star's z-index
+        const newZIndex = starInFront ? this.Z.starFront : this.Z.starBack;
+
+        if (this.star.zIndex !== newZIndex) {
+            this.star.zIndex = newZIndex;
+            // Mark ordering dirty so Scene3D resort happens this frame
+            if (this._collection) {
+                this._collection._zOrderDirty = true;
+            }
+        }
+    }
+
+    onResize() {
+        const game = this.game;
+        if (this.bh) {
+            this.bh.onResize(game.baseScale * CONFIG.bhRadiusRatio);
+        }
+        if (this.star) {
+            this.star.onResize(
+                game.baseScale * CONFIG.starRadiusRatio,
+                game.baseScale * CONFIG.star.initialOrbitRadius
+            );
+        }
+        if (this.disk && this.bh) {
+            this.disk.updateBHRadius(this.bh.currentRadius);
+        }
+        if (this.stream && this.bh) {
+            this.stream.updateBHRadius(this.bh.currentRadius);
+            // Update disk bounds for capture detection
+            if (this.disk) {
+                this.stream.updateDiskBounds(this.disk.innerRadius, this.disk.outerRadius);
+            }
+        }
+        if (this.jets && this.bh) {
+            this.jets.updateBHRadius(this.bh.currentRadius);
+        }
+    }
+}

package/demos/js/tde/config.js

@@ -0,0 +1,59 @@
+export const CONFIG = {
+    // Sizing (as fraction of screen baseScale)
+    bhRadiusRatio: 0.01,        // Initial dormant black hole size (larger for visible lensing)
+    bhFinalRadiusRatio: 0.12,   // Final size after consuming star
+    starRadiusRatio: 0.08,
+
+    // Phase durations (seconds)
+    durations: {
+        approach: 10.0,      // Stable wide orbit
+        stretch: 10.0,       // Orbit begins to decay
+        disrupt: 20.0,      // Mass transfer (event-based exit)
+        accrete: 1.0,       // Debris accretion
+        flare: 5.0,         // Jets firing - spectacular cosmic event!
+        stable: Infinity,   // Final stable state
+    },
+
+    // Flash effect (now handled by Tweenetik in FSM)
+
+    // Physics params
+    blackHole: {
+        initialMass: 2,
+        color: "#000",
+    },
+    star: {
+        initialMass: 25,
+        color: "#FF6030",  // Deep red-orange (cooler K/M type star)
+        // Orbit sizing (fraction of half the smaller screen dimension)
+        // apoapsis = initialOrbitRadius * (1 + eccentricity)
+        // periapsis = initialOrbitRadius * (1 - eccentricity)
+        initialOrbitRadius: 1.2,  // Semi-major axis
+        eccentricity: 0.25,       // Lower = more circular, periapsis closer to edge
+        // With these values:
+        // periapsis (right) = 1.2 * 0.75 = 0.9 (90% to edge - visible on RIGHT side!)
+        // apoapsis (left) = 1.2 * 1.25 = 1.5 (goes off screen left)
+        orbitSpeed: 0.4,
+        decayRate: 0.4,
+        massTransferStart: 0.1,
+        rotationSpeed: 0.71,
+        temperature: 3800,
+        orbitCenterX: 0,
+        orbitCenterY: 0,
+        bypassConstraints: true,
+        // Start angle: star should be VISIBLE at start, then swing through orbit
+        // 0 = right (periapsis), π/2 = top, π = left (apoapsis), 3π/2 = bottom
+        startAngle: Math.PI * 1.85,  // Start lower-right, comes FROM right, swings up and around
+    },
+    sceneOptions: {
+        starCount: 3000,
+    },
+
+    // Accretion disk settings
+    disk: {
+        innerRadiusRatio: 0.03,     // ISCO (innermost stable orbit)
+        outerRadiusRatio: 0.15,     // Outer halo edge
+        maxParticles: 2000,
+        orbitalSpeed: 0.8,
+        activationProgress: 0.8,   // Start at 80% of disrupt phase
+    },
+};