Add Steam-Style Achievements to Any Linux Game: A Practical How-To

Want the satisfaction of Steam-style achievements even when a game wasn't built for them? A new open-source community tool makes it possible to add local achievements and overlay notifications to non-Steam games on Linux. This guide walks you through installing the tool, integrating it with popular launchers (Steam, Lutris, Heroic), enabling the overlay, troubleshooting common problems, and hardening your setup against cheating.

What this tool does — and what it doesn’t

The tool (we'll call it achieve-linux for the purposes of this walkthrough) provides three components:

• a lightweight achievement daemon that runs in the background and records events;
• a small overlay process that shows pop-up achievement notifications in-game;
• an optional server backend (self-host or community) that stores achievement records and validates submissions.

Important: this does not add achievements to Steam's cloud or Steam Achievements system. It provides a Steam-style local achievement experience (notifications, collections, and optional online leaderboards) for non-Steam titles.

Prerequisites

• Linux desktop (X11 recommended; Wayland supported in many compositors but can be trickier).
• Basic command-line familiarity and access to install packages.
• Optional: a community backend account or your own server if you want cloud-synced achievements or leaderboards.

Step 1 — Install the tool

The project is open-source and provides multiple delivery formats: a prebuilt AppImage/Flatpak, distro packages, and a build-from-source option. Pick the one that matches your comfort level.

AppImage / Flatpak (fastest)

Download the latest AppImage from the release page, make it executable and run:

chmod +x achieve-linux-x86_64.AppImage
./achieve-linux-x86_64.AppImage

For Flatpak (if available):

flatpak install flathub io.community.achieve-linux
flatpak run io.community.achieve-linux

Debian/Ubuntu

If there's a DEB package or an APT PPA:

sudo dpkg -i achieve-linux_*.deb
sudo apt -f install

Or build from source (Rust example):

git clone https://github.com/community/achieve-linux.git
cd achieve-linux
cargo build --release
sudo cp target/release/achieve-linux /usr/local/bin/

Arch / Manjaro

Check AUR for a package, or build from source:

yay -S achieve-linux
# or build from git
git clone ...
makepkg -si

Step 2 — Configure achievements for a game

Achievements are defined by JSON files that describe triggers, unlock conditions, icons and optional hints. A typical achievements.json looks like:

{
  "game": "My Indie Game",
  "id": "myindie-001",
  "achievements": [
    {"id": "first_blood", "title": "First Kill", "trigger": "event:enemy_killed", "icon": "firstkill.png"},
    {"id": "collector", "title": "Collector", "trigger": "stat:items_collected>=100", "icon": "collect.png"}
  ]
}

Ways to emit triggers from a game:

• Write a tiny plugin/mod that posts events to the local daemon (Unix socket or HTTP).
• Use a scripting layer in the engine to call the local socket.
• Use a game wrapper that watches log output and emits events when certain log lines appear.

If you're not authoring the game, the wrapper/log approach is the easiest because it requires no code changes.

Step 3 — Integrate the overlay with your launcher

To show pop-up notifications in-game, the overlay process must be started and must be able to render on top of the game window. Here are practical integration methods for common Linux game launchers.

Steam (adding a non-Steam game)

1. Create a small wrapper script that starts the achievement daemon (if not already running) and launches the game. Example wrapper launch_with_achieve.sh:

#!/bin/bash
# Start daemon if missing
if ! pgrep -x achieve-linux >/dev/null; then
  achieve-linux --daemon &
  sleep 0.3
fi
# Start overlay in background
achieve-linux --overlay &
# Launch the actual game binary
/usr/bin/mygame "$@"

2. Make it executable (chmod +x), then in Steam: Games > Add a Non-Steam Game > Browse > select your script.
3. Right-click the added entry > Properties > Set Launch Options if you need custom arguments.

Lutris

In Lutris you can set a custom executable or use “Runner options” / “Game options” to add a pre-launch script. Set the executable to your wrapper script and use the same technique as with Steam. For Wine/Proton games, ensure the wrapper launches the correct wine binary with the configured prefix.

Heroic & Other Launchers

Heroic also supports custom executables per game. Point the launcher at the wrapper script that starts the daemon and overlay then launches the real game. For games running through Proton/Wine, pass the Proton/Wine prefix as usual.

Wayland notes

Wayland compositors differ in how they allow overlays. If you run GNOME (Mutter), KDE (KWin) or Sway, try the following:

• Enable XWayland support and use X11 overlay fallback if the overlay doesn't render natively.
• Use the overlay's experimental Wayland backend (if available) and follow the compositor-specific instructions in the tool's README.

Troubleshooting checklist

If the overlay or achievements don't appear:

• Check logs at ~/.local/share/achieve-linux/logs (or the path shown in the tool's UI).
• Confirm the daemon and overlay are running with pgrep -a achieve-linux.
• If using Proton/Wine, launch the wrapper inside the same Proton prefix. Sometimes the overlay needs to run inside the prefix to draw on the game window.
• Wayland: try the X11 mode or run the overlay as rootless XWayland client if your compositor blocks overlays.
• Missing icons? Ensure the icon path in the JSON is correct and readable by the daemon.
• If wrappers hang, add a short sleep after launching the daemon so it registers its socket before the game starts.

Keeping achievements secure and minimizing cheating

A local achievement system can be manipulated if everything is client-side. Here are practical ways to reduce cheating and protect online leaderboards:

1. Keep sensitive validation server-side

Wherever possible, move final validation to a server: the client reports events, and the server recomputes whether the achievement condition was met. This prevents users from faking a single success event to unlock high-value rewards.

2. Use signed events and short-lived tokens

Each event submission should be cryptographically signed (HMAC) with a server-issued ephemeral token. Tokens should be short-lived and tied to a session; replay protection (nonces/timestamps) denies reuse.

3. Log contextual proof

When possible, include minimal, non-sensitive proof with submissions: a checksum of the game state, hashed sequence of recent events, or short, deterministic replays that the server can verify. Don't send raw memory dumps — that creates privacy issues.

4. Rate-limit and heuristics

Apply rate limits per user and per achievement. Use heuristics to detect impossible unlock patterns (e.g., many instant unlocks across many users) and flag for manual review.

5. Avoid exposing debug APIs

The local daemon should not expose simple, unauthenticated endpoints that unlock achievements. Require local sockets with proper permissions and consider UIDs/GIDs that match the game process to verify caller identity.

6. Anti-cheat compatibility

If a game already uses kernel-level anti-cheat (rare on Linux) or vendor systems such as EasyAntiCheat/BattlEye via Proton, be careful: hooking additional overlays or injection techniques can conflict with anti-cheat and cause bans. Practical advice:

• Test first in a safe environment (no official matchmaking) to ensure no anti-cheat triggers.
• Prefer in-process, documented APIs provided by game developers over injection.
• If the game uses third-party anti-cheat, consult the tool's docs and community about known compatibility issues.

Practical tips and best practices

• Start with non-competitive achievements (cosmetic or single-player progress) before enabling online leaderboards.
• Publish achievement definitions so other community members can reuse them and build shared leaderboards.
• Backup user achievement files to cloud or to your own server if you care about persistence across installs.
• Use the tool’s debug mode to simulate events and verify unlocks without playing through the whole game.

Where to go next

Once you have achievements working, explore other ways to improve the experience: tie achievement unlocks to streaming overlays or social notifications when you stream — our guide on creating the ultimate streaming space covers sound and overlay best practices for streamers wanting tighter integration.

For performance-sensitive titles, check engine-specific integrations or higher-fidelity overlays that reduce CPU/GPU overhead. If you tune game performance before adding overlays, this article about optimizing your game experience will help you prepare for beta testing and smooth gameplay.

Related reading:

• Spellcasters Chronicles: Optimizing Your Game Experience Ahead of Closed Beta 2
• Gaming in Harmony: How to Create the Ultimate Streaming Space with Your Favorite Tunes

Summary

Adding Steam-style achievements to non-Steam Linux games is realistic and practical thanks to the new open-source tooling ecosystem. With a small wrapper script, a JSON definition for achievements, and careful integration into Steam/Lutris/Heroic launchers, you can get the same satisfying pop-ups and progress tracking for your favorite indie titles. Secure your setup by moving sensitive validation to a server, signing events, and testing for anti-cheat compatibility.

If you're experimenting with achievements for a community mod or an indie release, start simple, collect community feedback, and iterate on validation strategies so achievements remain fun and fair.