NX Library 0.1.4

Mods arrive in NX Library: turn on your own, or find and install the ones that work from GameBanana, in a game's page or in a new mod store. Games now build on the drive they are installed to, and the engine moves to a newer, tested version.

Mods

• Your own mods, no rebuild. Put a file mod (a folder with romfs inside) into a game's mods folder, then turn it on in the game's new Mods band or in Game options → Mods, and play. The engine reads mods at launch, so nothing is rebuilt. When two mods change the same file, the order you set decides which one wins. Remove moves a mod to the Trash, so nothing is lost by mistake.
• Mods from GameBanana in a game's page. The Mods band also lists the GameBanana mods that work with the engine. Open one to see its images, author, version and files, then press Install: it downloads into the game's mods folder and is on at the next launch. Update appears when the author replaces the file.
  • Why only some mods: NX Library checks every file of a mod before showing it and keeps only file mods (romfs). Mods that patch the game's code (exefs, such as most 60 fps patches) don't work with the engine, so they are left out instead of failing after the download.
  • Finding the right game: when the game's GameBanana page isn't certain, the band asks once and remembers your choice; Wrong game? picks another.
  • Every mod links to its page on GameBanana, so its authors keep the credit.
• Mod store. A new Mods card in Spotlight's row. Go down from it into a store of the mods that work with your games: a large Featured banner, the most popular mods for your games, a row per category (characters, worlds, graphics, music, interface, gameplay) and a row for each of your games, last played first. Sort by Popular, Most liked, Newest or Recently updated.
  • It opens at once from what it found last time and checks GameBanana again in the background, so you never wait on a blank page.
  • A small arrow at a row's right end shows when more mods are hidden past the edge.
  • The card shows the art of the best mods, and the background glides to gold while it is selected. Don't want it? Hide it in Settings → Spotlight or from its Y menu.
• Installing one file installs only that file. In a mod with several files, only the one you chose shows its progress; the others wait until it ends.
• A mod's panel reads well with long text. Read more sits right under the description and opens all of it; the files follow under their own Files title. The panel scrolls with the wheel, the trackpad or Up and Down, which read the text before moving to the next row.

