WIP: feat(builder): accept .nx archives (NXFormat) as the game files #685

Draft

nussico wants to merge 1 commit from nussico/Longshot:builder/nx-format into main

pull from: nussico/Longshot:builder/nx-format

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 1 Commits 1 Files changed 11 +674 -20

nussico commented 2026-11-15 04:24:51 +00:00

First-time contributor

• Copy link
• Copy Markdown

Type: feat · Risk: low · Tested on: Windows 11, RTX 2070 · Needs: Linux, any GPU

Why

Players who keep their game as a .nx file (NXFormat, github.com/fab918/nxformat, made with nxconvert pack-nup) have to convert it back to a .nup or to folders before Longshot can build. With this PR the builder takes the .nx directly.

What changed

make_game.py now reads a .nx archive wherever it reads a .nup: it tells the two apart by the file's first bytes and runs a new reader for the .nx. The reader reuses nup.py's extraction, so path checks, progress and the damaged-.zs list behave the same, and every file is checked against its SHA-256 in the archive.

• nx2: nx2/nxar.py (class Nx and a CLI like nup.py's) reads NX 0.2 and 0.3 archives holding exefs/romfs trees. A .nx holding NCA files (nxconvert pack) is refused with a message saying how to convert it. nx2/test_nxar.py builds archives from the spec, game-free.
• nx2: nx2/nup.py: the step after extraction (plain NSOs, ZBIC) moved into plain_modules(), which nxar.py calls too. The .nup path is unchanged.
• make_game: package_script() in nx2/make_game.py picks nx2/nxar.py or nx2/nup.py by the NXAR magic, in check() and in main()'s extraction; --nup and --game help mention .nx. Test: tests/test_make_game_package_script.py.
• game files: .gitignore ignores *.nx and scripts/release.py's NOT_A_RELEASE_FILE refuses .nx (a .nx is a whole dump); CONTRIBUTING lists it with the game files.
• docs: README (game copy section and command line), website/src/content/docs/requirements.mdx (its copy) and docs/development.md.

The launcher's side (finding, browsing and dropping .nx files) is a separate PR on LongshotLauncher, and needs a Longshot release with this change.

Measurements

Nothing to measure in the game: this changes only how the builder reads the game file; the build it makes and the game are unchanged (see Testing for the extraction check and its speed).

Flags and settings

None

Testing

Tested: On Windows 11 build 26300 (llvm-mingw 20260616), with my own copy, the same code in Hookshot's tree (this PR is that change with Longshot's names). The game files never left my PC.

• The .nx and the .nup of the same game hold the same 186,592 files by path, size and SHA-256, with byte-identical exefs and build id e0f3ccfa.
• Every file of the .nx decoded and SHA-256-checked: 26.27 GB in 158 s from disk (166 MB/s).
• make_game.py --check --nup <file.nx>: "This is the version ... supports (build e0f3ccfa)."
• A build from the .nx extracted all 186,592 files, made main a plain NSO and translated 100% of the code. The game it built starts and plays (NVIDIA GeForce RTX 2070, driver 32.0.16.2101).
• In this tree: nx2/test_nxar.py and tests/test_make_game_package_script.py pass. python -I -B tests/run_all.py: 504 passed, 19 failed, 72 skipped; the same 19 fail on main @ 53f96d7 on this PC: test_appimage_player_build, test_cpm_discovery, test_cpp_preflight, test_crash_dialog, test_cv_signal_race, test_env_on, test_fpx_sticky, test_lift_cleanup_error, test_linux_preflight, test_make_game_cache, test_make_game_prepare, test_missing_nup, test_oot_state_tap, test_readback_late, test_spawn_emit, test_tested_configurations, test_vk_pgo, test_vram_budget_row, test_walk_key.

