# VibeStack Weekly (https://vibestackweekly.com) | Steam achievement icon maker (make_achievement_icons.py) # From https://vibestackweekly.com/steam-achievements-for-indie-games/#icon-script # MIT License. Copyright (c) 2026 VibeStack Weekly. # Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files # (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, # publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, # subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or # substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT # NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR # COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """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()