dopaminejs 1.2.0 → 2.0.1

package/src/interfaces/IParticleSystem.js

@@ -0,0 +1,51 @@
+import { ISystem } from './ISystem.js';
+
+/**
+ * IParticleSystem - Interface for particle system implementations
+ * 
+ * Allows different renderers (Canvas, WebGL, custom) to be swapped
+ */
+export const IParticleSystem = {
+    ...ISystem,
+
+    /**
+     * Register a sprite for particles
+     * @param {string} key - Sprite identifier
+     * @param {string} url - Path to image
+     */
+    registerSprite(key, url) { },
+
+    /**
+     * Register a custom effect
+     * @param {string} name - Effect name
+     * @param {Function} callback - Effect function (x, y, ...args) => void
+     */
+    registerEffect(name, callback) { },
+
+    /**
+     * Play a registered effect
+     * @param {string} name - Effect name
+     * @param {number} x - X position
+     * @param {number} y - Y position
+     * @param {...any} args - Additional arguments
+     */
+    play(name, x, y, ...args) { },
+
+    /**
+     * Emit particles with custom configuration
+     * @param {Object} config - Particle configuration
+     */
+    emit(config) { },
+
+    /**
+     * Clear all particles
+     */
+    clear() { },
+
+    // Built-in effects (optional, but recommended)
+    confetti(x, y, count) { },
+    coinShower(x, y, count) { },
+    sparkle(x, y, count, color) { },
+    fire(x, y, count) { },
+    starBurst(x, y, count) { },
+};

package/src/interfaces/IPhysicsSystem.js

@@ -0,0 +1,52 @@
+import { ISystem } from './ISystem.js';
+
+/**
+ * IPhysicsSystem - Interface for physics implementations
+ * 
+ * Allows different physics engines (custom, Matter.js, Box2D) to be swapped
+ */
+export const IPhysicsSystem = {
+    ...ISystem,
+
+    /**
+     * Add a physics body to the simulation
+     * @param {Object} body - Physics body (implementation-specific)
+     */
+    addBody(body) { },
+
+    /**
+     * Remove a physics body from the simulation
+     * @param {Object} body - Physics body to remove
+     */
+    removeBody(body) { },
+
+    /**
+     * Check collision between two bodies
+     * @param {Object} a - First body
+     * @param {Object} b - Second body
+     * @returns {boolean} - True if colliding
+     */
+    checkCollision(a, b) { },
+
+    /**
+     * Perform a raycast
+     * @param {Object} origin - Ray origin {x, y}
+     * @param {Object} direction - Ray direction {x, y}
+     * @param {number} distance - Maximum ray distance
+     * @returns {Object|null} - Hit result or null
+     */
+    raycast(origin, direction, distance) { },
+
+    /**
+     * Set gravity for the physics world
+     * @param {number} x - Gravity X component
+     * @param {number} y - Gravity Y component
+     */
+    setGravity(x, y) { },
+
+    /**
+     * Step the physics simulation
+     * @param {number} dt - Delta time
+     */
+    step(dt) { },
+};

package/src/interfaces/ISystem.js

@@ -0,0 +1,48 @@
+/**
+ * ISystem - Base interface for all systems
+ * 
+ * All systems should implement this interface.
+ * Methods are optional - only implement what you need.
+ */
+export const ISystem = {
+    /**
+     * Called when system is registered to the kernel
+     * @param {DopamineKernel} kernel - The kernel instance
+     */
+    init(kernel) { },
+
+    /**
+     * Called each frame (variable timestep)
+     * @param {number} dt - Delta time in seconds
+     */
+    update(dt) { },
+
+    /**
+     * Called at fixed timestep (for physics)
+     * @param {number} dt - Fixed delta time
+     */
+    fixedUpdate(dt) { },
+
+    /**
+     * Called when system is unregistered
+     */
+    destroy() { },
+};
+
+/**
+ * Base System class that implements ISystem
+ * Systems can extend this for convenience
+ */
+export class System {
+    constructor() {
+        this.kernel = null;
+    }
+
+    init(kernel) {
+        this.kernel = kernel;
+    }
+
+    update(dt) { }
+    fixedUpdate(dt) { }
+    destroy() { }
+}

