🎮 Achievements

A desktop application built with Electron that monitors running games and displays achievement notifications for:

• ✅ Achievement unlocks
• ⏱️ Playtime tracking (Now Playing / You Played X minutes)
• 📈 Progress updates
• 🖼️ Game image overlays
• 📊 Real-time achievement dashboard
• Steam/Uplay/GOG/Epic emulators, Xbox PC, RetroAchievements, XLiveLessNess, MarkerPatch, MadnessPatch, FINAL FANTASY VII achievement.dat and official launcher schema support (auto-detected where possible)

☕ Support

If you’d like to support the project further, you can buy me a coffee on Ko-fi:

1. Install Node.js and Git.
2. Clone this repository:

git clone https://github.com/PSerban93/achievements.git
   cd achievements

1. Install dependencies:

npm install

1. Install the full Playwright Chromium runtime used for schema scraping and local runs:

npm run dl-browsers

This command installs and validates the current full Chromium revision before removing obsolete Chromium revisions and Headless Shell variants. Scraping uses Chromium's new headless mode, while the manual schema-generator --headed mode remains available.

🚀 Running the App

npm start

Application Launch Arguments

An existing config can be opened directly by passing both its AppID and platform to the installed or unpacked executable:

Achievements.exe --appid=239140/steam
Achievements.exe --appid=239140 --platform=steam

• Both formats are supported and are equivalent.
• If Achievements is already running, the existing instance is opened and navigates to the matching config.
• The AppID and platform must match one existing config exactly. These arguments do not generate a config or launch the game.
• Supported platform values: steam, steam-official, uplay, ubisoft-official, ea-official, epic, epic-official, gog, gog-official, xbox-pc, retroachievements, xenia, rpcs3, shadps4, markerpatch, madnesspatch, xlivelessness.

🧱 Building a Windows Executable

Create an unpacked Windows build:

npm run pack

Create the Windows installer:

npm run dist

Build output is created in the dist/ folder. The build scripts verify the native process watcher and SAN notification runtime. Both npm run pack and npm run dist install and validate full Playwright Chromium automatically before packaging. Chromium Headless Shell is not bundled.

📦 Dependencies

Core

• Electron - Cross-platform desktop application framework
• @vscode/windows-process-tree - Native Windows process monitoring
• Koffi - Native Windows API bindings used by local detection services
• ps-list - Limited process-monitoring fallback
• crc-32 - Checksum calculation

Achievement Processing

• Playwright - Browser automation for achievement scraping, packaged with full Chromium and using its new headless mode by default
• axios - HTTP client for platform APIs and metadata services
• cheerio - HTML parsing

Features

• screenshot-desktop - Optional achievement screenshot capture
• windows-capture - Windows Graphics Capture and hardware-accelerated H.264 encoding for optional achievement video clips and HDR screenshots. The bundled recorder uses a locally patched MIT-licensed 2.0.1 source snapshot to pass GPU tone-mapped surfaces directly to the encoder.
• @xboxreplay/xboxlive-auth - Microsoft/Xbox Network authentication
• ini - Config file parsing

Notification customisation inspiration

The SAN-style template and theme workflow in Notification Customisation is independently implemented for Achievements, with credit to Steam Achievement Notifier for the design inspiration. Existing Achievements presets remain supported separately.

Background Services

• chokidar keeps config/save directories under watch to trigger UI refreshes
• @vscode/windows-process-tree runs in an isolated Electron utility process and provides process events plus command-line data when required
• ps-list (via utils/pslist-wrapper.mjs) reconciles native snapshots and remains active as the limited fallback
• achievements-recorder.exe runs only while achievement records are enabled, retains bounded rolling video/audio segments on disk, and captures the default Windows output mix through WASAPI loopback (microphone input is not captured; unavailable audio safely falls back to video-only)
• Native snapshots run at ~1s; fallback detection runs at ~2s and hybrid reconciliation at ~12s
• Disabling the native process watcher in Settings -> Advanced keeps executable-name detection active through the limited ps-list fallback; command-line arguments are not available in that mode
• A config selected automatically from a running executable is cleared when its last matching process closes; configs selected manually or by save-folder watchers remain selected
• The Settings log viewer uses a filesystem watcher with a lightweight polling fallback only while the Logs tab is active; both are released when the tab or Settings is closed
• GitHub release notes are fetched on demand from the public repository API and cached atomically for offline reuse

🎮 Setup & Configuration

