Home › Steam Achievements for Indie Games (2026): Icons, Sets, Bulk Import and Code

Steam Achievements for Indie Games (2026): Icons, Sets, Bulk Import and Code

Achievements are one of the cheapest Steam features to add: a few icons, a name and a description each, and one unlock call in your game. Valve also changed how they work in October 2026, with a new achievements editor, Achievement Sets (beta), archiving and a bulk CSV import. This guide covers what Valve requires, how to make the icons with AI or by hand, the bulk upload, the code for Godot, Unity, Electron and C++, and how to test before release. Every rule comes from Valve's Steamworks documentation or the engine plugins' own docs, checked November 4, 2026.

Last updated:

Free download · one page + PDF · updated weekly, current edition November 16, 2026

🎁 Free: The AI Game Dev Stack 2026

The best AI tool for each job in a solo or indie game (3D, sprites and pixel art, animation, audio, NPCs), MCP setups for Unity, Unreal, Godot and Roblox, and which free plans you can actually ship with.

Yours free when you join the VibeStack Weekly: new AI game-dev tools and releases every Monday, 5-minute read. Unsubscribe anytime.

Quick answers

QuestionAnswer (from Valve's docs)
Icon size256×256 PNG for best results; as small as 64×64; must be square; larger icons are scaled down to 256×256; JPG also accepted
Locked (unachieved) iconValve recommends colourful achieved icons and grayscale unachieved ones, and can generate the grayscale one for you
Bulk icon file namesAPI_NAME_ACHIEVED.png and API_NAME_UNACHIEVED.png, for example LEVEL_20_ACHIEVED.png
How many achievements5,000 per app, but 100 until your app is vetted (reaches the Profile Features threshold); 40 sets including the base game set; archived achievements count toward the limit
Hidden achievementsNow called Spoiler achievements: name and description stay hidden until unlocked or revealed
CodeSetAchievement("API_NAME") then StoreStats(); the Steam overlay shows the unlock
Before releaseTick Steam Achievements under Supported Features, give every achievement an icon and a name in every configured language, and publish

What changed in October 2026: the new editor and Achievement Sets

On October 15, 2026 Valve started a beta of Achievement Sets in the Steam client, along with a new achievements page for players. Achievements are now edited in a new achievements editor (Edit Steamworks Settings → Stats & Achievements → Achievements, then the banner at the top) with two tabs: Manage Achievements and Bulk Import/Export. Valve's docs say sets are still in beta and will change.

You don't need a new SDK or a game update for sets: they're configured in Steamworks and use the same API names and calls. For a small indie game the practical advice is simple: keep everything in the base game set, and add a new set when you ship a DLC, a big update or a new mode, because adding achievements to a set players have already finished shows a “completed” set with locked achievements in it.

The fields for each achievement

FieldWhat it is
API NameUnique name your code passes to the API, e.g. ACH_WIN_ONE_GAME. Required. It's also the file name for bulk icons, and it's case sensitive in the localization CSV.
Display Name, DescriptionWhat players see. Localizable per language.
IconsAchieved and unachieved icon (see below).
Set ByClient, game server or official game server. Server-set achievements can't be set by clients.
Progress StatOptional stat plus a range that maps to 0% and 100%, for a progress bar. The stat must already exist and have the same permission.
VisibilityVisible, or Spoiler (hidden until unlocked).
Optional StatusAvailable, or Archived.
In SetWhich set it belongs to (base game by default).

Valve also says achievement names and icons should be all-ages appropriate. Spoiler and archived achievements don't show in the achievements panel on your store page.

Achievement icons: size, style and the locked version

Make each icon 256×256 PNG. Valve accepts 64×64 and JPG, but recommends the larger size, and anything larger is scaled down to 256×256. Icons must be square. For the locked state you can upload your own unachieved icon, click Generate in the editor, or tick Automatically generate unachieved icons on a bulk upload to get a grayscale copy of the achieved icon; you can replace the generated one at any time.

Players mostly see achievement icons small (in the unlock pop-up, the achievements list and the store panel), so design for that: one bold subject, a strong silhouette, no text, and the same framing and background across the set. A consistent set is the same problem as any game icon set, so the tools and workflow in our AI game icon and UI generator guide apply directly:

Achievement icons are content players see on your store page and their profiles, so if they're AI-generated, they belong in your Steam AI disclosure: see Steam AI disclosure: what to write and log each one in the free Steam AI asset log (CSV).

Free script: make every achievement icon in one command (tested)

This Python script takes a folder of icon art named after each achievement's API name (ACH_WIN_ONE_GAME.png, .jpg or .webp, any size) and writes a ready-to-upload folder: API_NAME_ACHIEVED.png and a grayscale API_NAME_UNACHIEVED.png for each, square and 256×256 by default. Non-square art is padded (or cropped with --fit crop), --bg fills the background with a colour, --pixel keeps pixel art crisp with whole-number nearest-neighbour scaling, --dim darkens the locked icon, and --csv writes a draft localization CSV. It also saves preview_64px.png, a contact sheet of every icon and its locked version at 64 px, so you can check they still read at small sizes. It refuses art smaller than 64×64 (unless --pixel), two source files for the same API name, and files already ending in _UNACHIEVED, then exits with code 1. Needs Python 3 and Pillow (pip install Pillow).

"""make_achievement_icons.py - turn a folder of icon art into Steam achievement
icons: API_NAME_ACHIEVED.png and API_NAME_UNACHIEVED.png (grayscale), square,
256x256 by default, ready for the Bulk Import/Export tab in Steamworks.

Usage:
  python3 make_achievement_icons.py art/ steam_icons/
  python3 make_achievement_icons.py art/ steam_icons/ --pixel --bg "#1b1b1b"
  python3 make_achievement_icons.py art/ steam_icons/ --fit crop --dim 0.7 --csv

Name each source image after the achievement's API name (ACH_WIN_ONE_GAME.png).
Needs Pillow:  pip install Pillow
"""
import argparse, csv, os, re, sys
from PIL import Image, ImageDraw, ImageOps

EXTS = (".png", ".jpg", ".jpeg", ".webp")
MIN_SIDE = 64          # Valve: icons "can be as small as 64x64"


def square(img, fit, bg):
    """Make an RGBA image square: pad (keep everything) or crop (center)."""
    w, h = img.size
    if w == h:
        return img
    if fit == "crop":
        s = min(w, h)
        left, top = (w - s) // 2, (h - s) // 2
        return img.crop((left, top, left + s, top + s))
    s = max(w, h)
    canvas = Image.new("RGBA", (s, s), bg)
    canvas.paste(img, ((s - w) // 2, (s - h) // 2), img)
    return canvas


def to_size(img, size, pixel):
    """Scale a square image to size x size. Pixel art: whole-number nearest-neighbour
    upscale, then pad the rest, so pixels stay crisp."""
    s = img.size[0]
    if s == size:
        return img
    if pixel and s < size:
        k = size // s
        big = img.resize((s * k, s * k), Image.NEAREST)
        out = Image.new("RGBA", (size, size), (0, 0, 0, 0))
        off = (size - s * k) // 2
        out.paste(big, (off, off))
        return out
    return img.resize((size, size), Image.NEAREST if pixel else Image.LANCZOS)


def locked(img, dim):
    """Grayscale (luminance) copy that keeps the alpha channel; dim < 1 darkens it."""
    gray = ImageOps.grayscale(img.convert("RGB"))
    if dim < 1:
        gray = gray.point(lambda v: int(v * dim))
    out = Image.merge("RGBA", (gray, gray, gray, img.getchannel("A")))
    return out


def parse_bg(text):
    if text == "transparent":
        return (0, 0, 0, 0)
    m = re.fullmatch(r"#?([0-9a-fA-F]{6})", text)
    if not m:
        sys.exit("--bg must be 'transparent' or a colour like #1b1b1b")
    v = m.group(1)
    return (int(v[0:2], 16), int(v[2:4], 16), int(v[4:6], 16), 255)


def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("src", help="folder of source images named API_NAME.png/.jpg/.webp")
    ap.add_argument("out", help="output folder (created if missing)")
    ap.add_argument("--size", type=int, default=256, help="output size in px (Valve recommends 256)")
    ap.add_argument("--fit", choices=("pad", "crop"), default="pad", help="how to make non-square art square")
    ap.add_argument("--bg", default="transparent", help="'transparent' or #RRGGBB fill behind the art")
    ap.add_argument("--pixel", action="store_true", help="pixel art: nearest-neighbour, whole-number scaling")
    ap.add_argument("--dim", type=float, default=1.0, help="brightness of the locked icon, 0-1 (1 = plain grayscale)")
    ap.add_argument("--csv", action="store_true", help="also write a draft localization CSV (api_name, field, english)")
    a = ap.parse_args()
    if not MIN_SIDE <= a.size <= 1024:
        sys.exit("--size must be between 64 and 1024 (Steam scales larger icons down to 256)")
    if not 0 < a.dim <= 1:
        sys.exit("--dim must be greater than 0 and at most 1")
    bg = parse_bg(a.bg)
    os.makedirs(a.out, exist_ok=True)

    names, problems, done = {}, [], []
    for f in sorted(os.listdir(a.src)):
        stem, ext = os.path.splitext(f)
        if ext.lower() not in EXTS:
            continue
        api = re.sub(r"_(UN)?ACHIEVED$", "", stem)
        if stem.endswith("_UNACHIEVED"):
            problems.append(f"{f}: skipped (we make the _UNACHIEVED icon from the achieved one)")
            continue
        if api in names:
            problems.append(f"{f}: two source files for {api} ({names[api]} and {f})")
            continue
        names[api] = f
        if not re.fullmatch(r"[A-Z0-9_]+", api):
            print(f"note: {api} - Valve's examples use capitals, digits and underscores; "
                  "the file name must match the API name exactly (case sensitive)")
        img = Image.open(os.path.join(a.src, f))
        img = ImageOps.exif_transpose(img).convert("RGBA")
        w, h = img.size
        if min(w, h) < MIN_SIDE and not a.pixel:
            problems.append(f"{f}: {w}x{h} is smaller than 64x64 (use --pixel for pixel art)")
            continue
        sq = square(img, a.fit, bg)
        if sq.size[0] < a.size and not a.pixel:
            print(f"note: {f} is {sq.size[0]}px, upscaling to {a.size}px will look soft")
        icon = to_size(sq, a.size, a.pixel)
        if bg[3] == 255:
            flat = Image.new("RGBA", icon.size, bg)
            flat.alpha_composite(icon)
            icon = flat
        icon.save(os.path.join(a.out, f"{api}_ACHIEVED.png"), optimize=True)
        locked(icon, a.dim).save(os.path.join(a.out, f"{api}_UNACHIEVED.png"), optimize=True)
        done.append((api, icon))

    if done:
        # preview at 64 px (the smallest size Valve allows) to check that each icon still reads
        cell, pad = 64, 8
        sheet = Image.new("RGBA", (pad + 2 * (cell + pad), pad + len(done) * (cell + pad + 12)), (40, 40, 40, 255))
        d = ImageDraw.Draw(sheet)
        for i, (api, icon) in enumerate(done):
            y = pad + i * (cell + pad + 12)
            small = icon.resize((cell, cell), Image.NEAREST if a.pixel else Image.LANCZOS)
            sheet.alpha_composite(small, (pad, y))
            sheet.alpha_composite(locked(small, a.dim), (2 * pad + cell, y))
            d.text((pad, y + cell + 1), api[:22], fill=(220, 220, 220, 255))
        sheet.save(os.path.join(a.out, "preview_64px.png"))
    if a.csv and done:
        with open(os.path.join(a.out, "achievements-localization-draft.csv"), "w", newline="", encoding="utf-8") as fh:
            wr = csv.writer(fh)
            wr.writerow(["api_name", "field", "english"])
            for api, _ in done:
                wr.writerow([api, "name", ""])
                wr.writerow([api, "description", ""])

    print(f"{len(done)} achievement(s) -> {a.out} ({2 * len(done)} icons at {a.size}x{a.size})")
    for p in problems:
        print("problem:", p)
    sys.exit(1 if problems else 0)


if __name__ == "__main__":
    main()

What we tested (November 4, 2026, Python 3.13.5 and Pillow 12.3.0): a 512×512 transparent PNG, an 800×600 JPG and a 32×32 pixel-art PNG. All outputs came out 256×256 RGBA with the right names; the JPG was padded (transparent bars) or centre-cropped with --fit crop; the 32×32 sprite was refused without --pixel and scaled exactly 8× with it; a 48×48 sprite scaled 5× to 240 px and was centred; a duplicate LEVEL_20.png + LEVEL_20.webp was reported and the exit code was 1. We haven't uploaded the output to a real Steamworks app, so we can't confirm how Steam displays transparent corners or whether its own Generate grayscale matches ours exactly. If you want Valve's grayscale instead, upload only the _ACHIEVED files and tick Automatically generate unachieved icons.

Download make_achievement_icons.py (the same script as a file, MIT license; needs Pillow). All files: free downloads.

Bulk import: CSV files and icons

The Bulk Import/Export tab lets you manage achievements as files instead of clicking through the editor:

  1. Click Export Definitions (.csv), Export Localization (.csv) and/or Export Set Localization (.csv). If your game has no achievements yet, the exports are templates with example rows starting with EXAMPLE_.
  2. Edit them in a spreadsheet. Header notes in parentheses, such as spoiler (true or false), are ignored on upload.
  3. Drag the .csv and .png files onto the upload box (several at once is fine).
  4. Check Uploaded Files for errors (removing a file undoes everything it contributed), then Pending Changes. Nothing is saved until you click Save imported data.
FileColumns
<appid>-achievements-definitions.csvapi_name (required, unique), setid (blank = base game), permission (Client, GameServer or OfficialGameServer), spoiler, archived, progress_stat_name, progress_stat_min, progress_stat_max. Names and descriptions are not in this file.
<appid>-achievements-localization.csvapi_name, field (name or description, so two rows per achievement), then one column per configured language (english, french, german…)
<appid>-achievement-sets-localization.csvsetid, then one column per language; english is required. Create sets in the editor first.
IconsAPI_NAME_ACHIEVED.png / API_NAME_UNACHIEVED.png, assigned automatically by name

Three traps from Valve's docs: rows whose api_name doesn't match an existing achievement are added as new achievements, so rename an API name in the editor first or its old data is removed; achievements missing from the CSV are kept unless you tick Delete these achievements; and if you upload icons together with a definitions CSV, icons only go to achievements in that CSV (upload icons alone to update any achievement). The script's --csv draft uses the api_name, field, english columns above; the safest route is still to export Valve's template and paste your rows into it.

Unlocking an achievement in your engine

The call is the same everywhere: set the achievement, then store stats so it uploads and the overlay pops. Valve's own C++ is SteamUserStats()->SetAchievement("ACH_WIN_ONE_GAME"); followed by SteamUserStats()->StoreStats();. Setting an already-unlocked achievement again is harmless. For progress achievements, IndicateAchievementProgress shows a progress pop-up (Valve's example: call it at 10 of 20 wins).

EnginePluginUnlock call
GodotGodotSteamSteam.setAchievement("ACH_WIN_ONE_GAME") then Steam.storeStats(). GodotSteam 4.14+ (3.28+) doesn't need to request stats first; the Steam client syncs them at boot since SDK 1.61.
Unity (or any .NET)Steamworks.NET (MIT, near 1:1 with the C++ API)if (SteamManager.Initialized) { SteamUserStats.SetAchievement("ACH_WIN_ONE_GAME"); SteamUserStats.StoreStats(); }
HTML5 game in Electronsteamworks.jsclient.achievement.activate('ACH_WIN_ONE_GAME') (also isActivated, clear, names); see how to put an HTML5 game on Steam
Unreal EngineOnline Subsystem SteamEpic's Steam module implements the Online Subsystem Achievements interface; use the engine's achievements interface rather than calling Steamworks directly
Custom C/C++Steamworks SDKSetAchievement + StoreStats, as in Valve's Spacewar sample

Two notes from GodotSteam's docs that apply to every engine: publish your achievements in Steamworks first (the game doesn't need to be released, but unpublished changes aren't exposed to the API and calls fail), and the unlock pop-up may not show in some setups (GodotSteam mentions Godot 4.x with Vulkan) but works when the game is run from the Steam client. Prompting a coding agent? Something like “Add a small Achievements singleton that wraps GodotSteam's setAchievement and storeStats, ignores calls when Steam isn't initialized, and takes the API names from a constants file” keeps API names in one place.

Testing and resetting

Release checklist for achievements

After release, https://steamcommunity.com/achievements/<appid> shows your game's achievements to anyone, owner or not, which is handy to link from a devlog or press kit. The global unlock rates also show whether a challenge is too hard. The rest of the launch steps are in our Steam launch checklist, and translating names and descriptions is covered in AI game localization for indie devs.

What we haven't tested

We don't have a Steamworks app on the box, so we haven't used the new editor, the bulk import or Achievement Sets ourselves; everything about them comes from Valve's documentation and announcement. The icon script was tested locally (above), not uploaded to Steam. The engine calls come from each plugin's docs and source (GodotSteam tutorial, Steamworks.NET's generated SteamUserStats class, steamworks.js type definitions), not from a shipped game.

Sources

Checked November 4, 2026.

More: Steam launch checklist · Steam AI disclosure · AI game icon generators · HTML5 game on Steam.

Get the Starter Stack ($12) Get the free weekly digest

Our picks (5)

freemium

PixelLab

Game Art & Assets

AI pixel art for games: characters with 4/8-direction rotations and animation, tilesets and inpainting. Web editor, Aseprite extension, MCP and API. Free trial, then subscription.

#pixel-art#sprites#game-assets
freemium

Scenario

Game Art & Assets

Train custom models on your game's art style to generate consistent assets. Also hosts NVIDIA Kimodo Text to Motion (text prompts → 3D skeleton clips; BVH on SOMA). Free plan is for personal/evaluation use; paid plans include a commercial license.

#image#game-assets
freemium

Ludo.ai

Game Art & Assets

Game-asset generator for sprites and spritesheet animation, 8-direction character sprites (Directional Sprites beta), 3D models with rigging, audio and video. My Animations (Nov 11, 2026): describe a humanoid move once (0.5 credits) and reuse it on sprites, rigged 3D models and Directional Sprites, with a left/right Mirror switch. API, MCP, CLI and a Unity plugin. 30 free credits, then Pro/Studio plans. The MIT-licensed CLI also has a free, offline Asset Toolbox (32 tools: sprite pivots and colliders, Godot/Unity/TexturePacker export, palette swaps, audio checks) that needs no account.

#sprites#game-assets#cli
freemium

Recraft

Game Art & Assets

AI image generator that also makes true vector (SVG) images, with custom styles from up to 10 reference images, Vectorize and background removal, plus an API. Useful for flat game UI icons. Free-plan images are public, owned by Recraft and not licensed for commercial use; paid plans (Basic $12/month, or $10/month billed annually) give full ownership and commercial rights.

#image#icons#ui
freemium

Leonardo.Ai

Game Art & Assets

AI image generation geared toward game assets and consistent styles. Free-plan images are public; paid plans keep them private.

#image#game-assets

+ Your tool here

Reach builders, vibe coders & indie game devs. Featured listings from $49/mo.

Advertise →
🧰 The Vibe Coder's Starter Stack: AI rules files, a prompt library and a ship-it checklist. $12.
Get the pack

FAQ

What size are Steam achievement icons?

Valve recommends 256×256 pixel PNG images. They can be as small as 64×64, must be square, and larger icons are scaled down to 256×256. JPG is also accepted.

Do I have to make the gray locked achievement icon myself?

No. Click Generate in the achievements editor, or tick Automatically generate unachieved icons when uploading in bulk, and Steam makes a grayscale unachieved icon from the achieved one. You can upload your own instead at any time.

How do I name achievement icons for bulk upload?

Use the achievement's API name plus _ACHIEVED or _UNACHIEVED, for example LEVEL_20_ACHIEVED.png and LEVEL_20_UNACHIEVED.png. Steam assigns them to the matching achievement automatically.

How many achievements can a Steam game have?

Up to 5,000 per app, but new apps are limited to 100 until they're vetted (reach the Profile Features threshold). You can have up to 40 achievement sets including the base game set, and archived achievements still count toward the limit.

What are Steam Achievement Sets?

A feature Valve put into beta on October 15, 2026: developers group achievements into sets (base game, DLC, modes or seasons), each with its own progress bar and a set-complete trophy. DLC sets don't count toward base game completion, and archived achievements stay with players who earned them. No SDK or game update is needed.

Can I hide achievements until players unlock them?

Yes. Set Visibility to Spoiler (formerly called Hidden). The name and description stay hidden until the player unlocks it or chooses to reveal it, and spoiler achievements don't show in your store page's achievements panel.

How do I unlock a Steam achievement in Godot or Unity?

In Godot with GodotSteam, call Steam.setAchievement("API_NAME") and then Steam.storeStats(). In Unity with Steamworks.NET, call SteamUserStats.SetAchievement("API_NAME") and SteamUserStats.StoreStats() after checking SteamManager.Initialized. Publish the achievements in Steamworks first or the calls fail.

Can I use AI-generated achievement icons?

Yes, as long as your tool's plan allows commercial use, and you disclose AI-generated content players see in Steam's Content Survey. Valve also asks that achievement names and icons are all-ages appropriate.

Free download · one page + PDF · updated weekly, current edition November 16, 2026

📬 Get the VibeStack Weekly + the free AI Game Dev Stack 2026

The best AI tool for each job in a solo or indie game (3D, sprites and pixel art, animation, audio, NPCs), MCP setups for Unity, Unreal, Godot and Roblox, and which free plans you can actually ship with.

Yours free when you join the VibeStack Weekly: new AI game-dev tools and releases every Monday, 5-minute read. Unsubscribe anytime.