NSP-Box README

README проекта с github.com/smarkyie/NSP-Box. Одним файлом markdown: README.md.

NSP Box: A Switch 2 Game Packager

NSP Box 4.0 — Meet NUP. Create compressed NUP archives from extracted game folders, convert plaintext NSP ↔ NUP, extract selected content, and inspect or verify archives. See NUP.md for content selection, update merging, compression, DLC compatibility and storage requirements.

Download · Build from source · Changelog · Disclaimer

A portable Windows app that packages a complete, already-extracted ExeFS/RomFS snapshot into a plaintext NSP for compatible emulators. Choose a folder, add your own artwork, and build an NSP.

Version 4.0 adds NUP Tools with Fast/Balanced/Smaller compression, source-aware Base / Updates / DLC selection, a smaller latest-game snapshot option, custom title and cropped artwork, and automatic output beside the source. Source inspection reuses its file index, duplicate data can share storage, the artificial 32 GiB NSP cap is removed, and valid larger-window Zstandard frames now decode correctly. Thanks to a55uka and the NUP project for the format specification, and @hlebushekhub for reporting the file-size cap in #8.

Use Game for complete ExeFS/RomFS snapshots and DLC for separate RomFS-only add-ons. A user installed the Bananza DLC NSP and confirmed that the game recognized it in PokeDinner 2.0.0. This is one successful user test, not universal DLC compatibility. See DLC instructions.

The reversible Emulator patch panel now lists its supported Windows x64 targets: Selevet performance build 4 (normal/30 FPS GUI), Eglantine nx2 98/96, AMD Experimental 77-2 (build-99), and PokeDinner 2.1.0a/2.0.0. Standard/PGO and GUI/CLI variants are identified explicitly. Compatible Windows x64 Selevet/Eglantine/PokeDinner builds read the metadata inside an NSP, so a separate main.npdm beside the game is unnecessary after applying the patch and restarting. See patch installation, removal and limits. Windows x64 downloads only; no Linux build is included.

Piracy is not supported. Use only files and artwork you have lawfully obtained and are authorized to use. No games, game artwork, firmware or Nintendo keys are provided. Nintendo Switch, Nintendo Switch 2 and related marks belong to Nintendo; game content belongs to its respective rights holders. This is an independent project, not affiliated with, sponsored by or endorsed by Nintendo. See ownership and use notices.

Caution — experimental software: set emulator memory to 12 GiB before testing Switch 2 packages. The app does not change this setting. The patch is optional and only applies to recognized compatible code; it cannot add Switch 2 emulation to an unsupported emulator. Verification checks package integrity, not booting or gameplay.

The startup modal has been removed. The Game tab shows the two ways to run Switch 2 NSPs: keep each game's own main.npdm beside its NSP, or use an emulator listed in Emulator patch with native support or the compatible patch applied. Full guidance remains in Notes & compatibility.

PokeDinner 2.5.0 and newer builds with native NSP support need no patch or external main.npdm. Thanks to Franseven, PokeDinner's creator, for integrating support; 2.5.0 release notes list Switch 2 NSP/NUP support. This is native format support, not a guarantee that every game works. Older builds without native detection need the exact game's external main.npdm or a supported patch. Use separate folders for different games' companion files. The file is main.npdm, not the exefs/main executable. Selecting 12 GiB alone can use incorrect timing on older, unpatched builds.

NSP output streams directly to its destination without an intermediate container. The app includes square artwork cropping, clipboard and drag-and-drop support, progress/cancellation, and full output verification.

Experimental build with limited real-world testing. If anything goes wrong, open an issue with your app/emulator versions, reproduction steps and error messages. Do not upload game files, keys or personal paths.

Quick start

  1. Extract the entire ZIP to a writable folder.
  2. Open NSP-Box.exe. Python is bundled; installation is not required.
  3. Click Browse folder and select your main game dump folder, or drag the folder into the window. Pasting a folder path and pressing Enter also works.
  4. Select the complete snapshot you want from the dropdown. The app reads its title ID from main.npdm.
  5. Edit the displayed game name/version if needed. Add, drop or paste artwork, then click Crop icon to position it. Select an NSP destination filename in Output.
  6. Leave Verify after building checked. Create package folder beneath it is on by default: a folder named after the output file contains the package, a metadata companion and JSON verification report. Uncheck it to save only the selected NSP. Then click Build NSP.

The app never overwrites an existing package and does not modify your source files. Cancellation removes the unfinished package. Verification works in both modes; it does not require saving a report. Allow roughly the input size plus 2% and 32 MB free disk space. The previous 32 GiB NSP cap has been removed; larger games are supported within the format, destination filesystem and available-space limits. See large-file limits.