package/src/interfaces/index.js

@@ -0,0 +1,7 @@
+/**
+ * Export all system interfaces
+ */
+export { ISystem, System } from './ISystem.js';
+export { IPhysicsSystem } from './IPhysicsSystem.js';
+export { IAudioSystem } from './IAudioSystem.js';
+export { IParticleSystem } from './IParticleSystem.js';

package/src/renderer/Renderer.js

@@ -0,0 +1,37 @@
+/**
+ * Handles the Canvas and Context for rendering.
+ */
+export class Renderer {
+    constructor(options = {}) {
+        this.width = options.width || 800;
+        this.height = options.height || 600;
+        this.backgroundColor = options.backgroundColor || '#000000';
+
+        this.canvas = document.createElement('canvas');
+        this.canvas.width = this.width;
+        this.canvas.height = this.height;
+        this.ctx = this.canvas.getContext('2d');
+
+        // Append to body or specified container
+        const parent = options.parent ?
+            (typeof options.parent === 'string' ? document.querySelector(options.parent) : options.parent)
+            : document.body;
+
+        parent.appendChild(this.canvas);
+    }
+
+    /**
+     * Clear the canvas.
+     */
+    clear() {
+        this.ctx.fillStyle = this.backgroundColor;
+        this.ctx.fillRect(0, 0, this.width, this.height);
+    }
+
+    resize(width, height) {
+        this.width = width;
+        this.height = height;
+        this.canvas.width = width;
+        this.canvas.height = height;
+    }
+}

package/src/systems/Director.js

@@ -0,0 +1,27 @@
+/**
+ * Manages Scene transitions and state.
+ */
+export class Director {
+    constructor(game) {
+        this.game = game;
+        this.currentScene = null;
+    }
+
+    /**
+     * Switch to a new scene.
+     * @param {Scene} scene 
+     */
+    run(scene) {
+        if (this.currentScene) {
+            this.currentScene.onExit();
+        }
+
+        this.currentScene = scene;
+        this.currentScene.game = this.game;
+
+        // Let the game know (if game engine needs to reference it directly)
+        this.game.scene = scene;
+
+        scene.onEnter();
+    }
+}

package/src/systems/Input.js

@@ -0,0 +1,77 @@
+/**
+ * Input System
+ * Tracks keyboard and mouse input.
+ */
+export class Input {
+    constructor() {
+        this.keys = new Map();
+        this.mouse = { x: 0, y: 0, buttons: new Map() };
+        this.kernel = null;
+
+        // Bind event listeners
+        this._onKeyDown = this._onKeyDown.bind(this);
+        this._onKeyUp = this._onKeyUp.bind(this);
+        this._onMouseMove = this._onMouseMove.bind(this);
+        this._onMouseDown = this._onMouseDown.bind(this);
+        this._onMouseUp = this._onMouseUp.bind(this);
+    }
+
+    /**
+     * ISystem interface - called when registered
+     */
+    init(kernel) {
+        this.kernel = kernel;
+
+        // Attach event listeners
+        window.addEventListener('keydown', this._onKeyDown);
+        window.addEventListener('keyup', this._onKeyUp);
+        window.addEventListener('mousemove', this._onMouseMove);
+        window.addEventListener('mousedown', this._onMouseDown);
+        window.addEventListener('mouseup', this._onMouseUp);
+    }
+
+    /**
+     * ISystem interface - cleanup
+     */
+    destroy() {
+        window.removeEventListener('keydown', this._onKeyDown);
+        window.removeEventListener('keyup', this._onKeyUp);
+        window.removeEventListener('mousemove', this._onMouseMove);
+        window.removeEventListener('mousedown', this._onMouseDown);
+        window.removeEventListener('mouseup', this._onMouseUp);
+    }
+
+    _onKeyDown(e) {
+        this.keys.set(e.key, true);
+    }
+
+    _onKeyUp(e) {
+        this.keys.set(e.key, false);
+    }
+
+    _onMouseMove(e) {
+        this.mouse.x = e.clientX;
+        this.mouse.y = e.clientY;
+    }
+
+    _onMouseDown(e) {
+        this.mouse.buttons.set(e.button, true);
+    }
+
+    _onMouseUp(e) {
+        this.mouse.buttons.set(e.button, false);
+    }
+
+    isKeyDown(key) {
+        return this.keys.get(key) || false;
+    }
+
+    isMouseButtonDown(button = 0) {
+        return this.mouse.buttons.get(button) || false;
+    }
+}
+
+// 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.');

