Setup

First-run flow, manual setup, and auto configuration.

This page reorganizes the main onboarding and configuration steps into a shorter flow users can follow without reading the full project README.

Video walkthroughs

Use these when the written steps are not enough.

  • First Run covers the first boot flow and initial setup.
  • Controller Support includes a Dashboard introduction and controller navigation.
  • Manual Config shows the manual configuration flow.
  • Auto Config shows watched folders, detection, and automatic config generation.

Quick start

  1. Download the Windows installer from GitHub Releases, install Achievements, and open the application. Node.js and Git are needed only when running the project from source.
  2. Open Settings and choose a preset and scale.
  3. Add Watched Folders so the app can discover save or emulator folders.
  4. Start the game once so its save folder or local achievement files exist.
  5. Let the watcher auto-create a config when possible, or create the config manually.
  6. Select the config and choose the language to view achievements, progress, and playtime.
  7. Optionally mute progress notifications for the active config.
Watched folders setup in Settings

Open an existing config from the command line

Pass both the AppID and platform to the installed or unpacked executable to open an existing config directly: 

Achievements.exe --appid=239140/steam
Achievements.exe --appid=239140 --platform=steam
  • Both formats are supported and equivalent.
  • If Achievements is already running, the existing instance opens and navigates to the matching config.
  • AppID and platform must exactly match an existing config. These arguments do not generate a config or launch the game.
  • Supported platform values are the same values listed in the Config JSON reference below.

First-run onboarding

  • On first run, or after the onboarding version changes, the welcome dialog offers Restore from Backup and Set Up as New Device.
  • Restoring opens the profile backup flow. Setting up a new device continues to folder selection before the full automatic scan begins.
  • In folder selection, Back returns to the welcome dialog without completing onboarding.
  • The app searches for known achievement signals such as achievements.json, achievements.ini, stats.bin, trophy files, and emulator progress files.
  • Start Auto-Config keeps selected folders active and mutes unchecked discovered folders.
  • Skip and mute all continues startup immediately and mutes the discovered or default auto-config roots.
  • Folder watchers and boot auto-config scans remain deferred while onboarding is pending, preventing unwanted config generation.
  • Onboarding state is stored in %APPDATA%\Achievements\preferences.json using autoConfigOnboardingCompleted, autoConfigOnboardingVersion, and autoConfigOnboardingCompletedAt.
  • If startup is still gated but the modal is hidden, use tray action Resume Startup (Mute all).
First boot onboarding flow

Achievements files generation

Auto-configuration follows a defined Steam lookup order depending on whether a Steam Web API key is stored in Settings.

  • With a key, the app tries the Steam Web API GetSchemaForGame endpoint first, followed by GetGameAchievements.
  • Without a key, it tries Schema Parse, the public Steam achievement JSON, SteamCommunity, and then SteamDB.
  • SteamCommunity supplies achievement IDs, text, color and gray icons, and available translations directly, without opening a browser.
  • Exophase can add translations when needed. If a requested translation is unavailable, the app falls back to English.
  • Sources used when available include Steam Web API, Schema Parse, SteamCommunity, SteamDB, Exophase, GOG, and Epic.

Manual configuration

Create a config with the following fields:

  • Name: your preferred identifier.
  • AppID: Steam AppID or folder identifier used for the game.
  • Config Path: folder containing achievements.json and img/, or leave empty to generate it.
  • Save Path: location of progress or save data.
  • Executable and Arguments: optional launch settings.
  • Process Name: optional explicit process name to monitor.

Names are sanitized before saving, and that sanitized value is used on disk and for playtime totals.

Manual config creation flow

Config JSON reference

  • appid – game id.
  • platform – one of steam, steam-official, uplay, ubisoft-official, ea-official, epic, epic-official, gog, gog-official, xbox-pc, retroachievements, x360recomp, ps3recomp, ps4recomp, pcports, xenia, rpcs3, shadps4, kytyps5, markerpatch, madnesspatch, or xlivelessness.
  • config_path – folder that contains achievements.json and image assets.
  • save_path – folder containing the local file or files where unlocked achievement state is saved. This is the achievement progress location, not necessarily the game's normal save-game folder.
  • process_name – executable name used for process tracking.
  • executable / arguments – optional launch metadata.

