Retro Roster Patcher

Patch real-world sports rosters into retro game ROMs.

Retro sports games shipped with the rosters of their release year and no way to change them. This tool fetches a squad from a live sports API, maps each player onto the attribute scale the game actually stores, and writes the result into the binary team tables of a ROM you already own — so a 1994 cartridge lines up with a 2025 season.

Every provider is keyless: no credential to supply, and no flag or environment variable for one. WE2002 also gets its menus translated out of Japanese as part of the same run.

This project ships no game data. It patches a ROM or ISO you supply, and never redistributes one. The tests build synthetic images byte by byte rather than committing a real dump.

Zero runtime dependencies — the standard library only, so it drops into an embedded or sandboxed interpreter with no wheel to build. Usable as a library or as a CLI, and the CLI speaks newline-delimited JSON so another process can drive it. It was extracted from a pygame launcher for exactly that reason; a Flutter app over embedded CPython is the other consumer.

Install

pip install retro-roster-patcher

Quick start

retro-roster list
retro-roster analyze --rom nhl94.bin
retro-roster fetch --game nhl94-genesis --provider nhl --season 2025 --out rosters.json
retro-roster patch --game nhl94-genesis --rom nhl94.bin --out nhl94-2025.bin --rosters rosters.json

fetch and patch are separate verbs so you can inspect — or hand-edit — rosters.json before anything touches a ROM. patch --season N does both in one run instead.

Command line

Four verbs: list, analyze, fetch, patch. req below means the verb refuses to run without the flag, yes means it accepts it, - means it does not.

--json and --help are accepted on either side of the verb. analyze without --game probes every registered patcher and reports the ones that recognise the file. patch needs exactly one of --season and --rosters; both, or neither, is a usage error.

What each game requires

League ids are the provider's own. ESPN's soccer ids run from 2001 (Premier League) through 2016, in sports.espn.ESPN_LEAGUES. An id the chosen provider does not know is reported as ApiError: League N not found.

A slot map is a JSON array of {"slot_index", "team_id", "team_name"} objects, which is what SlotMapping.to_dict() produces:

import json
from pathlib import Path

from retro_roster_patcher import SlotMapping

mappings = [
    SlotMapping(slot_index=0, team_id=359, team_name="Arsenal"),
    SlotMapping(slot_index=1, team_id=364, team_name="Liverpool"),
]
Path("slot-map.json").write_text(json.dumps([m.to_dict() for m in mappings], indent=2))

Translations and user assets

--language is honoured by games that ship translations — we2002 takes en, es, fr and pt — and is a usage error on a game that does not, rather than a flag silently dropped.

--assets-dir is a directory the tool only ever reads. Its one use today is the community WE2002 menu translation w202-english.ppf, which this project does not redistribute: drop that file in and its menu records are merged into whichever language PPF --language selected. Without it the roster patch still applies and the menus stay Japanese.

Library

Everything the CLI does is a call on a Patcher. list_patchers() describes what is registered without instantiating anything:

from retro_roster_patcher import list_patchers

for info in list_patchers():
    print(info.game_id, info.platform, info.sport, info.providers)

get_patcher(game_id) returns the class; you construct it. The four methods are analyze_rom, fetch, map_rosters and patch, in that order — fetch and map_rosters are split from patch so a caller can preview, cache or edit between them without repeating the network step. The block below is not executed by the test suite: it needs a provider and a ROM.

from pathlib import Path

from retro_roster_patcher import RetroRosterError, get_patcher

patcher = get_patcher("nhl94-genesis")(
    cache_dir=Path("~/.cache/retro-roster-patcher").expanduser(),
    provider="nhl",
)
try:
    data = patcher.fetch(season=2025)
    rosters = patcher.map_rosters(data)
    result = patcher.patch(
        rom_path=Path("nhl94.bin"),
        output_path=Path("nhl94-2025.bin"),
        rosters=rosters,
    )
except RetroRosterError as exc:
    raise SystemExit(f"{type(exc).__name__}: {exc}") from exc

print(result.output_path, result.teams_patched, result.players_patched)

RetroRosterError heads the hierarchy, so one except catches everything this library reports, including the filesystem errors it converts at its boundaries. Catch a subclass when you want to react differently: RomError, ApiError, MappingError, CapabilityError, StorageError, MissingAssetError. Constructors take optional on_status and on_partial callbacks and fetch/patch take on_progress; the CLI wires those to the events below.

