dopaminejs 1.2.0 → 2.0.0

package/src/core/EventBus.js

@@ -0,0 +1,183 @@
+/**
+ * EventBus - Central event system for loose coupling between systems
+ * 
+ * Performance optimizations:
+ * - Priority queues for critical events (tick, render)
+ * - Object pooling for event data (future enhancement)
+ * - Pre-allocated arrays to minimize GC
+ */
+export class EventBus {
+    constructor() {
+        // Map<eventName, Set<{callback, priority}>>
+        this._listeners = new Map();
+        this._onceListeners = new Map();
+
+        // Cache for sorted listeners by priority
+        this._sortedCache = new Map();
+    }
+
+    /**
+     * Register an event listener
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function
+     * @param {number} priority - Higher priority = called first (default: 0)
+     * @returns {EventBus} - For chaining
+     */
+    on(event, callback, priority = 0) {
+        if (!this._listeners.has(event)) {
+            this._listeners.set(event, new Set());
+        }
+
+        this._listeners.get(event).add({ callback, priority });
+
+        // Invalidate cache for this event
+        this._sortedCache.delete(event);
+
+        return this;
+    }
+
+    /**
+     * Register a one-time event listener
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function
+     * @returns {EventBus} - For chaining
+     */
+    once(event, callback) {
+        if (!this._onceListeners.has(event)) {
+            this._onceListeners.set(event, new Set());
+        }
+
+        this._onceListeners.get(event).add(callback);
+        return this;
+    }
+
+    /**
+     * Remove an event listener
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function to remove
+     * @returns {EventBus} - For chaining
+     */
+    off(event, callback) {
+        const listeners = this._listeners.get(event);
+        if (listeners) {
+            // Find and remove the listener with matching callback
+            for (const listener of listeners) {
+                if (listener.callback === callback) {
+                    listeners.delete(listener);
+                    this._sortedCache.delete(event);
+                    break;
+                }
+            }
+        }
+
+        const onceListeners = this._onceListeners.get(event);
+        if (onceListeners) {
+            onceListeners.delete(callback);
+        }
+
+        return this;
+    }
+
+    /**
+     * Emit an event to all registered listeners
+     * @param {string} event - Event name
+     * @param {*} data - Event data
+     */
+    emit(event, data) {
+        // Get sorted listeners (cached for performance)
+        const listeners = this._getSortedListeners(event);
+
+        // Call regular listeners
+        for (let i = 0; i < listeners.length; i++) {
+            listeners[i].callback(data);
+        }
+
+        // Call and remove once listeners
+        const onceListeners = this._onceListeners.get(event);
+        if (onceListeners && onceListeners.size > 0) {
+            for (const callback of onceListeners) {
+                callback(data);
+            }
+            onceListeners.clear();
+        }
+    }
+
+    /**
+     * Get sorted listeners for an event (with caching)
+     * @private
+     */
+    _getSortedListeners(event) {
+        // Check cache first
+        if (this._sortedCache.has(event)) {
+            return this._sortedCache.get(event);
+        }
+
+        const listeners = this._listeners.get(event);
+        if (!listeners || listeners.size === 0) {
+            return [];
+        }
+
+        // Sort by priority (higher first)
+        const sorted = Array.from(listeners).sort((a, b) => b.priority - a.priority);
+
+        // Cache the result
+        this._sortedCache.set(event, sorted);
+
+        return sorted;
+    }
+
+    /**
+     * Remove all listeners for an event, or all events if no event specified
+     * @param {string} [event] - Event name (optional)
+     */
+    clear(event) {
+        if (event) {
+            this._listeners.delete(event);
+            this._onceListeners.delete(event);
+            this._sortedCache.delete(event);
+        } else {
+            this._listeners.clear();
+            this._onceListeners.clear();
+            this._sortedCache.clear();
+        }
+    }
+
+    /**
+     * Check if an event has listeners
+     * @param {string} event - Event name
+     * @returns {boolean}
+     */
+    hasListeners(event) {
+        const listeners = this._listeners.get(event);
+        const onceListeners = this._onceListeners.get(event);
+        return (listeners && listeners.size > 0) || (onceListeners && onceListeners.size > 0);
+    }
+}
+
+/**
+ * Standard event names for performance-critical events
+ * Using constants avoids string allocation
+ */
+EventBus.Events = {
+    // Core game loop events
+    TICK: 'tick',
+    FIXED_UPDATE: 'fixed_update',
+    RENDER: 'render',
+
+    // Physics events
+    COLLISION_ENTER: 'collision_enter',
+    COLLISION_EXIT: 'collision_exit',
+
+    // Dopamine events (from RewardSystem)
+    XP_GAINED: 'xp_gained',
+    LEVEL_UP: 'level_up',
+    ACHIEVEMENT_UNLOCKED: 'achievement_unlocked',
+    NEW_HIGH_SCORE: 'new_high_score',
+    STREAK_UPDATED: 'streak_updated',
+
+    // System lifecycle events
+    SYSTEM_REGISTERED: 'system_registered',
+    SYSTEM_UNREGISTERED: 'system_unregistered',
+    PLUGIN_LOADED: 'plugin_loaded',
+    PLUGIN_UNLOADED: 'plugin_unloaded',
+};