Not tested: A build from this Longshot branch in the game (only Hookshot's tree with the same change); Linux (I have no Linux PC).

Must be tested:

• Linux, any GPU: run python -I nx2/make_game.py --check --nup <your .nx> and then a build with --nup <your .nx> (a .nx made from your .nup with nxconvert pack-nup), expecting the check to report build e0f3ccfa and the game to start (by hand: a tester with a .nx, since the farm's copies are .nup).

Risks

What could break: Only a file starting with NXAR goes to the new reader; every .nup still goes to nup.py, whose extraction is unchanged except that its last step moved into a function.

Turning it off: revert the commit.

Compatibility: Nothing changes for a player who builds from a .nup or folders: no saves, options, caches or vk ABI touched.

Issues

Fixes #411

Checklist

Everyone

• One topic.
• The title is a Conventional Commit (type(scope): description) of the status line's type.
• Why gives the reason plainly and links the issues that fit (the tracker searched).
• Measurements has a verdict, or one line saying why there is nothing to measure.
• Testing names what was tested, what wasn't, and what must still be tested, where and how.
• Rebased on current main.
• python -I -B tests/run_all.py passes (any failure that also fails on main is named).
• No game files, dumps, build output or generated files.
• third_party/ untouched (a new folder with a PROVENANCE.md instead).
• The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

• A check under tests/ that reads changed source updated in this PR, not weakened.
• Docs updated.

**Type:** feat · **Risk:** low · **Tested on:** Windows 11, RTX 2070 · **Needs:** Linux, any GPU ## Why Players who keep their game as a `.nx` file (NXFormat, github.com/fab918/nxformat, made with `nxconvert pack-nup`) have to convert it back to a `.nup` or to folders before Longshot can build. With this PR the builder takes the `.nx` directly. ## What changed `make_game.py` now reads a `.nx` archive wherever it reads a `.nup`: it tells the two apart by the file's first bytes and runs a new reader for the `.nx`. The reader reuses `nup.py`'s extraction, so path checks, progress and the damaged-`.zs` list behave the same, and every file is checked against its SHA-256 in the archive. - nx2: `nx2/nxar.py` (class `Nx` and a CLI like `nup.py`'s) reads NX 0.2 and 0.3 archives holding exefs/romfs trees. A `.nx` holding NCA files (`nxconvert pack`) is refused with a message saying how to convert it. `nx2/test_nxar.py` builds archives from the spec, game-free. - nx2: `nx2/nup.py`: the step after extraction (plain NSOs, ZBIC) moved into `plain_modules()`, which `nxar.py` calls too. The `.nup` path is unchanged. - make_game: `package_script()` in `nx2/make_game.py` picks `nx2/nxar.py` or `nx2/nup.py` by the NXAR magic, in `check()` and in `main()`'s extraction; `--nup` and `--game` help mention `.nx`. Test: `tests/test_make_game_package_script.py`. - game files: `.gitignore` ignores `*.nx` and `scripts/release.py`'s `NOT_A_RELEASE_FILE` refuses `.nx` (a `.nx` is a whole dump); CONTRIBUTING lists it with the game files. - docs: README (game copy section and command line), `website/src/content/docs/requirements.mdx` (its copy) and `docs/development.md`. The launcher's side (finding, browsing and dropping `.nx` files) is a separate PR on LongshotLauncher, and needs a Longshot release with this change. ## Measurements Nothing to measure in the game: this changes only how the builder reads the game file; the build it makes and the game are unchanged (see Testing for the extraction check and its speed). ### Flags and settings None ## Testing **Tested:** On Windows 11 build 26300 (llvm-mingw 20260616), with my own copy, the same code in Hookshot's tree (this PR is that change with Longshot's names). The game files never left my PC. - The `.nx` and the `.nup` of the same game hold the same 186,592 files by path, size and SHA-256, with byte-identical exefs and build id `e0f3ccfa`. - Every file of the `.nx` decoded and SHA-256-checked: 26.27 GB in 158 s from disk (166 MB/s). - `make_game.py --check --nup <file.nx>`: "This is the version ... supports (build e0f3ccfa)." - A build from the `.nx` extracted all 186,592 files, made `main` a plain NSO and translated 100% of the code. The game it built starts and plays (NVIDIA GeForce RTX 2070, driver 32.0.16.2101). - In this tree: `nx2/test_nxar.py` and `tests/test_make_game_package_script.py` pass. `python -I -B tests/run_all.py`: 504 passed, 19 failed, 72 skipped; the same 19 fail on `main` @ 53f96d7 on this PC: test_appimage_player_build, test_cpm_discovery, test_cpp_preflight, test_crash_dialog, test_cv_signal_race, test_env_on, test_fpx_sticky, test_lift_cleanup_error, test_linux_preflight, test_make_game_cache, test_make_game_prepare, test_missing_nup, test_oot_state_tap, test_readback_late, test_spawn_emit, test_tested_configurations, test_vk_pgo, test_vram_budget_row, test_walk_key. **Not tested:** A build from this Longshot branch in the game (only Hookshot's tree with the same change); Linux (I have no Linux PC). **Must be tested:** - Linux, any GPU: run `python -I nx2/make_game.py --check --nup <your .nx>` and then a build with `--nup <your .nx>` (a `.nx` made from your `.nup` with `nxconvert pack-nup`), expecting the check to report build e0f3ccfa and the game to start (by hand: a tester with a `.nx`, since the farm's copies are `.nup`). ## Risks **What could break:** Only a file starting with `NXAR` goes to the new reader; every `.nup` still goes to `nup.py`, whose extraction is unchanged except that its last step moved into a function. **Turning it off:** revert the commit. **Compatibility:** Nothing changes for a player who builds from a `.nup` or folders: no saves, options, caches or vk ABI touched. ## Issues Fixes #411 ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated.

nussico added 1 commit 2026-11-15 04:24:52 +00:00

feat(builder): accept .nx archives (NXFormat) as the game files 012546faae

nussico referenced this pull request from MagicBeanDev/LongshotLauncher 2026-11-15 04:25:07 +00:00

feat(launcher): find, browse and drop .nx archives beside .nup files #77

HumanBean referenced this pull request from a commit 2026-11-15 04:37:18 +00:00

feat(launcher): find, browse and drop .nx archives beside .nup files (#77)

mooki added the

area/install

kind

feature

platform/linux

platform/windows

priority

low

labels 2026-11-15 13:58:09 +00:00

HumanBean force-pushed builder/nx-format from 012546faae to c9d3ac620f 2026-11-15 18:46:26 +00:00 Compare

HumanBean commented 2026-11-15 18:47:13 +00:00

Owner

• Copy link
• Copy Markdown

Rebased onto main @ 7bacf846: no conflicts. No tests were run here; the test boxes stay yours.

Rebased onto `main` @ 7bacf846: no conflicts. No tests were run here; the test boxes stay yours.

BeanIssues added the

risk

low

label 2026-11-15 20:27:53 +00:00

Some checks failed

Hide checks

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped

Details

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped

Details

Third-party parts / The same as upstream (pull_request) Has been skipped

Details

Website / Website on Cloudflare (pull_request) Has been skipped

Details

PR description / Description follows the template (pull_request_target) Successful in 6s

Details

CI / Conventional Commit title (pull_request) Successful in 5s

Details

CI / Workflow lint (actionlint) (pull_request) Successful in 8s

Details

Guide screenshots / Guide images and local UI source review (pull_request) Failing after 9s

Details

Third-party parts / As their notes say (pull_request) Successful in 15s

Details

Website / Website on Cloudflare (pull_request_target) Has been skipped

Details

This pull request is marked as a work in progress.

This branch is out-of-date with the base branch

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u 'builder/nx-format:nussico-builder/nx-format'

git switch 'nussico-builder/nx-format'

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/tooling

Developer tools: scripts, CI, build and release tooling

  

area/upscaling

DLSS, FSR, frame generation

  

beanstalk: approved @ 1697603

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 2c5a62e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 4fd82b7

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 64d6d09

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 6f91fae

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 70a78f9

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8015c9a

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8d361dc

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 9d8356e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ abf2227

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ d82f202

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ e5f1e40

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ ee8ab5f

Set by Beanstalk for show; the farm's database is what counts

  

ci: approved

A maintainer approved CircleCI for this fork PR (sticky; removed after 14 quiet days)

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Affects Linux (a change for every system carries both Windows and Linux)

  

platform/macos

macOS (Apple silicon or Intel Macs)

  

platform/steam-deck

Steam Deck

  

platform/windows

Affects Windows (a change for every system carries both Windows and Linux)

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

regression

Worked in an earlier build, broken in a newer one: highest priority, above other bugs

  

risk

high

Broad or core change: the renderer, defaults on many systems, saves, installs, security

  

risk

low

Small, contained change: little can break

  

risk

medium

Changes behaviour in one area, or a default on some systems

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

  

ci: approved

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/tooling

area/upscaling

beanstalk: approved @ 1697603

beanstalk: approved @ 2c5a62e

beanstalk: approved @ 4fd82b7

beanstalk: approved @ 64d6d09

beanstalk: approved @ 6f91fae

beanstalk: approved @ 70a78f9

beanstalk: approved @ 8015c9a

beanstalk: approved @ 8d361dc

beanstalk: approved @ 9d8356e

beanstalk: approved @ abf2227

beanstalk: approved @ d82f202

beanstalk: approved @ e5f1e40

beanstalk: approved @ ee8ab5f

ci: approved

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/macos

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

regression

risk

high

risk

low

risk

medium

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

ci: approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

MagicBeanDev/Longshot!685

No description provided.