@web-engine-dev/achievements

Achievement and trophy system for web-engine-dev.

Features

• Achievement Tracking: Define and track achievements
• Progress Tracking: Incremental achievements
• Unlocking: Achievement unlock logic
• Notifications: Achievement popups
• Cloud Sync: Sync across devices
• Statistics: Player stats tracking

Installation

npm install @web-engine-dev/achievements
# or
pnpm add @web-engine-dev/achievements

Quick Start

import { AchievementSystem, Achievement } from '@web-engine-dev/achievements';

// Create achievement system
const achievements = new AchievementSystem();

// Define achievements
achievements.register({
  id: 'first_blood',
  name: 'First Blood',
  description: 'Defeat your first enemy',
  icon: 'achievements/first_blood.png',
  hidden: false,
});

achievements.register({
  id: 'collector',
  name: 'Collector',
  description: 'Collect 100 coins',
  icon: 'achievements/collector.png',
  progress: { target: 100 },
});

// Unlock achievement
achievements.unlock('first_blood');

// Update progress
achievements.addProgress('collector', 10);

// Listen for unlocks
achievements.on('unlock', (achievement) => {
  showNotification(achievement);
});

API Overview

Achievement Definition

achievements.register({
  id: 'master',
  name: 'Master',
  description: 'Complete the game on hard mode',
  icon: 'icon.png',
  hidden: true, // Hidden until unlocked
  secret: false, // Show description?
  points: 100, // Gamerscore-like points
  progress: {
    target: 1,
    showProgress: false,
  },
  prerequisites: ['complete_normal'], // Required achievements
});

Tracking Progress

// Increment progress
achievements.addProgress('kill_enemies', 1);

// Set progress
achievements.setProgress('collect_coins', totalCoins);

// Get progress
const progress = achievements.getProgress('collect_coins');
console.log(`${progress.current}/${progress.target}`);

Checking State

// Check if unlocked
if (achievements.isUnlocked('first_blood')) {
  // ...
}

// Get all unlocked
const unlocked = achievements.getUnlocked();

// Get all locked
const locked = achievements.getLocked();

// Get all achievements
const all = achievements.getAll();

Statistics

// Set stat
achievements.setStat('total_kills', kills);

// Increment stat
achievements.addStat('games_played', 1);

// Get stat
const stat = achievements.getStat('total_kills');

// Stat-based achievements
achievements.register({
  id: 'veteran',
  name: 'Veteran',
  stat: 'games_played',
  statValue: 100,
});

Events

achievements.on('unlock', (achievement) => {
  showUnlockNotification(achievement);
  playUnlockSound();
});

achievements.on('progress', (achievement, progress) => {
  if (progress.percentage >= 0.5) {
    showProgressNotification(achievement, progress);
  }
});