dopaminejs 1.0.2 → 1.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,36 @@
+# 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.

package/README.md

@@ -121,6 +121,79 @@ Pre-loaded satisfying sound effects (generated synthetically or minimal assets).
 soundManager.playSuccess();
 ```
 
+### 🎧 Audio Customization (New in v1.1.0)
+You can replace the default synthesized sounds with your own audio files (`.mp3`, `.wav`, etc.).
+
+```javascript
+// 1. Register custom sounds
+soundManager.registerSound('jump', '/assets/audio/jump_v2.mp3');
+soundManager.registerSound('win', '/assets/audio/epic_win.wav');
+
+// 2. Play them (auto-loads on first play if not preloaded)
+soundManager.play('jump');
+
+// 3. Or pass them in initial config
+const app = new Dopamine({
+    sound: {
+        customSounds: {
+            'click': '/assets/ui_click.mp3',
+            'level_up': '/assets/level_up.mp3'
+        }
+    }
+});
+```
+
+### 🎨 Visual Customization (New in v1.2.0)
+
+#### Custom Sprites
+Use your own images instead of shapes.
+
+```javascript
+// 1. Register sprite
+particleSystem.registerSprite('gold_coin', '/assets/coin.png');
+
+// 2. Emit particles using that sprite
+particleSystem.emit({
+    x: 100, y: 100,
+    sprite: 'gold_coin',
+    count: 10,
+    size: 20,
+    gravity: 0.5
+});
+```
+
+#### Custom Effects
+Create reusable effects that you can call anywhere.
+
+```javascript
+// Define "Blood Splatter"
+particleSystem.registerEffect('blood', (x, y) => {
+    particleSystem.emit({
+        x, y,
+        count: 15,
+        color: ['#8a0303', '#ff0000'],
+        speed: 4,
+        gravity: 0.3,
+        decay: 0.05
+    });
+});
+
+// Use it
+particleSystem.play('blood', 200, 300);
+```
+
+#### Multi-Screen Support
+Target a specific game container instead of the whole screen.
+
+```javascript
+const app = new Dopamine({
+    particles: {
+        container: '#game-board', // Selector or HTMLElement
+        zIndex: 10
+    }
+});
+```
+
 ### 🎨 Game UI
 Built-in UI components to show progress without coding HTML/CSS.
 - **Notifications**: "Achievement Unlocked", "Level Up", etc.