FtlDat - itb-community/ITB-ModLoader Wiki

Table of Contents

 

FtlDat

A class used for dealing with .dat archive files, providing several useful abstractions and functionalities.

Keep in mind that this is an internal mod loader API that is generally not intended for usage by regular mods.
For functions that mods should use for dealing with assets, see modApi | Assets

Memory usage

When loaded from an existing .dat archive, all of its contents are loaded into memory. At the time of writing, the vanilla resource.dat file takes around 347MB on disk, so that's also the approximate amount of RAM that an FtlDat instance loaded from it is going to take.

As such, it is important to:

  • Create new instances of FtlDat as infrequently as possible,
  • Immediately destroy them once they're no longer needed, using destroy.

Usage notes

General usage pattern is as follows:

local ftldat = FtlDat("resources/resource.dat")

-- modify the archive using ftldat:put_x
ftldat:put_entry_string("some/file.txt", "Stuff")

-- write out the modified archive
ftldat:write("resources/resource.dat")

-- cleanup
ftldat:destroy()

For regular usage, the put_entry_file function should be sufficient, since it is rare that mods need to dynamically create a file's content. For these more advanced cases, put_entry_string and put_entry_byte_array are more suitable.

For some reason, Lua has some trouble with large strings that describe contents of binary files, such as images, and tends to crash. As such, for dealing with images in cases where put_entry_file is insufficient, the put_entry_byte_array is preferable. FtlDat by itself doesn't provide any abstraction over byte arrays.

 

(constructor)

Signature: FtlDat FtlDat(path)

Argument name Type Description
path string Path to a .dat file. Optional.

Creates an instance of FtlDat class, which is an in-memory representation of a .dat file.

If path argument is provided, the instance will contain data from the specified archive. If path points to a file that does not exist, an error will be thrown. If path is nil, the instance will represent a new, empty archive that contains no data.

Example:

local ftldat = FtlDat("resources/resource.dat")

 

remove_all_files

Signature: void remove_all_files()

Removes all files from this FtlDat archive.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:remove_all_files()

 

write

Signature: void write(outputPath)

Argument name Type Description
outputPath string Path to the file in which the contents of the .dat archive will be written

Writes out the data currently stored in this FtlDat instance to the specified file. Creates a new file if it doesn't exist yet, and overwrites the file if it already exists.

Example:

local ftldat = FtlDat("resources/resource.dat")

 

put_entry_string

Signature: void put_entry_string(innerPath, content)

Argument name Type Description
innerPath string Path to the file within the .dat archive
content string Content of the file, in the form of a string

Sets the content of the file at the specified innerPath to the specified content. Creates a new entry in the FtlDat instance if it doesn't already exist, and overwrites it if it does.

This method is not suited to adding large file entries, such as images. Instead, use put_entry_byte_array or put_entry_file.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:put_entry_string("path/to/some_file.txt", "This will be stored inside the file")

 

put_entry_byte_array

Signature: void put_entry_byte_array(innerPath, byteArray)

Argument name Type Description
innerPath string Path to the file within the .dat archive
byteArray table Content of the file, in the form of a byte array

Sets the content of the file at the specified innerPath to the specified content. Creates a new entry in the FtlDat instance if it doesn't already exist, and overwrites it if it does.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:put_entry_byte_array("path/to/some_binary_file.bin", { 35, 87, 123 })

 

put_entry_file

Signature: void put_entry_file(innerPath, sourcePath)

Argument name Type Description
innerPath string Path to the file within the .dat archive
sourcePath string Path to the file on the file system, whose content will be used as the entry's content

Sets the content of the file at the specified innerPath to the specified sourcePath file's content. Creates a new entry in the FtlDat instance if it doesn't already exist, and overwrites it if it does.

This immediately reads the specified source file, and stores its content in the entry within the FtlDat instance.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:put_entry_file("img/units/my_unit_image.png", "path/to/my_mod/my_unit_image.png")

 

file_exists

Signature: boolean file_exists(innerPath)

Argument name Type Description
innerPath string Path to the file within the .dat archive

Returns true if an entry with the specified innerPath exists within this FtlDat instance, false otherwise.

Example:

local ftldat = FtlDat("resources/resource.dat")
LOG(ftldat:file_exists("some/file.txt"))        -- prints false

ftldat:put_entry_string("some/file.txt", "Stuff")
LOG(ftldat:file_exists("some/file.txt"))        -- prints true

 

entry_content_string

Signature: string entry_content_string(innerPath)

Argument name Type Description
innerPath string Path to the file within the .dat archive

Returns the content of the entry at the specified innerPath within this FtlDat instance, as a string. This may or may not work if the entry's content was originally added as a byte array.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:put_entry_string("some/file.txt", "Stuff")

local content = ftldat:entry_content_string("some/file.txt")
LOG(content) -- prints "Stuff"

 

entry_content_byte_array

Signature: table entry_content_string(innerPath)

Argument name Type Description
innerPath string Path to the file within the .dat archive

Returns the content of the entry at the specified innerPath within this FtlDat instance, as a byte array. This may or may not work if the entry's content was originally added as a string.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:put_entry_string("some/file.bin", { 35, 87, 123 })

local content = ftldat:entry_content_string("some/file.txt")
LOG(content) -- prints "Stuff"

 

inner_paths

Signature: table inner_paths()

Returns a table list of all inner paths within this FtlDat instance.

Example:

local ftldat = FtlDat("resources/resource.dat")
for index, innerPath in ipairs(ftldat:inner_paths()) do
    LOG(index, innerPath)
end

 

extract_file

Signature: void extract_file(innerPath, destinationPath)

Argument name Type Description
innerPath string Path to the file within the .dat archive
destinationPath string Path on the file system, to which the entry will be extracted

Extracts the entry at the specified innerPath from this FtlDat instance, and saves it to the specified destinationPath.

Example:

local ftldat = FtlDat("resources/resource.dat")
ftldat:extract_file("img/units/player/mech_punch.png", "resources/unpacked/mech_punch.png")

 

destroy

Signature: void destroy()

Sets the internal userdata reference to nil and invokes collectgarbage(), so that Lua immediately frees up all memory taken up by this FtlDat instance. Once this function is called, this FtlDat instance is no longer usable.

 

Lexicon

byte array

A byte array is a table of u8 (0-255, inclusive) integer numbers, eg. { 35, 87, 123 }.