common

Common utilities shared by all the platform modules.

Includes the Stream class for binary I/O, CLI bootstrapping for tools, logging, text section and XLIFF translation files, string extraction and repacking, folder and patching helpers, and texture utilities.

class hacktools.common.Stream(fpath='', mode='m', little=True)

Endian-aware binary stream, wrapping a file or an in-memory buffer.

The underlying file is opened when entering the context manager. Most read and write methods have an At variant that operates at the given position and restores the current one afterwards.

Parameters:

• fpath (str) – Path of the file to open, unused for memory streams.

• mode (str) – Mode passed to open, or “m” for an in-memory stream.

• little (bool) – Whether the stream is little endian.

f

The underlying file object, or the file path before opening.

mode

The mode the stream was created with.

endian

Endianness prefix used for struct operations, “<” or “>”.

half

Nibble buffered by readHalf() and writeHalf(), or None.

close()

Close the underlying file.

Return type:

None

tell()

Return the current position in the stream.

Return type:

int

seek(pos, whence=0)

Move the current position of the stream.

Parameters:

• pos (int) – Offset to move to, relative to whence.

• whence (int) – 0 for absolute, 1 for relative, 2 for relative to the end.

Return type:

None

read(n=-1)

Read n bytes, or all the remaining ones.

Parameters:

n (int) – Number of bytes to read, or -1 to read until the end.

Returns:

The data that was read.

Return type:

bytes

readAt(pos, n=-1)

Read n bytes at pos, restoring the current position afterwards.

Parameters:

• pos (int) – Position to read at.

• n (int) – Number of bytes to read, or -1 to read until the end.

Returns:

The data that was read.

Return type:

bytes

write(data)

Write data to the stream.

Parameters:

data (bytes) – Data to write.

Return type:

None

writeAt(pos, data)

Write data at pos, restoring the current position afterwards.

Parameters:

• pos (int) – Position to write at.

• data (bytes) – Data to write.

Return type:

None

peek(n)

Read n bytes without advancing the current position.

Parameters:

n (int) – Number of bytes to read.

Returns:

The data that was read.

Return type:

bytes

writeLine(data)

Write a string followed by a line feed, for text mode streams.

Parameters:

data (str) – String to write.

Return type:

None

setEndian(little)

Set the endianness of the stream.

Parameters:

little (bool) – Whether the stream is little endian.

Return type:

None

swapEndian()

Switch the stream between little and big endian.

Return type:

None

readLong()

Read a signed 64-bit integer.

Return type:

int

readLongAt(pos)

Read a signed 64-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readULong()

Read an unsigned 64-bit integer.

Return type:

int

readULongAt(pos)

Read an unsigned 64-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readInt()

Read a signed 32-bit integer.

Return type:

int

readIntAt(pos)

Read a signed 32-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readUInt()

Read an unsigned 32-bit integer.

Return type:

int

readUIntAt(pos)

Read an unsigned 32-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readFloat()

Read a 32-bit float.

Return type:

float

readFloatAt(pos)

Read a 32-bit float at pos, restoring the current position.

Parameters:

pos (int)

Return type:

float

readDouble()

Read a 64-bit float.

Return type:

float

readDoubleAt(pos)

Read a 64-bit float at pos, restoring the current position.

Parameters:

pos (int)

Return type:

float

readShort()

Read a signed 16-bit integer.

Return type:

int

readShortAt(pos)

Read a signed 16-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readUShort()

Read an unsigned 16-bit integer.

Return type:

int

readUShortAt(pos)

Read an unsigned 16-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readByte()

Read an unsigned 8-bit integer.

Return type:

int

readByteAt(pos)

Read an unsigned 8-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readSByte()

Read a signed 8-bit integer.

Return type:

int

readSByteAt(pos)

Read a signed 8-bit integer at pos, restoring the current position.

Parameters:

pos (int)

Return type:

int

readHalf(big=False)

Read a nibble, buffering the byte it belongs to.

The first call reads and buffers a full byte, the second one consumes the remaining nibble.

Parameters:

big (bool) – Whether to read the high nibble of a new byte first.

Returns:

The nibble that was read.

Return type:

int

readZeros(size)

Skip zero bytes, stopping at the first non-zero byte or at size.

Parameters:

size (int) – Position to stop at.

Return type:

None

readBytes(n, upper=False)

