ndspy.fnt: Filename Tables

ROM files (ndspy.rom) and NARC archives (ndspy.narc) both use the same format for filename tables. ndspy.fnt provides a consistent interface for these.

Warning

Some games (such as New Super Mario Bros.) load files by hardcoded file IDs rather than by their filenames. Thus, when editing filename tables, you should avoid changing existing file IDs unless you’re sure that the game loads files by their filenames.

A filename table is represented as a Folder. This class does not contain any file data; it merely defines the folder hierarchy, and names of folders and files. As such, this particular page of documentation page will use the terms “filename” and “file” rather interchangeably.

Filenames and file IDs

It’s important to understand how file IDs relate to filenames. Here’s an example directory structure showing both filenames and file IDs:

(root)/                             87
    barrier-skip.mp4                (87)
    sm64-upwarp.zip                 (88)
    books/                          89
        hyrule-historia.pdf         (89)
        ndspy-documentation.pdf     (90)
        lord-of-the-rings/          91
            book1.pdf               (91)
            book2.pdf               (92)
            book3.pdf               (93)
    songs/                          94
        smb3-athletic.mp3           (94)
        zeldas-lullaby.mp3          (95)

Folders have a “first ID” attribute (Folder.firstID) that specifies the ID of the first file within the folder; these are shown above as numbers without parentheses. The files within the folder then implicitly have ascending file IDs starting with that value; these are shown above as parenthesized numbers.

Files in a folder’s subfolders have IDs greater than those of the files directly in the folder. Files and folders are usually sorted in ASCIIbetical order, though that probably does not have to be the case.

File IDs referenced by a filename table do not always start at 0. ROMs, for instance, usually include overlays as unnamed files starting at ID 0, causing the filename table to begin at some higher file ID.

ndspy.fnt.load(fnt)

Create a Folder from filename table data. This is the inverse of save().

Parameters:

fnt (bytes) – The filename table data to parse.

Returns:

The root folder of the filename table.

Return type:

Folder

ndspy.fnt.save(root)

Generate a bytes object representing this root folder as a filename table. This is the inverse of load().

Parameters:

root (Folder) – The root folder of the filename table.

Returns:

The filename table data.

Return type:

bytes

class ndspy.fnt.Folder([folders[, files[, firstID]]])

A single folder within a filename table, or an entire filename table – ndspy does not make a distinction between these. It can contain subfolders (folders) and files (files).

All files within a folder implicitly have consecutive IDs. This is done by only specifying the ID of the first file in the folder (firstID). The second file in the folder then has file ID “firstID + 1”, the third has “firstID + 2”, etc. See the introduction to this page for a more thorough explanation.

Parameters:

• folders – The initial value for the folders attribute.

• files – The initial value for the files attribute.

• firstID – The initial value for the firstID attribute.

Note

For convenience, Folder supports indexing syntax (folder[key]):

• If the key is a int, indexing is equivalent to calling filenameOf().

• If the key is a str, indexing is equivalent to first calling idOf(), and then calling subfolder() if that returns None.

Thus, you can index by file ID to retrieve a filename, index by filename to get a file ID, and index by subfolder name to get a Folder instance.

Warning

Unless you know exactly what the filename table you’re parsing contains, it’s a good idea to explicitly use idOf() and subfolder() instead of indexing syntax for retrieving file IDs. Indexing syntax is the same for accessing both files and subfolders, so you may run into confusing problems if a subfolder with the same name as the file you’re looking for exists, or vice versa.

raises TypeError:

if a folder is indexed by something other than a str or int

raises KeyError:

if the given file ID or filename or subfolder name cannot be found

files

The files within this folder. The first one implicitly has file ID firstID, the second has file ID “firstID + 1”, and so on.

Type:

list of str

Default:

[]

firstID

The file ID of the first file within this folder (that is, the file ID of “files[0]”).

Type:

int

Default:

0

folders

The folders contained within this folder.

This is presented as a list of name-value pairs because collections.OrderedDict – the best choice for an order-preserving dictionary type – does not provide an easy way to adjust the order of its elements.

See also

ndspy.indexInNamedList(), ndspy.findInNamedList(), ndspy.setInNamedList() – helper functions you can use to find and replace values in this list.

Type:

list of (name, folder), where name is of type str and folder is of type Folder

Default:

[]

idOf(path)

Find the file ID for the given filename, or for the given file path (using / as the separator) relative to this folder.

See also

subfolder()

The equivalent function for finding folders instead of files.

Parameters:

path (str) – The filename or /-separated file path to look for.

Returns:

The file ID, or None if no such file is found.

Return type:

int or None

filenameOf(id)

Find the filename of the file with the given ID. If it exists in a subfolder, the filename will be returned as a path separated by forward slashes (/).

Parameters:

id (int) – The file ID to look for.

Returns:

The filename, or None if no file with that ID exists or if the file has no name.

Return type:

str or None

subfolder(path)

Find the Folder instance for the given subfolder name, or for the given folder path (using / as the separator) relative to this folder.

See also

idOf()

The equivalent function for finding files instead of folders.

Parameters:

path (str) – The subfolder name or /-separated folder path to look for.

Returns:

The folder, or None if no such folder is found.

Return type:

Folder or None