With Create package folder enabled, D:\Packed\Game.nsp is saved as D:\Packed\Game\Game.nsp, with main.npdm and Game.nsp.report.json beside it. The companion is an optional workaround for the checked loader's early Switch 2 memory/clock detection. Keep each game/snapshot in a separate folder if using it; a conflicting companion is refused. The exact snapshot metadata is also embedded inside the package in both modes. After applying the emulator patch, the companion is unnecessary for supported containers: the emulator reads the embedded metadata. Keep the original companion as a backup if you plan to remove the patch.

NSP is a PFS0 container with Program, Control and Meta NCAs for games, or Data and Meta NCAs for DLC. It is not compressed. Outputs are unsigned plaintext emulator repacks; this does not make them authenticated retail-console packages. Loading depends on the emulator's plaintext-content support. NSP Box does not create XCI files.

Use the emulator patch

PokeDinner 2.5.0 and newer builds with native NSP support can skip these steps.

  1. Fully close the emulator and open Emulator patch in the packager header.
  2. Select the folder containing the Windows x64 Selevet/Eglantine/PokeDinner executables, then Check and Add patch. Matching unverified builds offer Try patch with an experimental warning.
  3. Restart the emulator. Open your NSP from a folder without an external main.npdm. Existing packages already contain their metadata and do not need rebuilding.
  4. For new single-file outputs, uncheck Create package folder. It remains on by default for compatibility with unpatched emulators.

The packager need not stay open while playing. Remove patch restores exact backed-up executable bytes; retain the emulator folder's .s2gp-patch directory while patched. If Older patch appears, remove it before adding the corrected patch. Re-check after emulator updates. Future releases/forks must match the reviewed loader and metadata-reader code; unmatched or ambiguous executables are not modified.

Accepted folder layouts

Direct snapshot:

My Game/
  exefs/
    main
    main.npdm
    rtld, sdk, subsdk* ... (as present in your dump)
  romfs/
    ... complete game filesystem ...

Main folder with snapshots:

My Game/
  base/
    exefs/...
    romfs/...
  updates/
    65536/
      exefs/...
      romfs/...

An empty base folder is fine when an update folder already contains the complete mounted game filesystem. A folder containing only update differences is not sufficient. Completeness cannot be reliably determined from filenames; select a snapshot you know is complete.

The Game tab does not merge separate updates or DLC; DLC folders are left out of game snapshots. Use the DLC tab to create a separate add-on package for installation through a compatible emulator. Multi-program applications, patch-only/BKTR data, encrypted NSP/XCI inputs, compressed ROM packages, decryption, and authenticated cartridge reconstruction are outside this release's scope. This is a snapshot packager, not an emulator or a universal game converter.

Artwork and metadata

Artwork is exported as a 256×256 JPEG, suitable for the emulator library icon. New artwork starts with a centered square crop. Crop icon opens an editor with drag-to-position, mouse-wheel/slider zoom, a live icon preview, Reset, Apply and Cancel. Fit whole image retains the entire image with padding instead. Cropping never changes the original file.

Supported inputs include PNG, JPEG/JFIF, WEBP, AVIF, GIF, TIFF, BMP/DIB, Windows ICO, Mac ICNS, TGA, PPM/PGM/PBM/PNM and JPEG2000. Animated or multi-page inputs use the first frame/page; icon containers use Pillow's selected image, normally the largest available. HEIC/HEIF and SVG are not decoded by this build.

Use Paste or Ctrl+V to add a copied bitmap, copied artwork file, or local image-file path. Ordinary text pastes in text fields continue to work normally. You can also drag one artwork file into the app. Clipboard images are held in temporary PNG files until the app closes; the app reads the clipboard only when you request a paste. Copying a URL alone does not download its image.

The app embeds the selected crop in the game NSP. No game artwork ships with this app.

If a standard control.nacp is present at the snapshot/main root or under control/, the app preserves it and updates uncompressed title text and the display version. Otherwise it generates basic control metadata. Generated fields are not a recreation of all original save-size, network, language, or DLC settings. A folder version such as 327680 is a numeric dump version, not necessarily a human-readable game version.

Eglantine plaintext compatibility entries

Some Eglantine builds require key entries even when NCA headers and sections are plaintext. This package includes compatibility/plaintext-repack.keys, containing locally generated placeholders, not Nintendo keys. They cannot decrypt retail content. The app does not install them or change emulator configuration automatically.

If Eglantine reports 0007-0015 or a missing key for this app's plaintext images, close it and use Notes & compatibility → Set up emulator keys folder…. Select that profile's keys folder, commonly %APPDATA%\eden\keys or user\keys beside a portable emulator. Setup adds only missing plaintext placeholders to prod.keys_autogenerated, preserves existing entries and never writes prod.keys. An existing autogenerated file is backed up before appending; invalid existing entries are reported rather than replaced. Restart the emulator afterwards.