If config_path points to a custom location, schema regeneration and cleanup will not overwrite that folder.

pcports, x360recomp, ps3recomp, ps4recomp, and kytyps5 configs are generated from supported folders through watched-folder discovery and Rescan. They are not intended for manual creation from the platform selector.

Auto configuration

Auto-config works best when the app can scan watched folders regularly.

  1. Add one or more Watched Folders that contain emulator data, save folders, or launcher caches.
  2. The app detects app ids and resolves the platform.
  3. It fetches the game name, schema, achievement data, and images when sources are available.
  4. It generates configs automatically.
Automatic detection and config generation

Default watched folders

  • %PUBLIC%\Documents\Steam\CODEX
  • %PUBLIC%\Documents\Steam\RUNE
  • %PUBLIC%\Documents\OnlineFix
  • %PUBLIC%\Documents\EMPRESS
  • %APPDATA%\Goldberg SteamEmu Saves
  • %APPDATA%\Goldberg UplayEmu Saves
  • %APPDATA%\R1 UplayEmu Saves
  • %APPDATA%\GSE Saves
  • %APPDATA%\NemirtingasEpicEmu
  • %APPDATA%\EMPRESS
  • %LOCALAPPDATA%\anadius\LSX emu\achievement_watcher
  • %APPDATA%\Steam\CODEX
  • %APPDATA%\SmartSteamEmu
  • %LOCALAPPDATA%\SKIDROW
  • %LOCALAPPDATA%\UniverseLAN

Goldberg UplayEmu Saves and R1 UplayEmu Saves use the Uplay-to-Steam mapping while retaining the original Uplay AppID and schema storage. %LOCALAPPDATA%\UniverseLAN is treated as a strict GOG root; see the UniverseLAN platform guide for its layout.

RUNE Ubisoft Connect saves

This integration is optional and must be added as a watched folder manually.

  1. Open Settings - Folders and add either %USERPROFILE%\Documents\RUNE\Ubisoft Connect or its achievements subfolder.
  2. Start the game once so RUNE creates <root>\achievements\<UserID>\<Uplay AppID>\achievements.cfg.
  3. Use Folders - Rescan if the config is not generated immediately.

Achievements sends this file through the existing Uplay schema and AppID mapping flow. The sibling savegames tree is ignored. This location is intentionally absent from the default watched-folder list, so adding it manually is required.

Folder rescan and blacklist

  • Folders - Rescan opens a modal containing the active watched folders. Use Select All or Deselect All, then scan only the selected roots.
  • Ignored folders and nested ignored 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 uses its AppID and platform identity, so the same AppID on another platform can remain active.
  • Settings - Advanced - Add Blacklisted AppIDs accepts multiple AppIDs, including incorrectly detected user IDs. Separate values with commas, spaces, or new lines.
  • Reset Blacklist removes global and platform-specific blacklist entries without removing watched folders or rescanning unrelated configs.
  • Automatic emulator discovery records confirmed missing IDs separately for Steam, Uplay, GOG, and Epic. A generic scan skips only the blacklisted provider and continues trying the other applicable providers; a known source skips its own blacklisted ID directly.
  • When a game is identified successfully but the provider confirms that it has no achievements, discovery stops for that game and its AppID is blacklisted only for the identified platform.
  • A network, authentication, parser, or other technical failure is not treated as proof that an AppID is invalid or that the game has no achievements. Ambiguous identification is also not a confirmed negative result.
  • An AppID becomes globally blacklisted only when every applicable provider returns a confirmed negative result, with no technical failures, ambiguity, or previously identified game.
  • Automatically recorded lookup reasons are removed together with their blacklist entries. Legacy entries that have no recorded reason are never used as evidence for creating a global blacklist entry.

Steam emulator progress files

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