dopaminejs 2.0.2 → 2.2.0

package/src/dopamine/core/RewardSystem.js

@@ -6,11 +6,62 @@
 import { EventEmitter } from './EventEmitter.js';
 
 export class RewardSystem extends EventEmitter {
+    /**
+     * @param {Object} dataService - Persistence, see DataService
+     * @param {Object} [config]
+     * @param {Object} [config.achievements] - Extra achievement definitions
+     * @param {Object} [config.events] - Kernel EventBus to mirror events onto
+     * @param {Object} [config.kernel] - Kernel; its `events` bus is used if present
+     */
     constructor(dataService, config = {}) {
         super();
         this.dataService = dataService;
         this.player = null;
         this.achievements = { ...this._initAchievements(), ...(config.achievements || {}) };
+
+        // Optional bridge to the kernel bus. EventBus.Events already declared
+        // XP_GAINED, LEVEL_UP and ACHIEVEMENT_UNLOCKED with nothing emitting
+        // them; this connects the two event systems without changing the
+        // existing rewardSystem.on(...) surface that games already use.
+        this.events = config.events || config.kernel?.events || null;
+
+        // Write batching. Every mutation used to hit storage directly, so one
+        // recordGame produced four full serializations of the player object.
+        this._batchDepth = 0;
+        this._pendingSave = false;
+    }
+
+    /**
+     * Emit locally, and mirror onto the kernel bus when one is attached.
+     * @private
+     */
+    _publish(event, data) {
+        this.emit(event, data);
+        if (this.events) {
+            this.events.emit(event, data);
+        }
+    }
+
+    /**
+     * Run `fn` with saves collapsed into a single write at the end.
+     *
+     * Nested batches are counted, so an inner operation that batches on its
+     * own still results in exactly one write for the outermost call.
+     *
+     * @param {Function} fn
+     * @private
+     */
+    async _batch(fn) {
+        this._batchDepth++;
+        try {
+            return await fn();
+        } finally {
+            this._batchDepth--;
+            if (this._batchDepth === 0 && this._pendingSave) {
+                this._pendingSave = false;
+                await this._write();
+            }
+        }
     }
 
     /**
@@ -18,7 +69,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,14 +104,55 @@ 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
      */
     async save() {
-        if (this.player) {
-            this.player.lastPlayedAt = Date.now();
-            await this.dataService.save('player', this.player);
+        if (!this.player) return;
+
+        // Inside a batch, mark dirty and let the outermost call do the write.
+        if (this._batchDepth > 0) {
+            this._pendingSave = true;
+            return;
         }
+
+        await this._write();
+    }
+
+    /**
+     * The actual persistence call. Bypasses batching.
+     * @private
+     */
+    async _write() {
+        this.player.lastPlayedAt = Date.now();
+        await this.dataService.save('player', this.player);
     }
 
     /**
@@ -69,6 +162,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;
 
@@ -83,10 +182,10 @@ export class RewardSystem extends EventEmitter {
         await this.save();
 
         // Notify listeners
-        this.emit('xp_gained', { amount, reason, leveledUp, newLevel });
+        this._publish('xp_gained', { amount, reason, leveledUp, newLevel });
 
         if (leveledUp) {
-            this.emit('level_up', { oldLevel, newLevel });
+            this._publish('level_up', { oldLevel, newLevel });
         }
 
         return { leveledUp, newLevel, xpGained: amount };
@@ -96,9 +195,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 +208,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
         };
     }
 
@@ -122,6 +230,15 @@ export class RewardSystem extends EventEmitter {
      * @param {Object} result - Game-specific result data
      */
     async recordGame(gameName, result) {
+        // Batched: addXP and each unlockAchievement below also save, which
+        // meant four full serializations of the player object per game.
+        return this._batch(() => this._recordGame(gameName, result));
+    }
+
+    /**
+     * @private
+     */
+    async _recordGame(gameName, result) {
         // Initialize stats for this game if not exists
         if (!this.player.stats[gameName]) {
             this.player.stats[gameName] = { totalPlays: 0, highScore: 0 };
@@ -136,7 +253,7 @@ export class RewardSystem extends EventEmitter {
         // Update high score if applicable
         if (result.score !== undefined && result.score > stats.highScore) {
             stats.highScore = result.score;
-            this.emit('new_high_score', { gameName, score: result.score });
+            this._publish('new_high_score', { gameName, score: result.score });
         }
 
         // Merge other result data into stats
@@ -175,8 +292,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,10 +324,11 @@ 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);
+        this._publish('achievement_unlocked', achievement);
         await this.save();
 
         return true;
@@ -278,19 +405,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 = [];
     }
 }