Skip to content

Beta 4 — Windows installers (no command prompt needed)

Pre-release
Pre-release

Choose a tag to compare

View all tags
@cruuz cruuz released this 25 Jul 22:37
beta-4
7f9700e

Beta 4 — Windows installers

Release: Beta 4 · Date: 2026-07-25 · Supersedes: Beta 3

Tools included

  • 2K5 Mod Studio — ESPN NFL 2K5 (original Xbox) — v1.0-RC29
  • APF 2K8 Mod Studio — All-Pro Football 2K8 (Xbox 360) — v0.1.0-alpha.34

Runs on Windows, macOS and Linux, verified on every push by CI across all
three, on Python 3.11 and 3.12.

🪟 Windows users: just download the Setup .exe

You no longer need Python, pip, 7-Zip, or a command prompt. Download the
installer for the editor you want, double-click, click through the wizard.
That's it. Everything is included, it installs to your own user folder, and it
never asks for administrator rights.

⚠️ Windows will warn you. That is expected. Here is what to click.

These installers are not code-signed — a certificate costs a few hundred
dollars a year and this is a free hobby project — so Windows shows this:

Windows protected your PC
Microsoft Defender SmartScreen prevented an unrecognised app from starting.

The only button you can see is Don't run. The one you want is hidden:

  1. Click the small More info link in the box.
  2. A Run anyway button appears.
  3. Click Run anyway.

That warning means "Windows has not seen this program before". It does not
mean Windows found anything harmful. You may see it twice: once for the
installer, once the first time the editor starts.

You do not have to take our word for it. Check the file you downloaded
against the SHA-256 in the table below — in PowerShell:

Get-FileHash -Algorithm SHA256 .\2K5-Mod-Studio-1.0-RC29-Setup.exe

If it matches, the file is exactly what was published. If it does not, delete
it. The installers rebuild byte-for-byte from source, so that hash is
reproducible rather than just asserted.

The wizard repeats all of this on its second page, before it writes anything.

Prefer the archive, or not on Windows? The .tar.gz releases are unchanged
and documented below. They are byte-identical to Beta 3.

Install — read the section for your system

The .tar.gz archives are pure Python and need Python 3.11+, PyQt5 and
Pillow. The Windows Setup.exe needs none of that — it brings its own.
Neither editor ships game data, and neither will ever write to your original disc
or disc image.

Windows

The easy way — the installer. Download the Setup.exe for the editor you
want, double-click it, and follow the wizard. Nothing else to install. See the
box at the top for the SmartScreen warning and the two clicks past it.

What it does: installs into %LOCALAPPDATA%\Programs\, adds Start Menu and
desktop shortcuts, and registers a normal entry in Apps & features so it
uninstalls like anything else. It never needs administrator rights and never
touches Program Files or your system Python — the interpreter it uses lives
inside its own folder and is removed with it.

The manual way — the archive. If you already have Python and would rather
not run an installer:

  1. Install Python 3.12 and tick
    "Add python.exe to PATH" in the installer.
  2. Install the two dependencies: 
    py -m pip install --upgrade PyQt5 Pillow
  3. Download the archive for the editor you want (below), and extract it. Windows
    Explorer does not open .tar.gz directly — use
    7-Zip or, on Windows 10 1803+, the built-in tar: 
    tar -xzf 2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz
  4. Start it from that folder: 
    cd 2K5-Mod-Studio-v1.0-RC29
py -m mod_editor --studio
    or, for APF: 
    cd apf2k8-mod-studio-0.1.0-alpha.34
py -m mod_editor.apf_studio

Point either editor at your .iso/XISO or at an already-extracted game folder —
both work. The APF archive bundles extract-xiso.exe (PE32+ x86-64), built from
the same vendored 2.7.1 source as the Linux binary, so ISO input needs nothing
extra from you.

The .sh launchers and the .desktop files in these archives are Linux desktop
integration; on Windows ignore them and use the py -m ... commands above.

macOS

  1. Install Python 3.12 — python.org
    or brew install python@3.12.
  2. Install the dependencies: 
    python3 -m pip install --upgrade PyQt5 Pillow
    On Apple Silicon, if pip cannot find a PyQt5 wheel, brew install pyqt@5
    works and exposes it to the Homebrew Python.
  3. Extract and start it (Finder opens .tar.gz on double-click): 
    tar -xzf 2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz
cd 2K5-Mod-Studio-v1.0-RC29
python3 -m mod_editor --studio
    or, for APF: 
    cd apf2k8-mod-studio-0.1.0-alpha.34
python3 -m mod_editor.apf_studio

macOS is the one platform with no bundled extractor. Bundling one would mean
vendoring a third architecture that cannot be built or tested from the build
host, so rather than ship something unverified: point APF at an
already-extracted game folder, or build extract-xiso yourself
(brew install extract-xiso, or cmake on the vendored source — see
tools/vendor/extract-xiso/BUILDING-THE-BUNDLED-BINARIES.md) and pass it as
SourceManager(extract_xiso=...). 2K5 Mod Studio is unaffected: it reads the
.xiso.iso directly and needs no extractor at all.

