synthos 0.8.0 → 0.9.0

package/static-files/retro-game.js

@@ -0,0 +1,877 @@
+/**
+ * RetroGame — Shared retro game infrastructure library
+ * Provides game loop, input, canvas sizing, particles, and more.
+ * Auto-served at /static/retro-game.js
+ */
+(function() {
+    if (window.RetroGame) return;
+
+    var RG = {};
+
+    // -------------------------------------------------------
+    // Constants
+    // -------------------------------------------------------
+    RG.BUTTON = {
+        A: 0, B: 1, X: 2, Y: 3,
+        LB: 4, RB: 5, LT: 6, RT: 7,
+        SELECT: 8, START: 9,
+        L_STICK: 10, R_STICK: 11,
+        DPAD_UP: 12, DPAD_DOWN: 13, DPAD_LEFT: 14, DPAD_RIGHT: 15
+    };
+
+    // -------------------------------------------------------
+    // 1. Game Loop
+    // -------------------------------------------------------
+    RG.createGameLoop = function(opts) {
+        var updateFn = opts.update;
+        var drawFn = opts.draw;
+        var targetFps = opts.fps || 60;
+        var interval = 1000 / targetFps;
+        var rafId = null;
+        var lastTime = 0;
+        var running = false;
+        var paused = false;
+        var currentDt = 0;
+        var measuredFps = 0;
+        var frameCount = 0;
+        var fpsAccum = 0;
+
+        function tick(now) {
+            rafId = requestAnimationFrame(tick);
+            var elapsed = now - lastTime;
+            if (elapsed < interval) return;
+            lastTime = now - (elapsed % interval);
+            var dt = Math.min(elapsed / 1000, 0.1); // clamp to 100ms max
+            currentDt = dt;
+
+            // FPS measurement
+            frameCount++;
+            fpsAccum += elapsed;
+            if (fpsAccum >= 1000) {
+                measuredFps = Math.round((frameCount * 1000) / fpsAccum);
+                frameCount = 0;
+                fpsAccum = 0;
+            }
+
+            if (!paused) {
+                updateFn(dt);
+            }
+            drawFn(dt);
+        }
+
+        var loop = {
+            get isPaused() { return paused; },
+            get isRunning() { return running; },
+            get dt() { return currentDt; },
+            get fps() { return measuredFps; },
+
+            start: function() {
+                if (running) return;
+                running = true;
+                paused = false;
+                lastTime = performance.now();
+                rafId = requestAnimationFrame(tick);
+            },
+            stop: function() {
+                running = false;
+                paused = false;
+                if (rafId !== null) {
+                    cancelAnimationFrame(rafId);
+                    rafId = null;
+                }
+            },
+            pause: function() {
+                paused = true;
+            },
+            resume: function() {
+                if (paused) {
+                    paused = false;
+                    lastTime = performance.now();
+                }
+            },
+            toggle: function() {
+                if (paused) loop.resume();
+                else loop.pause();
+            }
+        };
+
+        return loop;
+    };
+
+    // -------------------------------------------------------
+    // 2. Responsive Canvas
+    // -------------------------------------------------------
+    RG.createCanvas = function(canvasEl, opts) {
+        var container = opts.container;
+        var aspectRatio = opts.aspectRatio != null ? opts.aspectRatio : 4 / 3;
+        var debounceMs = opts.debounceMs != null ? opts.debounceMs : 150;
+        var onResizeCb = opts.onResize || null;
+        var ctx = canvasEl.getContext("2d");
+        var timer = 0;
+        var destroyed = false;
+
+        function doResize() {
+            if (destroyed) return;
+            var cw = container.clientWidth;
+            var ch = container.clientHeight;
+            if (cw < 1 || ch < 1) return;
+            var w, h;
+            if (cw / ch > aspectRatio) {
+                h = ch;
+                w = Math.floor(h * aspectRatio);
+            } else {
+                w = cw;
+                h = Math.floor(w / aspectRatio);
+            }
+            canvasEl.width = w;
+            canvasEl.height = h;
+            if (onResizeCb) onResizeCb(w, h);
+        }
+
+        function onWindowResize() {
+            doResize();
+            clearTimeout(timer);
+            timer = setTimeout(doResize, debounceMs);
+        }
+
+        window.addEventListener("resize", onWindowResize);
+        doResize();
+
+        return {
+            get width() { return canvasEl.width; },
+            get height() { return canvasEl.height; },
+            get ctx() { return ctx; },
+            resize: doResize,
+            set onResize(fn) { onResizeCb = fn; },
+            destroy: function() {
+                destroyed = true;
+                window.removeEventListener("resize", onWindowResize);
+                clearTimeout(timer);
+            }
+        };
+    };
+
+    // -------------------------------------------------------
+    // 3. Keyboard Input
+    // -------------------------------------------------------
+    RG.createKeyboard = function() {
+        var current = {};  // currently held
+        var previous = {}; // snapshot from last poll
+        var destroyed = false;
+
+        function onKeyDown(e) {
+            current[e.code] = true;
+        }
+        function onKeyUp(e) {
+            current[e.code] = false;
+        }
+
+        window.addEventListener("keydown", onKeyDown);
+        window.addEventListener("keyup", onKeyUp);
+
+        return {
+            isDown: function(code) {
+                return !!current[code];
+            },
+            wasPressed: function(code) {
+                return !!current[code] && !previous[code];
+            },
+            wasReleased: function(code) {
+                return !current[code] && !!previous[code];
+            },
+            poll: function() {
+                // Snapshot current state into previous
+                for (var k in previous) delete previous[k];
+                for (var k in current) previous[k] = current[k];
+            },
+            destroy: function() {
+                if (destroyed) return;
+                destroyed = true;
+                window.removeEventListener("keydown", onKeyDown);
+                window.removeEventListener("keyup", onKeyUp);
+            }
+        };
+    };
+
+    // -------------------------------------------------------
+    // 4. Gamepad Input
+    // -------------------------------------------------------
+    RG.createGamepad = function(opts) {
+        opts = opts || {};
+        var deadzone = opts.deadzone != null ? opts.deadzone : 0.3;
+        var padIndex = opts.index != null ? opts.index : -1; // -1 = first connected
+        var connected = false;
+        var platform = "unknown";
+        var current = {};
+        var previous = {};
+        var lx = 0, ly = 0, rx = 0, ry = 0;
+        var dirLeft = false, dirRight = false, dirUp = false, dirDown = false;
+        var onConnectCb = null;
+        var onDisconnectCb = null;
+        var wasConnected = false;
+
+        function detectPlatform(pad) {
+            if (!pad) return "unknown";
+            var id = (pad.id || "").toLowerCase();
+            if (id.indexOf("playstation") !== -1 || id.indexOf("dualsense") !== -1 ||
+                id.indexOf("dualshock") !== -1 || id.indexOf("054c") !== -1 ||
+                id.indexOf("sony") !== -1) {
+                return "ps";
+            }
+            if (id.indexOf("xbox") !== -1 || id.indexOf("xinput") !== -1 ||
+                id.indexOf("045e") !== -1 || id.indexOf("microsoft") !== -1) {
+                return "xbox";
+            }
+            return "unknown";
+        }
+
+        function applyDeadzone(v) {
+            return Math.abs(v) < deadzone ? 0 : v;
+        }
+
+        function getPad() {
+            var pads = navigator.getGamepads ? navigator.getGamepads() : [];
+            if (padIndex >= 0) {
+                var p = pads[padIndex];
+                return (p && p.connected) ? p : null;
+            }
+            for (var i = 0; i < pads.length; i++) {
+                if (pads[i] && pads[i].connected) return pads[i];
+            }
+            return null;
+        }
+
+        return {
+            get connected() { return connected; },
+            get platform() { return platform; },
+            get leftStickX() { return lx; },
+            get leftStickY() { return ly; },
+            get rightStickX() { return rx; },
+            get rightStickY() { return ry; },
+            get left() { return dirLeft; },
+            get right() { return dirRight; },
+            get up() { return dirUp; },
+            get down() { return dirDown; },
+            set onConnect(fn) { onConnectCb = fn; },
+            set onDisconnect(fn) { onDisconnectCb = fn; },
+
+            isDown: function(btn) {
+                return !!current[btn];
+            },
+            wasPressed: function(btn) {
+                return !!current[btn] && !previous[btn];
+            },
+            wasReleased: function(btn) {
+                return !current[btn] && !!previous[btn];
+            },
+
+            poll: function() {
+                // Save previous state
+                for (var k in current) previous[k] = current[k];
+
+                var pad = getPad();
+                wasConnected = connected;
+                connected = !!pad;
+
+                if (connected && !wasConnected) {
+                    platform = detectPlatform(pad);
+                    if (onConnectCb) onConnectCb();
+                } else if (!connected && wasConnected) {
+                    platform = "unknown";
+                    if (onDisconnectCb) onDisconnectCb();
+                }
+
+                if (!pad) {
+                    lx = ly = rx = ry = 0;
+                    dirLeft = dirRight = dirUp = dirDown = false;
+                    for (var b = 0; b < 17; b++) current[b] = false;
+                    return;
+                }
+
+                var axes = pad.axes;
+                var btns = pad.buttons;
+
+                lx = applyDeadzone(axes[0] || 0);
+                ly = applyDeadzone(axes[1] || 0);
+                rx = applyDeadzone(axes[2] || 0);
+                ry = applyDeadzone(axes[3] || 0);
+
+                for (var b = 0; b < btns.length && b < 17; b++) {
+                    current[b] = btns[b] && btns[b].pressed;
+                }
+
+                var dpadUp = !!current[RG.BUTTON.DPAD_UP];
+                var dpadDown = !!current[RG.BUTTON.DPAD_DOWN];
+                var dpadLeft = !!current[RG.BUTTON.DPAD_LEFT];
+                var dpadRight = !!current[RG.BUTTON.DPAD_RIGHT];
+
+                dirLeft = lx < 0 || dpadLeft;
+                dirRight = lx > 0 || dpadRight;
+                dirUp = ly < 0 || dpadUp;
+                dirDown = ly > 0 || dpadDown;
+            }
+        };
+    };
+
+    // -------------------------------------------------------
+    // 5. Gamepad UI
+    // -------------------------------------------------------
+    RG.createGamepadUI = function(gamepadInput, opts) {
+        opts = opts || {};
+        var statusEl = opts.statusElement || null;
+
+        function getPlatform() {
+            return gamepadInput.platform;
+        }
+
+        var ui = {
+            update: function() {
+                if (!statusEl) return;
+                if (gamepadInput.connected) {
+                    statusEl.textContent = "GAMEPAD DETECTED";
+                    statusEl.className = "connected";
+                } else {
+                    statusEl.textContent = "NO GAMEPAD";
+                    statusEl.className = "";
+                }
+            },
+
+            buttonGlyph: function(name) {
+                var p = getPlatform();
+                if (p === "ps") {
+                    switch (name) {
+                        case "a": return '<span class="gp-btn gp-btn-ps-cross">\u2715</span>';
+                        case "b": return '<span class="gp-btn gp-btn-ps-circle">\u25CB</span>';
+                        case "x": return '<span class="gp-btn gp-btn-ps-square">\u25A1</span>';
+                        case "y": return '<span class="gp-btn gp-btn-ps-triangle">\u25B3</span>';
+                    }
+                }
+                // Xbox / default
+                switch (name) {
+                    case "a": return '<span class="gp-btn gp-btn-xa">A</span>';
+                    case "b": return '<span class="gp-btn gp-btn-xb">B</span>';
+                    case "x": return '<span class="gp-btn gp-btn-xx">X</span>';
+                    case "y": return '<span class="gp-btn gp-btn-xy">Y</span>';
+                }
+                return name.toUpperCase();
+            },
+
+            buttonName: function(name) {
+                var p = getPlatform();
+                if (p === "ps") {
+                    switch (name) {
+                        case "a": return "Cross";
+                        case "b": return "Circle";
+                        case "x": return "Square";
+                        case "y": return "Triangle";
+                    }
+                }
+                return name.toUpperCase();
+            },
+
+            startName: function() {
+                return getPlatform() === "ps" ? "OPTIONS" : "START";
+            },
+
+            prompt: function(kbHtml, gpHtml) {
+                return gamepadInput.connected ? gpHtml : kbHtml;
+            },
+
+            get css() { return GAMEPAD_CSS; }
+        };
+
+        return ui;
+    };
+
+    var GAMEPAD_CSS =
+        '.gp-btn{display:inline-flex;align-items:center;justify-content:center;width:22px;height:22px;border-radius:50%;font-size:13px;font-weight:700;line-height:1;vertical-align:middle;margin:0 2px;font-family:"Segoe UI",sans-serif}' +
+        '.gp-btn-xa{background:#3a9a3a;color:#fff;text-shadow:0 0 4px rgba(0,0,0,.5)}' +
+        '.gp-btn-xb{background:#c83232;color:#fff;text-shadow:0 0 4px rgba(0,0,0,.5)}' +
+        '.gp-btn-xx{background:#2a6ac8;color:#fff;text-shadow:0 0 4px rgba(0,0,0,.5)}' +
+        '.gp-btn-xy{background:#c8a82a;color:#fff;text-shadow:0 0 4px rgba(0,0,0,.5)}' +
+        '.gp-btn-ps-cross{background:transparent;border:2px solid #6699cc;color:#6699cc;font-size:15px;width:20px;height:20px}' +
+        '.gp-btn-ps-circle{background:transparent;border:2px solid #e66a6a;color:#e66a6a;font-size:14px;width:20px;height:20px}' +
+        '.gp-btn-ps-square{background:transparent;border:2px solid #d68ad6;color:#d68ad6;font-size:12px;width:20px;height:20px}' +
+        '.gp-btn-ps-triangle{background:transparent;border:2px solid #6ad6a0;color:#6ad6a0;font-size:14px;width:20px;height:20px}' +
+        '.gp-label{display:inline-block;padding:1px 6px;border:1px solid rgba(0,255,255,.4);border-radius:3px;font-size:11px;color:#0ff;background:rgba(0,255,255,.05);vertical-align:middle;margin:0 2px;font-family:"Segoe UI",sans-serif}';
+
+    RG.injectCSS = function() {
+        if (document.getElementById("retro-game-gp-css")) return;
+        var style = document.createElement("style");
+        style.id = "retro-game-gp-css";
+        style.textContent = GAMEPAD_CSS;
+        document.head.appendChild(style);
+    };
+
+    // -------------------------------------------------------
+    // 6. Distance
+    // -------------------------------------------------------
+    RG.distance = function(a, b) {
+        var dx = b.x - a.x;
+        var dy = b.y - a.y;
+        return Math.sqrt(dx * dx + dy * dy);
+    };
+
+    // -------------------------------------------------------
+    // 7. Circles Overlap
+    // -------------------------------------------------------
+    RG.circlesOverlap = function(a, b, rA, rB) {
+        var dx = b.x - a.x;
+        var dy = b.y - a.y;
+        var dist = dx * dx + dy * dy;
+        var radii = rA + rB;
+        return dist < radii * radii;
+    };
+
+    // -------------------------------------------------------
+    // 8. Wrap
+    // -------------------------------------------------------
+    RG.wrap = function(obj, width, height, margin) {
+        margin = margin != null ? margin : 50;
+        if (obj.x < -margin) obj.x = width + margin;
+        if (obj.x > width + margin) obj.x = -margin;
+        if (obj.y < -margin) obj.y = height + margin;
+        if (obj.y > height + margin) obj.y = -margin;
+    };
+
+    // -------------------------------------------------------
+    // 9. Particle System
+    // -------------------------------------------------------
+    RG.createParticles = function(opts) {
+        opts = opts || {};
+        var maxParticles = opts.maxParticles || 500;
+        var pool = [];
+        var activeCount = 0;
+
+        // Pre-allocate pool
+        for (var i = 0; i < maxParticles; i++) {
+            pool.push({ active: false, x: 0, y: 0, vx: 0, vy: 0, life: 0, maxLife: 0, color: "", size: 0, decay: 0 });
+        }
+
+        function acquire() {
+            // Find a dead particle to reuse
+            for (var i = 0; i < pool.length; i++) {
+                if (!pool[i].active) return pool[i];
+            }
+            return null; // pool exhausted
+        }
+
+        return {
+            get count() { return activeCount; },
+
+            emit: function(x, y, count, emitOpts) {
+                emitOpts = emitOpts || {};
+                var color = emitOpts.color || "#ffffff";
+                var speed = emitOpts.speed != null ? emitOpts.speed : 5;
+                var size = emitOpts.size != null ? emitOpts.size : 3;
+                var lifetime = emitOpts.lifetime != null ? emitOpts.lifetime : 1.0;
+                var decay = emitOpts.decay != null ? emitOpts.decay : 0;
+                var spread = emitOpts.spread != null ? emitOpts.spread : Math.PI * 2;
+                var direction = emitOpts.direction != null ? emitOpts.direction : Math.random() * Math.PI * 2;
+
+                for (var i = 0; i < count; i++) {
+                    var p = acquire();
+                    if (!p) break;
+                    var angle = direction + (Math.random() - 0.5) * spread;
+                    var spd = speed * (0.4 + Math.random() * 0.6);
+                    p.active = true;
+                    p.x = x;
+                    p.y = y;
+                    p.vx = Math.cos(angle) * spd;
+                    p.vy = Math.sin(angle) * spd;
+                    p.life = lifetime * (0.6 + Math.random() * 0.4);
+                    p.maxLife = p.life;
+                    p.color = color;
+                    p.size = size * (0.3 + Math.random() * 0.7);
+                    p.decay = decay;
+                    activeCount++;
+                }
+            },
+
+            update: function(dt) {
+                activeCount = 0;
+                for (var i = 0; i < pool.length; i++) {
+                    var p = pool[i];
+                    if (!p.active) continue;
+                    p.life -= dt;
+                    if (p.life <= 0) {
+                        p.active = false;
+                        continue;
+                    }
+                    p.x += p.vx * dt * 60; // normalize to ~60fps feel
+                    p.y += p.vy * dt * 60;
+                    if (p.decay) {
+                        p.vx *= (1 - p.decay * dt * 60);
+                        p.vy *= (1 - p.decay * dt * 60);
+                    }
+                    activeCount++;
+                }
+            },
+
+            draw: function(ctx) {
+                for (var i = 0; i < pool.length; i++) {
+                    var p = pool[i];
+                    if (!p.active) continue;
+                    var alpha = p.life / p.maxLife;
+                    ctx.globalAlpha = alpha;
+                    ctx.fillStyle = p.color;
+                    ctx.fillRect(p.x - p.size / 2, p.y - p.size / 2, p.size, p.size);
+                }
+                ctx.globalAlpha = 1;
+            },
+
+            clear: function() {
+                for (var i = 0; i < pool.length; i++) {
+                    pool[i].active = false;
+                }
+                activeCount = 0;
+            }
+        };
+    };
+
+    // -------------------------------------------------------
+    // 10. Screen Shake
+    // -------------------------------------------------------
+    RG.createShake = function() {
+        var intensity = 0;
+        var ox = 0;
+        var oy = 0;
+
+        return {
+            get offsetX() { return ox; },
+            get offsetY() { return oy; },
+            get isActive() { return intensity > 0.5; },
+
+            trigger: function(amount, duration) {
+                // duration is unused — shake decays exponentially.
+                // Keeping the param for API consistency; intensity drives magnitude.
+                intensity = amount;
+            },
+
+            update: function(dt) {
+                if (intensity < 0.5) {
+                    intensity = 0;
+                    ox = 0;
+                    oy = 0;
+                    return;
+                }
+                ox = (Math.random() - 0.5) * intensity * 2;
+                oy = (Math.random() - 0.5) * intensity * 2;
+                // Exponential decay: ~0.9 per frame at 60fps
+                intensity *= Math.pow(0.9, dt * 60);
+            }
+        };
+    };
+
+    // -------------------------------------------------------
+    // 11. Sound Effects
+    // -------------------------------------------------------
+    RG.createSoundEffects = function(opts) {
+        opts = opts || {};
+        var masterVolume = opts.volume != null ? opts.volume : 1;
+        var basePath = opts.basePath || null;
+        var manifestUrl = opts.manifest || null;
+        var loaded = false;
+        var manifest = null;
+        var audioPool = {}; // name -> Array of Audio objects
+        var activeAudios = {}; // name -> Array of currently-playing Audio
+        var loopTimers = {}; // name -> timeout id for delay-based loops
+        var ambientSources = {}; // name -> { source, gain } for Web Audio ambient loops
+        var audioCtx = null;
+        var audioBuffers = {}; // name -> AudioBuffer (cached)
+        var POOL_SIZE = 4;
+
+        // Auto-detect basePath from current page URL
+        function getBasePath() {
+            if (basePath) return basePath;
+            // Derive from current page: /api/files/{pageName}
+            var path = window.location.pathname.replace(/^\//, '').replace(/\/$/, '');
+            return '/api/files/' + encodeURIComponent(path);
+        }
+
+        function getManifestUrl() {
+            return manifestUrl || (getBasePath() + '/effects.json');
+        }
+
+        function createAudioClone(name) {
+            var entry = manifest.effects.find(function(e) { return e.name === name; });
+            if (!entry) return null;
+            var audio = new Audio(getBasePath() + '/' + encodeURIComponent(entry.file));
+            audio.volume = masterVolume;
+            audio.preload = 'auto';
+            return audio;
+        }
+
+        function getFromPool(name) {
+            var pool = audioPool[name];
+            if (!pool || pool.length === 0) return createAudioClone(name);
+            // Find one that's not currently playing
+            for (var i = 0; i < pool.length; i++) {
+                if (pool[i].paused || pool[i].ended) {
+                    pool[i].currentTime = 0;
+                    pool[i].volume = masterVolume;
+                    return pool[i];
+                }
+            }
+            // All busy — create a new clone
+            var clone = createAudioClone(name);
+            if (clone) pool.push(clone);
+            return clone;
+        }
+
+        function preloadAll() {
+            if (!manifest || !manifest.effects) return;
+            for (var i = 0; i < manifest.effects.length; i++) {
+                var name = manifest.effects[i].name;
+                audioPool[name] = [];
+                activeAudios[name] = [];
+                for (var j = 0; j < POOL_SIZE; j++) {
+                    var a = createAudioClone(name);
+                    if (a) audioPool[name].push(a);
+                }
+            }
+        }
+
+        function getAudioCtx() {
+            if (!audioCtx) audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+            return audioCtx;
+        }
+
+        function fetchBuffer(name) {
+            if (audioBuffers[name]) return Promise.resolve(audioBuffers[name]);
+            var entry = getEffectEntry(name);
+            if (!entry) return Promise.reject(new Error('Unknown effect: ' + name));
+            var url = getBasePath() + '/' + encodeURIComponent(entry.file);
+            return new Promise(function(resolve, reject) {
+                var xhr = new XMLHttpRequest();
+                xhr.open('GET', url, true);
+                xhr.responseType = 'arraybuffer';
+                xhr.onload = function() {
+                    if (xhr.status < 200 || xhr.status >= 300) {
+                        reject(new Error('Failed to fetch audio: HTTP ' + xhr.status));
+                        return;
+                    }
+                    getAudioCtx().decodeAudioData(xhr.response, function(buf) {
+                        audioBuffers[name] = buf;
+                        resolve(buf);
+                    }, reject);
+                };
+                xhr.onerror = function() { reject(new Error('Network error')); };
+                xhr.send();
+            });
+        }
+
+        function getEffectEntry(name) {
+            if (!manifest || !manifest.effects) return null;
+            return manifest.effects.find(function(e) { return e.name === name; }) || null;
+        }
+
+        var sfx = {
+            get isLoaded() { return loaded; },
+
+            get volume() { return masterVolume; },
+            set volume(v) {
+                masterVolume = Math.max(0, Math.min(1, v));
+                // Update all active HTML audios
+                for (var name in activeAudios) {
+                    var list = activeAudios[name];
+                    for (var i = 0; i < list.length; i++) {
+                        list[i].volume = masterVolume;
+                    }
+                }
+                // Update all ambient gain nodes
+                for (var aName in ambientSources) {
+                    if (ambientSources[aName].gain) {
+                        ambientSources[aName].gain.gain.value = masterVolume;
+                    }
+                }
+            },
+
+            get effects() {
+                if (!manifest || !manifest.effects) return [];
+                return manifest.effects.map(function(e) { return e.name; });
+            },
+
+            has: function(name) {
+                return !!getEffectEntry(name);
+            },
+
+            load: function() {
+                return new Promise(function(resolve, reject) {
+                    var url = getManifestUrl();
+                    var xhr = new XMLHttpRequest();
+                    xhr.open('GET', url, true);
+                    xhr.onload = function() {
+                        if (xhr.status < 200 || xhr.status >= 300) {
+                            reject(new Error('Failed to load effects manifest: HTTP ' + xhr.status));
+                            return;
+                        }
+                        try {
+                            manifest = JSON.parse(xhr.responseText);
+                        } catch (e) {
+                            reject(new Error('Invalid effects manifest JSON'));
+                            return;
+                        }
+                        preloadAll();
+                        loaded = true;
+                        resolve();
+                    };
+                    xhr.onerror = function() {
+                        reject(new Error('Network error loading effects manifest'));
+                    };
+                    xhr.send();
+                });
+            },
+
+            play: function(name) {
+                if (!loaded) return;
+                var entry = getEffectEntry(name);
+                if (!entry) return;
+
+                var loop = entry.loop || {};
+                var isAmbient = loop.ambient || false;
+
+                if (isAmbient) {
+                    // Web Audio API — gapless ambient loop
+                    if (ambientSources[name]) return; // already playing
+                    fetchBuffer(name).then(function(buffer) {
+                        var ctx = getAudioCtx();
+                        if (ctx.state === 'suspended') ctx.resume();
+                        var source = ctx.createBufferSource();
+                        source.buffer = buffer;
+                        source.loop = true;
+                        var gain = ctx.createGain();
+                        gain.gain.value = masterVolume;
+                        source.connect(gain);
+                        gain.connect(ctx.destination);
+                        source.start(0);
+                        ambientSources[name] = { source: source, gain: gain };
+                    }).catch(function() {});
+                    return;
+                }
+
+                // Standard HTML Audio path
+                var audio = getFromPool(name);
+                if (!audio) return;
+
+                if (!activeAudios[name]) activeAudios[name] = [];
+                activeAudios[name].push(audio);
+
+                var loopEnabled = loop.enabled || false;
+                var minDelay = (loop.minDelay || 0) * 1000;
+                var maxDelay = (loop.maxDelay || 0) * 1000;
+                var seamless = loopEnabled && minDelay === 0 && maxDelay === 0;
+
+                if (seamless) {
+                    audio.loop = true;
+                } else {
+                    audio.loop = false;
+                }
+
+                audio.play().catch(function() {});
+
+                if (loopEnabled && !seamless) {
+                    audio.onended = function() {
+                        var idx = activeAudios[name] ? activeAudios[name].indexOf(audio) : -1;
+                        if (idx >= 0) activeAudios[name].splice(idx, 1);
+                        if (!loopTimers[name] && loopTimers[name] !== 0) return;
+                        var delay = minDelay + Math.random() * (maxDelay - minDelay);
+                        loopTimers[name] = setTimeout(function() {
+                            sfx.play(name);
+                        }, delay);
+                    };
+                    loopTimers[name] = -1;
+                } else if (!loopEnabled) {
+                    audio.onended = function() {
+                        var idx = activeAudios[name] ? activeAudios[name].indexOf(audio) : -1;
+                        if (idx >= 0) activeAudios[name].splice(idx, 1);
+                    };
+                }
+            },
+
+            stop: function(name) {
+                // Stop ambient source if present
+                if (ambientSources[name]) {
+                    try { ambientSources[name].source.stop(); } catch (e) {}
+                    try { ambientSources[name].source.disconnect(); } catch (e) {}
+                    try { ambientSources[name].gain.disconnect(); } catch (e) {}
+                    delete ambientSources[name];
+                }
+                // Clear loop timer
+                if (loopTimers[name] != null) {
+                    if (loopTimers[name] > 0) clearTimeout(loopTimers[name]);
+                    delete loopTimers[name];
+                }
+                // Stop all active HTML audios for this effect
+                var list = activeAudios[name];
+                if (list) {
+                    for (var i = 0; i < list.length; i++) {
+                        list[i].loop = false;
+                        list[i].pause();
+                        list[i].currentTime = 0;
+                        list[i].onended = null;
+                    }
+                    activeAudios[name] = [];
+                }
+            },
+
+            stopAll: function() {
+                var name;
+                for (name in ambientSources) {
+                    sfx.stop(name);
+                }
+                for (name in activeAudios) {
+                    sfx.stop(name);
+                }
+            }
+        };
+
+        return sfx;
+    };
+
+    // -------------------------------------------------------
+    // 12. Pause Manager
+    // -------------------------------------------------------
+    RG.createPauseManager = function(overlayEl, opts) {
+        opts = opts || {};
+        var visibleClass = opts.visibleClass || "visible";
+        var gameLoop = opts.gameLoop || null;
+        var paused = false;
+
+        function syncOverlay() {
+            if (paused) {
+                overlayEl.classList.add(visibleClass);
+            } else {
+                overlayEl.classList.remove(visibleClass);
+            }
+        }
+
+        return {
+            get isPaused() { return paused; },
+
+            toggle: function() {
+                if (paused) this.resume();
+                else this.pause();
+            },
+
+            pause: function() {
+                if (paused) return;
+                paused = true;
+                if (gameLoop) gameLoop.pause();
+                syncOverlay();
+            },
+
+            resume: function() {
+                if (!paused) return;
+                paused = false;
+                if (gameLoop) gameLoop.resume();
+                syncOverlay();
+            }
+        };
+    };
+
+    // -------------------------------------------------------
+    // Expose namespace
+    // -------------------------------------------------------
+    window.RetroGame = RG;
+})();