Quick Start (Tutorial)

1. Open Settings and set Preset, and Scale.
2. Add your Watched Folders (recommended) so the app can detect saves/emulators.
3. Start a game once so its save folder appears; the watcher will auto-create a config when possible.
4. Let the game identify and auto-select the config, or Select the config manually, set your Language to view achievements, progress, and playtime.
5. Optional: mute progress notifications for that config using the checkbox under the config dropdown.

First-Run Onboarding (Auto-Config Gate)

• On first run (or after onboarding version changes), startup pauses and shows a folder selection modal before full auto-scan starts.
• The app searches for known achievement/save signals (for example achievements.json, achievements.ini, stats.bin, emulator trophy/gpd files) and lists candidate folders.
• Start Auto-Config keeps selected folders active and mutes unchecked discovered folders, then continues startup and background config generation.
• Skip and mute all continues startup immediately and mutes discovered/default auto-config roots.
• While onboarding is pending, folder watchers and boot auto-config scans are deferred by design to avoid unwanted automatic generation.
• Onboarding completion state is saved in %APPDATA%/Achievements/preferences.json (autoConfigOnboardingCompleted, autoConfigOnboardingVersion, autoConfigOnboardingCompletedAt).
• If the modal is not visible but startup is gated, use tray action Resume Startup (Mute all).

Basic Setup

Manual Configuration

1. Create a new config with:

Config JSON fields (reference):

• appid (string) – game id
• platform (string) – steam/uplay/gog/gog-official/epic/epic-official/xbox-pc/retroachievements/xenia/rpcs3/shadps4/markerpatch/madnesspatch/xlivelessness/steam-official/ubisoft-official/ea-official
• config_path (string) – folder containing achievements.json and img/
• save_path (string) – location of save/achievement progress
• process_name (string) – executable name for process tracking
• executable / arguments (optional) – used for Launch

Auto Configuration

1. Use Watched Folders (recommended) to scan your emulator/save directories.
2. The app will:

1. Default watched folders include:

Note: Auto-configuration uses the Steam Web API when a key is provided in Settings. Without a key, it falls back to SteamDB/SteamHunters + Languages from Exophase. Sources used when available: Steam Web API, SteamDB, SteamHunters, Exophase, GOG, Epic. Goldberg UplayEmu Saves and R1 UplayEmu Saves are explicitly routed through the Uplay-to-Steam mapping while keeping the original Uplay AppID and Uplay schema storage. %LOCALAPPDATA%\UniverseLAN is treated as a strict GOG root. Each immediate directory is mapped to a GOG config, and runtime progress is monitored from \UniverseLANData\Achievements.ini. Legacy game-local UniverseLAN installations continue to use UniverseLAN.ini discovery.

RUNE Ubisoft Connect saves are supported as an opt-in watched folder. Add %USERPROFILE%\Documents\RUNE\Ubisoft Connect (or its achievements subfolder) manually in Settings -> Folders. The app reads \achievements\\\achievements.cfg, routes it through the existing Uplay schema/mapping flow, and ignores the sibling savegames tree. This path is intentionally not added to the default watched-folder list.

Folder Rescan & Blacklist

• Folders -> Rescan opens a selection modal containing active watched folders. Use Select All or Deselect All, then scan only the selected roots.
• Ignored folders and ignored nested folders remain excluded even when their parent watched folder is selected.
• Rescan does not clear the folder ignore list or the AppID blacklist.
• Ignoring a configured game from the config/dashboard uses its AppID + platform identity, so another platform with the same AppID can remain active.
• Settings -> Advanced -> Add Blacklisted AppIDs adds one or more AppIDs globally, including incorrectly detected UserIDs. Separate values with commas, spaces or new lines.
• Reset Blacklist removes the saved global and platform-specific blacklist entries. It does not remove watched folders or rescan unrelated configs.

Steam Emulator Progress Files

• Online-Fix unlock state is read from Achievements.ini; Stats.ini supplies only mapped achievement progress and progress notifications.
• An empty Online-Fix Stats.ini is valid and remains monitored. It does not unlock achievements or clear the existing achievement cache; later stat values are applied when written.
• Tenoke reads unlock state and stats from user_stats.ini. Stats are mapped to schema progress rules through the achievement operand1 value when available.
• Stats never mark an achievement unlocked by themselves; the emulator's achievement state remains the unlock source of truth.

LumaPlay Support