These archives are unsigned and not notarised, so Gatekeeper will complain if you
try to run anything from them by double-clicking. Launching through python3 from
Terminal, as above, is the supported path and avoids that entirely.

Linux

The original and most exercised target — the desktop app has been smoke-tested
end to end here.

  1. Debian / Ubuntu / Linux Mint: 
    sudo apt install python3 python3-pyqt5 python3-pil
  2. Extract and start it: 
    tar -xzf 2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz
cd 2K5-Mod-Studio-v1.0-RC29
./tools/launch_2k5_mod_studio.sh
    or, for APF: 
    cd apf2k8-mod-studio-0.1.0-alpha.34
./tools/launch_apf2k8_mod_studio.sh
    The launchers check your Python/PyQt5/Pillow and show a desktop error dialog
    rather than a terminal trace if something is missing. python3 -m mod_editor --studio and python3 -m mod_editor.apf_studio work too.

For a menu entry, install packaging/*.desktop and packaging/*.svg as
described in packaging/README.md.

New in Beta 4

Windows installers, so nobody has to open a command prompt to use these
tools. A user asked whether he was going to have to paste commands; today the
honest answer was yes, four times over. Now it is a wizard.

Each installer carries a private CPython beside the application rather than
being a frozen bundle. That is not a stylistic choice: these editors verify their
own integrity at runtime by reading each pinned module from disk and hashing it,
and a frozen build has neither real .py files nor a usable __file__. Freezing
would have quietly deleted the guarantee that makes the tool safe to point at a
game, so the application ships byte-identical to the archive and simply gains an
interpreter next to it.

The second wizard page is a plain-English warning about the SmartScreen prompt,
shown before anything is written and with Next disabled until it is
acknowledged — what the box says, which button is the one you actually need,
and how to verify the download yourself instead of trusting us.

Built and exercised end to end under wine before publishing: silent install,
the shortcut's exact command running without exiting, and a clean uninstall.

New in Beta 3

Documentation, licensing and packaging only — see the box at the top for why.

  • LICENSE and NOTICE.md now ship inside both archives. MIT requires its
    own text to travel with every copy; neither archive had one.
  • NOTICE.md carries the game-IP scope (what the MIT grant does not cover),
    the retail-free statement, third-party attribution for the bundled
    extract-xiso, and the trademark notice. LICENSE is now the MIT text alone,
    so licence scanners identify the project correctly. No terms changed.
  • The extractor build receipt ships in the APF archive rather than only being
    referenced from these notes.
  • The release pipeline is in the repository — packaging/stage_release.py,
    packaging/build_archive.py, packaging/repin.py — so anyone can rebuild
    these bytes and compare.
  • Contributing is now documented: CONTRIBUTING.md, SECURITY.md,
    CODE_OF_CONDUCT.md, issue forms and a PR template. If you want to add a
    capability, CONTRIBUTING.md explains the classification ladder and why a
    writer ships with an independent verifier.

What was new in Beta 2

Cross-platform support

Windows and macOS are now first-class. Every OS difference is concentrated in one
shim (mod_editor/core/platform_compat.py) so the editors behave the same way on
each, and where a platform genuinely cannot provide a guarantee the tools say
so rather than pretending. Concretely, that meant real fixes rather than
if windows: skip:

  • Positional file I/O, directory transactions, atomic no-clobber publication,
    private-cache privacy, ownership, and durable flushes all have real Windows and
    macOS implementations.
  • Windows file locking, which refuses to rename a file that has an open handle,
    is handled by opening staged files with FILE_SHARE_DELETE — so the writer
    keeps the descriptor it verified through, instead of dropping the proof to
    satisfy the OS.
  • Binary-mode reads, CRLF translation and 8.3 short names no longer corrupt
    byte-exact artifacts.
  • The APF archive bundles extract-xiso for both Linux and Windows, built
    from the same vendored 2.7.1 source and each pinned by exact size and SHA-256
    in the release gate.

APF 2K8 — new editable capabilities

  • Team logos on helmets and the score bug.
  • Field art / endzones.
  • Both proven bit-exact by an independent verifier, taking the capability
    registry to 65.

Release integrity

Each editor ships as a deterministic, byte-for-byte reproducible archive with an
adjacent SHA-256 sidecar. Rebuilding from the same staged tree reproduces the same
bytes — verified for this release, not merely asserted.

The scripts that produce these assets are in the repository rather than being
described only in prose: packaging/stage_release.py copies exactly the
allowlisted paths, and packaging/build_archive.py writes the tarball with
mtimes, ownership, modes and the gzip header all pinned. So the reproducibility
claim is something you can run rather than take on trust:

git checkout beta-4
python3 packaging/stage_release.py packaging/release-allowlist.txt stage/2k5
python3 packaging/build_archive.py stage/2k5 2K5-Mod-Studio-v1.0-RC29 \
    out.tar.gz $(date -u -d 2026-07-25 +%s)

The beta-4 tag points at exactly the commit these bytes were built from. (Two
of the archive's inputs — the vendored extractor binaries and the reviewed
reports/assets catalogs — are deliberately gitignored, so a clean clone
reproduces every source file but not those; that is why the release-gate CI job
skips loudly rather than pretending.)
STATUS.md
records these identities plus every superseded upload, so an older download can
still be identified instead of left ambiguous.

The installers are reproducible too, by a different route worth stating. The
archives are deterministic because every input lives in this repository. The
installers additionally fetch an interpreter and four wheels from the network, so
each of those five artifacts is pinned to an exact SHA-256 and checked before
use. A hash mismatch, an unpinned wheel the resolver decided to add, or a pinned
wheel that fails to arrive all stop the build rather than shipping something
unreviewed — the refusal path was tested by feeding the build a wrong hash and
confirming it halts. With those pinned, the installer output is itself
deterministic: both were built twice and compared byte for byte.

python3 packaging/windows/build_windows_installer.py \
    --stage stage/2k5 --product 2k5 --version 1.0-RC29 --out dist
makensis dist/work/installer.nsi
Asset SHA-256
2K5-Mod-Studio-1.0-RC29-Setup.exe c52464be5a0dc9660d704a7148fd9aad7d7c7c35bfb8d0e64716f6eed4c2fa80
APF-2K8-Mod-Studio-0.1.0-alpha.34-Setup.exe 9b920484f348aab416bd15ccaf583382839ce91c03e7464b7bc5caa67a4efdf3
2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz 3966d12eeeb73a8f0acd2bb68fca7fda2a683c1865b1d18a58b1dda80f1a251b
apf2k8-mod-studio-0.1.0-alpha.34-20260725.tar.gz feb49eefa5233d4c0459dc8f1783bb1aa3bbe93608c61c34a0191da1585b544d

Both .tar.gz archives are byte-identical to their Beta 3 uploads — no editor
code changed.

Verify before extracting:

sha256sum -c 2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz.sha256      # Linux / macOS
certutil -hashfile 2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz SHA256  # Windows

Both archives pass an automated retail-free gate (no game bytes, decoded
pixels or audio, private paths, symlinks or undeclared files) and a
runtime-closure check (every shipped module imports from the clean stage).
Both gates were run again against the extracted archives, not only the staging
tree, so what you download is what was checked.

The two bundled extract-xiso binaries are pinned by exact size and SHA-256, and
each must still be the image format its platform can run (ELF / PE). .exe
remains a forbidden file type everywhere else in the release — the extractor is
one named, reviewed exception, not a relaxed category. The Windows build is
reproducible (-Wl,--no-insert-timestamp), and the exact build commands,
toolchain and hashes are recorded in
tools/vendor/extract-xiso/BUILDING-THE-BUNDLED-BINARIES.md so you can rebuild
the bytes yourself rather than trust them.

Verification

  • CI: all six jobs — Windows, macOS and Linux × Python 3.11 and 3.12 — report
    an identical 107 of 126 files, 1304 tests. The 19 that do not pass need
    retail game data, which never touches CI, so they fail the same way on every OS.
  • Independent security review: the Windows/macOS port was audited by a
    different model (GPT-5.6) across ten passes. It rejected the port nine times.
    The first round found four genuine blockers, including a pinned directory handle
    opened without the access right needed to answer its own ownership query, and a
    DACL check blind to WRITE_DAC. Later rounds found documentation that claimed
    more than the code enforced. The final verdict is ACCEPT, with every remaining
    platform limitation disclosed in the code where a caller meets it.

Known limits

  • 19 test files need retail game data and cannot run in CI on any OS. They are
    exercised locally against real discs.
  • macOS has no bundled extract-xiso. See the macOS section above.
  • APF: XMA1 audio encoding still needs a user-supplied encoder, on every
    platform.
  • The audio panel needs a wider minimum window on Windows, because the default
    UI font there is considerably wider. Cosmetic; no effect on any guarantee.
  • Three privacy tests are skipped on Windows. They express "unsafe" by
    chmod-ing something world-readable, and Windows mode bits confer no privacy at
    all — a directory always reports 0o777. Privacy there is the DACL, which is
    covered by other checks. Each skip states this rather than quietly passing.
  • The GUI has not been manually driven on Windows or macOS. The suite passes
    identically on all three, but treat the window itself as less exercised there.
  • Both editors remain beta / alpha. Always keep a backup of your original disc
    image; the tools only ever write to a copy, but back it up anyway.

These tools ship no game data and require your own legally obtained disc.

Assets 10
Loading