package/src/core/Game.js

@@ -0,0 +1,89 @@
+import { DopamineKernel } from './DopamineKernel.js';
+import { Scene } from './Scene.js';
+import { Director } from '../systems/Director.js';
+import { EventBus } from './EventBus.js';
+
+/**
+ * The main Game entry point.
+ * Now uses DopamineKernel for system management.
+ */
+export class Game {
+    constructor(config = {}) {
+        this.config = config;
+
+        // NEW: Use kernel for system management
+        this.kernel = new DopamineKernel(config);
+
+        // Initialize Director
+        this.director = new Director(this);
+
+        // Bind to kernel tick event for scene updates
+        this.kernel.events.on(EventBus.Events.TICK, this._update.bind(this), 10);
+        this.kernel.events.on(EventBus.Events.RENDER, this._render.bind(this), 10);
+    }
+
+    /**
+     * Backward compatibility accessors
+     */
+    get renderer() {
+        return this.kernel.renderer;
+    }
+
+    get ticker() {
+        return this.kernel.ticker;
+    }
+
+    get physics() {
+        return this.kernel.physics;
+    }
+
+    get input() {
+        return this.kernel.input;
+    }
+
+    /**
+     * Start the game loop.
+     */
+    start() {
+        this.kernel.start();
+    }
+
+    /**
+     * Stop the game loop.
+     */
+    stop() {
+        this.kernel.stop();
+    }
+
+    /**
+     * Switch to a new scene.
+     * @param {Scene} newScene 
+     */
+    setScene(newScene) {
+        // Inject kernel into scene
+        newScene.kernel = this.kernel;
+        this.director.run(newScene);
+    }
+
+    _update({ dt }) {
+        // Update scene logic
+        if (this.director.currentScene) {
+            this.director.currentScene.update(dt);
+        }
+    }
+
+    _render({ dt }) {
+        // Clear and render
+        this.renderer.clear();
+        if (this.director.currentScene) {
+            this.director.currentScene.render(this.renderer.ctx);
+        }
+    }
+
+    /**
+     * Destroy the game and cleanup
+     */
+    destroy() {
+        this.kernel.destroy();
+    }
+}

package/src/core/GameObject.js

@@ -0,0 +1,83 @@
+import { Component } from './Component.js';
+
+/**
+ * Base Entity class.
+ * Has position, scale, rotation, and a list of Components.
+ */
+export class GameObject {
+    constructor(x = 0, y = 0) {
+        this.x = x;
+        this.y = y;
+        this.rotation = 0;
+        this.scale = { x: 1, y: 1 };
+
+        this.components = [];
+        this.children = [];
+        this.parent = null;
+        this.kernel = null; // Injected by Scene or Game
+    }
+
+    /**
+     * Add a child object.
+     * @param {GameObject} child 
+     */
+    addChild(child) {
+        child.parent = this;
+        child.kernel = this.kernel; // Propagate kernel
+        this.children.push(child);
+        return child;
+    }
+
+    /**
+     * Add a component.
+     * @param {Component} component 
+     */
+    addComponent(component) {
+        component.gameObject = this;
+        component.kernel = this.kernel; // Inject kernel reference
+        this.components.push(component);
+        component.onAttach();
+        return component;
+    }
+
+    /**
+     * Get a component by class type.
+     * @param {class} type 
+     */
+    getComponent(type) {
+        return this.components.find(c => c instanceof type);
+    }
+
+    update(dt) {
+        // Update components
+        for (const component of this.components) {
+            if (component.update) component.update(dt);
+        }
+
+        // Update children
+        for (const child of this.children) {
+            child.update(dt);
+        }
+    }
+
+    render(ctx) {
+        ctx.save();
+
+        // Apply Transforms
+        ctx.translate(this.x, this.y);
+        ctx.rotate(this.rotation);
+        ctx.scale(this.scale.x, this.scale.y);
+
+        // Render components
+        for (const component of this.components) {
+            if (component.render) component.render(ctx);
+        }
+
+        // Render children
+        for (const child of this.children) {
+            child.render(ctx);
+        }
+
+        ctx.restore();
+    }
+}

