Add Achievements to Non‑Steam Games on Linux: A Practical Guide for Power Users

Add Achievements to Non‑Steam Games on Linux: A Practical Guide for Power Users

Linux gaming has come a long way, and one of the small but meaningful comforts of modern platforms is achievements: those chimes and popups that reward exploration and extend playtime. If you play DRM‑free titles, indie releases, or emulated classics outside Steam, you might miss that little dopamine hit. Fortunately, the Linux community has created tools and workflows that add achievement overlays to non‑Steam games. This guide walks you through practical, step‑by‑step methods for native Linux games, Proton/Windows titles, Lutris launches, and emulators, plus troubleshooting for common edge cases.

Why add achievements to non‑Steam games?

Achievements aren't just vanity: they improve game retention, provide optional goals for speedrunners and completionists, and create community challenges. For storefront‑agnostic players they restore a modern UX element and make old or indie games feel more alive. This guide focuses on community tools that surface overlay popups and track progress, rather than proprietary platform services.

What you'll need

• A modern Linux distribution (Ubuntu/Fedora/Arch or similar)
• Build tools (gcc/clang, make, meson/ninja depending on the project)
• Access to the terminal and basic package management skills
• A copy of the target game or emulator installed
• Optional: Steam client (for adding non‑Steam shortcuts) and Lutris

Overview of approaches

There are two broad ways community projects implement achievements for non‑Steam games:

1. Overlay hooking — a shared library that injects into the game process with LD_PRELOAD and displays an on‑screen popup when achievement criteria are met.
2. Backend integrations — services that map in‑game events (memory, API hooks, or emulator events) to achievement definitions and optionally sync progress to an account or local database.

Most practical setups combine both: a small backend storing achievements + a lightweight overlay library that listens for signals and displays popups. Below are step‑by‑step instructions using generic, community tools and patterns you can adapt to the specific project you choose.

Step‑by‑step: Installing a basic achievement overlay

The example steps use a typical open‑source overlay project layout. Replace repository and build steps with the project you pick.

1) Clone and install dependencies

On Debian/Ubuntu:

sudo apt update
sudo apt install git build-essential libx11-dev libgl1-mesa-dev libsndfile1-dev pkg-config

On Fedora:

sudo dnf install git gcc make libX11-devel mesa-libGL-devel libsndfile-devel pkgconfig

2) Get the code

git clone https://github.com/community/achievements-overlay.git
cd achievements-overlay

3) Build

Common build patterns:

./configure && make && sudo make install
# or
meson setup build && ninja -C build && sudo ninja -C build install

Note: many overlays require both 64‑bit and 32‑bit builds if you plan to inject into 32‑bit games. On multiarch systems enable i386 architecture and install lib32 variants of dependencies.

4) Test the overlay on a native Linux game

Quick test using LD_PRELOAD:

LD_PRELOAD=/usr/local/lib/libachieveoverlay.so /path/to/game/binary

If you see the overlay's debug message or a test popup, you have a working injection. If nothing happens, see the Troubleshooting section below.

Using the overlay with Proton (Windows titles)

Proton runs Windows games inside a Wine environment. To inject your overlay into a Proton process, you typically need to set LD_PRELOAD for the game process that Steam launches.

Method A — Add the non‑Steam game to Steam

1. Open Steam → Games → Add a Non‑Steam Game to My Library.
2. Point Steam to a launcher script (recommended) or the game's native launcher.
3. In the game's Properties → Set Launch Options, add:
   LD_PRELOAD=/home/youruser/.local/lib/libachieveoverlay.so %command%
4. Ensure Steam Play is enabled and the selected Proton version is set for the game.

Tip: Steam sometimes strips environment changes. Using a small wrapper script that exports LD_PRELOAD then execs %command% is more reliable. Example wrapper (make it executable):

#!/bin/sh
export LD_PRELOAD='/home/youruser/.local/lib/libachieveoverlay.so:$LD_PRELOAD'
exec "$@"

Point Steam to that wrapper as the 'exe' and use the Steam Launch Options to call the actual game binary if needed.

Method B — Launch via Lutris or a custom script

If you use Lutris, open the game's configuration → Runner options → Environment and add:

LD_PRELOAD=/home/youruser/.local/lib/libachieveoverlay.so