league_data_to_dict and league_data_from_dict are the round trip behind fetch --out / patch --rosters, so a consumer can hold rosters in its own store.

Root exports

from retro_roster_patcher import ...

• Errors: RetroRosterError, ApiError, CapabilityError, MappingError, MissingAssetError, RomError, StorageError
• Registry: Patcher, PatcherInfo, get_patcher, list_patchers, register
• Game-side models: MappedRosters, PatchResult, RomInfo, RomSlot, SlotMapping
• Sports models: League, LeagueData, Player, PlayerStats, Team, TeamRoster
• Serialisation: league_data_from_dict, league_data_to_dict
• Finding a ROM on disk: RomFinder, RomFinderConfig, RomFinderResult
• Also: Transport, __version__

from retro_roster_patcher.sports import ...

• Clients: EspnClient, NhlApiClient, Transport, team_colors
• Models: League, LeagueData, Player, PlayerStats, Team, TeamRoster

The --json protocol

With --json, stdout carries protocol and nothing else: one JSON object per line, flushed per line. Human logs and progress go to stderr. This is the surface the pygame launcher and the Flutter bridge code against.

Events

Every line has an event key.

{"event":"status","msg":"Fetching NHL teams..."}
{"event":"progress","pct":0.42,"msg":"Fetching Boston Bruins..."}
{"kind":"patch","output_path":"nhl94-2025.bin","teams_patched":26,"players_patched":598,"event":"result","ok":true}

Guarantees a consumer may rely on:

• Exactly one terminal line per run, result or error, and nothing after it.
• status, progress and partial appear zero or more times, only before the terminal line. list and analyze emit the terminal line alone.
• pct is clamped to [0.0, 1.0] and restarts at 0 for each phase, so it is not monotone across a whole patch --season run — that run fetches and then writes.
• result sets event and ok last, so a payload carrying keys of those names cannot overwrite the two a consumer parses on.
• fetch without --out emits the entire rosters payload as a partial before its result, because there is no file to point at.

Result payloads

The kind key says which payload a result carries.

Exit codes

A consumer that only reads the exit code still learns whether to look at stdout. Two edges are worth knowing. When argparse rejects the argv — an unknown verb, a missing required flag — it prints usage as plain text on stderr and exits 2 without writing any JSON, because no renderer has been chosen yet. And an untyped exception is a bug in this project rather than something you can act on: the error line is written and then the exception is re-raised unchanged, so a Python traceback follows on stderr and the exit status is CPython's.

How a player becomes a number

None of these games stores a rating anyone published. Every number below is this project's own arithmetic over a provider's season totals, and the three do it differently. Some attributes are measured; several are estimated from position and age, because no feed publishes them at all.

WE2002: ranked against the league, 1-9

Fifteen attributes per player. Ten are earned, five are always estimated.

The ten are grouped into categories — offensive, defensive, body balance, stamina, pass accuracy, shoot power, shoot accuracy, technique, dribble, aggression — each a small formula over PlayerStats fields (offensive is goals + 0.7 x assists + 0.3 x shots on target, and so on). Every player in the whole fetched league is pooled, the formula is evaluated for each, and a player's percentile is the share of the pool scoring strictly below him. That percentile becomes the rating: 95th and up is a 9, then 85 → 8, 70 → 7, 50 → 6, 35 → 5, 20 → 4, 10 → 3, 3 → 2, and the rest a 1. Position adjustments follow (a midfielder gains a point of passing, a goalkeeper is capped at 3 for shooting accuracy), then everything is clamped back into 1-9.

So a 9 means top 5% of the league you fetched, not top 5% of the world. Patch the Premier League and the Chilean Primera División from the same tool and the two ROMs are not on a common scale.

The five that are never measured — speed, acceleration, jump power, heading and curve — come from a position base nudged by age. A 24-year-old attacker is quick because attackers are quick and he is young, not because anyone timed him.

unsupplied, and why zero is not an answer. Every count on PlayerStats is declared int or float and is never None, so a consumer can do arithmetic without a guard. That leaves a provider which does not measure duels nowhere to say so except by writing 0 — and a zero reads as a measurement, ranking the player below everyone who was measured and padding the denominator for everyone who was. PlayerStats.unsupplied names the fields carrying filler rather than data. A player whose provider did not measure a category's inputs is dropped from that category's ranking entirely, and his rating comes from a position-and-age estimator instead of a percentile he was never in. ESPN, the only soccer provider here, reports no duels and no dribbles, which is why body balance, technique and dribble have estimators and the other seven categories do not.