package/src/core/PluginRegistry.js

@@ -0,0 +1,197 @@
+/**
+ * PluginRegistry - Manages plugin lifecycle
+ * 
+ * Plugins can extend the engine by:
+ * - Registering new systems
+ * - Replacing existing systems
+ * - Adding event listeners
+ * - Modifying kernel configuration
+ */
+export class PluginRegistry {
+    constructor(kernel) {
+        this.kernel = kernel;
+
+        // Map<pluginName, plugin>
+        this._plugins = new Map();
+
+        // Track plugin load order for proper cleanup
+        this._loadOrder = [];
+    }
+
+    /**
+     * Register and initialize a plugin
+     * 
+     * Plugin interface:
+     * {
+     *   name: string,
+     *   version?: string,
+     *   init(kernel): void,
+     *   destroy?(): void
+     * }
+     * 
+     * @param {Object} plugin - Plugin instance
+     * @returns {PluginRegistry} - For chaining
+     */
+    use(plugin) {
+        if (!plugin.name) {
+            throw new Error('[PluginRegistry] Plugin must have a name');
+        }
+
+        if (this._plugins.has(plugin.name)) {
+            console.warn(`[PluginRegistry] Plugin "${plugin.name}" already registered. Skipping.`);
+            return this;
+        }
+
+        if (!plugin.init || typeof plugin.init !== 'function') {
+            throw new Error(`[PluginRegistry] Plugin "${plugin.name}" must have an init() method`);
+        }
+
+        // Store plugin
+        this._plugins.set(plugin.name, plugin);
+        this._loadOrder.push(plugin.name);
+
+        // Initialize plugin
+        try {
+            plugin.init(this.kernel);
+
+            // Emit event
+            this.kernel.events.emit('plugin_loaded', {
+                name: plugin.name,
+                version: plugin.version
+            });
+
+            console.log(`[PluginRegistry] Loaded plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}`);
+        } catch (error) {
+            console.error(`[PluginRegistry] Failed to initialize plugin "${plugin.name}":`, error);
+            this._plugins.delete(plugin.name);
+            this._loadOrder.pop();
+            throw error;
+        }
+
+        return this;
+    }
+
+    /**
+     * Register and initialize a plugin asynchronously
+     * Useful for plugins that need to load external resources
+     * 
+     * @param {Object} plugin - Plugin instance with async init
+     * @returns {Promise<PluginRegistry>} - For chaining
+     */
+    async useAsync(plugin) {
+        if (!plugin.name) {
+            throw new Error('[PluginRegistry] Plugin must have a name');
+        }
+
+        if (this._plugins.has(plugin.name)) {
+            console.warn(`[PluginRegistry] Plugin "${plugin.name}" already registered. Skipping.`);
+            return this;
+        }
+
+        if (!plugin.init || typeof plugin.init !== 'function') {
+            throw new Error(`[PluginRegistry] Plugin "${plugin.name}" must have an init() method`);
+        }
+
+        // Store plugin
+        this._plugins.set(plugin.name, plugin);
+        this._loadOrder.push(plugin.name);
+
+        // Initialize plugin (await if it returns a promise)
+        try {
+            await plugin.init(this.kernel);
+
+            // Emit event
+            this.kernel.events.emit('plugin_loaded', {
+                name: plugin.name,
+                version: plugin.version
+            });
+
+            console.log(`[PluginRegistry] Loaded plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}`);
+        } catch (error) {
+            console.error(`[PluginRegistry] Failed to initialize plugin "${plugin.name}":`, error);
+            this._plugins.delete(plugin.name);
+            this._loadOrder.pop();
+            throw error;
+        }
+
+        return this;
+    }
+
+    /**
+     * Remove a plugin
+     * @param {string} name - Plugin name
+     * @returns {boolean} - True if plugin was found and removed
+     */
+    remove(name) {
+        const plugin = this._plugins.get(name);
+        if (!plugin) {
+            return false;
+        }
+
+        // Call destroy if available
+        if (plugin.destroy) {
+            try {
+                plugin.destroy();
+            } catch (error) {
+                console.error(`[PluginRegistry] Error destroying plugin "${name}":`, error);
+            }
+        }
+
+        this._plugins.delete(name);
+
+        // Remove from load order
+        const index = this._loadOrder.indexOf(name);
+        if (index > -1) {
+            this._loadOrder.splice(index, 1);
+        }
+
+        // Emit event
+        this.kernel.events.emit('plugin_unloaded', { name });
+
+        return true;
+    }
+
+    /**
+     * Get a plugin by name
+     * @param {string} name - Plugin name
+     * @returns {Object|undefined} - Plugin instance
+     */
+    get(name) {
+        return this._plugins.get(name);
+    }
+
+    /**
+     * Check if a plugin is registered
+     * @param {string} name - Plugin name
+     * @returns {boolean}
+     */
+    has(name) {
+        return this._plugins.has(name);
+    }
+
+    /**
+     * Get all registered plugin names
+     * @returns {string[]}
+     */
+    getPluginNames() {
+        return Array.from(this._plugins.keys());
+    }
+
+    /**
+     * Get plugin load order
+     * @returns {string[]}
+     */
+    getLoadOrder() {
+        return [...this._loadOrder];
+    }
+
+    /**
+     * Clear all plugins (in reverse load order)
+     */
+    clear() {
+        // Unload in reverse order
+        for (let i = this._loadOrder.length - 1; i >= 0; i--) {
+            this.remove(this._loadOrder[i]);
+        }
+    }
+}