Read n bytes and format them as space-separated hex values.

Parameters:

• n (int) – Number of bytes to read.

• upper (bool) – Whether to use uppercase hex digits.

Returns:

The formatted string, with a trailing space.

Return type:

str

readString(length)

Read a fixed-length string, one character per byte.

Null bytes are skipped, while the 0x82 and 0x86 control characters are replaced with a space.

Parameters:

length (int) – Number of bytes to read.

Returns:

The string that was read.

Return type:

str

readStringAt(pos, length)

Read a fixed-length string at pos, restoring the current position.

Parameters:

• pos (int)

• length (int)

Return type:

str

readNullString()

Read a null-terminated string, one character per byte.

Return type:

str

readNullStringAt(pos)

Read a null-terminated string at pos, restoring the current position.

Parameters:

pos (int)

Return type:

str

readEncodedString(encoding='utf-8')

Read a null-terminated string decoded with the given encoding.

Parameters:

encoding (str) – Encoding to decode the string with.

Returns:

The decoded string.

Return type:

str

readEncodedStringAt(pos, encoding='utf-8')

Read a null-terminated encoded string at pos, restoring the current position.

Parameters:

• pos (int)

• encoding (str)

Return type:

str

writeLong(num)

Write num as a signed 64-bit integer.

Parameters:

num (int)

Return type:

None

writeLongAt(pos, num)

Write num as a signed 64-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeULong(num)

Write num as an unsigned 64-bit integer.

Parameters:

num (int)

Return type:

None

writeULongAt(pos, num)

Write num as an unsigned 64-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeInt(num)

Write num as a signed 32-bit integer.

Parameters:

num (int)

Return type:

None

writeIntAt(pos, num)

Write num as a signed 32-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeUInt(num)

Write num as an unsigned 32-bit integer.

Parameters:

num (int)

Return type:

None

writeUIntAt(pos, num)

Write num as an unsigned 32-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeFloat(num)

Write num as a 32-bit float.

Parameters:

num (float)

Return type:

None

writeFloatAt(pos, num)

Write num as a 32-bit float at pos, restoring the current position.

Parameters:

• pos (int)

• num (float)

Return type:

None

writeDouble(num)

Write num as a 64-bit float.

Parameters:

num (float)

Return type:

None

writeDoubleAt(pos, num)

Write num as a 64-bit float at pos, restoring the current position.

Parameters:

• pos (int)

• num (float)

Return type:

None

writeShort(num)

Write num as a signed 16-bit integer.

Parameters:

num (int)

Return type:

None

writeShortAt(pos, num)

Write num as a signed 16-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeUShort(num)

Write num as an unsigned 16-bit integer.

Parameters:

num (int)

Return type:

None

writeUShortAt(pos, num)

Write num as an unsigned 16-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeByte(num)

Write num as an unsigned 8-bit integer.

Parameters:

num (int)

Return type:

None

writeByteAt(pos, num)

Write num as an unsigned 8-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeSByte(num)

Write num as a signed 8-bit integer.

Parameters:

num (int)

Return type:

None

writeSByteAt(pos, num)

Write num as a signed 8-bit integer at pos, restoring the current position.

Parameters:

• pos (int)

• num (int)

Return type:

None

writeHalf(num, little=True)

Write a nibble, buffering it until a full byte can be written.

Parameters:

• num (int) – Nibble to write.

• little (bool) – Whether the first nibble of each byte is the low one.

Return type:

None

writeString(str)

Write a string encoded as ASCII.

Parameters:

str (str) – String to write.

Return type:

None

writeZero(num)

Write num zero bytes.

Parameters:

num (int) – Number of bytes to write.

Return type:

None

writeBytes(byte, num)

Write num copies of a byte value.

Parameters:

• byte (int) – Byte value to write.

• num (int) – Number of copies to write.

Return type:

None

truncate()

Truncate the underlying file at the current position.

Return type:

None

class hacktools.common.FileFilter(name='')

Logging filter that hides progress messages starting with “prg-“.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

hacktools.common.setupFileLogging(log)

Set up logging to the tool.log file.

Parameters:

log (bool) – Whether to also log debug messages.

Return type:

None

hacktools.common.logMessage(*messages)

Log a message at info level, also shown on the console.

Parameters:

*messages – Values joined with a space.

Return type:

None

