FFXIV Game Data Layer

Relevant source files

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

The clarity/ffxiv package provides a standalone, dependency-free Python implementation for reading and writing FINAL FANTASY XIV proprietary binary formats directly from sqpack archives clarity/ffxiv/init.py:1-9. It bypasses external dependencies like .NET runtimes or TexTools, enabling direct asset inspection, texture decoding, material modification, and model patching.

For details on individual sub-topics, refer to the child pages:

4.1 SQPack Archive Access

The sqpack.py module implements a read-only parser for FFXIV Win32/DX11 archive files clarity/ffxiv/sqpack.py:1-9. It calculates path hashes using a custom bitwise-NOT CRC-32 implementation clarity/ffxiv/sqpack.py:40-44 to locate assets across base game and expansion repositories (ffxiv, ex1 through ex5) clarity/ffxiv/sqpack.py:37-97.

The GameData class acts as the main entry point for path resolution and file extraction clarity/ffxiv/sqpack.py:113-169. Process-wide access is managed via the game() singleton, which automatically locates the game installation using environment variables or standard paths clarity/ffxiv/init.py:44-55.

graph TD
    A["game()"] --> B["GameData"]
    B --> C["Repository"]
    C --> D["Index"]
    C --> E[".win32.dat file"]
    D --> F["Index.decode()"]
    F --> E

Figure 4.1: SQPack archive resolution flow using codebase components.

Sources: clarity/ffxiv/sqpack.py:1-169, clarity/ffxiv/__init__.py:44-55

4.2 Texture Formats: Decoding and Writing

Texture manipulation spans four core modules. tex.py parses .tex headers and calculates mipmap offsets clarity/ffxiv/tex.py:1-50. texdecode.py decodes texture surfaces into NumPy arrays, delegating to texture2ddecoder for BC6H/BC7 formats while providing pure-Python fallbacks for BC1, BC3, BC4, and BC5 blocks clarity/ffxiv/texdecode.py:1-117.

graph TD
    A["TexHeader"] --> B["texdecode.decode()"]
    B --> C{"Format Type"}
    C -->|BC7/BC6H| D["texture2ddecoder"]
    C -->|BC1-BC5| E["_bc1_blocks / _bc_alpha_plane"]
    D --> F["NumPy RGBA Array"]
    E --> F
    F --> G["texwrite.py / bc7enc.py"]

Figure 4.2: Texture decoding and serialization mapping.

texwrite.py handles .tex file serialization, and bc7enc.py provides a pure-Python BC7 encoder clarity/ffxiv/init.py:11.

For details, see Texture Formats: Decoding and Writing.

Sources: clarity/ffxiv/tex.py:1-50, clarity/ffxiv/texdecode.py:1-117, clarity/ffxiv/__init__.py:1-11

4.3 Materials, Models and Tables

Metadata and asset structures are parsed and modified through dedicated file handlers:

mtrl.py: Reads and writes .mtrl material files, exposing 32x32 colour tables (rows) and managing migrations from legacy shaders (characterlegacy.shpk) to Dawntrail shaders (character.shpk) clarity/ffxiv/mtrl.py:1-112.
mdlpatch.py and mdlstrings.py: Handle model string table parsing and vertex path patching clarity/ffxiv/init.py:1-11.
exd.py and imcfile.py: Parse game Excel tables (.exd) and variant mapping files (.imc) clarity/ffxiv/init.py:1-11.