diff --git a/scripts/fetch_badges.py b/scripts/fetch_badges.py
new file mode 100644
index 0000000..45273fb
--- /dev/null
+++ b/scripts/fetch_badges.py
@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""One-time script to download badge images from Bulbapedia."""
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+BADGES_DIR = Path(__file__).resolve().parent.parent / "frontend" / "public" / "badges"
+SEEDS_DIR = (
+ Path(__file__).resolve().parent.parent
+ / "backend"
+ / "src"
+ / "app"
+ / "seeds"
+ / "data"
+)
+
+MEDIAWIKI_API = "https://archives.bulbagarden.net/w/api.php"
+
+
+def get_referenced_badges() -> set[str]:
+ """Extract all unique non-null badge_image_url from seed files."""
+ badges = set()
+ for f in SEEDS_DIR.glob("*-bosses.json"):
+ data = json.loads(f.read_text())
+ for boss in data:
+ url = boss.get("badge_image_url")
+ if url:
+ badges.add(url)
+ return badges
+
+
+def get_missing_badges() -> list[str]:
+ """Return badge paths that are referenced but don't exist on disk."""
+ referenced = get_referenced_badges()
+ missing = []
+ for badge_path in sorted(referenced):
+ full_path = BADGES_DIR / Path(badge_path).name
+ if not full_path.exists():
+ missing.append(badge_path)
+ return missing
+
+
+def badge_path_to_bulbapedia_filename(badge_path: str) -> str:
+ """Convert /badges/coal-badge.png -> Coal_Badge.png"""
+ name = Path(badge_path).stem # e.g. "coal-badge"
+ parts = name.split("-") # ["coal", "badge"]
+ title_parts = [p.capitalize() for p in parts]
+ return "_".join(title_parts) + ".png"
+
+
+def resolve_image_urls(filenames: list[str]) -> dict[str, str | None]:
+ """Use MediaWiki API to resolve image filenames to direct URLs."""
+ results = {}
+ # Process in batches of 50
+ for i in range(0, len(filenames), 50):
+ batch = filenames[i : i + 50]
+ titles = "|".join(f"File:{fn}" for fn in batch)
+ cmd = [
+ "curl",
+ "-s",
+ f"{MEDIAWIKI_API}?action=query&titles={titles}"
+ "&prop=imageinfo&iiprop=url&format=json",
+ ]
+ result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+ data = json.loads(result.stdout)
+
+ # Build normalization map (API normalizes underscores to spaces)
+ norm_map = {}
+ for entry in data.get("query", {}).get("normalized", []):
+ norm_map[entry["to"]] = entry["from"]
+
+ pages = data.get("query", {}).get("pages", {})
+ for page in pages.values():
+ title = page.get("title", "").replace("File:", "")
+ # Map back to original underscore form
+ original = norm_map.get(f"File:{title}", f"File:{title}").replace(
+ "File:", ""
+ )
+ imageinfo = page.get("imageinfo", [])
+ if imageinfo:
+ results[original] = imageinfo[0]["url"]
+ else:
+ results[original] = None
+ return results
+
+
+def download_file(url: str, dest: Path) -> bool:
+ """Download a file using curl."""
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ result = subprocess.run(
+ ["curl", "-sL", "-o", str(dest), url],
+ capture_output=True,
+ text=True,
+ )
+ return result.returncode == 0 and dest.exists() and dest.stat().st_size > 0
+
+
+def main():
+ missing = get_missing_badges()
+ if not missing:
+ print("All badge images already exist!")
+ return
+
+ print(f"Missing {len(missing)} badge images:")
+ for b in missing:
+ print(f" {b}")
+
+ # Build mapping: badge_path -> bulbapedia_filename
+ path_to_filename = {}
+ for badge_path in missing:
+ path_to_filename[badge_path] = badge_path_to_bulbapedia_filename(badge_path)
+
+ print(f"\nResolving {len(path_to_filename)} image URLs from Bulbapedia...")
+ filenames = list(set(path_to_filename.values()))
+ url_map = resolve_image_urls(filenames)
+
+ # Download
+ success = 0
+ failed = []
+ for badge_path, bp_filename in sorted(path_to_filename.items()):
+ url = url_map.get(bp_filename)
+ if not url:
+ print(f" FAILED: {badge_path} (no URL for {bp_filename})")
+ failed.append((badge_path, bp_filename))
+ continue
+
+ dest = BADGES_DIR / Path(badge_path).name
+ if download_file(url, dest):
+ print(f" OK: {badge_path}")
+ success += 1
+ else:
+ print(f" FAILED: {badge_path} (download error)")
+ failed.append((badge_path, bp_filename))
+
+ print(f"\nDownloaded: {success}/{len(missing)}")
+ if failed:
+ print(f"Failed ({len(failed)}):")
+ for badge_path, bp_filename in failed:
+ print(f" {badge_path} -> {bp_filename}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/fetch_boss_sprites.py b/scripts/fetch_boss_sprites.py
new file mode 100644
index 0000000..c45ad1f
--- /dev/null
+++ b/scripts/fetch_boss_sprites.py
@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+"""One-time script to fetch boss battle sprites from Bulbapedia archives.
+
+For trainer bosses (gym leaders, elite four, champions, kahunas):
+ Downloads VS portraits or battle sprites from archives.bulbagarden.net.
+
+For totem/noble pokemon bosses:
+ Links to existing pokemon sprites already in the project.
+
+Usage:
+ python scripts/fetch_boss_sprites.py
+"""
+
+import json
+import re
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SEED_DIR = ROOT / "backend" / "src" / "app" / "seeds" / "data"
+SPRITE_DIR = ROOT / "frontend" / "public" / "boss-sprites"
+
+BULBA_API = "https://archives.bulbagarden.net/w/api.php"
+USER_AGENT = "nuzlocke-tracker-sprite-fetch/1.0"
+
+# ── Game slug → Bulbapedia sprite naming conventions ──
+# For Gen 1-5: Spr_{CODE}_{Name}.png (pixel battle sprites)
+# For Gen 6+: VS{Name}.png or VS{Name}_{CODE}.png (VS portraits)
+GAME_SPRITE_CONFIG: dict[str, dict] = {
+ "red": {"prefix": "Spr", "code": "RG", "fmt": "spr"},
+ "yellow": {"prefix": "Spr", "code": "Y", "fmt": "spr"},
+ "gold": {"prefix": "Spr", "code": "GS", "fmt": "spr"},
+ "crystal": {"prefix": "Spr", "code": "C", "fmt": "spr"},
+ "ruby": {"prefix": "Spr", "code": "RS", "fmt": "spr"},
+ "emerald": {"prefix": "Spr", "code": "E", "fmt": "spr"},
+ "firered": {"prefix": "Spr", "code": "FRLG", "fmt": "spr"},
+ "diamond": {"prefix": "Spr", "code": "DP", "fmt": "spr"},
+ "platinum": {"prefix": "Spr", "code": "Pt", "fmt": "spr"},
+ "heartgold": {"prefix": "Spr", "code": "HGSS", "fmt": "spr"},
+ "black": {"prefix": "Spr", "code": "BW", "fmt": "spr"},
+ "black-2": {"prefix": "Spr", "code": "B2W2", "fmt": "spr"},
+ "x": {"suffix": "", "fmt": "vs"},
+ "omega-ruby": {"suffix": "", "fmt": "vs"},
+ "sun": {"suffix": "", "fmt": "vs"},
+ "ultra-sun": {"suffix": "USUM", "fmt": "vs"},
+ "lets-go-pikachu": {"suffix": "PE", "fmt": "vs"},
+ "sword": {"suffix": "", "fmt": "vs"},
+ "brilliant-diamond": {"suffix": "BDSP", "fmt": "vs"},
+ "legends-arceus": {"suffix": "LA", "fmt": "vs"},
+ "scarlet": {"suffix": "", "fmt": "vs"},
+}
+
+# ── Boss name → Bulbapedia filename overrides ──
+# For names that don't map cleanly to Bulbapedia filenames
+NAME_OVERRIDES: dict[str, str] = {
+ "Lt. Surge": "Lt_Surge",
+ "Crasher Wake": "Crasher_Wake",
+ "Professor Kukui": "Professor_Kukui",
+ "Tate & Lisa": "Tate_and_Liza",
+ "Tate & Liza": "Tate_and_Liza",
+ "Top Champion Geeta": "Geeta",
+}
+
+# ── Totem/Noble pokemon → pokemon name in seed data for sprite lookup ──
+TOTEM_POKEMON: dict[str, str] = {
+ "Totem Gumshoos": "Gumshoos",
+ "Totem Wishiwashi": "Wishiwashi Solo",
+ "Totem Salazzle": "Salazzle",
+ "Totem Lurantis": "Lurantis",
+ "Totem Vikavolt": "Vikavolt",
+ "Totem Mimikyu": "Mimikyu Disguised",
+ "Totem Kommo-o": "Kommo O",
+ "Totem Araquanid": "Araquanid",
+ "Totem Togedemaru": "Togedemaru",
+ "Totem Ribombee": "Ribombee",
+ # Legends: Arceus nobles
+ "Lord Kleavor": "Kleavor",
+ "Lady Lilligant": "Lilligant (Hisui)",
+ "Lord Arcanine": "Arcanine (Hisui)",
+ "Lord Electrode": "Electrode (Hisui)",
+ "Lord Avalugg": "Avalugg (Hisui)",
+ "Origin Dialga / Palkia": "Dialga (Origin)",
+ "Arceus": "Arceus",
+ # Scarlet/Violet Titan pokemon
+ "Stony Cliff Titan": "Klawf",
+ "Open Sky Titan": "Bombirdier",
+ "Lurking Steel Titan": "Orthworm",
+ "Quaking Earth Titan": "Great Tusk",
+ "False Dragon Titan": "Dondozo",
+}
+
+# Multi-boss entries: use the first trainer's name
+MULTI_BOSS_PRIMARY: dict[str, str] = {
+ "Cilan / Chili / Cress": "Cilan",
+}
+
+
+def slugify(name: str) -> str:
+ slug = name.lower().replace(" ", "-")
+ return re.sub(r"[^a-z0-9-]", "", slug)
+
+
+def bulba_filename(boss_name: str, config: dict) -> str | None:
+ """Construct the Bulbapedia filename for a trainer boss."""
+ name = MULTI_BOSS_PRIMARY.get(boss_name, boss_name)
+ name = NAME_OVERRIDES.get(name, name)
+
+ # Replace spaces with underscores for Bulbapedia
+ bulba_name = name.replace(" ", "_")
+
+ if config["fmt"] == "spr":
+ return f"Spr_{config['code']}_{bulba_name}.png"
+ else:
+ suffix = config.get("suffix", "")
+ if suffix:
+ return f"VS{bulba_name}_{suffix}.png"
+ else:
+ return f"VS{bulba_name}.png"
+
+
+def resolve_image_urls(filenames: list[str]) -> dict[str, str | None]:
+ """Batch-resolve Bulbapedia filenames to direct download URLs via the MediaWiki API."""
+ result: dict[str, str | None] = {}
+ batch_size = 50
+
+ for i in range(0, len(filenames), batch_size):
+ batch = filenames[i : i + batch_size]
+ titles = "|".join(f"File:{fn}" for fn in batch)
+ url = f"{BULBA_API}?action=query&titles={urllib.request.quote(titles)}&prop=imageinfo&iiprop=url&format=json"
+
+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+ try:
+ with urllib.request.urlopen(req, timeout=30) as resp:
+ data = json.loads(resp.read())
+ except (urllib.error.URLError, OSError) as exc:
+ print(f" API error: {exc}")
+ for fn in batch:
+ result[fn] = None
+ continue
+
+ pages = data.get("query", {}).get("pages", {})
+ # Build title → url mapping
+ page_urls: dict[str, str] = {}
+ for page in pages.values():
+ info = page.get("imageinfo", [])
+ if info:
+ # Normalize title: "File:Spr BW Cilan.png" → "Spr_BW_Cilan.png"
+ title = page["title"].removeprefix("File:").replace(" ", "_")
+ page_urls[title] = info[0]["url"]
+
+ for fn in batch:
+ result[fn] = page_urls.get(fn)
+
+ if i + batch_size < len(filenames):
+ time.sleep(0.5) # be polite
+
+ return result
+
+
+def download_image(url: str, dest: Path) -> bool:
+ """Download an image file."""
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+ try:
+ with urllib.request.urlopen(req, timeout=30) as resp:
+ dest.write_bytes(resp.read())
+ return True
+ except (urllib.error.URLError, OSError) as exc:
+ print(f" FAILED to download {url}: {exc}")
+ return False
+
+
+def load_pokemon_sprites() -> dict[str, str]:
+ """Load pokemon name → sprite_url mapping from the pokemon seed data."""
+ pokemon_file = SEED_DIR / "pokemon.json"
+ if not pokemon_file.exists():
+ return {}
+ with open(pokemon_file) as f:
+ pokemon_list = json.load(f)
+ return {p["name"]: p.get("sprite_url", "") for p in pokemon_list if p.get("sprite_url")}
+
+
+def main():
+ pokemon_sprites = load_pokemon_sprites()
+ if not pokemon_sprites:
+ print("Warning: Could not load pokemon sprites for totem/noble mapping")
+
+ # Collect all filenames we need to resolve
+ all_filenames: list[str] = []
+ # Track: (game_slug, boss_index, bulba_filename, dest_path, is_pokemon)
+ tasks: list[tuple[str, int, str | None, Path, bool]] = []
+
+ boss_files = sorted(SEED_DIR.glob("*-bosses.json"))
+
+ for boss_file in boss_files:
+ game_slug = boss_file.name.removesuffix("-bosses.json")
+ config = GAME_SPRITE_CONFIG.get(game_slug)
+ if config is None:
+ print(f"Skipping {game_slug}: no sprite config defined")
+ continue
+
+ with open(boss_file) as f:
+ bosses = json.load(f)
+
+ sprite_subdir = SPRITE_DIR / game_slug
+ for idx, boss in enumerate(bosses):
+ boss_name = boss["name"]
+ boss_slug = slugify(boss_name)
+ dest = sprite_subdir / f"{boss_slug}.png"
+ local_path = f"/boss-sprites/{game_slug}/{boss_slug}.png"
+
+ # Check if sprite already exists on disk
+ if dest.exists():
+ # Ensure seed file has the path
+ if boss.get("sprite_url") != local_path:
+ boss["sprite_url"] = local_path
+ tasks.append((game_slug, idx, None, dest, False))
+ continue
+
+ # Check if this is a totem/noble pokemon boss
+ if boss_name in TOTEM_POKEMON:
+ pokemon_name = TOTEM_POKEMON[boss_name]
+ sprite = pokemon_sprites.get(pokemon_name)
+ if sprite:
+ boss["sprite_url"] = sprite
+ tasks.append((game_slug, idx, None, dest, True))
+ continue
+ else:
+ print(f" Warning: No pokemon sprite found for {boss_name} ({pokemon_name})")
+
+ # Construct Bulbapedia filename
+ fn = bulba_filename(boss_name, config)
+ if fn:
+ all_filenames.append(fn)
+ tasks.append((game_slug, idx, fn, dest, False))
+ else:
+ print(f" Could not construct filename for {boss_name}")
+ tasks.append((game_slug, idx, None, dest, False))
+
+ # Write back any sprite_url fixes
+ with open(boss_file, "w") as f:
+ json.dump(bosses, f, indent=2, ensure_ascii=False)
+ f.write("\n")
+
+ if not all_filenames:
+ print("No sprites to download!")
+ return
+
+ # Deduplicate filenames (some bosses appear across games with same Bulba file)
+ unique_filenames = list(dict.fromkeys(all_filenames))
+ print(f"\nResolving {len(unique_filenames)} unique Bulbapedia filenames...")
+ url_map = resolve_image_urls(unique_filenames)
+
+ resolved = sum(1 for v in url_map.values() if v)
+ print(f"Resolved {resolved}/{len(unique_filenames)} URLs")
+
+ # Report missing
+ missing = [fn for fn, url in url_map.items() if not url]
+ if missing:
+ print(f"\nCould not resolve {len(missing)} filenames:")
+ for fn in missing:
+ print(f" - {fn}")
+
+ # Download sprites and update seed files
+ downloaded = 0
+ skipped = 0
+ failed = 0
+
+ # Re-read seed files for updating
+ seed_data: dict[str, list] = {}
+ for boss_file in boss_files:
+ game_slug = boss_file.name.removesuffix("-bosses.json")
+ with open(boss_file) as f:
+ seed_data[game_slug] = json.load(f)
+
+ for game_slug, idx, bulba_fn, dest, is_pokemon in tasks:
+ if is_pokemon or dest.exists():
+ skipped += 1
+ continue
+
+ if bulba_fn is None:
+ continue
+
+ url = url_map.get(bulba_fn)
+ if not url:
+ failed += 1
+ continue
+
+ boss_slug = dest.stem
+ local_path = f"/boss-sprites/{game_slug}/{boss_slug}.png"
+
+ if download_image(url, dest):
+ seed_data[game_slug][idx]["sprite_url"] = local_path
+ downloaded += 1
+ print(f" {game_slug}/{boss_slug}.png")
+ else:
+ failed += 1
+
+ time.sleep(0.3) # rate limit
+
+ # Write updated seed files
+ for game_slug, bosses in seed_data.items():
+ boss_file = SEED_DIR / f"{game_slug}-bosses.json"
+ with open(boss_file, "w") as f:
+ json.dump(bosses, f, indent=2, ensure_ascii=False)
+ f.write("\n")
+
+ print(f"\nDone! Downloaded: {downloaded}, Skipped (existing): {skipped}, Failed: {failed}")
+
+ # Fallback attempts for failed sprites
+ if missing:
+ print("\n--- Attempting fallback filenames for missing sprites ---")
+ _attempt_fallbacks(missing, url_map, seed_data, tasks)
+
+
+def _attempt_fallbacks(
+ missing_filenames: list[str],
+ url_map: dict[str, str | None],
+ seed_data: dict[str, list],
+ tasks: list,
+):
+ """Try alternate Bulbapedia filename patterns for sprites that weren't found."""
+ fallback_filenames: list[str] = []
+ fallback_map: dict[str, str] = {} # fallback_fn → original_fn
+
+ for orig_fn in missing_filenames:
+ # Try VS ↔ Spr swaps
+ if orig_fn.startswith("Spr_"):
+ # Spr_CODE_Name.png → VSName.png
+ parts = orig_fn.removeprefix("Spr_").removesuffix(".png").split("_", 1)
+ if len(parts) == 2:
+ name = parts[1]
+ alt = f"VS{name}.png"
+ fallback_filenames.append(alt)
+ fallback_map[alt] = orig_fn
+ elif orig_fn.startswith("VS"):
+ # VSName.png → VSName_2.png (alternate appearance)
+ base = orig_fn.removesuffix(".png")
+ alt = f"{base}_2.png"
+ fallback_filenames.append(alt)
+ fallback_map[alt] = orig_fn
+
+ if not fallback_filenames:
+ return
+
+ print(f"Trying {len(fallback_filenames)} fallback filenames...")
+ fallback_urls = resolve_image_urls(fallback_filenames)
+
+ found = 0
+ for fb_fn, fb_url in fallback_urls.items():
+ if fb_url:
+ orig_fn = fallback_map[fb_fn]
+ url_map[orig_fn] = fb_url
+ found += 1
+
+ # Find and download for matching tasks
+ for game_slug, idx, bulba_fn, dest, is_pokemon in tasks:
+ if bulba_fn == orig_fn and not dest.exists():
+ boss_slug = dest.stem
+ local_path = f"/boss-sprites/{game_slug}/{boss_slug}.png"
+ if download_image(fb_url, dest):
+ seed_data[game_slug][idx]["sprite_url"] = local_path
+ print(f" {game_slug}/{boss_slug}.png (fallback: {fb_fn})")
+ time.sleep(0.3)
+
+ if found:
+ # Re-save seed files
+ for game_slug, bosses in seed_data.items():
+ boss_file = SEED_DIR / f"{game_slug}-bosses.json"
+ with open(boss_file, "w") as f:
+ json.dump(bosses, f, indent=2, ensure_ascii=False)
+ f.write("\n")
+
+ print(f"Fallback resolved: {found}/{len(fallback_filenames)}")
+
+
+if __name__ == "__main__":
+ main()