A player with no stats at all, or with zero appearances, skips the percentiles and takes a position default adjusted for age: under 23 gains pace and stamina and loses technique; from 31 it goes the other way.

NHL94: measured against a fixed yardstick, 0-6

Twelve attributes on a 0-6 scale, and no league ranking anywhere. Each stat is scaled linearly inside a fixed window, so a 40-goal season is a 6 no matter what the rest of the league did:

A skater's speed, agility, checking and endurance are position defaults, with a single point of speed and agility added past 50 points; a goalie's are fixed constants, and only the two rows above are read off his stat line. Weight class is (pounds - 140) // 8, clamped to 0-14. A player the provider has no stats for gets the position defaults untouched.

NBA Live 95: scaled inside fixed windows, 25-99

Sixteen attributes. The scale the ROM stores is 0-99, but the mapper clamps to a floor of 25, so nothing this tool writes is ever rated below 25. Every input is a per-game average from ESPN's team-leaders endpoint, scaled linearly inside a window and clamped:

The two attributes missing from that table, dunking and speed, are position constants with one bonus each: dunking starts at 35 for a point guard through 60 for a power forward and gains 10 above .520 shooting, and speed starts at 35 for a centre through 75 for a point guard and gains 8 above 1.2 steals a game. A player the provider has no stats for gets a whole row of position defaults and none of the windows above.

Height is always a position default — 6'2" at point guard through 6'11" at centre — because ESPN's roster response carries no height. Weight is ESPN's when it reports one. Experience is age minus 21, floored at zero. The roster is the top 12 by minutes played, two per position and then the best remaining.

Two fields are written but never derived, and both are inherited from the code this port came from. season_stats is 17 zeros for every patched player, which erases the 1994 season line the cartridge shipped with — ESPN's leaders endpoint publishes averages, not the games, minutes, makes and attempts those fields hold, so there is nothing honest to put there. Skin tone and hair style are written as 0 for everyone, so every patched player looks the same.

In short: WE2002 grades on a curve, NHL94 and NBA Live 95 against absolute yardsticks, and in all three the physical attributes are priors rather than measurements.

Limits

• Past seasons are not historical squads, except on the nhl provider. ESPN's roster endpoints take no season parameter at all; they serve the current squad. --season 2003 against ESPN therefore returns today's players labelled 2003, and reports success. For nhl94-genesis, --provider nhl is the real answer: the NHL API serves squads back to 1993. For we2002 and nbalive95-genesis there is no second provider, so a past season is a present squad with a past label. (Per-player soccer statistics are fetched per season and are genuinely that season's, as are NBA team leaders; only the squad list is current.)
• Four patchers, three sports. A fifth is a Patcher subclass and a @register line; see below.
• No ROMs, no ISOs, no dumps. You supply the image.
• The community WE2002 English menu PPF is not redistributed. See --assets-dir.

Adding a game

A patcher is a Patcher subclass decorated with @register. Its package is imported from retro_roster_patcher/__init__.py, at the bottom of the import block, so the decorator has run by the time anyone calls get_patcher. The registry is an in-tree dict, not entry points: every game here is first-party.

from retro_roster_patcher.core.patcher import Patcher
from retro_roster_patcher.core.registry import register


@register("mygame", platform="snes", sport="basketball", providers=("espn",))
class MyGamePatcher(Patcher):
    def analyze_rom(self, rom_path): ...
    def fetch(self, *, season, league_id=None, on_progress=None): ...
    def map_rosters(self, data, slot_mapping=None): ...
    def patch(self, *, rom_path, output_path, rosters, on_progress=None, **options): ...

register's keyword arguments become the capability record list reports and the CLI enforces. Set requires_slot_mapping=True if the ROM's team slots cannot be matched automatically; Patcher.check_slot_mapping then rejects both a missing mapping and an unwanted one.

Development

pip install -e ".[dev]"
pytest
ruff check . && ruff format --check .
mypy src tests

That test run reports 5 deselected: tests/test_packaging.py asserts the import came from an installed distribution, so it fails against the source tree by design. Running that file on its own selects nothing and exits 5. CI's wheel job selects it with -m packaging after installing a built wheel.

tests/test_readme.py pins this file against the code: the flag table against the argument parser, the exported names against __all__, the event and payload tables against the renderer and the command handlers, the games table against the registry, and every Python example against the interpreter. A claim here that stops being true fails the build.