Manual export remains available:

  1. Close Eglantine and open its user keys folder, commonly %APPDATA%\eden\keys.
  2. If prod.keys_autogenerated does not exist, copy plaintext-repack.keys there and rename the copy to prod.keys_autogenerated.
  3. If that file already exists, keep it. Back it up before editing and add only missing placeholder entries. Keep all real keys in prod.keys; that file takes precedence in the checked Eglantine loader.
  4. Restart Eglantine.

The GUI's export button saves another copy without overwriting anything. Setup runs only when explicitly selected, never during scanning/building. These placeholders support this app's plaintext repacks; they do not replace your own retail keys for encrypted games. Eglantine forks can differ; consult the fork's documentation if its key-loading rules differ.

Portability and privacy

Source and redistribution

Full application source, icon assets and synthetic tests are available in the separate source ZIP on the release page. The portable ZIP contains the app, documentation and required license notices; it does not duplicate the source. In this repository, application modules are under src/ and tests are at the root. The original application code is released under the MIT license in LICENSE.txt; third-party components retain their own licenses under licenses/ and THIRD_PARTY_NOTICES.md.

You may redistribute the app and source with the required license notices. The software was developed with AI assistance. This package includes no Nintendo code, game data, game cover artwork, console firmware, tickets, certificates, or Nintendo cryptographic keys. Use your own extracted data and artwork; redistribution rights for input/output content are separate from the app's license.

See TECHNICAL_NOTES.md for implementation details and BUILD.md in the source ZIP to rebuild the EXE. See GITHUB_RELEASES.md for publishing future versions.

NSP-Box (smarkyie/NSP-Box)

Ищем в базе…

Что это такое?Портативное приложение для Windows, которое упаковывает полностью распакованную папку игры (ExeFS/RomFS) в NSP-файл без шифрования, который могут загрузить совместимые эмуляторы. Также можно добавить свои иллюстрации, применить патч к некоторым сборкам эмуляторов и проверить результат.
Это эмулятор или конвертер игр?Ни то, ни другое. Программа лишь пересобирает уже имеющуюся у вас папку в NSP-файл. Это не эмулятор и не универсальный конвертер.
Как это запустить?Распакуйте весь ZIP-архив в папку, в которую можно записывать файлы, и откройте NSP-Box.exe. Укажите полную папку игры, выберите снимок, задайте имя выходного файла и нажмите Build NSP.
Нужно ли сначала устанавливать Python или эмулятор?Нет. Python уже встроен в приложение. Эмулятор нужен только для запуска результата, а патч для эмулятора необязателен.
Будет ли результат работать в любом эмуляторе?Не обязательно. NSP — это неподписанная пересборка без шифрования, поэтому загрузка зависит от того, поддерживает ли эмулятор незашифрованное содержимое. Патч для эмулятора работает только с распознанными сборками Selevet, Eglantine и PokeDinner для Windows x64.
Можно ли использовать это на Linux или macOS?Нет. Программа предназначена только для Windows 10/11 x64, сборка для Linux не входит в комплект.
Отправляет ли программа мои файлы или данные куда-либо?Нет. Телеметрии, отправки или автоматической загрузки нет. Локальные JSON-отчёты могут содержать пути к папкам, поэтому перед отправкой их стоит проверить.
Что на самом деле меняет патч для эмулятора?Он меняет только распознанные исполняемые файлы Selevet, Eglantine и PokeDinner для Windows x64 и сохраняет их исходные байты, поэтому «Remove patch» может их восстановить. После применения патча и перезапуска эмулятор читает метаданные, встроенные в NSP, поэтому отдельный main.npdm не нужен.
Почему программа помечена как экспериментальная?Её реальное тестирование ограничено. Один пользователь подтвердил, что NSP с DLC работал в PokeDinner 2.0.0, но это не доказывает универсальную совместимость с DLC, а одинаковый FPS во всех играх не гарантирован.
Сколько свободного места на диске нужно для сборки?Примерно размер исходных файлов плюс 2% и 32 МБ свободного места. Поддерживаются пакеты размером до 32 ГиБ.
Работает ли программа с DLC и обновлениями игр?DLC собирается отдельно как дополнение только с RomFS на вкладке DLC. Обновления не объединяются, поэтому папки, содержащей только различия обновления, недостаточно. Используйте снимок, полноту которого вы точно знаете.
Автор
smarkyie
Размер
12.3 MB
Звёзды
608
Возраст
18 д
Коммиты · 90 дней