FtlDat - itb-community/ITB-ModLoader GitHub Wiki

FtlDat

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.

FtlDat - itb-community/ITB-ModLoader GitHub Wiki

Table of Contents

FtlDat

Memory usage

Usage notes

(constructor)

remove_all_files

write

put_entry_string

put_entry_byte_array

put_entry_file

file_exists

entry_content_string

entry_content_byte_array

inner_paths

extract_file

destroy

`(constructor)`

`remove_all_files`

`write`

`put_entry_string`

`put_entry_byte_array`

`put_entry_file`

`file_exists`

`entry_content_string`

`entry_content_byte_array`

`inner_paths`

`extract_file`

`destroy`