Skip to content

Add NxNative Converter, a native Mac app over the NSP script's mac-app build - #209

Closed
gnosticgeek wants to merge 2 commits into
seedds:mainfrom
gnosticgeek:mac-converter-app
Closed

gnosticgeek wants to merge 2 commits into
seedds:mainfrom
gnosticgeek:mac-converter-app

Conversation

@gnosticgeek

@gnosticgeek gnosticgeek commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Tom

Before: making a Mac app of a game meant installing the tools from the README, running scripts/build_ipa_from_nsp.py --platform mac-app in a terminal, and finding out about a missing tool or a wrong key partway through the build. There was also no record of which engine commit an app was built from, so nothing showed when an app was out of date after a host fix.

After: app/ holds NxNative Converter, a native SwiftUI app for macOS 26 and later. Building it needs only Xcode (app/bundle.sh). It has four pages:

  • Convert checks the chosen game folder against prod.keys in under a second, then builds and signs the app while showing the script's seven stages.
  • Builds lists every app the converter built, the engine commit each was built on, and a Rebuild button. It also lists the older copies a rebuild kept in app-backups/.
  • Toolchain shows every tool the script needs, grouped, each with a Fix button, plus the engine checkout with check and update buttons, and a Copy diagnostics button.
  • Settings covers appearance, notifications, the output folder, the default keys file, reusing cached stages, keeping old builds, log detail and the build cache.

The same steps also run headless (--check, --validate, --convert, --rebuild, --engine, --verify).

How:

  • Key check, using CommonCrypto. For each NCA in each NSP or XCI, the converter decrypts the header with AES-XTS (Nintendo's big-endian sector tweak) using header_key. It then decrypts the title key from the NSP's ticket with titlekek_XX (or the key area with key_area_key_*_XX), and decrypts the first bytes of a CTR section to confirm they read as PFS0 or RomFS. No key value is printed, logged or saved.
  • Finding tools. Tools are resolved through the script's own TOOL_PATHS, then PATH, so a tick means the script will find the same tool. The shader translator's launcher finds .NET only through DOTNET_ROOT or /usr/local/share/dotnet, not through PATH. The converter therefore sets DOTNET_ROOT to the folder of the dotnet the script resolves, and its check actually starts the translator.
  • Build. The converter runs the script with --progress json and follows its stage, progress and say events. Afterwards it checks that the launcher is executable and that codesign --verify --deep --strict passes. A lock file allows only one build per game folder at a time.
  • Engine versions. Each build is recorded with the checkout's commit in ~/Library/Application Support/NxNative Converter/builds.json, because the bundle carries no commit. Rebuild first renames the old app into app-backups/, then runs the full script into the same path, so stages with unchanged inputs are reused. If the build fails, the old app is put back.

The first version of this PR was written in Rust and egui. It is now Swift, so that it uses the system's own controls and builds with Xcode alone.

Tested on an Apple silicon Mac with Mario vs. Donkey Kong. The key check gave the same per-NCA results as the earlier Rust version, and fake keys and an empty folder give the right errors. A full build from the window completed all 7 stages, and the result was signed and verified. Every page was checked with real window captures. dm/tools/tests/test_docs.py passes.

🤖 Generated with Claude Code

app/ is a Rust (egui) app that runs scripts/build_ipa_from_nsp.py --platform mac-app
from a window: it checks each tool the script needs (resolved through the script's own
TOOL_PATHS, and starting the shader translator), checks a game folder against prod.keys
by decrypting each NCA's header, title key or key area and the start of a section (no
key value is shown or stored), runs the build with --progress json, and verifies the
app's signature. Each build is recorded with the engine's git commit, so an app built
on an older commit can be rebuilt in place, the old one kept in app-backups/ and put
back if the build fails. One build per game folder at a time.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@jthrilly

Copy link
Copy Markdown
Contributor

Having built something similar myself, I would suggest that this sort of thing should stay separate from the core.

The converter in app/ is now a Swift package (SwiftUI, macOS 26 or later) instead of
Rust and egui, so it builds with Xcode alone: the key check uses CommonCrypto (AES-XTS
for NCA headers built on its ECB mode, ECB for title keys and the key area, CTR for
section data). Same steps and command-line modes as before, with four pages: Convert,
Builds (search, sort, a detail panel and the copies a rebuild kept in app-backups/),
Toolchain (grouped checks, engine updates, diagnostics) and Settings (appearance,
notifications, output folder, default keys, cache reuse, keeping old builds, logs).

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@gnosticgeek gnosticgeek changed the title Add NxNative Converter, a Mac app over the NSP script's mac-app build Add NxNative Converter, a native Mac app over the NSP script's mac-app build Oct 25, 2026
@v0lumehi

Copy link
Copy Markdown
Contributor