hacktools.common.logDebug(*messages)

Log a message at debug level, only written to the log file.

Parameters:

*messages – Values joined with a space.

Return type:

None

hacktools.common.logWarning(*messages)

Log a warning message, only written to the log file.

Parameters:

*messages – Values joined with a space.

Return type:

None

hacktools.common.logError(*messages)

Log a message at error level, also shown on the console.

Parameters:

*messages – Values joined with a space.

Return type:

None

hacktools.common.varsHex(o)

Format the attributes of an object like vars, but with ints as hex.

Parameters:

o – Object to format.

Returns:

A string with the int, str and list attributes of the object.

Return type:

str

hacktools.common.showProgress(iterable)

Wrap an iterable with a progress bar, if tqdm is available.

Parameters:

iterable – Iterable to wrap.

Returns:

The wrapped iterable, or the original one if tqdm is not available.

hacktools.common.toHex(byte, upper=False)

Format a number as hex, without the 0x prefix and padded to two digits.

Parameters:

• byte (int) – Number to format.

• upper (bool) – Whether to use uppercase hex digits.

Returns:

The formatted string, with a minus sign in front if negative.

Return type:

str

hacktools.common.isAscii(s)

Check if a string only contains printable ASCII characters.

Parameters:

s (str) – String to check.

Returns:

True if no character is a control code or above ASCII 127.

Return type:

bool

hacktools.common.codeToChar(code, encoding='shift_jis', little=True)

Convert a character code to a string.

Parameters:

• code (int) – Character code, ASCII if below 128, 2-byte encoded otherwise.

• encoding (str) – Encoding used for 2-byte codes.

• little (bool) – Byte order of 2-byte codes.

Returns:

The decoded character, or an empty string if it can’t be decoded.

Return type:

str

hacktools.common.loadTable(tablefile)

Load a replacement table file into the global table dictionary.

Parameters:

tablefile (str) – Path of the table file, with one key=value pair per line.

Return type:

None

hacktools.common.shiftPointer(pointer, pointerdiff)

Shift a pointer by the length differences that apply before it.

Parameters:

• pointer (int) – Original pointer value.

• pointerdiff (dict[int, int]) – Dictionary of position -> length difference.

Returns:

The pointer shifted by all the differences at earlier positions.

Return type:

int

hacktools.common.checkShiftJIS(first, second)

Check if two bytes form a valid 2-byte Shift-JIS character.

Parameters:

• first (int) – First byte.

• second (int) – Second byte.

Returns:

True if the bytes are a valid Shift-JIS sequence.

Return type:

bool

hacktools.common.openSection(file, filestart=1, fileend=10)

Open a text section file, concatenating numbered parts if split.

Parameters:

• file (str) – Path of the file, with a {} placeholder for the part number.

• filestart (int) – First part number to check.

• fileend (int) – Last part number to check.

Returns:

A file-like object with the file contents, or None if not found.

hacktools.common.getSectionNames(f)

Get the names of the !FILE: sections in an open section file.

Parameters:

f – File-like object to read from.

Returns:

The list of section names.

Return type:

list[str]

hacktools.common.getSection(f, title, comment='#', fixchars=[], justone=True, inorder=False)

Read the entries of a !FILE: section from an open section file.

Parameters:

• f – File-like object to read from.

• title (str) – Name of the section, or “” to read from the start.

• comment (str) – Comment marker, contents after it are ignored.

• fixchars (list) – List of (old, new) character replacements to apply.

• justone (bool) – Whether to stop at the next section, instead of merging all the sections with the same name.

• inorder (bool) – Whether to return entries in order instead of a dictionary.

Returns:

A dictionary of string -> list of translations, or a list of {“name”, “value”} entries if inorder is True.

hacktools.common.getSections(file, comment='#', fixchars=[], inorder=False)

Read all the sections from a section file.

Parameters:

• file (str) – Path of the section file.

• comment (str) – Comment marker, contents after it are ignored.

• fixchars (list) – List of (old, new) character replacements to apply.

• inorder (bool) – Whether sections contain ordered entries, see getSection().

Returns:

A dictionary of section name -> section entries.

Return type:

dict

hacktools.common.getSectionPercentage(section, chartot=0, transtot=0)

Count the total and translated characters in a section.

Parameters:

• section (dict) – Section dictionary returned by getSection().

• chartot (int) – Character count to add to.

