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. Open Settings and choose a preset and scale.
  2. Add Watched Folders so the app can discover save or emulator folders.
  3. Start the game once so its save folder or local achievement files exist.
  4. Let the watcher auto-create a config when possible, or create the config manually.
  5. Select the config and choose the language to view achievements, progress, and playtime.
  6. 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, startup can pause and show a folder selection modal before full auto-scan begins.
  • 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

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, xenia, rpcs3, shadps4, markerpatch, madnesspatch, or xlivelessness.
  • config_path – folder that contains achievements.json and image assets.
  • save_path – folder with local progress or save data.
  • 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.

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%\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.

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.

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.

Steam API key behavior

Auto-configuration prefers the Steam Web API when a key is stored in Settings.

  • With a key: the app uses Steam Web API for schema and metadata when possible.
  • Without a key: it falls back to SteamDB, SteamHunters, and Exophase for language enrichment when available.
  • Sources used when available include Steam Web API, SteamDB, SteamHunters, Exophase, GOG, and Epic.