Module libxivdat::xiv_macro

Contains the high-level toolkit for working with macro files, MACRO.DAT and MACROSYS.DAT. This module contains two equivalent implementations: Macro, read_macro(), and read_macro_content() for working with files on disk and MacroData, as_macro(), and as_macro_vec() for working with pre-allocated byte arrays and `SectionData.

Enabled by feature macro.

Examples

Reading a macro file

use libxivdat::xiv_macro::read_macro_content;
use libxivdat::xiv_macro::icon::MacroIcon;

let macro_contents = read_macro_content("./resources/TEST_MACRO.DAT").unwrap();

assert_eq!(macro_contents[0].title, "0");
assert_eq!(macro_contents[0].lines[0], "DefaultIcon");
assert_eq!(macro_contents[0].get_icon().unwrap(), MacroIcon::DefaultIcon);

assert_eq!(macro_contents[1].title, "1");
assert_eq!(macro_contents[1].lines[0], "DPS1");
assert_eq!(macro_contents[1].get_icon().unwrap(), MacroIcon::DPS1);

Writing a macro file

Macro files use variable-length Sections to store data on disk, so it is not possible to easily overwrite a single macro in-place. The recommended approach to modifying macros is to read and write the entire file as a block.

use libxivdat::dat_file::write_content;
use libxivdat::xiv_macro::{read_macro_content, to_writeable_bytes, Macro};
use libxivdat::xiv_macro::icon::MacroIcon;


let mut macro_vec = read_macro_content("./resources/TEST_MACRO.DAT").unwrap();
// Replace macro #0 with a new macro. Macro::new will enforce the game's specs for macros.
macro_vec[0] = Macro::new(
    String::from("libxivdat was here"),
    vec![String::from("/sh I <3 libxivdat!!!")],
    MacroIcon::SymbolExclamation
).unwrap();

// Write it back out to a file. to_writeable_bytes will validate every macro in the vector.
let out_bytes = to_writeable_bytes(&macro_vec).unwrap();
write_content(&out_path, &out_bytes);

Modules

icon

Contains MacroIcon, an enumeration of all valid macro icons and the helper functions macro_icon_to_key_and_id() and macro_icon_from_key_and_id() for conversions between enum values and raw Section contents.

Structs

Macro

Resource definition for a Final Fantasy XIV macro. Macro owns its constituent data and is returned from helper functions like read_macro(). To build a section with refrences to a pre-allocated buffer, use MacroData.

MacroData

Resource definition for a Final Fantasy XIV macro. MacroData is used to build sections with references to pre-allocated buffers. To build a section that owns its own data, use Macro.

Constants

EXPECTED_ITEM_COUNT

The number of Macro items expected in a valid macro file.

SECTION_TAG_ICON

The Section tag for macro icon ids.

SECTION_TAG_KEY

The Section tag for macro icon keys.

SECTION_TAG_LINE

The Section tag for macro icon lines.

SECTION_TAG_TITLE

The Section tag for macro titles.

Functions

as_macro

Interprets a byte slice as MacroData.

as_macro_vec

Interprets a byte slice as a block of MacroData, returning a Vec of them.

as_writeable_bytes

Returns a byte vector representing a slice of MacroData. This can then be written back to a a file using write_content(). This function validates each macro. Additionally, the slice will be padded with empty macros to 100 (EXPECTED_ITEM_COUNT) items if it is shorter.

as_writeable_bytes_unsafe

Returns a byte vector representing a slice of MacroData. This can then be written back to a a file using write_content().

read_macro

Reads the next Macro from a DATFile.

read_macro_content

Reads all Macros from a specified DAT file, returning a Vec of them. This performs only one read operation on the underlying file, loading the entire content into memory to prevent repeat file access. This is similar to read_content(), but returns a Vec<Macro> instead of raw bytes. A valid macro file should always contain 100 macros, but this function will attempt to read files of other sizes.

read_macro_content_unsafe

Reads all Macros from a specified DAT file, returning a Vec of them. This performs only one read operation on the underlying file, loading the entire content into memory to prevent repeat file access. This is similar to read_content(), but returns a Vec<Macro> instead of raw bytes. A valid macro file should always contain 100 macros, but this function will attempt to read files of other sizes. This does not check that the file is a macro file.

read_macro_unsafe

Reads the next Macro from a DATFile. This does not check that the target file is a macro file.

to_writeable_bytes

Returns a byte vector representing a slice of Macros. This can then be written back to a a file using write_content(). This function validates each macro. Additionally, the slice will be padded with empty macros to 100 (EXPECTED_ITEM_COUNT) items if it is shorter.

to_writeable_bytes_unsafe

Returns a byte vector representing a slice of Macros. This can then be written back to a a file using write_content().