• transtot (int) – Translated character count to add to.

Returns:

A tuple (chartot, transtot) with the updated counts.

Return type:

tuple[int, int]

hacktools.common.mergeSections(file1, file2, output, comment='#', fixchars=[])

Merge two section files, filling empty translations in file1 from file2.

Parameters:

• file1 (str) – Path of the main section file.

• file2 (str) – Path of the section file to take missing translations from.

• output (str) – Path of the merged output file.

• comment (str) – Comment marker, contents after it are ignored.

• fixchars (list) – List of (old, new) character replacements to apply.

Return type:

None

class hacktools.common.TranslationFile(path='')

Translation file in the XLIFF format used by Weblate.

Parameters:

path (str) – Path of the xliff file to load, or “” to create an empty one.

files

Dictionary of file name -> XML file element.

lookup

Dictionary of source text -> translation, filled by preloadLookup().

offlookup

Dictionary of offset -> source text, filled by preloadLookup().

offsets

Dictionary of file name -> list of offsets, filled by preloadOffsets().

chartot

Total character count, filled by preloadLookup().

transtot

Translated character count, filled by preloadLookup().

root

Root XML element.

mergeSection(path, filename='', section='', comments='#', fixchars=[])

Merge the translations from a section file into this file.

Parameters:

• path (str) – Path of the section file.

• filename (str) – Only merge into this file entry, or “” for all of them.

• section (str) – Name of the section to read, or “” to read from the start.

• comments (str) – Comment marker, contents after it are ignored.

• fixchars (list) – List of (old, new) character replacements to apply.

Return type:

None

addEntry(text, filename, offset, translation='', comment='')

Add a translation unit to a file, creating the file entry if needed.

Parameters:

• text (str) – Source text.

• filename (str) – Name of the file entry.

• offset (int) – Offset of the string, used as the unit ID.

• translation (str) – Translated text, if any.

• comment (str) – Note to attach to the unit, if any.

Return type:

None

preloadLookup(comments='#')

Fill the lookup dictionaries and the progress counts.

Parameters:

comments (str) – Comment marker, stripped from the translations.

Return type:

None

preloadOffsets()

Fill the offsets dictionary with the unit IDs of each file.

Return type:

None

getEntry(text, filename, offset)

Get the translation for a string.

Tries to match by offset first, then by source text in the same file entry, then by source text in the whole lookup.

Parameters:

• text (str) – Source text.

• filename (str) – Name of the file entry.

• offset (int) – Offset of the string.

Returns:

The translation, or “” if not found or not translated.

Return type:

str

setEntry(text, filename, offset, newtext)

Set the translation for a string, matched by offset or source text.

Parameters:

• text (str) – Source text.

• filename (str) – Name of the file entry.

• offset (int) – Offset of the string.

• newtext (str) – Translation to set.

Return type:

None

hasFile(filename)

Check if a file entry exists.

Parameters:

filename (str) – Name of the file entry.

Returns:

True if the file entry exists.

Return type:

bool

getProgress()

Return the translation percentage, as counted by preloadLookup().

Return type:

float

save(filename, dummy=False)

Save the translation file, formatted like Weblate would.

Parameters:

• filename (str) – Output path, parent folders are created if missing.

• dummy (bool) – Whether to add a dummy entry, to avoid saving an empty file.

Return type:

None

class hacktools.common.FontGlyph(start, width, length, char='', code=0, index=0)

Position and width information for a single font glyph.

start

Start offset of the glyph in the font.

width

Width of the glyph.

length

Horizontal space occupied by the glyph when drawn.

char

Character the glyph represents.

code

Character code.

index

Index of the glyph in the font.

hacktools.common.wordwrap(text, glyphs, width, codefunc=None, default=6, linebreak='|', sectionsep='>>', strip=True)

Word wrap text to fit a pixel width, based on glyph lengths.

Parameters:

• text (str) – Text to wrap.

• glyphs (dict[str, FontGlyph]) – Dictionary of character -> FontGlyph.

• width (int) – Maximum line width, in pixels.

• codefunc – Function called with (text, position) that returns the length of the control code at that position, or 0 if none.

• default (int) – Length of characters not found in glyphs.

• linebreak (str) – Line break marker.

• sectionsep (str) – Separator between sections that are wrapped independently.

