Home

DopamineJS

Progression mechanics for web apps: XP, levels, achievements and daily streaks, plus the particles, sound and UI overlay that go with them. A small 2D game engine sits underneath and is exported too.

The core package has no runtime dependencies and ships its own TypeScript declarations.

npm install dopaminejs

import { RewardSystem, DataService } from 'dopaminejs';

const rewards = new RewardSystem(new DataService());
await rewards.init();

rewards.on('level_up', ({ oldLevel, newLevel }) => console.log(oldLevel, 'to', newLevel));

await rewards.addXP(250);

rewards.getXPForNextLevel();
// { total: 300, needed: 50, progress: 0.75 }

Start here

• Installation: packages, entry points, requirements.
• Quick Start: rewards only, rewards with the overlay, and the one-line facade.

The progression layer

• Reward System: XP, the level curve, games, achievements, streaks.
• Events: every event, its payload, and the two event classes.
• Storage and Saved State: where progress lives and how to move it.
• Game UI: the overlay, popups and summary screen.
• Particles: the canvas particle system.
• Sound: synthesized and file-based sound.
• Dopamine Facade: all of the above wired together.

The engine

• Engine: Game, Scene, GameObject, components, physics, input.
• Writing a Plugin: systems, plugins and their lifecycle.

Packages

Package	Version	Page
dopaminejs	2.4.0	this wiki
dopaminejs-plugin-ecosystem	2.0.0	Plugin: Ecosystem
dopaminejs-plugin-feedback-effects	1.0.2	Plugin: Feedback Effects
dopaminejs-plugin-debug-overlay	1.0.1	Plugin: Debug Overlay
dopaminejs-plugin-webgl-particles	1.1.2	Plugin: WebGL Particles
dopaminejs-plugin-howler-audio	1.0.0	Plugin: Howler Audio
dopaminejs-plugin-sound-packs	1.0.0	Plugin: Sound Packs
dopaminejs-themes	1.0.2	Themes
dopaminejs-react	1.0.0	React

Reference

• Security: what the library protects and what it cannot.
• Migration: v1 to v2, the retired dopaminejs-plugins bundle, ecosystem 1 to 2.
• Known Gaps: things the code does not do yet.
• Development: commands, tests and repo rules.
• Releasing: how a tag becomes an npm release.

Licence

dopaminejs is MPL-2.0. The plugins, themes and React packages are MIT.