Materials Models and Tables

Materials, Models and Tables

Relevant source files

The following files were used as context for generating this wiki page:

This page details the implementation of FFXIV proprietary file parsers and manipulation modules within clarity.ffxiv, covering variable-length model path patching (mdlstrings.py and mdlpatch.py), game Excel tables (exd.py), and Image Change variant mapping tables (imcfile.py). These components bridge raw binary archives (sqpack) with asset upscaling and packaging pipelines.

1. Model Path Patching and String Tables

FFXIV .mdl model files contain a runtime section starting with a counts header followed by a contiguous blob of null-terminated strings (attributes, bones, material paths, shape names) clarity/ffxiv/mdlstrings.py:1-21. Because every mesh or component references these strings via fixed 32-bit byte offsets into the blob, replacing asset paths traditionally required maintaining exact byte-length parity clarity/ffxiv/mdlstrings.py:7-13.

The codebase provides clarity.ffxiv.mdlstrings to bypass length constraints by fully rebuilding the string blob, shifting offsets, and updating the model header's vertex and index buffer offsets accordingly clarity/ffxiv/mdlstrings.py:12-21.

Implementation Mechanics

Mdl Class (mdlpatch.py): Parses model header fields (HDR), vertex declarations (_decls), and runtime sections (_runtime) to validate file layouts and track offsets clarity/ffxiv/mdlpatch.py:53-183.
read(raw) (mdlstrings.py): Extracts the string blob and parses attribute, material, bone, and shape name arrays using absolute offset tables clarity/ffxiv/mdlstrings.py:48-67.
rewrite(raw, mapping) (mdlstrings.py): Reconstructs the string blob in its original order using a provided mapping dictionary clarity/ffxiv/mdlstrings.py:70-89. It recalculates blob length delta, repoints attribute, material, bone, and shape offset arrays, and shifts vertex/index buffer pointers in the file header and LOD records clarity/ffxiv/mdlstrings.py:90-127.

graph TD
    A["Raw Model Data (bytes)"].->B["mdlpatch.Mdl(raw)"]
    B --> C["mdlstrings.read(raw)"]
    C --> D["String Blob & Tables Parsing"]
    D --> E["mdlstrings.rewrite(raw, mapping)"]
    E --> F["Rebuild Blob with New Lengths"]
    F --> G["Recalculate Offsets & Delta"]
    G --> H["Patch Header & LOD Buffer Pointers"]
    H --> I["Patched Model Binary (bytes)"]

    style A fill:#fff,stroke:#000,stroke-width:2px
    style I fill:#fff,stroke:#000,stroke-width:2px

Sources: clarity/ffxiv/mdlstrings.py:1-127, clarity/ffxiv/mdlpatch.py:53-183

2. Game Tables: Excel Data (`exd.py`) and Image Change (`imcfile.py`)

Game metadata tables reside in big-endian Excel format (.exh / .exd) and equipment variant definition files (.imc).

Excel Headers and Data (`exd.py`)

Exh Class: Parses the big-endian EXHF header file, extracting version info, data offsets, column definitions, data page ranges, and supported languages clarity/ffxiv/exd.py:6-30.
Exd Class: Parses EXDF data pages, indexing absolute file offsets by row ID (rid) clarity/ffxiv/exd.py:32-43.
row(rid): Decodes fixed-size columns, bitfields, and variable-length string pointers (relative to string blobs) into native Python types clarity/ffxiv/exd.py:44-84.
load_sheet(gd, name, language): Resolves and loads corresponding sheet headers and language-suffixed data pages from the game data accessor clarity/ffxiv/exd.py:86-95.

Image Change Tables (`imcfile.py`)

Equipment variants map to specific material folders, decals, and VFX identifiers via .imc files clarity/ffxiv/imcfile.py:1-6.

SLOT_PART Mapping: Maps equipment slots (met, top, glv, dwn, sho, ear, nek, wrs, rir, ril) to internal bitmask part indices clarity/ffxiv/imcfile.py:10-21.
ImcEntry Class: Stores material_id, decal_id, vfx_id, and attribute_and_sound words, exposing properties for attribute masks and sound IDs clarity/ffxiv/imcfile.py:24-52.
ImcFile Class: Parses count headers, part bitmasks (part_mask), and variant entry matrices clarity/ffxiv/imcfile.py:55-74.
entry(variant, slot): Resolves 1-based item variants (stored in Item.ModelMain) to specific ImcEntry instances based on part presence clarity/ffxiv/imcfile.py:75-87.

graph TD
    J["GameData Accessor"] --> K["exd.load_sheet()"]
    K --> L["Exh (Header Parsing)"]
    K --> M["Exd (Row Indexing & Decoding)"]
    J --> N["imcfile.load()"]
    N --> O["ImcFile (Variant Matrix & Part Mask)"]
    O --> P["ImcEntry (Material/Decal/VFX ID)"]

    style J fill:#fff,stroke:#000,stroke-width:2px
    style M fill:#fff,stroke:#000,stroke-width:2px
    style P fill:#fff,stroke:#000,stroke-width:2px

Sources: clarity/ffxiv/exd.py:1-95, clarity/ffxiv/imcfile.py:1-93, tests/test_exd.py:1-159, tests/test_imcfile.py:1-142