• strip (bool) – Whether to strip whitespace from the wrapped lines.

Returns:

The wrapped text, with lines joined by linebreak.

Return type:

str

hacktools.common.centerLines(text, glyphs, width, codefunc=None, default=6, linebreak='|', centercode='<<')

Center the lines marked with centercode, by prepending spaces.

Parameters:

• text (str) – Text with the lines to center.

• glyphs (dict[str, FontGlyph]) – Dictionary of character -> FontGlyph.

• width (int) – Total width to center within, in pixels.

• codefunc – Function called with (text, position) that returns the length of the control code at that position, or 0 if none.

• default (int) – Length of characters not found in glyphs.

• linebreak (str) – Line break marker.

• centercode (str) – Marker at the start of the lines to center.

Returns:

The text with the marked lines centered.

Return type:

str

hacktools.common.readEncodedString(f, encoding='shift_jis', upper=False)

Read a null-terminated encoded string from a stream.

Line feeds are read as “|”, and invalid 2-byte sequences followed by 0x01 are kept as UNK(xxyy) markers.

Parameters:

• f (Stream) – Stream to read from.

• encoding (str) – Encoding used for 2-byte characters.

• upper (bool) – Whether UNK markers use uppercase hex digits.

Returns:

The decoded string.

Return type:

str

hacktools.common.detectEncodedString(f, encoding='shift_jis', startascii=[37], startenc=[], upper=False)

Try to read a null-terminated encoded string from a stream.

Parameters:

• f (Stream) – Stream to read from.

• encoding (str) – Encoding used for 2-byte characters.

• startascii (list) – ASCII bytes the string is allowed to start with.

• startenc (list) – (first, second) byte tuples allowed as unknown start codes.

• upper (bool) – Whether UNK markers use uppercase hex digits.

Returns:

The detected string, or “” if the data doesn’t look like one.

Return type:

str

hacktools.common.detectASCIIString(f, encoding='ascii', startascii=[])

Try to read a null-terminated ASCII string from a stream.

Parameters:

• f (Stream) – Stream to read from.

• encoding (str) – Unused, kept for compatibility with detectEncodedString().

• startascii (list) – Unused, kept for compatibility with detectEncodedString().

Returns:

The detected string, or “” if a non-ASCII byte is found.

Return type:

str

hacktools.common.writeEncodedString(f, s, maxlen=0, encoding='shift_jis', zerobytes=1)

Write an encoded string to a stream, terminated by zero bytes.

“|” characters are written as line feeds, and UNK(xxyy) markers as their raw bytes.

Parameters:

• f (Stream) – Stream to write to.

• s (str) – String to write.

• maxlen (int) – Maximum length in bytes, or 0 for no limit.

• encoding (str) – Encoding used for non-ASCII characters.

• zerobytes (int) – Number of zero bytes used as terminator.

Returns:

The number of bytes written, or -1 if the string doesn’t fit in maxlen.

Return type:

int

hacktools.common.extractBinaryStrings(infile, binranges, func=<function detectEncodedString>, encoding='shift_jis')

Extract encoded strings from ranges of a binary file.

Parameters:

• infile (str) – Path of the binary file.

• binranges (list) – List of (start, end) ranges to scan.

• func – Function used to detect strings, called with (stream, encoding).

• encoding (str) – Encoding passed to func.

Returns:

A tuple (strings, positions), where positions holds the list of offsets each string was found at.

Return type:

tuple[list[str], list[list[int]]]

class hacktools.common.BinaryPointer(old, new, str)

Old and new location of a string relocated by repackBinaryStrings().

old

Pointer to the original string location.

new

Pointer to the new string location.

str

The string the pointer refers to.

hacktools.common.repackBinaryStrings(section, infile, outfile, binranges, freeranges=None, readfunc=<function detectEncodedString>, writefunc=<function writeEncodedString>, encoding='shift_jis', pointerstart=0, injectstart=0, fallbackf=None, injectfallback=0, sectionname='bin', preformat=None, postformat=None, pointeralign=1)

Repack translated strings into ranges of a binary file.

Strings found in binranges are replaced in place when the translation fits. When it doesn’t and freeranges is given, the translation is written in one of those ranges instead, pointers to it are searched and updated in the whole file, and the freed space is added to the free ranges pool.

Parameters:

• section – Dictionary of translations, or a TranslationFile.

