dopaminejs 2.1.0 → 2.3.0

package/src/dopamine/index.js

@@ -24,6 +24,7 @@ export default class Dopamine {
 
     async init() {
         await this.rewardSystem.init();
+        this._syncUI();
         return {
             rewardSystem: this.rewardSystem,
             gameUI: this.gameUI,
@@ -32,30 +33,61 @@ export default class Dopamine {
         };
     }
 
+    /**
+     * Draw the loaded player. Without this the overlay keeps its placeholder
+     * (level 1, 0 XP, streak 1) until the first event arrives.
+     * @private
+     */
+    _syncUI() {
+        const { player } = this.rewardSystem;
+        const { total, needed, progress } = this.rewardSystem.getXPForNextLevel();
+
+        this.gameUI.updateXP(player.xp, needed, total, progress);
+        this.gameUI.updateLevel(player.level);
+        this.gameUI.updateStreak(player.streak.current);
+    }
+
     _bindEvents() {
-        this.rewardSystem.on('xp_gained', (data) => {
-            const { total, needed } = this.rewardSystem.getXPForNextLevel();
-            this.gameUI.updateXP(this.rewardSystem.player.xp, needed, total);
-
-            if (data.xpGained > 0) {
-                // Show floating text for XP gain
-                // We might need a way to know WHERE to show this, or just show it in a standard place
-                // For now, let's just update the bar
-            }
-        });
-
-        this.rewardSystem.on('level_up', (data) => {
-            this.gameUI.updateLevel(data.newLevel);
-            this.gameUI.showLevelUp(data.oldLevel, data.newLevel);
-        });
-
-        this.rewardSystem.on('achievement_unlocked', (achievement) => {
-            this.gameUI.showAchievement(achievement);
-        });
-
-        this.rewardSystem.on('new_high_score', (data) => {
-            this.gameUI.showNotification(`New High Score: ${data.score}!`, 'legendary');
-            this.soundManager.playSuccess();
-        });
+        const rewards = this.rewardSystem;
+
+        this._unsubscribe = [
+            rewards.on('xp_gained', () => {
+                const { total, needed, progress } = rewards.getXPForNextLevel();
+                this.gameUI.updateXP(rewards.player.xp, needed, total, progress);
+            }),
+
+            rewards.on('level_up', (data) => {
+                this.gameUI.updateLevel(data.newLevel);
+                this.gameUI.showLevelUp(data.oldLevel, data.newLevel);
+            }),
+
+            rewards.on('achievement_unlocked', (achievement) => {
+                this.gameUI.showAchievement(achievement);
+            }),
+
+            rewards.on('streak_updated', (data) => {
+                this.gameUI.updateStreak(data.current);
+            }),
+
+            rewards.on('new_high_score', (data) => {
+                this.gameUI.showNotification(`New High Score: ${data.score}!`, 'legendary');
+                this.soundManager.playSuccess();
+            })
+        ];
+    }
+
+    /**
+     * Remove the overlay and canvas, stop audio, and detach from the reward
+     * system. The reward system itself stays usable.
+     */
+    destroy() {
+        for (const unsubscribe of this._unsubscribe) {
+            unsubscribe();
+        }
+        this._unsubscribe = [];
+
+        this.gameUI.destroy();
+        this.particleSystem.destroy();
+        this.soundManager.destroy();
     }
 }

package/src/dopamine/ui/GameUI.js

@@ -56,6 +56,22 @@ export class GameUI {
             </div>
         `;
 
+        // Popups are decorative and short-lived, so a screen reader would
+        // miss them. This region repeats them as plain text.
+        this.liveRegion = document.createElement('div');
+        this.liveRegion.className = 'dopamine-live-region';
+        this.liveRegion.setAttribute('aria-live', 'polite');
+        this.liveRegion.setAttribute('role', 'status');
+        Object.assign(this.liveRegion.style, {
+            position: 'absolute',
+            width: '1px',
+            height: '1px',
+            overflow: 'hidden',
+            clipPath: 'inset(50%)',
+            whiteSpace: 'nowrap'
+        });
+        this.container.appendChild(this.liveRegion);
+
         document.body.appendChild(this.container);
 
         // Scoped to this instance. Document-wide getElementById would make a
@@ -91,6 +107,16 @@ export class GameUI {
         return el;
     }
 
+    /**
+     * Repeat a popup as text for assistive technology.
+     * @private
+     */
+    _announce(message) {
+        if (this.liveRegion) {
+            this.liveRegion.textContent = message;
+        }
+    }
+
     /**
      * Replay a CSS animation by clearing it for one tick.
      * @private
@@ -106,10 +132,15 @@ export class GameUI {
      * @param {number} current - XP held right now
      * @param {number} needed - XP still required for the next level
      * @param {number} total - XP total that marks the next level
+     * @param {number} [progress] - Position within the current level, 0 to 1.
+     *   Without it the bar falls back to current / total, which is lifetime
+     *   XP and starts every level after the first partly full.
      */
-    updateXP(current, needed, total) {
-        const progress = total > 0 ? (current / total) * 100 : 0;
-        this.xpBar.style.width = `${Math.max(0, Math.min(100, progress))}%`;
+    updateXP(current, needed, total, progress) {
+        const fraction = Number.isFinite(progress)
+            ? progress
+            : (total > 0 ? current / total : 0);
+        this.xpBar.style.width = `${Math.max(0, Math.min(100, fraction * 100))}%`;
         this.xpText.textContent = `${current} / ${total} XP`;
 
         this._replayAnimation(this.xpBar, 'xp-pulse 0.3s ease-out');
@@ -134,6 +165,8 @@ export class GameUI {
             this.streakBadge.style.background = 'linear-gradient(135deg, #ff6b00 0%, #ff4400 100%)';
         } else if (days >= 3) {
             this.streakBadge.style.background = 'linear-gradient(135deg, #ff8800 0%, #ff6b00 100%)';
+        } else {
+            this.streakBadge.style.background = '';
         }
     }
 
@@ -167,6 +200,7 @@ export class GameUI {
         popup.querySelector('.achievement-xp').textContent = `+${achievement.xp ?? 0} XP`;
 
         this._mount(popup);
+        this._announce(`Achievement unlocked: ${achievement.name ?? ''}`);
 
         // Trigger confetti at popup location
         this._defer(() => {
@@ -197,6 +231,7 @@ export class GameUI {
         overlay.querySelector('.level-up-number').textContent = newLevel;
 
         this._mount(overlay);
+        this._announce(`Level up: ${newLevel}`);
 
         // Fireworks effect
         this._defer(() => {
@@ -265,13 +300,20 @@ export class GameUI {
         const x = window.innerWidth / 2;
         const y = window.innerHeight / 3;
 
+        // The message is shown as written. showLuckyMoment and showCombo
+        // expect a multiplier and would wrap it in "LUCKY ...×!".
         if (type === 'legendary') {
-            this.showLuckyMoment(message, x, y);
+            this.showFloatingText(message, x, y, '#ffd700', '36px');
+            this.particleSystem.starBurst(x, y, 12);
+            this.particleSystem.confetti(x, y, 25);
         } else if (type === 'rare') {
-            this.showCombo(message, x, y);
+            this.showFloatingText(message, x, y, '#ff6b6b', '32px');
+            this.particleSystem.fire(x, y, 20);
         } else {
             this.showFloatingText(message, x, y, '#fff', '24px');
         }
+
+        this._announce(message);
     }
 
     /**
@@ -367,6 +409,7 @@ export class GameUI {
 
         this.container?.remove();
         this.container = null;
+        this.liveRegion = null;
         this.xpBar = null;
         this.xpText = null;
         this.levelBadge = null;

package/src/dopamine/ui/dopamine.css

@@ -375,3 +375,21 @@
         font-size: 80px;
     }
 }
+
+/* Users who asked the OS for less motion get the same information without
+   the movement. Floating text keeps its place until the script removes it:
+   its animation ends at opacity 0, so cutting the duration would hide it. */
+@media (prefers-reduced-motion: reduce) {
+    .game-ui-overlay *,
+    .achievement-popup,
+    .achievement-popup *,
+    .level-up-overlay,
+    .level-up-overlay * {
+        animation: none !important;
+        transition: none !important;
+    }
+
+    .floating-text {
+        animation: none !important;
+    }
+}

package/src/engine.js

@@ -0,0 +1,38 @@
+/**
+ * Engine subpath export — `import { Game, Scene } from 'dopaminejs/engine'`
+ *
+ * The game engine that DopamineJS is built on. Use this subpath if your project
+ * only needs the entity/component system, renderer, or physics, and not the
+ * progression mechanics (RewardSystem, GameUI, DataService).
+ *
+ * The root `dopaminejs` export continues to re-export everything, so nothing breaks.
+ * This subpath makes the README's distinction between the engine and the progression
+ * layer real in code and gives bundlers a clear surface to tree-shake against.
+ */
+
+// Entity / component system
+export { Game } from './core/Game.js';
+export { Scene } from './core/Scene.js';
+export { GameObject } from './core/GameObject.js';
+export { Component } from './core/Component.js';
+export { Vector2 } from './core/Vector2.js';
+export { Collider } from './core/Collider.js';
+export { Sprite } from './core/Sprite.js';
+export { Animator } from './core/Animator.js';
+
+// Kernel and plugin infrastructure
+export { DopamineKernel } from './core/DopamineKernel.js';
+export { EventBus } from './core/EventBus.js';
+export { SystemRegistry } from './core/SystemRegistry.js';
+export { PluginRegistry } from './core/PluginRegistry.js';
+
+// Built-in systems
+export { Renderer } from './renderer/Renderer.js';
+export { Ticker } from './systems/Ticker.js';
+export { Loader, GlobalLoader } from './systems/Loader.js';
+export { Input, GlobalInput } from './systems/Input.js';
+export { Director } from './systems/Director.js';
+export { Physics, GlobalPhysics } from './systems/Physics.js';
+
+// Engine-level components
+export { ParticleEmitter, ScreenShake } from './dopamine/components/index.js';

package/src/index.js

@@ -12,6 +12,12 @@ export { PluginRegistry } from './core/PluginRegistry.js';
 // Export System Interfaces
 export * from './interfaces/index.js';
 
+// The emitter RewardSystem extends, so consumers can type their listeners.
+export { EventEmitter } from './dopamine/core/EventEmitter.js';
+
+// Storage resolution, useful for tests and for SSR where localStorage is absent.
+export { createMemoryStorage, resolveStorage } from './dopamine/utils/storage.js';
+
 // Export New Engine Core
 export { Game } from './core/Game.js';
 export { Scene } from './core/Scene.js';

package/src/systems/Director.js

@@ -14,11 +14,18 @@ export class Director {
     run(scene) {
         if (this.currentScene) {
             this.currentScene.onExit();
+
+            // Its colliders would keep colliding with the next scene.
+            this.currentScene.kernel = null;
         }
 
         this.currentScene = scene;
         this.currentScene.game = this.game;
 
+        if (this.game?.kernel) {
+            scene.kernel = this.game.kernel;
+        }
+
         // Let the game know (if game engine needs to reference it directly)
         this.game.scene = scene;
 

package/src/systems/Input.js

@@ -1,3 +1,5 @@
+import { deprecatedGlobal } from './deprecate.js';
+
 /**
  * Input System
  * Tracks keyboard and mouse input.
@@ -71,7 +73,9 @@ export class Input {
     }
 }
 
-// DEPRECATED: Keep for backward compatibility
-export const GlobalInput = new Input();
-// Note: GlobalInput won't have listeners attached unless init() is called
-console.warn('[DopamineJS] GlobalInput is deprecated. Use kernel.input instead.');
+// DEPRECATED: kept for v1 compatibility. Warns on first use, not on import.
+// Note: listeners are not attached unless init() is called.
+export const GlobalInput = deprecatedGlobal(
+    new Input(),
+    '[DopamineJS] GlobalInput is deprecated. Use kernel.input instead.'
+);

package/src/systems/Loader.js

@@ -1,3 +1,5 @@
+import { deprecatedGlobal } from './deprecate.js';
+
 /**
  * Asset Loader
  * Loads and caches images, audio, etc.
@@ -39,6 +41,8 @@ export class Loader {
     }
 }
 
-// DEPRECATED: Keep for backward compatibility
-export const GlobalLoader = new Loader();
-console.warn('[DopamineJS] GlobalLoader is deprecated. Use kernel.loader instead.');
+// DEPRECATED: kept for v1 compatibility. Warns on first use, not on import.
+export const GlobalLoader = deprecatedGlobal(
+    new Loader(),
+    '[DopamineJS] GlobalLoader is deprecated. Use kernel.loader instead.'
+);

package/src/systems/Physics.js

@@ -1,3 +1,5 @@
+import { deprecatedGlobal } from './deprecate.js';
+
 import { Collider } from '../core/Collider.js';
 
 export class Physics {
@@ -112,6 +114,8 @@ export class Physics {
     setGravity(x, y) { /* TODO: Add gravity support */ }
 }
 
-// DEPRECATED: Keep for backward compatibility, but log warning
-export const GlobalPhysics = new Physics();
-console.warn('[DopamineJS] GlobalPhysics is deprecated. Use kernel.physics instead.');
+// DEPRECATED: kept for v1 compatibility. Warns on first use, not on import.
+export const GlobalPhysics = deprecatedGlobal(
+    new Physics(),
+    '[DopamineJS] GlobalPhysics is deprecated. Use kernel.physics instead.'
+);

package/src/systems/Ticker.js

@@ -9,6 +9,7 @@ export class Ticker {
         this.callbacks = new Set();
         this._frameHandle = null;
         this._tick = this._tick.bind(this);
+        this._failed = new WeakSet();
     }
 
     /**
@@ -64,12 +65,22 @@ export class Ticker {
         const dt = (time - this.lastTime) / 1000; // Delta time in seconds
         this.lastTime = time;
 
-        // Cap dt to prevent huge jumps if tab was inactive
-        const safeDt = Math.min(dt, 0.1);
+        // Cap dt to prevent huge jumps if tab was inactive. Floored at 0: the
+        // first frame's timestamp can predate the performance.now() in start().
+        const safeDt = Math.max(0, Math.min(dt, 0.1));
 
         // Snapshot: a callback may add or remove callbacks mid-frame.
         for (const callback of [...this.callbacks]) {
-            callback(safeDt);
+            try {
+                callback(safeDt);
+            } catch (error) {
+                // A throw here used to skip the re-queue below with `running`
+                // still true, so the loop died and start() refused to revive it.
+                if (!this._failed.has(callback)) {
+                    this._failed.add(callback);
+                    console.error('[Ticker] Callback threw:', error);
+                }
+            }
         }
 
         // A callback may have called stop(); don't queue another frame if so.

package/src/systems/deprecate.js

@@ -0,0 +1,38 @@
+/**
+ * Deprecation helper for the v1 global singletons.
+ *
+ * These used to warn at module scope, which meant importing the package
+ * printed a warning for every legacy global whether or not the consumer
+ * touched one. A deprecation notice should cost you something only when you
+ * use the deprecated thing, otherwise it is just noise that trains people to
+ * ignore warnings.
+ *
+ * @param {Object} instance - The real system to delegate to
+ * @param {string} message - Warning text, emitted once on first use
+ * @returns {Object} A proxy that warns on first property access
+ */
+export function deprecatedGlobal(instance, message) {
+    let warned = false;
+
+    return new Proxy(instance, {
+        get(target, prop, receiver) {
+            if (!warned) {
+                warned = true;
+                console.warn(message);
+            }
+
+            const value = Reflect.get(target, prop, receiver);
+            // Methods must stay bound to the real instance, not the proxy,
+            // or internal `this` access re-enters the trap on every field.
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+
+        set(target, prop, value) {
+            if (!warned) {
+                warned = true;
+                console.warn(message);
+            }
+            return Reflect.set(target, prop, value);
+        }
+    });
+}