-
Notifications
You must be signed in to change notification settings - Fork 18
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
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
.
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.
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")
Signature: void remove_all_files()
Removes all files from this FtlDat archive.
Example:
local ftldat = FtlDat("resources/resource.dat")
ftldat:remove_all_files()
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")
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")
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 })
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")
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
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"
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"
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
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")
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.