• infile (str) – Path of the original binary file.

• outfile (str) – Path of the output binary file, already copied from infile.

• binranges (list) – List of (start, end) ranges to scan.

• freeranges (list | None) – List of (start, end) ranges that can hold relocated strings. A range can have a third element with the pointer start to use for it, or a boolean to use injectstart.

• 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.

• 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, 0 to disable it.

• sectionname (str) – File entry name used when section is a TranslationFile.

• 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.

• pointeralign (int) – Alignment required for pointer matches, to skip false positives.

Returns:

A tuple (notfound, freeranges) with the list of BinaryPointer that weren’t found and the updated free ranges, or None if freeranges wasn’t given.

Return type:

tuple[list[BinaryPointer], list | None]

hacktools.common.makeFolder(folder, clear=True)

Create a folder, optionally deleting an existing one first.

Parameters:

• folder (str) – Path of the folder to create.

• clear (bool) – Whether to delete the existing folder first.

Return type:

None

hacktools.common.clearFolder(folder)

Delete a folder and its contents, clearing read-only flags.

Parameters:

folder (str) – Path of the folder to delete.

Return type:

None

hacktools.common.copyFolder(f1, f2)

Copy a folder, replacing the destination.

Parameters:

• f1 (str) – Path of the source folder.

• f2 (str) – Path of the destination folder.

Return type:

None

hacktools.common.mergeFolder(f1, f2)

Copy a folder into another, overwriting the files that exist in both.

Parameters:

• f1 (str) – Path of the source folder.

• f2 (str) – Path of the destination folder.

Return type:

None

hacktools.common.copyFile(f1, f2)

Copy a file, replacing the destination.

Parameters:

• f1 (str) – Path of the source file.

• f2 (str) – Path of the destination file.

Return type:

None

hacktools.common.makeFolders(path)

Create a folder and its parents, ignoring the ones that exist.

Parameters:

path (str) – Path of the folder to create.

Return type:

None

hacktools.common.getFiles(path, extensions=[])

List all the files in a folder, recursively.

Parameters:

• path (str) – Path of the folder to scan.

• extensions (str | list) – Extension or list of extensions to filter by.

Returns:

The file paths relative to path, sorted and with forward slashes.

Return type:

list[str]

hacktools.common.getFolders(path)

List all the subfolders in a folder, recursively.

Parameters:

path (str) – Path of the folder to scan.

Returns:

The folder paths relative to path, sorted and with forward slashes.

Return type:

list[str]

hacktools.common.bundledFile(name)

Get the path of a data file, supporting PyInstaller bundles.

Parameters:

name (str) – Name of the file.

Returns:

The file name, or its path in the PyInstaller temporary folder.

Return type:

str

hacktools.common.bundledExecutable(name)

Get the path of an executable, supporting PyInstaller bundles.

The .exe extension is stripped when not running on Windows.

Parameters:

name (str) – Name of the executable, with the .exe extension.

Returns:

The executable path, possibly in the PyInstaller temporary folder.

Return type:

str

hacktools.common.execute(cmd, show=True)

Run a command, logging its output.

Parameters:

• cmd (str) – Command line to run.

• show (bool) – Whether to log the output at info level instead of debug.

Return type:

None

hacktools.common.crcFile(f)

Calculate the CRC32 checksum of a file.

Parameters:

f (str) – Path of the file.

Returns:

The CRC32 checksum.

Return type:

int

hacktools.common.crc16(data)

Calculate the CRC16 checksum of some data, in the MODBUS variant.

Parameters:

data (bytes) – Data to checksum.

Returns:

The CRC16 checksum.

Return type:

int

hacktools.common.xdeltaPatch(patchfile, infile, outfile)

Create an xdelta patch, using pyxdelta or calling the xdelta executable externally.

Parameters:

• patchfile (str) – Path of the patch file to create.

• infile (str) – Path of the original file.

• outfile (str) – Path of the modified file.

Return type:

None

hacktools.common.ipsPatch(patchfile, infile, outfile)

Create an ips patch, using ips_util.

Parameters:

• patchfile (str) – Path of the patch file to create.

• infile (str) – Path of the original file.

• outfile (str) – Path of the modified file.

Return type:

None

hacktools.common.armipsPatch(file, defines={}, labels={})

Apply an armips patch, using pyarmips or calling the armips executable externally.

