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 是未签名的明文重新打包文件,能否加载取决于模拟器是否支持明文内容。模拟器补丁只适用于已识别的 Windows x64 版 Selevet、Eglantine 和 PokeDinner 版本。
我可以在 Linux 或 macOS 上使用吗?不可以。它仅支持 Windows 10/11 x64,且不包含 Linux 版本。
它会把我的文件或数据发送到别处吗?不会。没有遥测、上传或自动下载功能。本地生成的 JSON 报告可能包含文件夹路径,因此分享前请先检查。
模拟器补丁究竟修改了什么?它只修改已识别的 Windows x64 版 Selevet、Eglantine 和 PokeDinner 可执行文件,并保持其原始字节完全一致,因此可以通过“Remove patch”还原。打补丁并重启后,模拟器会读取 NSP 中内嵌的元数据,所以不需要单独的 main.npdm。
为什么标注为实验性功能?它在真实环境中的测试有限。有一位用户确认 DLC NSP 在 PokeDinner 2.0.0 中可以运行,但这并不能证明 DLC 普遍兼容,也不保证所有游戏的帧率都一致。
生成一个包需要多少可用磁盘空间?大约需要输入大小加上 2% 再加 32 MB 的可用空间。支持最大 32 GiB 的包。
它能处理 DLC 和游戏更新吗?DLC 是在 DLC 标签页中单独构建的,仅包含 RomFS 的附加内容。更新不会自动合并,因此仅包含更新差异的文件夹是不够的。请使用你确认完整的快照。
作者
smarkyie
大小
12.3 MB
星标
608
时长
18天
提交 · 90 天