Game UI

Game UI

GameUI is the overlay: an XP bar, a level badge, a streak badge, and the popups for achievements, level ups and notifications.

import { GameUI, ParticleSystem } from 'dopaminejs';
import 'dopaminejs/style.css';

const ui = new GameUI(new ParticleSystem());

The constructor builds the DOM and appends it to document.body. Do not call init() again. The stylesheet is required.

The particle system you pass must have confetti, fire, sparkle and starBurst. The core ParticleSystem does. The WebGL plugin's system does not.

GameUI does not listen to anything. Either wire it to a RewardSystem yourself (see Quick Start) or use the Dopamine Facade.

The HUD

Method	Effect
updateXP(current, needed, total, progress)	Sets the bar width from progress (0 to 1) and the label
updateLevel(level)	Sets the level badge
updateStreak(days)	Sets the streak badge. Its colour changes at 3 and at 7 days.

The four arguments of updateXP line up with the player's XP and the result of getXPForNextLevel():

const { total, needed, progress } = rewards.getXPForNextLevel();
ui.updateXP(rewards.player.xp, needed, total, progress);

Popups

ui.showAchievement({ name: 'Perfect', description: 'Score 100', icon: '<img src="/perfect.svg" alt="">', xp: 150 });
ui.showLevelUp(4, 5);
ui.showNotification('Saved', 'normal');   // 'normal', 'rare' or 'legendary'

Method	Notes
showAchievement(achievement)	Confetti after 300 ms. Removed after about 4.3 seconds.
showLevelUp(oldLevel, newLevel)	Full-screen "LEVEL UP!" overlay with five confetti bursts. Removed after about 3 seconds.
showNotification(message, type = 'normal')	Floating text at the centre of the viewport. rare is larger and red with a fire effect. legendary is gold with a star burst and confetti.
showFloatingText(text, x, y, color = '#ffd700', size = '24px')	Text that floats up from a point. Removed after 2 seconds.
showCombo(multiplier, x, y)	Floating <multiplier>× COMBO! with fire particles.
showNearMiss(x, y)	Floating CLOSE CALL! with sparkles.
showLuckyMoment(multiplier, x, y)	Floating LUCKY <multiplier>×! with a star burst and confetti.

x and y are viewport pixels.

achievement.icon is inserted as HTML so an icon can be an <img> or an inline SVG. Every other field is inserted as text. Never build icon from user input. See Security.

Summary screen

const screen = ui.showSummary({
    score: 1200,
    metrics: { Accuracy: '92%', Time: '48s' },
    onReplay: () => restart(),
    onExit: () => router.push('/')
});

• Shows a "Game Over" heading, the score, the metrics and a "Play Again" button.
• Returns the element. The screen does not remove itself, so call screen.remove() in your handlers.
• onReplay defaults to reloading the page.
• The exit button is shown only when onExit is given.

Accessibility

• An aria-live="polite" region repeats achievements, level ups and notifications as text, so a screen reader announces them.
• The stylesheet honours prefers-reduced-motion.
• ParticleSystem drops all effects under reduced motion by default.

Cleanup

ui.destroy();

Removes the overlay, any open popups and pending timers.

Styling

The overlay root has the class game-ui-overlay. It also takes the id game-ui-overlay when no other element has it.

The core stylesheet does not read CSS variables, so dopaminejs-themes does not restyle it. Override the classes in your own CSS. See Themes.