Heads-up: seedds plans a community front-end page that lists projects by the same criteria, with support for each front end in its own repository (#388). #387 added docs/frontends.md, which describes what a front end can rely on: the build progress events, launcher.json and the environment switches. The next step is one settings schema and one store for player choices, so front ends can draw the settings in their own style without forking. Proposal and discussion: #388 (comment) Input from a front end's point of view is very welcome there.

v0lumehi added a commit to v0lumehi/NX2Apple that referenced this pull request Oct 27, 2026
…build (LNPANDY#65)

A game built last month keeps running on the host, rewriter and shaders
of last month, whatever the checkout has fixed since: the automatic pull
(LNPANDY#60) brings the fixes into the repository, not into the games already
built. Nothing in the library said which games a pull had left behind
(idea from seedds/nxnative#209).

A finished build now records the checkout's commit in its library entry
(toolsCommit, taken when the build starts; only for a git checkout, and
decoded with decodeIfPresent, so older library files load). When the
checkout has moved on, ToolsAge runs `git diff --name-only <commit> HEAD`
off the main thread and marks a game when a file a build reads changed:
dm/host, dm/gfx, dm/tools, dm/ios, dm/mac, dm/third_party, the build
script, game.py, profile_guess.py, the launch settings, and the game's
own profile (dm/games/<title ID>/), without notes (*.md) and tests. One
diff per recorded commit; it runs when the app opens, after a clone,
pull or update check finished (the automatic pull among them), when
the checkout changes and after a build was recorded, not on a render.
A game with no recorded commit, or a commit the checkout does not have,
shows nothing.

A marked game's card says "Older tools" beside its status, the hero
"Built with older tools" with a Rebuild button, and Manage's Build again
reads "Rebuild with current tools…"; both open the game's build as
Build again does.

Checked: swift build -c release; swift test, 54 tests (OlderToolsTests
uses a local git repository: a change under dm/host marks the game, a
docs-only change does not, a game without a recorded commit is not
marked, another game's profile does not count, an unknown commit marks
nothing, the check publishes off the main thread, and an old library
file loads); the visual QA renders library-older-tools at 1440 and 900
points wide.
v0lumehi added a commit to v0lumehi/NX2Apple that referenced this pull request Oct 27, 2026
…sue LNPANDY#63)

Keys that are too old for an update, or a header_key that does not open the game, used to fail
the build minutes in, in the extraction step, with LibHac's message in the log. The answer is in
the first kilobyte of each NCA: its header, encrypted with header_key, names the key generation
the content needs.

As soon as the base game and prod.keys are chosen, the Builds page reads the PFS0 table of the
NSP or NSZ (base game, update, DLC), decrypts the first 0x400 bytes of each NCA with AES-128-XTS
(Nintendo's big-endian sector tweak, built on CommonCrypto's ECB) and checks that titlekek_XX or
key_area_key_<kind>_XX of the newest generation is in the file (or master_key_XX, which LibHac
derives them from). The generation is the larger of the fields at 0x206 and 0x220, minus one, as
LibHac and hactool derive it. The line under prod.keys says "Keys fit", that header_key is
missing or does not open a file, or which generation and key are missing with the firmware that
brought it. An XCI is not read through its HFS0 partitions: it says it cannot be checked before
building, as does an NCZ whose first bytes are not the NCA header. Key values are never shown or
logged. The check runs off the main thread whenever the files or the keys change. Idea from
seedds/nxnative#209.

Checked: swift build -c release; swift test (54 tests, the new KeyCheckTests against IEEE 1619
vectors, a big-endian-tweak reference from Python's cryptography, and synthetic NSP, NSZ and XCI
files with made-up keys); the Builds page rendered with keys that fit and with keys too old for
an update (visual QA).
@seedds

seedds commented Oct 28, 2026

Copy link
Copy Markdown
Owner

Thank you for building NxNative Converter and for testing and documenting the complete build flow. The toolchain checks and rebuild workflow could be useful to players.

I'm closing this PR and asking that the converter continue in its own repository, following the contribution policy's Graphical front ends section. I have limited development and review time and need to keep this repository focused on the runtime, graphics and shared build tools. I can't also take on maintaining and supporting a converter app here.

Please do keep developing it as a community front end. The front-end interfaces are intended to support separate apps, and a focused issue or small PR for a missing progress event or settings field is welcome. Thank you for putting time into making nxnative easier to use.

@seedds seedds closed this Oct 28, 2026
@gnosticgeek
gnosticgeek deleted the mac-converter-app branch November 9, 2026 09:20
ltrdpper pushed a commit to ltrdpper/BananaNative that referenced this pull request Nov 14, 2026
…GB devices, resolution and upscaling settings, FSR 3.1 recommended' (seedds#209) from iH8Ecchi/BananaNative:fefw-settings into android

Reviewed-on: https://git.eden-emu.dev/moceure/BananaNative/pulls/209
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants