Extract, import and FUSE program for common save format for 3DS, written in rust.
This project, along with documentation, is still WIP. There are two main components in the project: the library
libsave3ds, and the FUSE program + extract/import tool
save3ds_fuse that builds on top of it. The FUSE feature is not available on Windows.
Both the library and the program currently supports the following operations:
- Full filesystem operation on save data and extdata stored on NAND, on SD or standalone
- Editing title database and tickets
Note that the supported NAND format is in unpacked cleartext filesystem. If you want to read/write on the original NAND FAT image, you need to use other tools to extract the NAND data, or map another layer of virtual filesystem (e.g. https://github.com/ihaveamac/ninfs)
- Complete cartridge save data support
- install pkg-config and FUSE library.
sudo apt-get install libfuse-dev pkg-config
sudo yum install fuse-devel pkgconfig
brew cask install osxfuse && brew install pkg-config
pkg install fusefs-libs pkgconf
Unix-like (no FUSE)
cd save3ds_fuse && cargo build --no-default-features
Windows (no FUSE)
This AES crate this program depends on chooses hardware/software implementation at compile time. Supply compiler options
-C target-feature=+aes to enable hardware AES feature for better performance.
save3ds_fuse ARCHIVE_NAME MOUNT_PATH [MODE] [RESOURCE_PATHS] [FORMAT_PARAM]
You can put options in arbitrary order. The detail description of them are:
ARCHIVE_NAME specifies the archive to operate on. It can be one of the following:
--sdsave ID: a game save data stored on SD.
IDis the game title ID in 16-digit hex.
--sdext ID: a game extdata stored on SD.
IDis the extdata ID in 16-digit hex.
--nandsave ID: a system save data stored on NAND.
IDis the save ID in 8-digit hex.
--nandext ID: a shared extdata stored on NAND.
IDis the extdata ID in 16-digit hex.
--bare FILE: a stand-alone save data file with path
FILE. Note that modification to this archive will result in invalid signature in the file, and you need other tools to fix the signature.
--db DB_TYPE: a title database archive.
DB_TYPEcan be one of the following:
nandtitlerefers to the file
nandimportrefers to the file
tmptitlerefers to the file
tmpimportrefers to the file
sdtitlerefers to the file
sdimportrefers to the file
ticketrefers to the file
--cart FILE: (experimental) a cartridge save data file with path
FILE. Currently only support Card1, non-N3DS-exclusive, and read-only (needs
MOUNT_PATH is a directory to mount/extract/import the archive content
MODE specifies the operation mode on the archive. It can be one of the following:
- mount mode (default). Mount the archive to
MOUNT_PATHas a virtual filesystem, allowing browsing and editing the content. Upon unmounting, the program saves the modification. This mode is not supported on Windows.
- with additional flag
--readonly, the program opens the archive in read-only mode, prevents any modification operation and skips the saving at the end.
- with additional flag
- extract mode (
--extract). Extracts all content of the archive to
- import mode (
--import). Clear the content of the archive, and import the content from
- touch mode (
--touch). Just open and close the archive. Useful for testing the correctness of other specified resources. No need to specify
MOUNT_PATHin this mode.
RESOURCE_PATHS contains multiple supporting directories/files. Different archive types require different portion of them. It can contain any of the following:
--nand DIR: NAND root path, required by all archive types except
--bare. However, if
--movableis provided, this can be omitted for SD-related archives (
--sd DIR: SD root path, required by SD-related archives.
--boot9 FILE: the
boot9.binfile dumped from 3DS, required by all archive types except
--otp FILE: the
otp.binfile dumped from 3DS, required by
--movable FILE: the
movable.sedfile dumped from 3DS, optionally required by SD-related archives , if
--nandis not provided.
--game FILE: the game dumped from the cartridge in CCI format, required by cartridge save
--priv FILE: the private header dumped from the cartrdige, required by cartridge save
--key FILE|HEX: AES slot 0x2F key Y for decrypting v6.0 cartridge save
FORMAT_PARAM is an optional group of options in the form of
--format param1:value1,param2:value2,..., used in conjuntion with mount mode or import mode. When the flag
--format presents, the archive will be formatted using the given parameters before mounting/importing. This is useful for creating a completely new archives. If an archive already exists in the place, it will be deleted. The difference between
--import --format is that, although both clearing the content,
--import retains the archive layout and capacity that depends on the formatting parameters, while the addition
--format flag can change the layout and capacity.
The parameters supported by
max_file: the maximum number of directories/files. The default is
file_buckets: the bucket count of the hash table for directories/files. The default value is calculated from
max_fileusing the common algorithm games use.
len: only for save data archive. Limits the physical size in bytes of the save data file. The defualt is
block_len: only for save data archive. The value can only be
4096. The default is
duplicate_data: only for save data archive. The value can only be
false. The default is
If you want leave all parameters in default values, you can specify an empty option, e.g.
These parameters behave the same as those in the
fs:USER 3DS service functions:
CreateExtSaveData. However, the
max_file specified here is two/one larger than the one in
CreateExtSaveData, as the latter one automatically counts the required
Title database files currently doesn't support
save3ds_fuse \ # Sets the path to NAND root, extracted/mounted from an NAND image. # For save/ext data on SD, # the only purpose of the NAND path is to provide movable.sed. # You can also provide the movable.sed file directly by # --movable /path/to/movable.sed --nand /home/wwylele/3ds-nand \ # Sets the path to SD root. # This can be the direct path to the SD card mounted on PC. --sd /media/wwylele/6339-6261 \ # Sets the path to the bootrom. # This is necessary for decryption & signing. --boot9 /home/wwylele/3dsbootrom/boot9.bin \ # Informs the program that we want to mount # the SD save data with title ID 0004000000164800 (Pokemon Sun). # The ID is a 16-digit hex number --sdsave 0004000000164800 \ # The target path. The directory must exist and be empty. # When the program is running, # the content of the mounted data will be shown in this directory. /home/wwylele/mount \ # Optional "read-only" flag. # When this flag presents, all write operations are disabled. # Please always backup your data if you don't set this flag! -r
Quirks and Limitations
Directory / file name
Save data and extdata support 16-byte directory / file name, interpreted in ASCII. As it techincally supports special characters like
'/' in the name, special mappings are implemented to display them on the host system: characters
'\', ASCII control characters, and characters beyond
0x7F are translated to the escape sequence
?? is the byte value in two-digit hex. These escaped characters will be used when displaying the directory / file name, and you can use them when editing the name. Names longer than 16-bytes are always rejected.
Prohibited characters specific to Windows are not taken care of. They are usually not used in games, but if they are unfortunately used, the program will likely crash / error out.
Files in title database archives are named with title ID in 16-digit hex. File names that contains non-hex characters or that is too long are rejected.
Extdata file size
Due to the format design, extdata does not support resizing files natively on 3DS, nor creating files with zero size. This program works around the issue by deleting and recreating files on resizing, which is stupidly slow if the user appends a file on every write operation. Zero-size files created by this program can't be opened on 3DS either, so one needs to make sure there is no such file before importing the data back to 3DS.
One can create a file with a specific size, similar to the
CreateFile operation on 3DS. This is done by specifying a special sequence
\+size in the file name. For example,
a.bin\+123 creates the file
a.bin with size of 123 bytes. This, however, doesn't comply with the expected filesystem behaviour, and breaks file name cache in browsers etc.
Because of all the mess, it is recommended to use
--import mode instead of mount mode if you intend to modify the content of an extdata.
Extdata filesystem structure
3DS system expects every extdata to have directories
/user, and the file
/icon. These directories and file are not automatically created when the program formats an extdata. One needs to manually create them, otherwise 3DS would likely fail to open the archive.
Broken block of title database
Due to a bug (?) in 3DS, the last free block (128 bytes) of a title database archive (except for
ticket.db) is broken. If the archive is almost full and data starts to be written to this block, they will not be saved.
Quota.dat for NAND extdata
The format and function of the
Quota.dat file is not fully investigated, and the program probably doesn't parse and update it properly for NAND extdata. This can potentially cause inconsistency if you modify a NAND extdata.
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.