Parameters:

• file (str) – Path of the asm file.

• defines (dict) – Dictionary of symbol -> value, passed as -equ.

• labels (dict) – Dictionary of label -> value, passed as -definelabel.

Return type:

None

hacktools.common.deltaToFrame(delta, fps=30)

Convert a time delta to a frame count.

Parameters:

• delta – datetime.timedelta to convert.

• fps (int) – Frames per second.

Returns:

The number of frames, rounded up.

Return type:

int

hacktools.common.readPalette(p)

Convert a 15-bit BGR color to an opaque RGBA tuple.

Parameters:

p (int) – 15-bit color value.

Returns:

The (r, g, b, 255) tuple.

Return type:

tuple

hacktools.common.getColorDistance(c1, c2, checkalpha=False)

Calculate the Euclidean distance between two colors.

Parameters:

• c1 (tuple) – First color, as an RGB or RGBA tuple.

• c2 (tuple) – Second color, as an RGB or RGBA tuple.

• checkalpha (bool) – Whether to include the alpha channel.

Returns:

The distance between the colors.

Return type:

float

hacktools.common.sumColors(c1, c2, a=1, b=1, c=2)

Calculate the weighted sum (c1 * a + c2 * b) / c of two colors.

Parameters:

• c1 (tuple) – First color, as an RGBA tuple. The result keeps its alpha.

• c2 (tuple) – Second color, as an RGBA tuple.

• a (int) – Weight of the first color.

• b (int) – Weight of the second color.

• c (int) – Divisor of the weighted sum.

Returns:

The resulting RGBA tuple.

Return type:

tuple

hacktools.common.readRGB5A3(color)

Convert an RGB5A3 color to an RGBA tuple.

If the high bit is set the color is an opaque RGB555, otherwise it has a 3-bit alpha and 4-bit color channels.

Parameters:

color (int) – 16-bit color value.

Returns:

The (r, g, b, a) tuple.

Return type:

tuple

hacktools.common.readRGB5A1(color)

Convert an RGB5A1 color to an RGBA tuple.

Parameters:

color (int) – 16-bit color value.

Returns:

The (r, g, b, a) tuple, with a either 0 or 255.

Return type:

tuple

hacktools.common.getPaletteIndex(palette, color, fixtransp=False, starti=0, palsize=-1, checkalpha=False, zerotransp=True, backwards=False, logcolor=False)

Get the index of the palette color that best matches a color.

Parameters:

• palette (list) – List of RGBA color tuples.

• color (tuple) – RGBA color tuple to search for.

• fixtransp (bool) – Whether to skip the first palette entry when matching.

• starti (int) – Index of the first palette entry to consider.

• palsize (int) – Number of palette entries to consider, or -1 for all.

• checkalpha (bool) – Whether to compare the alpha channel too.

• zerotransp (bool) – Whether to return 0 for fully transparent colors.

• backwards (bool) – Whether to search the palette backwards.

• logcolor (bool) – Whether to log colors that aren’t matched exactly.

Returns:

The index of the exact color or of the closest one, relative to starti.

Return type:

int

hacktools.common.findBestPalette(palettes, colors)

Get the index of the palette that best matches a list of colors.

Parameters:

• palettes (list) – List of palettes, each a list of RGBA color tuples.

• colors (list) – List of RGBA color tuples to match.

Returns:

The index of the palette with the smallest total distance.

Return type:

int

hacktools.common.drawPalette(pixels, palette, width, ystart=0, transp=True)

Draw a palette as 5x5 pixel swatches, 8 per row.

Parameters:

• pixels – PIL pixel access object to draw on.

• palette (list) – List of RGBA color tuples.

• width (int) – X position to start drawing at, usually the image width.

• ystart (int) – Y position to start drawing at.

• transp (bool) – Whether to keep the alpha channel of the colors.

Returns:

The pixels object.

hacktools.common.flipTile(tile, hflip, vflip, tilewidth=8, tileheight=8)

Flip a tile horizontally and/or vertically.

Parameters:

• tile (list) – Flat list of tile values, one row after the other.

• hflip (bool) – Whether to flip the tile horizontally.

• vflip (bool) – Whether to flip the tile vertically.

• tilewidth (int) – Width of the tile.

• tileheight (int) – Height of the tile.

Returns:

The flipped tile, as a new list.

Return type:

list