1. Enable Settings -> Folders -> Enable LumaPlay Watcher.
2. The app scans achievement entries under HKCU\SOFTWARE\LumaPlay and generates matching uplay configs with emu=lumaplay when possible.
3. While enabled, native registry change events trigger achievement refreshes and notifications without repeatedly polling the entire registry tree.

• The LumaPlay registry watcher is Windows-only and starts only while the option is enabled.
• Disabling this option stops LumaPlay registry monitoring, but does not disable watched-folder monitoring or normal process detection.

Xenia-Canary Support

1. Open Xenia and create a User Profile.
2. Use Watched Folders add the 'Xenia Location'\Content/xxxxxx/xxxx/xxxx/xxxxxx' folder which is created after the Account is created in Xenia.
3. Start and play the game.
4. The app will:

RPCS3 Support

1. Use Watched Folders add the 'RPCS3 Location\dev_hdd0\home\xxxxxxx\trophy' folder which is created after the RPCS3 is configured.
2. Start and play the game.
3. The app will:

ShadPS4 Support

1. Use Watched Folders and add the ShadPS4 root folder: %APPDATA%\shadPS4.
2. Start and play the game so ShadPS4 creates the trophy schema and user progress files.
3. The app will:

Important notes:

• Modern ShadPS4 storage is based on %APPDATA%\shadPS4\trophy\ for schema/icons and %APPDATA%\shadPS4\home\\trophy\.xml for progress.
• Legacy ShadPS4 storage under %APPDATA%\shadPS4\game_data\\TrophyFiles\trophy00 is still supported, but the modern trophy/progress layout is preferred when both exist.
• If multiple ShadPS4 users exist, caches are scoped per user so switching users does not overwrite another user's achievement state.

FINAL FANTASY VII achievement.dat Support

1. In the FINAL FANTASY VII game directory, add steam_appid.txt containing only 39140.
2. In Settings -> Folders, add that game directory.
3. Detection activates only when steam_appid.txt, ff7input.cfg, ff7sound.cfg and ff7video.cfg are present together.
4. The app generates a separate Steam config and schema for AppID 39140, then reads unlock bits from the adjacent achievement.dat.

• steam_appid.txt alone is ignored, so ordinary game folders and other platform flows are unaffected.
• achievement.dat is optional during config generation. An adaptive watcher waits for the game to create it.
• Existing unlocks are imported silently when the file already exists. If the file is first created after monitoring starts, newly set bits generate notifications and receive the local detection time in the cache.
• The file does not contain historical unlock timestamps; previously unlocked achievements without a cached timestamp therefore display no fabricated historical date.
• An existing Steam config for AppID 39140 is not modified or merged. This source receives its own config, identified internally by the ff7-achievement-dat provider.

Dead Space 2 MarkerPatch Support

1. Install MarkerPatch in the Dead Space 2 game directory.
2. In Settings -> Folders, add the game directory containing deadspace2.exe, MarkerPatch.ini and the achievements folder.
3. The app creates a local markerpatch config and schema from the mod's text and image resources.
4. Achievement unlocks are monitored from %LOCALAPPDATA%\EA Games\Dead Space 2\settings.txt by reading Controls.AcL.X and Controls.AcL.Y as one 64-bit bitflag.

• The selected game directory is treated as a MarkerPatch root and is not scanned as a generic AppID container, including when it contains numeric subfolders.
• Only unlock state is supported. MarkerPatch progress values are not imported or displayed.
• The app reads the installed mod resources and the external settings file; it does not modify the game, the mod or its settings.
• If the settings directory or settings.txt does not exist yet, an adaptive watcher waits for it and attaches automatically without requiring an app restart.

Alice: Madness Returns MadnessPatch Support

1. Install MadnessPatch in the game's Binaries\Win32 directory.
2. In Settings -> Folders, add either that Win32 directory or the game directory containing it.
3. The app creates a local madnesspatch config and schema from the mod's Achievements\txt and Achievements\img resources.
4. Unlocks are monitored from the active profile files under Documents\My Games\Alice Madness Returns\AliceGame\CheckPoint\\Achievements.txt.