Lutris will export that variable into the Proton/Wine process, injecting the overlay. For standalone Proton launches use a wrapper that sets LD_PRELOAD before calling the proton script.

Emulator setups: RetroArch, Dolphin, and others

Emulator ecosystems already have achievement projects worth knowing:

• RetroAchievements: integrates with RetroArch cores and many retro emulators. Sign in within RetroArch's Online Updater → 'RetroAchievements' settings and provide username/token. It shows in‑game popups and tracks progress.
• RetroArch core + overlay: some community overlays can inject into RetroArch if you need a consistent visual style across emulators; use LD_PRELOAD on the RetroArch binary.
• Dolphin has community projects and plugins to create achievement-like experiences; check the Dolphin forums for updated integrations.

When using emulators, prefer native integrations (RetroAchievements) where available—they are more reliable than LD_PRELOAD injections into complex emulator processes.

Practical tips for creating or importing achievement packs

• Look for existing JSON or YAML packs in the project's repo — many communities publish achievement definition files for popular indie titles.
• If you author achievements, keep them modular and stable: avoid relying on memory offsets that change between versions.
• Use event hooks exposed by the community project (game state, API calls) where possible, rather than fragile memory scanning.
• Share your pack in GitHub/Gist so other users can import it into their overlay/backends.

Troubleshooting: common edge cases and fixes

Overlay doesn't show on Wayland

Wayland intentionally limits global overlays for security. If your overlay relies on X APIs it may not work under a native Wayland session. Workarounds:

• Run the game under XWayland (many games default to XWayland automatically).
• Switch to an X11 session when you need overlays.
• Look for Wayland‑native overlay support in the project or compositor plugins (rare).

Injection fails for 32‑bit games

LD_PRELOAD requires a library that matches the game process architecture. Build both 64‑bit and 32‑bit versions of the overlay and point to the right .so for 32‑bit executables. On Debian/Ubuntu, enable i386 multiarch and install lib32 versions of dependencies.

Steam strips LD_PRELOAD or ignores environment

Use a wrapper script that exports LD_PRELOAD and then execs the game binary. Make sure Steam is launching your wrapper and not bypassing it. For Proton games, ensure you set the wrapper as the executable Steam runs.

Overlay conflicts with Steam or other injectors

If multiple preloaders are used, order matters. Combine multiple .so files into LD_PRELOAD separated by colons, with the overlay first or last depending on the required symbol resolution. Example:

LD_PRELOAD='/home/user/libmyoverlay.so:/usr/lib/steam/steamoverlay.so' %command%

Achievements don't trigger or miscount

• Confirm the achievement pack matches your game version.
• Enable logging in the overlay backend and inspect logs for event recognition problems.
• For emulator achievements, verify ROM checksum matches the achievement definitions.

Security and stability considerations

LD_PRELOAD and injection techniques run code inside game processes. Only use overlays from trusted sources and review the code if possible. Keep separate profiles for experimental setups and back up save files before testing new achievement packs.

Keeping your setup tidy and maintainable

1. Pin overlay versions in a local folder and record build commands in a dotfiles repo.
2. Use wrapper scripts for each game; store them in ~/bin and add descriptive comments so you remember why each game needs special options.
3. Document your achievement packs and share them in a GitHub repo with a short README so friends can import them.

Final thoughts and next steps

Adding achievements to non‑Steam games on Linux is a very niche but rewarding hobbyist project that improves game retention and makes smaller titles feel modern. Start small: test with a native Linux game, then experiment with a Proton title or RetroArch core. If you enjoy packaging and sharing achievement definitions, you can contribute to community repositories and help others rediscover old favorites with fresh goals.

Want a different kind of retro gaming enrichment? Explore RetroAchievements for emulators, or check out community repos on GitHub for ready‑made packs. And if you’re upgrading your setup while tweaking overlays, don’t miss our deals and storage guides to keep your library accessible: Beat the Price Hike and Switch 2 Storage Masterclass.

If you run into a stubborn bug, include these details when asking for help: distro and version, window system (X11/Wayland), game executable path, overlay log output, and whether the target process is 32‑bit or 64‑bit. That context helps maintainers diagnose injection and event recognition issues quickly.