Installation

Installation

npm install dopaminejs

Node 20.19 or newer for tooling. The package is ESM first and also ships a CommonJS build.

Entry points

Import	What it holds
dopaminejs	Everything: rewards, UI, particles, sound and the engine
dopaminejs/engine	The engine only: Game, Scene, GameObject, kernel, systems
dopaminejs/style.css	The stylesheet for Game UI

import { RewardSystem, DataService } from 'dopaminejs';
import { Game, Scene } from 'dopaminejs/engine';
import 'dopaminejs/style.css';

CommonJS:

const { RewardSystem, DataService } = require('dopaminejs');

The default export is the Dopamine facade. It exists for v1 compatibility. New code uses the named exports.

TypeScript

Declarations ship in the package (types/index.d.ts). No @types package is needed. They are written by hand, and a test checks that they declare exactly what the module exports. The engine shapes are pinned by a runtime test since 2.3.1.

Stylesheet

GameUI builds DOM that the stylesheet positions and animates. Import dopaminejs/style.css once if you use GameUI or the facade. RewardSystem on its own needs no CSS.

Server rendering

Importing the package does not touch window or localStorage. DataService falls back to an in-memory store when localStorage is missing or blocked, so RewardSystem can be constructed on a server.

GameUI, ParticleSystem and the Dopamine facade create DOM in their constructors. Construct those in the browser only.

Plugins and themes

Each plugin is its own package. Install the ones you use.

npm install dopaminejs-plugin-ecosystem
npm install dopaminejs-plugin-feedback-effects
npm install dopaminejs-plugin-debug-overlay
npm install dopaminejs-plugin-webgl-particles
npm install dopaminejs-plugin-howler-audio howler
npm install dopaminejs-plugin-sound-packs
npm install dopaminejs-themes

Package	Needs
dopaminejs-plugin-ecosystem 2.0.0	dopaminejs 2.3.0 or newer
dopaminejs-plugin-feedback-effects	dopaminejs 2.0.1 or newer
dopaminejs-plugin-howler-audio	dopaminejs 2.x and howler 2.2 or newer
the rest	dopaminejs 2.x

The old bundle dopaminejs-plugins was unpublished. See Migration.

Size

CI fails if the ESM entry or the CJS entry goes over its 14 KB size-limit budget.