package/src/core/Scene.js

@@ -0,0 +1,65 @@
+/**
+ * Represents a specific state or screen in the game (e.g., Menu, Level1).
+ */
+export class Scene {
+    constructor() {
+        this.children = [];
+        this.game = null;
+    }
+
+    /**
+     * Called when the scene is added to the Game.
+     */
+    onEnter() { }
+
+    onExit() { }
+
+    /**
+     * Update loop for the scene.
+     * @param {number} dt 
+     */
+    update(dt) {
+        // Update all children (GameObjects)
+        for (const child of this.children) {
+            if (child.update) child.update(dt);
+        }
+    }
+
+    /**
+        this.gameObjects = [];
+        this.kernel = null; // Injected by Game
+    }
+
+    /**
+     * Add a GameObject to the scene.
+     * @param {GameObject} gameObject 
+     */
+    add(gameObject) {
+        gameObject.kernel = this.kernel; // Inject kernel
+        this.gameObjects.push(gameObject);
+        return gameObject;
+    }
+
+    /**
+     * Remove a GameObject from the scene.
+     * @param {GameObject} gameObject 
+     */
+    remove(gameObject) {
+        const index = this.gameObjects.indexOf(gameObject);
+        if (index > -1) {
+            this.gameObjects.splice(index, 1);
+        }
+    }
+
+    update(dt) {
+        for (const obj of this.gameObjects) {
+            obj.update(dt);
+        }
+    }
+
+    render(ctx) {
+        for (const obj of this.gameObjects) {
+            obj.render(ctx);
+        }
+    }
+}

package/src/core/Sprite.js

@@ -0,0 +1,51 @@
+import { Component } from '../core/Component.js';
+
+export class Sprite extends Component {
+    constructor(image) {
+        super();
+        this.image = image; // Image or Canvas element
+        this.anchor = { x: 0.5, y: 0.5 };
+        this.width = image ? image.width : 0;
+        this.height = image ? image.height : 0;
+
+        // Frame support (for spritesheets)
+        this.frame = { x: 0, y: 0, w: this.width, h: this.height };
+    }
+
+    setFrame(x, y, w, h) {
+        this.frame = { x, y, w, h };
+        this.width = w;
+        this.height = h;
+    }
+
+    setTexture(image) {
+        this.image = image;
+        // Reset frame if full texture
+        if (image) {
+            this.setFrame(0, 0, image.width, image.height);
+        }
+    }
+
+    render(ctx) {
+        if (!this.image) return;
+
+        // The transform (pos, rot, scale) is already handled by the Scene/GO before calling render?
+        // Wait, our GameObject implementation currently propagates render but doesn't apply context transform automatically in the base class loop?
+        // Let's check GameObject.js.
+
+        // Checking GameObject.js...
+        // "ctx.save(); ctx.translate(this.x, this.y); ctx.rotate(this.rotation); ctx.scale(this.scale.x, this.scale.y); ... ctx.restore();"
+        // YES, it handles logic. So we render at 0,0 local space.
+
+        const w = this.frame.w;
+        const h = this.frame.h;
+        const offsetX = -w * this.anchor.x;
+        const offsetY = -h * this.anchor.y;
+
+        ctx.drawImage(
+            this.image,
+            this.frame.x, this.frame.y, w, h, // Source
+            offsetX, offsetY, w, h            // Destination
+        );
+    }
+}