dopaminejs 2.0.1 → 2.1.0

package/src/dopamine/audio/SoundManager.js

@@ -3,16 +3,23 @@
  * Handles synthesized sound effects using Web Audio API
  */
 
+import { resolveStorage } from '../utils/storage.js';
+
 export class SoundManager {
     constructor(config = {}) {
         this.audioContext = null;
         this.storageKey = config.storageKey || 'dopamineSoundsMuted';
-        this.muted = localStorage.getItem(this.storageKey) === 'true';
+        this.storage = config.storage || resolveStorage();
+        this.muted = this.storage.getItem(this.storageKey) === 'true';
 
         // Asset management
         this.assets = new Map(); // key -> AudioBuffer
         this.customSounds = config.customSounds || {}; // key -> url
 
+        // Master gain, created with the AudioContext on first use.
+        this.masterGain = null;
+        this._volume = config.volume ?? 1;
+
         // Preload custom sounds if provided
         if (Object.keys(this.customSounds).length > 0) {
             this.preloadSounds(this.customSounds);
@@ -24,12 +31,53 @@ export class SoundManager {
      */
     initAudio() {
         if (!this.audioContext) {
-            const AudioContext = window.AudioContext || window.webkitAudioContext;
-            this.audioContext = new AudioContext();
+            const Ctor = typeof window !== 'undefined'
+                ? (window.AudioContext || window.webkitAudioContext)
+                : undefined;
+
+            // No Web Audio API: SSR, a worker, or a very old browser. Stay
+            // silent rather than taking the whole game down.
+            if (!Ctor) return false;
+
+            this.audioContext = new Ctor();
+            this.masterGain = this.audioContext.createGain();
+            this.masterGain.gain.value = this._volume;
+            this.masterGain.connect(this.audioContext.destination);
         }
+
         if (this.audioContext.state === 'suspended') {
             this.audioContext.resume();
         }
+
+        return true;
+    }
+
+    /**
+     * Set master output volume.
+     * @param {number} value - 0..1
+     */
+    setVolume(value) {
+        this._volume = Math.max(0, Math.min(1, value));
+        if (this.masterGain) {
+            this.masterGain.gain.value = this._volume;
+        }
+        return this._volume;
+    }
+
+    /**
+     * Current master output volume.
+     * @returns {number}
+     */
+    getVolume() {
+        return this._volume;
+    }
+
+    /**
+     * Node every sound routes through, so volume and mute apply uniformly.
+     * @private
+     */
+    _output() {
+        return this.masterGain || this.audioContext.destination;
     }
 
     /**
@@ -38,7 +86,7 @@ export class SoundManager {
      */
     toggleMute() {
         this.muted = !this.muted;
-        localStorage.setItem(this.storageKey, this.muted);
+        this.storage.setItem(this.storageKey, this.muted);
         return this.muted;
     }
 
@@ -92,7 +140,7 @@ export class SoundManager {
      */
     async play(key) {
         if (this.muted) return;
-        this.initAudio();
+        if (!this.initAudio()) return;
 
         // 1. Try custom asset first
         if (this.assets.has(key)) {
@@ -127,7 +175,7 @@ export class SoundManager {
     _playBuffer(buffer) {
         const source = this.audioContext.createBufferSource();
         source.buffer = buffer;
-        source.connect(this.audioContext.destination);
+        source.connect(this._output());
         source.start(0);
     }
 
@@ -136,18 +184,20 @@ export class SoundManager {
      */
     playTone(frequency, duration, type = 'sine', volume = 0.3) {
         if (this.muted) return;
-        this.initAudio();
+        if (!this.initAudio()) return;
 
         const oscillator = this.audioContext.createOscillator();
         const gainNode = this.audioContext.createGain();
 
         oscillator.connect(gainNode);
-        gainNode.connect(this.audioContext.destination);
+        gainNode.connect(this._output());
 
         oscillator.frequency.value = frequency;
         oscillator.type = type;
 
-        gainNode.gain.setValueAtTime(volume, this.audioContext.currentTime);
+        // exponentialRampToValueAtTime cannot reach or start from zero.
+        const peak = Math.max(0.0001, volume);
+        gainNode.gain.setValueAtTime(peak, this.audioContext.currentTime);
         gainNode.gain.exponentialRampToValueAtTime(0.01, this.audioContext.currentTime + duration);
 
         oscillator.start(this.audioContext.currentTime);

package/src/dopamine/core/DataService.js

@@ -3,9 +3,11 @@
  * Handles local storage persistence
  */
 
+import { resolveStorage } from '../utils/storage.js';
+
 export class DataService {
     constructor(config = {}) {
-        this.storage = config.storage || window.localStorage;
+        this.storage = config.storage || resolveStorage();
         this.prefix = config.prefix || 'dopamine_';
     }
 

package/src/dopamine/core/RewardSystem.js

@@ -18,7 +18,8 @@ export class RewardSystem extends EventEmitter {
      * @returns {Promise<Object>} Player data
      */
     async init() {
-        this.player = await this.dataService.load('player', this._getDefaultPlayer());
+        const saved = await this.dataService.load('player', null);
+        this.player = this._migrate(saved);
 
         // Check daily streak
         this._updateDailyStreak();
@@ -52,6 +53,33 @@ export class RewardSystem extends EventEmitter {
         };
     }
 
+    /**
+     * Merge a persisted player record onto the current default shape.
+     *
+     * Saves written by older versions are missing whatever fields were added
+     * since. Without this the first property access on a new field throws
+     * before the game has drawn a frame.
+     *
+     * @param {Object|null} saved - Previously persisted player, if any
+     * @returns {Object} Player object guaranteed to have every field
+     * @private
+     */
+    _migrate(saved) {
+        const defaults = this._getDefaultPlayer();
+
+        if (!saved || typeof saved !== 'object') {
+            return defaults;
+        }
+
+        return {
+            ...defaults,
+            ...saved,
+            streak: { ...defaults.streak, ...(saved.streak || {}) },
+            achievements: saved.achievements || {},
+            stats: saved.stats || {}
+        };
+    }
+
     /**
      * Save player data
      */
@@ -69,6 +97,12 @@ export class RewardSystem extends EventEmitter {
      * @returns {Object} { leveledUp: boolean, newLevel: number, xpGained: number }
      */
     async addXP(amount, reason = '') {
+        if (!Number.isFinite(amount)) {
+            // Adding undefined/NaN here would poison player.xp permanently:
+            // NaN survives every subsequent arithmetic op and gets persisted.
+            throw new TypeError(`[DopamineJS] addXP expects a finite number, received ${amount}`);
+        }
+
         const oldLevel = this.player.level;
         this.player.xp += amount;
 
@@ -96,9 +130,9 @@ export class RewardSystem extends EventEmitter {
      * Calculate level from XP (exponential curve)
      */
     _calculateLevel(xp) {
-        // Formula: XP = 50 * level * (level - 1)
-        // Solving for level: level = (1 + sqrt(1 + 8*XP/50)) / 2
-        const level = Math.floor((1 + Math.sqrt(1 + 8 * xp / 50)) / 2);
+        // Curve: XP = 50 * level * (level - 1)
+        // 50L² - 50L - xp = 0  =>  L = (1 + sqrt(1 + 4*xp/50)) / 2
+        const level = Math.floor((1 + Math.sqrt(1 + 4 * xp / 50)) / 2);
         return Math.max(1, level);
     }
 
@@ -109,10 +143,19 @@ export class RewardSystem extends EventEmitter {
         const nextLevel = this.player.level + 1;
         const xpNeeded = 50 * nextLevel * (nextLevel - 1);
         const currentLevelXP = 50 * this.player.level * (this.player.level - 1);
+        const band = xpNeeded - currentLevelXP;
+
+        // Clamped: a save written before the curve fix banked levels at half
+        // the XP, so player.xp can sit below its own level's floor. Those
+        // players keep the level they earned and start the band at 0.
+        const progress = band > 0
+            ? Math.max(0, Math.min(1, (this.player.xp - currentLevelXP) / band))
+            : 0;
+
         return {
             total: xpNeeded,
-            needed: xpNeeded - this.player.xp,
-            progress: (this.player.xp - currentLevelXP) / (xpNeeded - currentLevelXP)
+            needed: Math.max(0, xpNeeded - this.player.xp),
+            progress
         };
     }
 
@@ -175,8 +218,17 @@ export class RewardSystem extends EventEmitter {
             // Skip if already unlocked
             if (this.player.achievements[id]) continue;
 
-            // Check if achievement condition is met
-            if (achievement.check(this.player, gameName, result)) {
+            // Check conditions are user-supplied; one throwing must not stop
+            // the others from ever unlocking.
+            let met = false;
+            try {
+                met = achievement.check(this.player, gameName, result);
+            } catch (error) {
+                console.error(`[DopamineJS] Achievement "${id}" check threw:`, error);
+                continue;
+            }
+
+            if (met) {
                 await this.unlockAchievement(id);
                 unlockedAchievements.push(achievement);
             }
@@ -198,8 +250,9 @@ export class RewardSystem extends EventEmitter {
             seen: false
         };
 
-        // Award XP
-        await this.addXP(achievement.xp, `Achievement: ${achievement.name}`);
+        // Award XP. `xp` is optional in a user-defined achievement.
+        await this.addXP(Number.isFinite(achievement.xp) ? achievement.xp : 0,
+            `Achievement: ${achievement.name}`);
 
         this.emit('achievement_unlocked', achievement);
         await this.save();
@@ -278,19 +331,37 @@ export class RewardSystem extends EventEmitter {
     }
 
     /**
-     * Get today's date as YYYY-MM-DD string
+     * Format a Date as a YYYY-MM-DD string in the player's local timezone.
+     *
+     * Deliberately not toISOString(), which formats in UTC. For anyone east or
+     * west of Greenwich that shifts the calendar day for part of every day and
+     * makes streaks reset or double-count.
+     *
+     * @param {Date} date
+     * @returns {string}
+     * @private
+     */
+    _toLocalDateString(date) {
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        return `${year}-${month}-${day}`;
+    }
+
+    /**
+     * Get today's local date as YYYY-MM-DD string
      */
     _getTodayDateString() {
-        return new Date().toISOString().split('T')[0];
+        return this._toLocalDateString(new Date());
     }
 
     /**
-     * Get yesterday's date as YYYY-MM-DD string
+     * Get yesterday's local date as YYYY-MM-DD string
      */
     _getYesterdayDateString() {
         const yesterday = new Date();
         yesterday.setDate(yesterday.getDate() - 1);
-        return yesterday.toISOString().split('T')[0];
+        return this._toLocalDateString(yesterday);
     }
 
     /**

package/src/dopamine/effects/ParticleSystem.js

@@ -10,32 +10,34 @@ export class ParticleSystem {
             : document.body;
 
         this.canvasId = config.canvasId || 'dopamine-particle-canvas';
-        this.canvas = document.getElementById(this.canvasId);
 
-        if (!this.canvas) {
-            this.canvas = document.createElement('canvas');
+        // Each instance owns its canvas. Sharing one by id meant two systems
+        // cleared each other's frames every tick.
+        this.canvas = document.createElement('canvas');
+        this.canvas.classList.add('dopamine-particle-canvas');
+        if (!document.getElementById(this.canvasId)) {
             this.canvas.id = this.canvasId;
-            this.canvas.style.pointerEvents = 'none';
-            this.canvas.style.zIndex = config.zIndex || '9999';
+        }
+        this.canvas.style.pointerEvents = 'none';
+        this.canvas.style.zIndex = config.zIndex || '9999';
 
-            if (this.container === document.body) {
-                this.canvas.style.position = 'fixed';
-                this.canvas.style.top = '0';
-                this.canvas.style.left = '0';
-            } else {
-                this.canvas.style.position = 'absolute';
-                this.canvas.style.top = '0';
-                this.canvas.style.left = '0';
-                // Ensure container is positioned
-                const style = window.getComputedStyle(this.container);
-                if (style.position === 'static') {
-                    this.container.style.position = 'relative';
-                }
+        if (this.container === document.body) {
+            this.canvas.style.position = 'fixed';
+            this.canvas.style.top = '0';
+            this.canvas.style.left = '0';
+        } else {
+            this.canvas.style.position = 'absolute';
+            this.canvas.style.top = '0';
+            this.canvas.style.left = '0';
+            // Ensure container is positioned
+            const style = window.getComputedStyle(this.container);
+            if (style.position === 'static') {
+                this.container.style.position = 'relative';
             }
-
-            this.container.appendChild(this.canvas);
         }
 
+        this.container.appendChild(this.canvas);
+
         this.ctx = this.canvas.getContext('2d');
         this.particles = [];
         this.pool = []; // Object pool
@@ -43,23 +45,44 @@ export class ParticleSystem {
         this.customEffects = new Map(); // key -> callback
         this.isAnimating = false;
 
+        // Kept on the instance so destroy() can actually detach them. An
+        // inline arrow passed to addEventListener can never be removed.
+        this._onResize = () => this._resize();
+        this._resizeObserver = null;
+        this._frameHandle = null;
+
         this._resize();
         // Use ResizeObserver for container resizing if supported, fallback to window resize
         if (window.ResizeObserver && this.container !== document.body) {
-            new ResizeObserver(() => this._resize()).observe(this.container);
+            this._resizeObserver = new ResizeObserver(this._onResize);
+            this._resizeObserver.observe(this.container);
         } else {
-            window.addEventListener('resize', () => this._resize());
+            window.addEventListener('resize', this._onResize);
         }
     }
 
     _resize() {
-        if (this.container === document.body) {
-            this.canvas.width = window.innerWidth;
-            this.canvas.height = window.innerHeight;
-        } else {
-            this.canvas.width = this.container.clientWidth;
-            this.canvas.height = this.container.clientHeight;
-        }
+        const cssWidth = this.container === document.body
+            ? window.innerWidth
+            : this.container.clientWidth;
+        const cssHeight = this.container === document.body
+            ? window.innerHeight
+            : this.container.clientHeight;
+
+        // Back the canvas with device pixels but keep the drawing coordinate
+        // system in CSS pixels, so particle positions stay in page units and
+        // nothing looks soft on a HiDPI display.
+        const dpr = window.devicePixelRatio || 1;
+
+        this.width = cssWidth;
+        this.height = cssHeight;
+
+        this.canvas.width = Math.round(cssWidth * dpr);
+        this.canvas.height = Math.round(cssHeight * dpr);
+        this.canvas.style.width = `${cssWidth}px`;
+        this.canvas.style.height = `${cssHeight}px`;
+
+        this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
     }
 
     /**
@@ -237,7 +260,9 @@ export class ParticleSystem {
     }
 
     _animate() {
-        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+        this._frameHandle = null;
+        // CSS pixels: the context is pre-scaled by devicePixelRatio.
+        this.ctx.clearRect(0, 0, this.width, this.height);
 
         for (let i = this.particles.length - 1; i >= 0; i--) {
             const p = this.particles[i];
@@ -288,7 +313,7 @@ export class ParticleSystem {
         }
 
         if (this.particles.length > 0) {
-            requestAnimationFrame(() => this._animate());
+            this._frameHandle = requestAnimationFrame(() => this._animate());
         } else {
             this.isAnimating = false;
         }
@@ -322,6 +347,33 @@ export class ParticleSystem {
         // Recycle all
         this.particles.forEach(p => this._recycleParticle(p));
         this.particles = [];
-        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+        this.ctx.clearRect(0, 0, this.width, this.height);
+    }
+
+    /**
+     * Stop animating, detach resize handling, and remove the canvas.
+     *
+     * Without this the resize listener and canvas outlive the instance, which
+     * matters in any single-page app that mounts and unmounts a game view.
+     */
+    destroy() {
+        this.clear();
+        this.isAnimating = false;
+
+        if (this._frameHandle !== null) {
+            cancelAnimationFrame(this._frameHandle);
+            this._frameHandle = null;
+        }
+
+        if (this._resizeObserver) {
+            this._resizeObserver.disconnect();
+            this._resizeObserver = null;
+        }
+        window.removeEventListener('resize', this._onResize);
+
+        this.canvas.remove();
+        this.sprites.clear();
+        this.customEffects.clear();
+        this.pool = [];
     }
 }

package/src/dopamine/index.js

@@ -24,7 +24,6 @@ export default class Dopamine {
 
     async init() {
         await this.rewardSystem.init();
-        console.log('DopamineJS Initialized 🚀');
         return {
             rewardSystem: this.rewardSystem,
             gameUI: this.gameUI,