nds¶

Support for NDS ROMs, based on ndspy.

Includes ROM extraction and repacking, banner editing, string extraction and repacking for binary files, arm9.bin expansion and the BIOS compression formats.

hacktools.nds.extractRom(romfile, extractfolder, workfolder='')[source]¶

Extract a NDS ROM with ndspy.

The filesystem is extracted to a data subfolder, along with the header, banner, arm7/arm9 binaries, overlay tables (y7/y9) and arm9 overlays.

Parameters:

romfile (str) – Path of the ROM file.
extractfolder (str) – Path of the folder to extract to.
workfolder (str) – Optional path of a work folder the extracted files are copied to.

Return type:

None

hacktools.nds.repackRom(romfile, rompatch, workfolder, patchfile='')[source]¶

Repack a NDS ROM, replacing the files found in a folder.

Parameters:

romfile (str) – Path of the original ROM file.
rompatch (str) – Path of the output ROM file.
workfolder (str) – Path of the folder with the files to replace, as extracted by extractRom().
patchfile (str) – Path of the xdelta patch to create, or empty to skip patch creation.

Return type:

None

hacktools.nds.editBannerTitle(file, title)[source]¶

Write a new game title in a banner file and update its CRC.

The title is written for all the 6 languages.

Parameters:

file (str) – Path of the banner file.
title (str) – Title to write.

Return type:

None

hacktools.nds.getHeaderID(file)[source]¶

Read the 6 character game ID from a header file.

Parameters:: file (str) – Path of the header or ROM file.
Returns:: The game and maker codes as a single string.
Return type:: str

hacktools.nds.extractBIN(binrange, readfunc=<function detectEncodedString>, encoding='shift_jis', binin='data/extract/arm9.bin', binfile='data/bin_output.txt', writepos=False, writedupes=False, sectionname='bin')[source]¶

Extract strings from ranges of a binary file.

The strings are written to a text file, or to an xliff translation file if binfile doesn’t have a .txt extension.

Parameters:

binrange – A (start, end) range, or a list of them.
readfunc – Function used to detect strings, called with (stream, encoding).
encoding (str) – Encoding passed to readfunc.
binin (str) – Path of the binary file.
binfile (str) – Path of the output text or xliff file.
writepos (bool) – Whether to write the positions of each string before it, for text file outputs.
writedupes (bool) – Whether to write one entry for every position a string is found at, instead of just the first one.
sectionname (str) – File entry name for xliff outputs.

Return type:

None

hacktools.nds.repackBIN(binrange, freeranges=[], readfunc=<function detectEncodedString>, writefunc=<function writeEncodedString>, encoding='shift_jis', comments='#', binin='data/extract/arm9.bin', binout='data/repack/arm9.bin', binfile='data/bin_input.txt', fixchars=[], pointerstart=33554432, injectstart=33554432, fallbackf=None, injectfallback=0, nocopy=False, sectionname='bin', preformat=None, postformat=None)[source]¶

Repack translated strings into a binary file.

The strings are read from a text file, or from an xliff translation file if binfile doesn’t have a .txt extension, and repacked with common.repackBinaryStrings.

Parameters:

binrange – A (start, end) range, or a list of them.
freeranges (list) – List of (start, end) ranges that can hold relocated strings.
readfunc – Function used to detect strings, called with (stream, encoding).
writefunc – Function used to write strings, called with (stream, string, maxlen, encoding).
encoding (str) – Encoding passed to readfunc and writefunc.
comments (str) – Comment marker used in the text file.
binin (str) – Path of the original binary file.
binout (str) – Path of the output binary file.
binfile (str) – Path of the input text or xliff file.
fixchars (list) – List of (old, new) character replacements to apply.
pointerstart (int) – Value added to file offsets to form pointers, usually the load address of the binary.
injectstart (int) – Pointer start for free ranges marked with a boolean.
fallbackf (Stream | None) – Stream to write strings to when no free range has room.
injectfallback (int) – Pointer start of the fallback stream.
nocopy (bool) – Whether to skip copying binin to binout first.
sectionname (str) – File entry name for xliff inputs.
preformat – Function called on each detected string, returning (string, pre, post) data passed to postformat.
postformat – Function called with (translation, pre, post), returning the final string to write.

Returns:

The updated free ranges, or False if the input file is missing.

class hacktools.nds.BINSection(f, ramaddr, ramlen, fileoff, bsssize, real=True)[source]¶

Section of an arm9.bin binary, as listed in its copytable.

Parameters:

f (Stream) – Stream to read the section data from, or None to create a zero-filled section.
ramaddr (int) – RAM address the section is copied to.
ramlen (int) – Length of the section.
fileoff (int) – Offset of the section data in the file.
bsssize (int) – Size of the section bss.
real (bool) – Whether the section is listed in the copytable.

offset¶: Offset of the section data in the file.

length¶: Length of the section.

ramaddr¶: RAM address the section is copied to.

bsssize¶: Size of the section bss.

real¶: Whether the section is listed in the copytable.

data¶: Data of the section.

hacktools.nds.expandBIN(binin, binout, headerin, headerout, newlengths, injectpos)[source]¶

Expand arm9.bin, adding new sections to its copytable.

The code settings offset is read from the header, or searched with a heuristic if it’s not there. A new section is added for each of the given lengths, the copytable is rebuilt, and the new arm9 length is written in the header along with its updated checksum.

Parameters:

binin (str) – Path of the original arm9.bin file.
binout (str) – Path of the output arm9.bin file.
headerin (str) – Path of the original header file.
headerout (str) – Path of the output header file.
newlengths – Length of the new section, or a list of lengths.
injectpos – RAM address of the new section, or a list of addresses.

Returns:

The file offset of the last added section, or False on error.

class hacktools.nds.CompressionType(*values)[source]¶: Compression types supported by decompress() and compress().

hacktools.nds.decompress(f, complength)[source]¶

Decompress BIOS-compressed data from the current stream position.

The compression type and decompressed length are read from the 4-byte header before the data.

Parameters:

f (Stream) – Stream to read from.
complength (int) – Length of the compressed data.

Returns:

The decompressed data, or the raw data if the compression type is not supported.

Return type:

bytes

hacktools.nds.compress(data, type)[source]¶

Compress data with the given BIOS compression type.

The output starts with the 4-byte header holding the compression type and the decompressed length.

Parameters:

data (bytes) – Data to compress.
type (CompressionType) – Compression type to use.

Returns:

The compressed data, or the raw data if the compression type is not supported.

Return type:

bytes

hacktools.nds.decompressFile(infile, outfile)[source]¶

Decompress a BIOS-compressed file.

Parameters:

infile (str) – Path of the compressed file.
outfile (str) – Path of the output file.

Return type:

None

hacktools.nds.compressFile(infile, outfile, type)[source]¶

Compress a file with the given BIOS compression type.

Parameters:

infile (str) – Path of the file to compress.
outfile (str) – Path of the output file.
type (CompressionType) – Compression type to use.

Return type:

None

hacktools.nds.decompressBinary(infile, outfile)[source]¶

Decompress an arm9.bin or overlay file with ndspy.

Parameters:

infile (str) – Path of the compressed file.
outfile (str) – Path of the output file.

Return type:

None

hacktools.nds.compressBinary(infile, outfile, arm9=True)[source]¶

Compress an arm9.bin or overlay file with ndspy.

For arm9 files, the compressed size in the code settings is updated.

Parameters:

infile (str) – Path of the file to compress.
outfile (str) – Path of the output file.
arm9 (bool) – Whether the file is an arm9.bin, instead of an overlay.

Return type:

None