Building on an external drive (#4, #6)

• Games build on the drive their app goes to. With the Game apps folder on an external APFS or Mac OS Extended drive, the extracted game, the shader cache and the new app stay on that drive, in a hidden .nxlibrary-build folder.
  • Why: before, every build happened on the Mac's own disk and the finished app was then copied across. A Switch 2 game needed tens of GB free on a small internal SSD (#4), and the final copy wrote ~35 GB again (#6). Now the Mac's disk needs no free space for the build, and the finished app is moved into place, which is instant.
  • A game whose build files were on the Mac's disk moves them at its next rebuild and frees that space.
  • exFAT drives still build on the Mac's disk: exFAT stores extended attributes in ._ files, which break a Mac app's signature. The space warning says so. Installing to exFAT works as before.

Game options

• The two upscalers, explained. They are two different steps of the same frame, and both can be on:
  • MetalFX upscaling enlarges the finished picture, menus and HUD included, to your window or screen with Apple's MetalFX instead of smooth scaling: sharper, for a little more GPU time.
  • Game's upscaler appears only in games that enlarge their 3D picture inside the frame with an upscaler of their own (such as Donkey Kong Bananza). Game's own keeps it; MetalFX does the same step with Apple's scaler in a fraction of the GPU time (about 1 ms instead of 3.5–5 ms on an M1), with Apple's look instead of the game's.
• Info beside a row. Rows with an explanation show an info button: click it, or press Y on the focused row.

Cheats

• Cheats or mods? A line under the Cheats panel's title tells them apart: cheats change values while you play, for one game version only; new items, looks or gameplay are mods.
• Cheats on imported games. A game added from an app built elsewhere no longer asks for a rebuild when its engine already supports cheats: NX Library reads the engine version the app carries.

Game app icons

• A game whose app has no icon (Switch 2 games and dumps) now shows the Icon you choose in Change artwork, in Finder and the Dock. For a game with its own icon, a question lets you use yours on the Mac too. The icon survives a rebuild, and Automatic brings back the game's own. Updating a large game's app takes about a minute.

Engine

• Updated nxnative to b2d46b86 (from 4a0551e4, through 04df08d4, which was tested with an Ocarina of Time build). The Metal compiler is the same, so no new setup is needed.
  • New game profiles: Kirby Air Riders and Ocarina of Time (Switch 2, from a NUP), ŌKAMI HD, Minecraft Dungeons II, and Sonic Superstars (provisional).
  • Ocarina of Time no longer crashes at the first note of the ocarina and runs lighter in the village.
  • Upstream also reports fixes for Trails in the Sky 1st Chapter and Just Dance (a crash at launch), Super Mario Galaxy 2 (cutscene picture shape), Super Smash Bros. Ultimate 13.0.5, Rhythm Heaven Groove and Fire Emblem: Three Houses.
  • A game's shader cache and shader libraries are now one file each, so a build writes far fewer files. The first build of each game after updating converts its cache and shows Updating shader cache meanwhile; every game translates its shaders again once.
  • Damaged game files are caught. A NUP or a dump has no checksums, so a damaged file used to make a game that reloads an asset for ever. The engine now checks the files once (about 16 s for Ocarina of Time) and stops with Some game files are damaged, with Port anyway if you want to try.
• Installed games keep their engine until you rebuild them.

Smoother and lighter

• Cards no longer wobble in a quick run of presses. Every card grows, shrinks and slides on one shared glide, so the gaps between cards hold; cards coming in at the edge no longer drift into line, and the lock, build progress and Add Game icon move with their card. In Spotlight and Collection.
• NX Library rests at about 0% CPU when idle, instead of a quarter of a core: the selected card's ring and shine now run in Core Animation, just as smooth.
• macOS Game Mode stays off for NX Library. It is a launcher, not a game, and Game Mode lowers the priority of background work such as builds. Games keep Game Mode off as the engine sets it, because it holds the GPU at its lowest clock after a few minutes. If macOS already remembers NX Library as a game, turn it off once in full screen: Command-Esc, Game Overlay, Game Mode.
• The background art no longer jumps or flashes when you move between games, and Spotlight's genres now leave and return with the game's buttons.
• The Mods card keeps its art when selected; new art crossfades in whole.
• The intro shows only the moving background, without the app icon.

Considered and not adopted

These were looked at in this release and left out on purpose:

• Downloading cheats from switch-cheats-db. It was built and then removed. A cheat works only on the exact game version it was written for, and the public collections (switch-cheats-db, MyNXCheats, Breeze's archive, the GBAtemp mirror) have nothing for the latest versions of most games, which are the ones people port. A panel that goes online on every open and almost never finds anything isn't worth it. You can still add cheat files yourself in the Cheats panel.
• Loading a cheat from another game version. The engine could load it, but its memory addresses would be wrong: crashes or damaged saves. Not offered.
• Code mods (exefs, e.g. 60 fps patches). The engine doesn't apply them, so NX Library doesn't list or install them.
• New engine switches without a player use: DM_PROBE_EVERY (a diagnostic counter), DM_NVN_CUT_BUSY (diagnostic) and DM_GUEST_FILE_DIR (iOS only) stay out of the app.
• Building on exFAT drives, for the signature reason above.
• A grid view for Collection (#3) is planned for a later release, to be done with proper focus, art and controller navigation rather than a quick port.

Known issue

• A game drawn upside down (#5). NX Library doesn't draw the game: the picture comes from the nxnative engine, and no NX Library option flips it. The engine already fixes this symptom game by game; please report affected games, with title ID and version, at nxnative's issues.

Updating

Updating keeps your library, mods and preferences. Existing game apps remain playable and are not rebuilt automatically; rebuild a game to use the new engine. Setup prepares the new engine in one step after the restart.

Use the DMG for a first installation. Installed release copies can update from Settings → About → Check now.

NX Library 0.1.3.3

Fixed

• Extracted games (dumps) are recognised in every layout the engine accepts. Before, only a folder holding base/exefs and base/romfs worked; choosing the base folder itself said "No NSP, XCI, NSZ, XCZ or NUP files were found in this folder". Now these work too:
  • a folder with exefs and romfs directly in it (a base folder, or what nup extract writes). A base folder inside a dump with updates or DLC brings them along;
  • a dump with only an update (updates/<version>/), played as the whole game;
  • a base with only its code, when an update has the RomFS.
• A folder with no game now says what NX Library looks for, extracted folders included.

NX Library 0.1.3.2

Fixed

• Games and updates for system 22.0.0 and later, whose code Nintendo compresses with ZBIC (its own zstd variant), now build. Before, the porting stopped with "The engine needs the zbic package to read this game's code", even after pip install zbic: NX Library uses only its built-in Python, which lacked the package. The built-in Python now includes zbic 1.0.1.post1 (GPLv2; its source ships in Runtime/sources/), and Setup checks it with the other modules.
• NSZ and XCZ files build without a separate nsz install. The engine converts them with the nsz tool, which the built-in Python lacked, so they worked only where nsz happened to be installed. The built-in Python now includes nsz 5.0.0 and its dependencies.
• Setup and the build check test every package and tool the engine needs (zbic, nsz and make too), so All set no longer appears when one is missing.
• A game built with a Language it does not have explains it and points to Game options (Game Default or one of the game's languages), instead of "The porting stopped".
• A package too damaged for Port anyway (cut off, or its own tables fail their hash check) asks for a new dump or download and no longer offers Port anyway.

NX Library 0.1.3.1

A quick fix on top of 0.1.3. If you already have 0.1.3, this update adds only the fix below; everything else is the same.

Fix in 0.1.3.1

• Add Game accepts Switch 2 NUP files without a base game, when their update holds the complete game, as the engine does. Before, such a file stopped with "The NUP file could not be read: AttributeError: 'NoneType' object has no attribute 'meta'". If the update is only a patch, the build now says a NUP with the base game is needed.

What's new in 0.1.3

Switch 2 support, game options that follow each game, more artwork sources and a verified engine upgrade.

Switch 2

• Add Game accepts Switch 2 NUP files: Review lists the base game, updates and DLC.
• Switch 2 games get their description, genres, cover, background and screenshots automatically, and show Nintendo Switch 2 as their platform.

Game options

• Options follow each game's own settings: a change made in the game's settings window shows in NX Library, and the other way round. Rebuild a game to use this.
• Frame rate (with 120 fps where a game supports it), the game's upscaler and the other settings a game offers appear only when the game has them.

Artwork

• Browse online in Change artwork opens LaunchBox and SteamGridDB (with your free API key). Images are downloaded at full size only when you choose them.

Engine

• Updated nxnative to 4a0551e4, with fixes and updated profiles for games such as Super Mario Odyssey, Tears of the Kingdom and Donkey Kong Bananza. Rebuild a game to use it; its shaders are prepared again.
• After a game is rebuilt and played with this engine, an older build of that game may not read some of its saves.
• Games the engine has no profile for are accepted with a provisional one, marked Not tested with this engine yet.
• Newest engine in Settings → Engine lets you try nxnative's latest version before NX Library has tested it. Back to tested returns to the tested engine at any time.
• Hold Home for 2 seconds, then A, to quit a game with the controller.

Fixes

• Refreshing the library no longer takes minutes for large games on an external drive.
• The Cheats switch no longer shows an error for a game without a cheat file.

Updating keeps your library and preferences. Existing game apps remain playable and are not rebuilt automatically. Setup prepares the new engine in one step after the restart.

Use the DMG for a first installation. Installed release copies can update from Settings → About → Check now.

NX Library 0.1.3

Switch 2 support, game options that follow each game, more artwork sources and a verified engine upgrade.

Switch 2

• Add Game accepts Switch 2 NUP files: Review lists the base game, updates and DLC.
• Switch 2 games get their description, genres, cover, background and screenshots automatically, and show Nintendo Switch 2 as their platform.

Game options

• Options follow each game's own settings: a change made in the game's settings window shows in NX Library, and the other way round. Rebuild a game to use this.
• Frame rate (with 120 fps where a game supports it), the game's upscaler and the other settings a game offers appear only when the game has them.

Artwork

• Browse online in Change artwork opens LaunchBox and SteamGridDB (with your free API key). Images are downloaded at full size only when you choose them.

Engine

• Updated nxnative to 4a0551e4, with fixes and updated profiles for games such as Super Mario Odyssey, Tears of the Kingdom and Donkey Kong Bananza. Rebuild a game to use it; its shaders are prepared again.
• After a game is rebuilt and played with this engine, an older build of that game may not read some of its saves.
• Games the engine has no profile for are accepted with a provisional one, marked Not tested with this engine yet.
• Newest engine in Settings → Engine lets you try nxnative's latest version before NX Library has tested it. Back to tested returns to the tested engine at any time.
• Hold Home for 2 seconds, then A, to quit a game with the controller.

Fixes

• Refreshing the library no longer takes minutes for large games on an external drive.
• The Cheats switch no longer shows an error for a game without a cheat file.

Updating keeps your library and preferences. Existing game apps remain playable and are not rebuilt automatically. Setup prepares the new engine in one step after the restart.

Use the DMG for a first installation. Installed release copies can update from Settings → About → Check now.

NX Library 0.1.2

A small usability update, with a verified upstream engine upgrade.

Library and controls

• Discover existing nxnative apps inside subfolders of Game apps. One Scan game apps action handles discovery and refresh; skipped folders are explained in Settings without repeated launch popups.
• In fullscreen, the pointer hides after three seconds without movement and returns when you move the mouse. Keyboard and controller navigation keep it hidden.
• Native menus preserve the selected game and open Details and Options through the normal navigation flow.
• Choose Start in fullscreen in Settings → Start-up for the next app launch.

Updates

• NX Library → Check for Updates… opens the same dialog as Settings → About, with scrollable release notes, a clear up-to-date result and retryable errors.

Engine

• Updated nxnative to b64a5ff0, including audio-start and memory-alignment fixes, renderer/shader corrections, updated profiles and shader-build improvements.
• Cache cleanup now shows its activity without an unreliable ETA. New key diagnostics distinguish outdated keys from a missing package ticket.
• Xcode 27.2 and certified Metal 32023.922 remain the build requirements.

Updating the launcher keeps your library and preferences. Existing game apps remain playable and are not rebuilt automatically; rebuild a game to apply the new engine to it. Setup can prepare the newly required engine checkout.

Use the DMG for a first installation. Installed release copies can update from Settings → About → Check now; automatic checks run at most once every 24 hours.

NX Library 0.1.1

nxnative engine update

NX Library 0.1.1 updates its pinned nxnative engine to 65501fbb.

• Automatic AV1 movie decoding with dav1d when hardware decoding is unavailable.
• Shader and rendering fixes, including texture-pool lifetime handling, geometry batching and primitive-ID pipelines.
• More robust jump-table rewriting and worker shutdown.
• Updated game profiles and Unity 2020.3 compute-shader support.

The build requirements remain Xcode 27.2 and certified Metal 32023.922. After updating NX Library, use Setup to prepare the required engine when prompted. Existing game apps remain playable; rebuilding applies the new engine to a game.

Download the DMG for a new installation. Installed release copies can update from Settings → About; the ZIP is used by the in-app updater. This alpha is ad-hoc signed and not notarised.

See the changelog for details. Games, firmware and keys are not included.

NX Library 0.1.0

First public alpha

NX Library is a macOS frontend for organising your game apps, preparing your own supported game files with nxnative and launching them from one library.

Downloads

• NXLibrary-0.1.0.dmg — first installation. Open the image and drag NX Library to Applications.
• NXLibrary-0.1.0.zip — the verified app archive used by the in-app updater.

Included

• Spotlight and Collection views, search, favourites, artwork and play activity.
• Two-step setup, with an optional first game and a shared folder for existing game apps and new builds.
• Local builds with source review, progress, cancellation and installation retries.
• Per-game launch options, cheats, local save backups and save-import previews.
• Themes, static and live backgrounds, interface sounds and controller prompts.
• A public app-update channel that needs no GitHub account.

Requirements and installation

Apple silicon and macOS 13 or later. Building games also requires Xcode 27.2, the certified Metal compiler, .NET 10 and the pinned nxnative engine; Setup guides you through the supported steps. Existing game apps can be played without the build tools or original sources.

This alpha is ad-hoc signed and not notarised. If macOS blocks first opening, use System Settings → Privacy & Security → Open Anyway only after confirming that you obtained this copy from this repository. Games, keys and firmware are not included.

See the README for the illustrated guide and changelog for the full list of changes. Please report reproducible problems through the repository's issue template; do not attach games, keys or private files.