package/src/systems/Loader.js

@@ -0,0 +1,44 @@
+/**
+ * Asset Loader
+ * Loads and caches images, audio, etc.
+ */
+export class Loader {
+    constructor() {
+        this.assets = new Map();
+        this.kernel = null;
+    }
+
+    /**
+     * ISystem interface - called when registered
+     */
+    init(kernel) {
+        this.kernel = kernel;
+    }
+
+    /**
+     * ISystem interface - cleanup
+     */
+    destroy() {
+        this.assets.clear();
+    }
+
+    async loadImage(key, url) {
+        return new Promise((resolve, reject) => {
+            const img = new Image();
+            img.onload = () => {
+                this.assets.set(key, img);
+                resolve(img);
+            };
+            img.onerror = reject;
+            img.src = url;
+        });
+    }
+
+    get(key) {
+        return this.assets.get(key);
+    }
+}
+
+// DEPRECATED: Keep for backward compatibility
+export const GlobalLoader = new Loader();
+console.warn('[DopamineJS] GlobalLoader is deprecated. Use kernel.loader instead.');

package/src/systems/Physics.js

@@ -0,0 +1,117 @@
+import { Collider } from '../core/Collider.js';
+
+export class Physics {
+    constructor() {
+        this.colliders = [];
+        this.kernel = null;
+    }
+
+    /**
+     * ISystem interface - called when registered
+     */
+    init(kernel) {
+        this.kernel = kernel;
+    }
+
+    /**
+     * ISystem interface - called at fixed timestep
+     */
+    fixedUpdate(dt) {
+        this.step();
+    }
+
+    /**
+     * ISystem interface - cleanup
+     */
+    destroy() {
+        this.colliders = [];
+    }
+
+    add(collider) {
+        this.colliders.push(collider);
+    }
+
+    remove(collider) {
+        const idx = this.colliders.indexOf(collider);
+        if (idx > -1) this.colliders.splice(idx, 1);
+    }
+
+    /**
+     * Main Physics Step.
+     * Checks all pairs and triggers callbacks.
+     */
+    step() {
+        // Naive O(N^2)
+        for (let i = 0; i < this.colliders.length; i++) {
+            for (let j = i + 1; j < this.colliders.length; j++) {
+                const a = this.colliders[i];
+                const b = this.colliders[j];
+
+                if (this._intersects(a, a.getBounds(), b, b.getBounds())) {
+                    // Notify GameObjects
+                    this._notifyCollision(a.gameObject, b.gameObject);
+                    this._notifyCollision(b.gameObject, a.gameObject);
+                }
+            }
+        }
+    }
+
+    _notifyCollision(go, other) {
+        if (!go || !go.components) return;
+        go.components.forEach(c => {
+            if (c.onCollisionEnter) c.onCollisionEnter(other);
+        });
+    }
+
+    /**
+     * Check if a specific collider overlaps with anything in the target group (tag).
+     * @param {Collider} source 
+     * @param {string} targetTag 
+     */
+    checkOverlap(source, targetTag) {
+        // ... (Keep existing manual check for flexibility)
+        const hits = [];
+        const sourceBounds = source.getBounds();
+
+        for (const target of this.colliders) {
+            if (target === source) continue;
+            if (targetTag && target.tag !== targetTag) continue;
+
+            const targetBounds = target.getBounds();
+
+            if (this._intersects(source, sourceBounds, target, targetBounds)) {
+                hits.push(target);
+            }
+        }
+        return hits;
+    }
+
+    _intersects(a, bA, b, bB) {
+        // Box vs Box
+        if (a.type === 'box' && b.type === 'box') {
+            return (bA.left < bB.right && bA.right > bB.left &&
+                bA.top < bB.bottom && bA.bottom > bB.top);
+        }
+        // Circle vs Circle
+        if (a.type === 'circle' && b.type === 'circle') {
+            const dx = bA.x - bB.x;
+            const dy = bA.y - bB.y;
+            const dist = Math.sqrt(dx * dx + dy * dy);
+            return dist < (bA.radius + bB.radius);
+        }
+
+        // TODO: Box vs Circle
+        return false;
+    }
+
+    // IPhysicsSystem interface methods (for plugin compatibility)
+    addBody(body) { this.add(body); }
+    removeBody(body) { this.remove(body); }
+    checkCollision(a, b) { return this._intersects(a, a.getBounds(), b, b.getBounds()); }
+    raycast(origin, direction, distance) { /* TODO */ return null; }
+    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.');

package/src/systems/Ticker.js

@@ -0,0 +1,61 @@
+/**
+ * The Ticker class manages the game loop.
+ * It uses requestAnimationFrame to provide a smooth loop.
+ */
+export class Ticker {
+    constructor() {
+        this.running = false;
+        this.lastTime = 0;
+        this.callbacks = new Set();
+        this._tick = this._tick.bind(this);
+    }
+
+    /**
+     * Add a callback to the loop.
+     * @param {Function} callback - Function to call each frame (receives dt).
+     */
+    add(callback) {
+        this.callbacks.add(callback);
+    }
+
+    /**
+     * Remove a callback from the loop.
+     * @param {Function} callback 
+     */
+    remove(callback) {
+        this.callbacks.delete(callback);
+    }
+
+    /**
+     * Start the loop.
+     */
+    start() {
+        if (this.running) return;
+        this.running = true;
+        this.lastTime = performance.now();
+        requestAnimationFrame(this._tick);
+    }
+
+    /**
+     * Stop the loop.
+     */
+    stop() {
+        this.running = false;
+    }
+
+    _tick(time) {
+        if (!this.running) return;
+
+        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);
+
+        for (const callback of this.callbacks) {
+            callback(safeDt);
+        }
+
+        requestAnimationFrame(this._tick);
+    }
+}

package/ARCHITECTURE.md

@@ -1,71 +0,0 @@
-# DopamineJS Architecture & Roadmap 🏗️
-
-**Vision**: To become the standard "Game Feel Engine" for the web—a plug-and-play layer that handles the "juice" (feedback, rewards, satisfaction) so developers can focus on core mechanics.
-
-## 🧠 Design Philosophy
-1.  **Zero-Config Start**: It must work beautifully out of the box.
-2.  **Infinite Extensibility**: Every default (sound, particle, UI style) must be replaceable.
-3.  **Asset Agnostic**: Support synthesized sounds/shapes (no assets) AND custom assets (mp3/png).
-4.  **AI-First**: APIs should be self-documenting and predictable for AI agents to use effectively.
-
-## 🗺️ Roadmap
-
-### Phase 1: Audio Extensibility (v1.1.0)
-**Goal**: Allow developers to bring their own soundscapes.
-
--   **[NEW] Asset Loader**: A lightweight preloader for audio files.
--   **[UPDATE] SoundManager**:
-    -   Add `registerSound(key, url)` method.
-    -   Support `Howler.js` integration (optional) or robust Web Audio buffer caching.
-    -   **Feature**: "Sound Packs" - Allow switching between 'Retro', 'Modern', 'Cute' preset packs.
-
-### Phase 2: Visual Customization (v1.2.0)
-**Goal**: Break free from geometric primitives.
-
--   **[UPDATE] ParticleSystem**:
-    -   **Sprite Support**: Allow `image` or `sprite` properties in particle config.
-    -   **Custom Emitters**: Define custom particle behaviors (gravity, velocity, life, decay) via JSON config.
-    -   **Editor**: (Long term) A web-based particle editor that exports JSON for DopamineJS.
-
-### Phase 3: UI Theming & Templates (v1.3.0)
-**Goal**: Make the UI fit any game art style.
-
--   **[NEW] Theme Engine**:
-    -   Use CSS Variables for all colors, fonts, and spacing.
-    -   `Dopamine.setTheme('dark-cyberpunk')`
--   **[UPDATE] GameUI**:
-    -   **Icon Sets**: Allow passing an icon map (SVG strings or URLs) to replace default emojis.
-    -   **Slots**: Allow developers to inject custom HTML into notifications or level-up screens.
-
-### Phase 4: The "Dopamine Ecosystem" (v2.0.0)
-**Goal**: Community-driven content.
-
--   **Plugin System**: Middleware for the `RewardSystem` (e.g., "BattlePass Plugin", "Leaderboard Plugin").
--   **Backend Integration**: Webhooks for `onLevelUp` or `onAchievement` to validate rewards on a server.
-
-## 📝 Developer Guide: How to Extend (Current Best Practices)
-
-While we build these features, here is how you can extend DopamineJS today:
-
-### Custom Achievements
-You can already define any achievement logic you want:
-
-```javascript
-achievements: {
-    'die_100_times': {
-        name: 'You Tried',
-        icon: '<img src="skull.png" width="20">', // HTML is supported in icons!
-        check: (p) => p.stats.deaths >= 100
-    }
-}
-```
-
-### Custom CSS
-Override the default styles by adding your own CSS *after* importing DopamineJS:
-
-```css
-/* Override the XP bar color */
-.xp-bar-fill {
-    background: linear-gradient(90deg, #ff00cc, #3333ff) !important;
-}
-```

package/CHANGELOG.md

@@ -1,36 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [1.2.0] - 2025-12-04
-### Added
-- **Visual Customization**:
-    - `registerSprite(key, url)`: Use custom images for particles.
-    - `emit(config)`: Create fully custom particle explosions.
-    - `registerEffect(name, callback)`: Define reusable custom effects.
-- **Multi-Screen Support**: Pass `container` selector to `ParticleSystem` to target specific elements.
-- **Optimization**: Implemented Object Pooling to reduce garbage collection and improve performance.
-
-## [1.1.0] - 2025-12-04
-### Added
-- **Audio Extensibility**: Support for custom audio files (`.mp3`, `.wav`).
-- `SoundManager.registerSound(key, url)`: Register custom assets.
-- `SoundManager.play(key)`: Unified API to play custom sounds or fallback to synth.
-- Support for `customSounds` in the initial configuration.
-
-## [1.0.2] - 2025-12-04
-### Fixed
-- Fixed `npm run release` script failing due to missing `vitest` dependency.
-- Uncommented `npm publish` in deployment script to ensure package is actually published to npm.
-
-## [1.0.1] - 2025-12-04
-### Added
-- Initial release of DopamineJS.
-- Core systems: `RewardSystem`, `ParticleSystem`, `SoundManager`, `GameUI`.
-- Basic gamification features: XP, Levels, Streaks, Achievements.
-- Built-in visual effects: Confetti, Coin Shower, Sparkles, Fire, Star Burst.
-- Synthesized sound effects.
-- Comprehensive README with "Vibe Coding" instructions for AI agents.
-
-## [1.0.0] - 2025-12-04
-- Initial scaffold.