• The Documents base is resolved through the Windows/Electron known folder, so a relocated Documents folder is supported without hardcoding C:\Users\....
• The app does not create the CheckPoint tree or Achievements.txt. If they do not exist yet, monitoring attaches automatically after MadnessPatch creates them.
• Each profile keeps an independent in-memory baseline. A newly discovered profile is seeded silently, while later bitflag changes generate notifications.
• Only the persisted unlock bitflag is imported. Runtime-only progress shown by the mod is not read from Achievements.txt.
• AchievementSupport must remain enabled in MadnessPatch.ini for the mod to create and update the state file.
• The selected game directory is treated as a MadnessPatch root and is not scanned as a generic AppID container.

XLiveLessNess Support

1. Install and configure XLiveLessNess for the supported Games for Windows - LIVE title, then start the game once if the emulator needs to create its profile data.
2. In Settings -> Folders, add the installed game directory. It can be the game root or a parent that contains the required files within the supported discovery depth.
3. Confirm that one executable directory contains xlive.dll, .exe and the matching .exe.cfg. Use Folders -> Rescan if the folder was added before these files were installed.
4. The app reads the title ID from .exe.cfg and the executable's embedded SPAFILE resource to obtain localized achievement names/descriptions, Gamerscore values and images.
5. A local xlivelessness config and schema are generated. The detected executable and process names are saved for launch, process detection, auto-select and playtime.
6. Unlocks are read from each matching \achievements.dat below XLiveLessNess\profile\title\.

<Game folder>\
└─ <executable directory>\
   ├─ xlive.dll
   ├─ <game>.exe
   └─ <game>.exe.cfg

Important notes:

• Discovery and SPAFILE/schema processing run asynchronously. XLiveLessNess scan and generation stages are reported through the same generation progress rail used by the other supported local platforms.
• achievements.dat is not required when the config is first generated. If the profile/title path does not exist yet, the adaptive watcher attaches after XLiveLessNess creates it.
• The default global state root %LOCALAPPDATA%\XLiveLessNess and game-local XLiveLessNess roots are monitored adaptively, including when their profile/title directories do not exist yet.
• A custom XLiveLessNess storage root can also be added directly in Settings -> Folders. The app links it to existing XLiveLessNess configs without treating profile or title folders as generic AppIDs.
• When process command-line detection is available, -xllnconfig= is resolved and its containing directory is added as another state root automatically.
• Multiple executables for the same title ID are kept in one config as process-name alternatives. Profiles keep independent baselines so changing profiles does not create false unlock notifications.
• Achievement schema languages follow the selection in Settings -> Advanced -> Achievements Schema Languages when the embedded SPAFILE contains those localizations.
• The app only reads the installed executable, XLiveLessNess title config and achievements.dat; it does not modify the game or emulator data.

Steam Launcher Support

1. Use Watched Folders add the 'C:\Program Files (x86)\Steam\appcache\stats' folder.
2. Start and play the game via Steam.
3. The app will:

Epic Games Launcher Support

1. Connect an Epic account in Settings and use Import Library to pull owned games.
2. The app imports owned titles with achievements as epic-official configs automatically.
3. Local detection uses Epic manifest files to resolve install location, executable path and process name when the game is installed.
4. Polling runs only for the detected running Epic game, or for an Epic Official config explicitly selected by the user.
5. The dashboard reads the local achievement cache; it does not run a full Epic sync just to render the grid.

• epic-official configs are auto-generated and are not meant to be created manually from the platform dropdown.
• The import flow relies on Epic login and local encrypted token storage.
• Store images are resolved through Epic product metadata first, then fall back to SteamGridDB only when Epic metadata cannot provide a usable image.
• For Epic emulator folders that use an artifact/AppID instead of a namespace, schema generation can resolve the related catalog item and namespace before continuing through the normal Epic schema flow.

GOG Galaxy Launcher Support

1. Install and sign in to GOG Galaxy.
2. Use Watched Folders add the %LOCALAPPDATA%\GOG.com\Galaxy\Applications folder.
3. Start and play the game via GOG Galaxy at least once.
4. The app will:

Important notes:

• gog-official is auto-generated from local GOG Galaxy data. It is not meant to be created manually from the platform dropdown.
• The config is created only after gameplay.db exists and the achievement table is populated and stable, to avoid generating an empty schema.
• If a game only has Storage\... data and no Gameplay\\gameplay.db yet, the app will detect the install path but will wait before creating the config.
• After creation, the config save_path points to the concrete Gameplay\ folder, while runtime progress is read from gameplay.db.

Ubisoft Connect Launcher Support

1. Install and sign in to Ubisoft Connect.
2. Use Watched Folders add the %LOCALAPPDATA%\Ubisoft Game Launcher\spool folder manually.
3. Start and play the game via Ubisoft Connect at least once so the local spool/cache files exist.
4. The app will:

Important notes:

• ubisoft-official is auto-generated from manually watched Ubisoft Connect spool roots. It is not meant to be created manually from the platform dropdown.
• The app does not assume the Ubisoft spool path automatically; the spool root must be added manually in Settings → Folders.
• The config is created only after both the .spool file and the local achievements archive are available, so the schema can be generated first.
• After creation, the config save_path points to the concrete spool\ folder, while runtime progress is read from .spool.

EA Desktop Launcher Support

1. Install and sign in to EA Desktop.
2. Use Watched Folders add the %LOCALAPPDATA%\Electronic Arts\EA Desktop\Logs folder manually.
3. Start and play the game via EA Desktop at least once so EADesktopVerbose.log contains the local achievement query for that game.
4. The app will:

Important notes:

• ea-official is auto-generated from manually watched EA Desktop log roots. It is not meant to be created manually from the platform dropdown.
• The app does not assume the EA Desktop logs path automatically; the logs root must be added manually in Settings -> Folders.
• The config is created only after EA Desktop has logged a full achievement set for that game, so the schema can be generated first.
• After creation, the config save_path points to the EA Desktop Logs folder, while runtime progress is read from EADesktopVerbose.log.
• EA Desktop can rotate EADesktopVerbose.log into EADesktopVerbose.bak; the app reads both so achievement events are not lost across log rotation.

Xbox PC (Microsoft / Xbox Network)

1. Open Settings -> Advanced and select Connect Xbox under Xbox PC (Microsoft / Xbox Network).
2. Sign in through Microsoft OAuth with the account used by the Windows Xbox

1. Use Import Xbox PC to:

1. Achievement state is refreshed directly from Xbox Network for the selected

Notes:

• Xbox console-only history is excluded. A title is imported only when Xbox

• Games delegated to EA App, Ubisoft Connect, or another launcher may not

• The app stores the Microsoft refresh token and Xbox XSTS session encrypted;

• The experimental authentication route uses the public desktop OAuth identity

• This client identity is not owned by the Achievements project. Microsoft can

• xbox-pc configs are auto-generated and are not meant to be created manually.

RetroAchievements

1. Open Settings -> Advanced and enter the RetroAchievements username and

1. Select Connect, then Import Library to create separate

1. Select a RetroAchievements config in the dashboard to start its API poller.

Notes:

• This integration uses only the read-only RetroAchievements Web API. It does

• The Web API key is stored with Electron safe storage and is not written as

• Polling runs only for the RetroAchievements config explicitly selected in the

• The initial import seeds existing unlocks silently, so historical unlocks do

Dashboard

• Press the "Show Dashboard" button to access the game grid
• Use search to filter games quickly
• Filter by platform and sort by name, progress, or last update time
• Click any game to load its config
• Use Ctrl + Click or the card context menu to select multiple games, then ignore, delete or clear the selection from the action bar
• Blacklisted games can be shown for inspection and restored from the dashboard when Show blacklisted games is enabled
• Use the play button for games with configured executables (dashboard closes and returns focus to the main UI)
• Automatic background polling selects the active game when its process starts
• Esc or the close button restores the dashboard overlay and re-enables input for the rest of the window

Customization

• Choose notification preset and screen position
• Choose Native Windows as the achievement preset to use Windows toast notifications instead of an animated preset
• Select notification sounds and language
• Select the achievement schema languages to generate from Settings -> Advanced -> Achievements Schema Languages
• Adjust UI scale (75% to 200%)
• Adjust achievement duration (auto or custom)
• Adjust achievement sound volume (0% to 200%)
• Toggle Show Hidden Description for hidden achievements
• Enable Close to Tray (X button hides to tray)
• Configure overlay shortcut or disable the overlay entirely
• Configure Overlay Interaction Key (toggle click-through ↔ drag/scroll)
• Optionally open the matching achievement when an animated or Native Windows notification is clicked from Settings -> Advanced -> Notification Click Action
• Choose whether notification clicks open the non-focusable, click-through overlay or the main application; opening the main application moves focus away from the game
• Native Windows notifications retain separate navigation routes when stored in Action Center, so each available notification can open its own achievement
• Enable/disable controller support for the overlay from Settings -> Advanced -> Rendering
• Enable/disable features:

• Per-game progress notifications can be muted when a config is active