Release list

Beta 3 — Cross-platform, licence included Pre-release

Pre-release

cruuz released this 25 Jul 19:59

beta-3

d6789ac

Beta 3 — Cross-platform

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

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

Beta 1 was Linux-only. Beta 2 and Beta 3 run on Windows, macOS and Linux,
verified on every push by CI across all three, on Python 3.11 and 3.12.

If you are here from Beta 2, read this

No editor code changed between Beta 2 and Beta 3. Both products still
identify as v1.0-RC29 and 0.1.0-alpha.34, because nothing in them was
altered. This release exists to fix the paperwork, which was wrong in a way
worth correcting properly rather than quietly:

The APF2K8-README.md inside the Beta 2 APF archive contradicted the
archive it shipped in. It told Windows users the ISO path would not work,
and reported the test suite as not yet passing on Windows or macOS. Neither
had been true for some time — the bundled extract-xiso.exe was sitting in
that same tarball, and all six CI jobs were already reporting identical
results. This project's whole promise is that it never claims more than it
can prove; shipping a document that claimed less than the truth is the same
defect pointed the other way, and it got treated as one.

Neither archive contained a licence. MIT requires its own text to travel
with every copy of the software, so the archives were out of compliance with
their own licence. LICENSE and NOTICE.md now ship inside both.

The Beta 2 APF asset was replaced twice under a single filename, which
made "which bytes do I have?" genuinely ambiguous. The Beta 3 APF asset
carries a date in its name, the way the 2K5 one always has, so that cannot
happen again. Every superseded upload is recorded with its size and SHA-256
in STATUS.md.

Beta 2 is superseded — use this release. If you already downloaded from
Beta 2, the editors you have are fine; you are only missing corrected docs and
the licence.

Install — read the section for your system

Both editors are pure Python. You need Python 3.11+, PyQt5 and Pillow.
Neither editor ships game data, and neither will ever write to your original disc
or disc image.

Windows

Install Python 3.12 and tick
"Add python.exe to PATH" in the installer.

Install the two dependencies:

py -m pip install --upgrade PyQt5 Pillow

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
```

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

Install Python 3.12 — python.org
or brew install python@3.12.
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.

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.

Debian / Ubuntu / Linux Mint:

sudo apt install python3 python3-pyqt5 python3-pil

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 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-3
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-3 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.

Editor	Archive	SHA-256
2K5 Mod Studio `v1.0-RC29`	`2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz`	`3966d12eeeb73a8f0acd2bb68fca7fda2a683c1865b1d18a58b1dda80f1a251b`
APF 2K8 Mod Studio `v0.1.0-alpha.34`	`apf2k8-mod-studio-0.1.0-alpha.34-20260725.tar.gz`	`feb49eefa5233d4c0459dc8f1783bb1aa3bbe93608c61c34a0191da1585b544d`

Verify b...

Assets 6

Beta 2 — Cross-platform (Windows, macOS, Linux) Pre-release

Pre-release

cruuz released this 25 Jul 15:30

beta-2

d5a012f

⚠️ Superseded by Beta 3

Beta 3 is the release to download. No editor code changed between the two —
Beta 3 corrects documentation that shipped inside the Beta 2 APF archive and
was wrong, and adds the LICENSE and NOTICE.md that neither Beta 2 archive
contained. The Beta 2 APF asset was also replaced twice under one filename;
Beta 3's is dated so that cannot recur.

If you are already running Beta 2, your editors work — you are only missing
corrected docs and the licence text.

Beta 2 — Cross-platform

Release: Beta 2 · Date: 2026-07-25

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

Beta 1 was Linux-only. Beta 2 runs on Windows, macOS and Linux, verified on
every push by CI across all three, on Python 3.11 and 3.12.

Updated twice on 2026-07-25, both times the APF archive only. The 2K5
archive is byte-identical to the original upload and its SHA-256 below has
never changed.

The APF archive was re-issued to bundle a Windows build of
extract-xiso, so handing the editor a .iso now works on Windows out of
the box — the first upload required an already-extracted game folder there.

It was re-issued once more because the APF2K8-README.md inside that
archive still said the opposite: that the ISO path would not work on
Windows, and that the test suite did not yet pass on Windows or macOS.
Neither was true any more. That file now matches what actually ships, and
the build receipt for both bundled binaries
(tools/vendor/extract-xiso/BUILDING-THE-BUNDLED-BINARIES.md) is bundled
alongside them instead of only being referenced from here.

If you downloaded the APF archive before 2026-07-25 19:10 UTC, re-download
it (the current bytes were uploaded at 19:08 UTC). Its current hash is f047682430… — the full value is in the integrity
table below, and the .sha256 sidecar next to the asset is authoritative.
Nothing in the editor itself changed between the second and third uploads;
only documentation and that bundled receipt.

Install — read the section for your system

Both editors are pure Python. You need Python 3.11+, PyQt5 and Pillow.
Neither editor ships game data, and neither will ever write to your original disc
or disc image.

Windows

Install Python 3.12 and tick
"Add python.exe to PATH" in the installer.

Install the two dependencies:

py -m pip install --upgrade PyQt5 Pillow

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
```

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

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

Install Python 3.12 — python.org
or brew install python@3.12.
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.

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

Linux

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

Debian / Ubuntu / Linux Mint:

sudo apt install python3 python3-pyqt5 python3-pil

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.

What is new since Beta 1

Cross-platform support

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

The two scripts that produce these assets are now 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. Staging from the
allowlist and rebuilding at epoch 2026-07-25T00:00:00Z reproduces the hashes
below, so the reproducibility claim is something you can run rather than take on
trust. Build from commit 071e7a0, not from the beta-2 tag: the tag still
points at d5a012f, one commit earlier, and the APF archive's documents changed
between the two — so a rebuild from the tag will not match the published APF
hash. The 2K5 archive is identical from either commit. STATUS.md records the same identities, including the two superseded APF
uploads, so an early download can be identified instead of left ambiguous.

Editor	Archive	SHA-256
2K5 Mod Studio `v1.0-RC29`	`2K5-Mod-Studio-v1.0-RC29-20260725.tar.gz`	`4c293e609ce15df55a2b7dd870ad13eefe419e9db2a88ae8bb4b82e01c2230e4`
APF 2K8 Mod Studio `v0.1.0-alpha.34`	`apf2k8-mod-studio-0.1.0-alpha.34.tar.gz`	`f047682430f4cc5be868b586b875fbf602c62799130cbd5623b128a6219676f1`

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...

Assets 6

Beta 1 — 2K5 Mod Studio + APF 2K8 Mod Studio Pre-release

Pre-release

cruuz released this 23 Jul 01:25

beta-1

aa4b92e

Beta Release Notes

Release: Beta 1
Date: 2026-07-22
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

This is the first public beta of both editors. They are functional, retail-free,
and Linux-first. Read the README for install/usage and the
license for terms.

What's in this beta

2K5 Mod Studio (v1.0-RC29)

Unified visual mod project: uniforms/Complete Team Kit, portraits, live faces,
create-team field art, scorebug/presentation art, Team Select cards.
Stadium Studio: 477 scenes, 23,838 editable P8 textures, with a
"People & sideline only" filter (fans, cheerleaders, coaches, officials,
chain crew, camera/media, ushers, sideline props).
Audio: all 850 standalone cues + all 53,571 playable streaming ranges
(exact-slot), with cue labels/notes.
Rosters: primary players (names + jersey), historical teams, and
secondary-pool jersey numbers.
Text: 20,074 editable strings across 716 banks.
Project save/load, autosave/crash recovery, build-to-new-XISO, xemu launch.

APF 2K8 Mod Studio (v0.1.0-alpha.34)

Uniforms: 96 editable textures (jersey/pants/helmet/shoulder) + digital_font
- draft_logo.
Rosters & Players: team names, player names, all 28 ratings, exact Position,
53-row roster planner.
Audio: all 47,775 editable AUDO/AUSB cues (exact-slot XMA1 via a user-supplied
encoder), cue labels/notes, batch folder/ZIP authoring.
Field Art inventory, Stadium Studio, presentation inspectors.

Release integrity

Each editor is shipped as a deterministic, byte-for-byte reproducible archive
with an adjacent SHA-256 sidecar:

Editor	Archive	SHA-256
2K5 Mod Studio v1.0-RC29	`2K5-Mod-Studio-v1.0-RC29-20260720.tar.gz`	`c1000937cdc47861ce6e1a23c4696c052a0c7bc3cebb1c0279ed9cc1efcdd99d`
APF 2K8 Mod Studio v0.1.0-alpha.34	`apf2k8-mod-studio-0.1.0-alpha.34-linux-x86_64.tar.gz`	`beb8b1409b83e052e6c432a9ddc4a79f9f990820c79e0b67dea894dc869393f4`

Verify with sha256sum -c <archive>.sha256 (must say OK).

Every archive passes an automated retail-free gate (no game bytes, decoded
pixels/audio, private paths, symlinks, or undeclared files) and a
runtime-closure check (every shipped module imports from the clean stage).

Known limits (beta)

Offline-proved vs runtime-proved. Most writers are offline-proved
(copied-image byte-diff verified). A smaller set is also runtime-proved in an
emulator. The capability registry labels each writer
(PROVED / READ ONLY / PORTME).
Emulator-only executable patches. Features that patch the game executable
invalidate the retail signature and run only on the named emulators (xemu /
Xenia), never original hardware.
Not done yet (tracked in
docs/product/NFL2K5_COMPLETION_STATUS_AND_WALLS.md):
3D model import (Crib/stadium geometry), whole streaming-bank audio repack and
per-cue loop/gain/pan/mixer editing, playbook route drawing/import, franchise
rookie-draft AI variety, save editing, and uniform pixel→body-region UV
decoding.
Windows / macOS are untested (the code is cross-platform Python + PyQt5,
but only Linux launchers/installers are provided).

How to run a mod

Install (extract the archive; ./install.sh or run the launcher).
Load your own clean game ISO (or extracted folder).
Browse → Replace editable assets with your own files.
Save a project, then Build to a new empty folder.
Run the built default.xbe (xemu) or default.xex (Xenia).

See the getting-started guides in docs/mod_editor/ for the
full walkthrough and the exact, evidence-backed boundary of each feature.

Beta disclaimer

Provided "as is", without warranty. Work-in-progress software for enthusiasts
modding games they legally own. Keep backups of your original game files.

Assets 6

Releases: cruuz/2k-football-mod-tools

Release list