These are global settings applied to the entire VFX. Parameters such as Revised Scale and Revised Color can be used to adjust the size and color of an entire VFX without having to manually change the values of each individual component.

Also of note are the DrawLayer parameter, which controls when the VFX is drawn (such as BeforeSky or BeforeCloud), and the Clipbox settings.

Welcome to the XIV Dev Wiki. The idea is for this to be a single place where everything is located in a easy to access and searchable manner. Meta discussion and questions should be via issues on the GitHub repo that this documentation is pulled from: .

Final Fantasy XIV © 2010-2022 SQUARE ENIX CO., LTD. All Rights Reserved. We are not affiliated with SQUARE ENIX CO., LTD. in any way.

A timeline consists of a list of items, and a list of clips.

Items represent the creation of an emitter, while clips represent other actions, such as deleting particles. Although clips are not well understood, the are probably used for things such as hiding a vfx when a weapon is sheathed.

Clips

Clips must be triggered from items using the ClipNumber parameter. Usually, items which trigger clips will have EmitterIndex = -1.

Items are also where emitters are attached to binders and effectors using BinderIndex, EmitterIndex, and EffectorIndex. Items which were originally used for a cutscene or background will usually have BinderIndex = -1, which will cause them to not be rendered on player characters, so creating a binder and setting BinderIndex = 0 can fix this.

(TODO)

Emitters, as their name suggests, emit objects (either other emitters, or particles). They are triggered through timeline items, and can be moved in 3D space just like any other object. Unlike particles, emitters themselves are not visible. Emitters can also trigger a sound to play.

When an emitter creates another object, it can influence the properties of its child (such as color, scale, or position). Whether or not an emitter will influence its children is determined by parameters such as InfluenceCoordScale.

There are several types of emitters:

• Point

• Cone

• Cone Model (like a cone, but is subdivided across its axes)

• Sphere

• Sphere Model

• Model (any model, where objects can be emitted on its vertices)

Lobby

Chat

World

Binders determine where a vfx should be created, and its tracking behavior (should it follow a moving character).

There are several types of binders:

• Point (the most common, attach to a character, for example)

• Camera

• Spline

• Linear

Binders can be attached to caster or target, and have several "property" fields. Properties have the attribute BinderPointId, which allows a vfx to be bound to a specific point on a model (such as at the hilt of a sword). Binder points are specified in the skeleton's .mdl file, although this is not well-understood.

Life controls how long a particle lives, and can be somewhat counter-intuitive. Life = -1 means that the emitter lives forever, so it's animations will only trigger once. If you want an emitter to continuously loop (that is, die and get re-created), set it a value greater than -1.

(TODO)

Every VFX has exactly 1 Scheduler.

Schedulers control when Timelines are started, and have 2 components: a list of items, and a list of triggers. A scheduler can have an arbitrary number of items, but must have 12 triggers. Both items and triggers follow the same format:

bool Enabled
int StartTime
int TimelineIndex

Triggers

What the triggers represent is not understood, but they are probably each for a specific type of action, such as sheathing a weapon, getting hit, etc. Unused triggers have TimelineIndex = -1.

Items

Items function like triggers, but will start automatically without any additional input. If you are having trouble viewing a VFX, such as one which was originally used for a cutscene, it can often be useful to disable all the triggers, and instead exclusively use items to start timelines.

Data files are xxx.dat files generally located in the XIV client folder and sub folders at <..>\Documents\My Games\FINAL FANTASY XIV - A Realm Reborn\.

Character Creator Presets

The FFXIV Character Creator saves presets, when saving a character appearance at the end of character creation, in a file called FFXIV_CHARA_XX.dat where XX is the preset slot number from 01 to 40.

All data related to characters that have been used on the current machine is saved in a folder called FFXIV_CHRxxxx where xxxx is a unique ID for the character.

This folder contains *.dat files for character settings, hotbars and UI configuration, macros and so on, as well as a log folder containing the chat logs.

Excel is the relational data storage system that the game uses to store information, similarly to a relational database. The structure of EXL, EXH and EXD files are documented here.

RSF is very similar to except it works on file level.

Pseudocode

The procedure to generate a RSF file is as follows:

Effectors apply miscellaneous effects to emitters, particles, or the camera. In order to be used, they must either be triggered through a , or an .

There are several types of effectors:

• Point light

• Directional light

(TODO)

Few things to note:

• Just like Super Mario 64, y component of coordinate represents altitude. Think z component as depth as in Z-buffer.

(TODO)

Particles are the visible component of a VFX, and are created exclusively by emitters. They are similar to emitters in that they can be positioned in 3D space.

There are several types of particles:

• Decal

• Decal Ring

• Disc

• Laser

• Light Model

• Line

• Model

• Parameter

• Polygon

• Polyline (line made of )

• Powder (used for small particles, such as the dust which some weapons create)

• Windmill

• Quad (a 1x1 square)

Particles can have textures mapped onto them using several different types of nodes (covered later).

Simple Animations

Sometimes, a particle does not require complex animations, and can use the SimpleAnimations node instead (in order for it to work, the SimpleAnimationsEnabled must be True) This is often used for Powder particles, which often have very basic animations due to their size and number.

Particle Textures

There are several types of texture nodes which can be applied to a particle. Most texture nodes will have a TextureIndex. This determines which texture will be used as a color, normal map, etc. TextureColor1 is especially important as it has MaskTextureIndex, which determines which parts of the particle will be transparent.

Most texture nodes will also have a UVSetIndex (UV Sets are discussed later).

UV Sets

UV Sets are contained within particles, and are used to manipulate textures. This primarily involves scaling, rotating, and offsetting a texture. For example, most aura or fire VFXs will use a UV Set to animate a texture so that it "scrolls" across the particle, creating the illusion of a moving flame or energy aura.

The packet sent from the server upon entering the instance is as follows:

// sent for each rsv string
struct RsvPkt {
  UInt32 value_size;    // len(without_nul_char(value))
  char key_str[32];     // null terminated
  char value_str[1024]; // null terminated
}

Pseudocode

void OnRsvPktreceived(RsvPkt pkt) {
  // e.g.) "_rsv_29752_-1_1_C0_0Action"
  var key = ReadCString(pkt.key_str);
  // e.g.) "Alternative End"
  var val = ReadCString(pkt.value_str);

  rsvMap[key] = val;
}

string GetActionName(int row) {
  var val = table[row, col];

  if (rsvMap.Contains(val)) {
    var key = val;
    return rsvMap[key];
  } else {
    return val;
  }
}

Links

*[Last updated FFXIV 6.58]

This folder, called FFXIV_CHRxxxx where xxxx is a unique ID for the character, contains all of the client side data related to one or another of the characters played.

Following is a list of the data files found in this folder.

Note: most of the information in here is taken from this reddit post without doublechekcing for now.

TODO: figure out the format for each file.

• ACQ.DAT: The list of recent /tell contacts. Binary format

• ADDON.DAT: This stores your UI settings such as HUD layouts and window sizes. Binary format

• COMMON.DAT: This stores your Character Settings. Plain text format.

• CONTROL0.DAT: This stores Keyboard/Mouse Settings. Plain text format.

• CONTROL1.DAT: This stores Gamepay Settings. Plain text format.

• GEARSET.DAT: This contains your Gear sets. Binary format.

• GS.DAT: Unknown. Binary format.

• HOTBAR.DAT: This contains the contents of your Hotbars, but not their positions or such. Binary format.

• ITEMFDR.DAT: Item search index, used when searching for similar items. Binary format.

• ITEMODR.DAT: This contains Inventory and Retainer item sort positions. Binary format.

• KEYBIND.DAT: This contains your Keybinds. Binary format.

• LOGFLTR.DAT: This contains your Chat log filters. Binary format.

• MACRO.DAT: This is your Macros. Binary format.

• UISAVE.DAT: This contains timers such as the retainer venture timer, possibly other stuff. Binary format.

• : The game writes your chat history to disk each time its internal buffer overflows, which potentially allows you to retrieve chat history in longer play sessions.

Encoded Process Argument

Upon launching the game, the retail launcher passes handful of information (e.g. login token, client language, etc...) to the game that usually looks like this:

//**sqex0003VGhpcyBpcyBqdXN0IGZvciBleGFtcGxlIHB1cnBvc2U7IGl0IGFjdHVhbGx5IG5ldmVyIGxvb2sgbGlrZSB0aGlzA**//

Encoding Process

• Encrypt UTF-8 plain text using Blowfish; you need to pad the buffer with zero as needed

  • Key is GetTickCount() & 0xFFFF_0000

  • Block cipher mode of operation is ECB (yes, you read it right.)

Checksum

Pseudocode

1. The client uses QueryPerformanceCounter to generate an arbitrary timestamp, which it converts roughly into milliseconds by dividing it by 10,000.

2. An IPC message is sent by the client which includes the timestamp encoded as a 32-bit integer value.

3. An IPC message is sent back by the server with the same timestamp.

4. The client generates a new timestamp, divides it by 10,000, and then computes the difference between them to get the RTT for the connection.

Pseudocode

Remarks

Animation lock is an internal timer that player has to wait certain amount of time before they are allowed to use any actions.

Basics

• Timer counts toward zero. (i.e. it represents remaining time)

In most zones, weather is pseudorandom and can be derived from the current time. Each zone has a weather table, which contains the possible weather states for the zone and the stacked probability of that weather being active.

Target value

The value that the pseudorandom number generator produces is referred to as the target value. This value can be calculated deterministically for any given instant. It will always be in the range [0, 99].

Calculation

Given a UNIX timestamp unixSeconds:

Weather lookup

Once the target value has been calculated, the WeatherRate row for the current TerritoryType is retrieved. The rates of each entry in the row are accumulated until the target value is less than the current value of the rate accumulator. At this point, the current weather rate entry is selected, and the corresponding weather ID denotes the Weather row that should be used.

Retrieving the weather for a zone by zone name

Territories can be queried by name using their PlaceName attribute. Territories have a WeatherRate that describes the weather rate row they use. Using the process described above, the current Weather being used can be determined.

Remarks

Some zones, such as the original version of Diadem, use the message to control what weather the player experiences. It is not known what zones currently use this message for weather.

This is a list of various open source resources and projects related to FFXIV. Please leave an issue if your project is listed here and you'd like to remove it.

Programs

XIVLauncher

A popular custom launcher with extra features. Good reference for the login flow (including Steam/Free Trial accounts) and the patching system.

Dalamud

A plugin framework and API, meant to be used with XIVLauncher. Almost all official plugins are open source.

Libraries

Lumina

Library for reading and interacting with FFXIV game files and Excel data.

SaintCoinach

Another library for reading and interacting with game files/Excel data. Provides community maintained metadata on Excel data types.

Ironworks

Yet another library for game data, but in Rust.

kobold

Another library for game data, in TypeScript.

FFXIVClientStructs

A C# library containing community-maintained structs in the client, and Python scripts to help reverse engineer the game binary in IDA/Ghidra.

Tools

SaintCoinach.Cmd

A command line interface for SaintCoinach. Features commands to export raw game files, the UI images, and music.

Godbert

A GUI interface for browsing Excel data and viewing territories, powered by SaintCoinach.

FFXIV Explorer

A GUI for browsing the game files. You may be interested in adding more features.

Websites & APIs

Thaliak

An API for game versions and patch information.

ResLogger2

A list of file paths in the game files, crowdsourced via a Dalamud plugin.

XIVAPI

A general-purpose API for FFXIV. Most useful if you can't embed a library into your application or need Lodestone information.

Networking

Sapphire

A server emulator. Not always up to date, but still a great reference on many things.

Machina

A general library for packet capture with specialized FFXIV functionality.

Velcro

A set of tools to capture network data and store it into an SQLite database.

Nari

A library to parse ACT logs.

We'll only cover version 3 for now.

Intro

This patch format has been extant since FFXIV 1.0, but has had a few modifications since then, especially from 2.0 onward.

A patch file name generally starts with either H or D, for HIST and DIFF, respectively, followed by a version string, such as 2013.08.09.0001.0000. This is optionally followed by a lowercase letter (starting at 'a') in case the patch file corresponding to that version string would be larger than 1.5GB for HIST files. e.g.: H2013.08.09.0001.0000a.patch, D2019.05.29.0000.0000.patch.

The character creator saves it's presets in binairy files called FFXIV_CHARA_XX.dat where XX is the preset slot number. These files are located in the <..>\Documents\My Games\FINAL FANTASY XIV - A Realm Reborn\ folder.

Note: The investigation into this format has been made in a very cursory manner. There is no garantie of accuracy.

Game packets are composed of 3 distinct parts, the packet header, the segment header and a (sometimes) optional IPC header.

Packet Header

Segment Header

Segment Types

IPC Header

Only present when the parent segment type is set to SEGMENTTYPE_IPC.

Decoding Packets

Decoding packets is reasonably simple and assuming you have a buffer that you write data in to for each connection, it's something like the following:

A lot of detail is omitted for brevity, but it's generally pretty straightforward.

A more comprehensive example of packet parsing can be found in Sapphire:

• (and some container-level parsing)

Primitives

SqpkChunk is a 'container' chunk which executes one of several operations in SqpkOperation. These will be detailed in the following subsections.

Important to note that any fields prepended with "Block" will mean that the number is in blocks, or units of 128-bytes. e.g., BlockOffset means that the offset in bytes would be calculated by BlockOffset << 7 or BlockOffset * 128.

These operations often contain fields indicating which file the operation will apply to. These adhere to the following structure:

When referring to block headers, the following struct will be relevant:

Types

Type A - Add Data

This operation writes SqpkAddData.Data to the dat File, at BlockOffset. It will then write BlockDeleteCount blocks of empty (0x00) 128-bytes.

Type D - Delete Data

This operation writes BlockCount empty (0x00) 128-byte blocks at BlockOffset, with the first of those blocks containing a BlockHeader struct with:Size = 128, Type = FileSize = UsedBlocks = 0, TotalBlocks = BlockCount

If Delete Data encounters EOF while writing or seeking to BlockOffset, it will fail.

Type E - Expand Data

Expand Data follows the same structure as Delete Data, but the behaviour differs. When Expand Data seeks past the end of file or writes past the end of file, it does not fail, since this is its intended use.

Type F - File Operation

Pseudocode

Notes:

• FilePath is a null terminated utf-8 string. Length of the string is designated by FileHeader.FilePathSize

Notes:

• If blkHeader.Compressed is true then the payload is a deflated stream.

• If blkHeader.Compressed is false then the payload is a raw bytes stream.

• Yes, AlignedBlockSize is very dodgy. Apparently they are rounded up to next multiple of 128 except they're not.

Type H - Header Update

Pseudocode

Type I - Index Update

This is currently no-op.

Type X - Patch Info

This is currently no-op.

Type T - Target Info

AVFX files are organized as a nested series of blocks, with each block following the format:

The contents of a block can further contain other blocks. It is also worth noting that the name of a block is reversed from its actual meaning. For example, the "top-level" block for an AVFX file is "XFVA"(AVFX reversed). Names which are fewer than 4 character are also padded out to 4 bytes. Blocks are also padded out to be 4-aligned, so even if Sizeis 3, there will be an extra 00 before the next block starts.

SqPack(s) are formed from the following concepts, in which order 'matters':

1. Repositories

2. Categories

4. Data Files

Repositories

Repositories are essentially a collection of categories and there's not much to know here. As of writing, there's 4, one for the base game (ffxiv) and one for each expansion (ex1, ex2, etc.). Consider the following directory structure:

Each folder inside sqpack/ is it's own repository. As an aside, when the game tries to access files, it distinguishes which repository to find a file in by parsing the file path and pulling out 2 segments, the repository name and the category.

For example:

The first two paths explicitly define their repository in their file path, and it's always the second segment - if it's omitted it defaults to the ffxiv repository. Category is always the first segment and must be present for a path to resolve.

Categories

Categories are just logical separations of game data. The following categories exist:

Every game path will start with one of the above names and it defines which index to search to find a file.

SqPack Files

Indexes and regular data files are effectively SqPack files and subsequently have a common header, SqPackHeader. It looks like the following:

Indexes (and data) starts at size so you want to seek to the value of size before you read anything out of the file.

Reading Index Data

The index data is located directly after the header and depends on which variant of index file you load. The retail client ships with both variants of index files, which we'll mostly refer to as index and index2 to make the difference obvious. Contrary to the retail client shipping with both index variants, benchmarks only ship with index2 files. The reason is unknown.

Immediately following the SqPackHeader there's a SqPackIndexHeader (which is only present in index files):

The actual SqPackIndexHeader is 0x400bytes large, but for the purposes of this, we're only interested in the first 16 bytes. From the indexDataOffset and indexDataSize, you can determine where to start reading from and how many index elements exist inside an index. indexDataOffset is an absolute offset to where the index data is located, and indexDataSize is the collective size of every IndexHashTableEntry that's in a file. This entry is slightly different in the case of index2 files, so we'll generally cover the two with a focus on index1 files for now.

Reading Index

There's a couple notable differences between the C++ and C# version, so we'll just explain the C++ version and the latter will make sense too.

The hash is a u64 that contains two u32s: the lower bits are the filename CRC32, the higher bits are the folder CRC32.

Generally speaking, calculating a hash works like this:

1. Convert the path to lowercase

2. Find the last instance of / and split the string with the last / existing in the first group. The filename needs to have no directory separators

3. Calculate the CRC32 of both path segments

The dataFileId is to identify which file (on disk) contains the file. Larger categories are split across multiple files (each is capped at 2,000,000,000 bytes, or 2 GB), so this is used to distinguish between 020000.win32.dat0 and 020000.win32.dat1 for example, where dataFileId would be 0 and 1 respectively for files located in either dat.

The offset is the absolute number of 8 byte aligned segments that the file is located at within a specific dat file. In a given dat file, a file is located at offset * 0x8 which gives you the absolute offset to start reading a file from.

Reading Index2

The main difference between index and index2 is that the entire path is encoded into one CRC32 hash and does not split the path by folder and filename. Outside of that, everything is identical to index.

Excel is a binary data format for storing relational data. It's composed of 3 different files:

1. Excel List (.exl) is used to provide the excel index for the game, and allows certain sheets to be accessed by an ID rather than a name.

2. Excel Header (.exh) is used to define the data layout, variant, segmentation and available languages in the event of localisation being present.

3. is the raw data itself and just contains an offset table and then data for each row. The structure of this file changes depending on which variant is defined in the header.

Excel List (.exl)

Probably the simplest format in the entire game given it's just a text file.

The first line of the file is its 'header' and defines its type, EXLT and it's version following that. Each sequential line after the 'header' is a path, relative to the exd/ category, and its immutable ID. The immutable ID is optional and in cases where not relevant (eg. quest dialogue files) it's value is -1.

For example, here's an example of the content of a list file:

From these entries, you can build something like the following:

From here, the only thing you can do is parse headers as you will not be able to accurately figure out data paths without first reading the header due to language and row segmentation.

As a note, any excel entry in this file with an ID set get their header pre-cached by the game on startup.

Excel Header (.exh)

The Excel Header defines the schema and how you read data files. The first structure in this file is it's header which contains information you'll need to parse the rest of the file.

Magic

The magic is always EXHF. If it's not, the file is probably not the file you're trying to read.

Data Offset

DataOffset isn't relevant to this file at all, but is required when loading certain data from Excel Data files such as strings. It points to the end of the fixed size data of a row. For example, a row can be made of a bunch of integral types which have a known length at compile time, however a string length is variable. This offset allows you to then seek to the end of the row and access any additional data that may be on the end. If this is weird, don't worry, because it'll make sense later.

Column Count

ColumnCount is how many columns exist within the file and is the first thing you'll read after the header. In other words, you'll need to read sizeof( ColumnDefinition ) * ColumnCount immediately after the header.

Offset is relative to the row offset, which you don't have until you read the offset table from a data file.

Type is the type of data stored. Most don't have any special handling outside of String and PackedBoolX but we'll cover that later.

Page Count

PageCount is the number of 'pages' an excel data sheet is split into. Many sheets only have a single page and every row will exist in a single page, however larger sheets such as Quest or Item have many pages. This information is another structure and immediately follows the column definition data.

startId is the row id where a page starts. You'll need this to build file paths for data files.

rowCount is how many parent rows a sheet contains. As a quick example before we cover it more in depth later is that given a row id, you can calculate which page a row is on with row >= startId && row < startId + rowCount - 1.

Language Count

Finally, the last thing you'll need to read out of a header file is the languages. These are needed to generate paths to data files along with the paging information.

You can read out the languages as is.

Variant

Used when reading data. Default requires no extra processing and you can just iterate over the offset list inside a data file. SubRows makes each row contain it's own rows. As a better example, it's like having a compound key on a database table. Instead of one column being the identifier for a row, you have two instead.

Row Count

This is the total count of all rows across every page. The game uses this field when it internally queries for a row count.

Generating Data File Paths

Once you have the 3 pieces of critical information from the headers, namely:

1. The column count

2. The page count

3. The languages

You have everything you need to find data files! How exciting. The files follow one of 2 path formats, which makes this pretty easy. Make sure not to discard the data from the header, there's still some other information you'll need from it.

If the no language is set, your paths follow the following format:

Otherwise, if one or many languages are set (as in, not None), the following format applies:

This should be relatively obvious, but here's a few examples:

The above also applies for quest sheets and so on which exist in subfolders.

Excel Data (.exd)

The data file contains a single page of sheet data and as mentioned before, you will need the header file to read data correctly.

The value of magic should always be EXDF.

indexSize is how large the row offset index is, in terms of total size. To convert that to a number of entries, you'd do indexSize / sizeof( ExcelDataOffset ).

Data Offset Entries

Immediately following the ExcelDataHeader, the root row offsets are stored. The reason it's called the 'root row offset' is because on variant 2 sheets (or sheets with subrows), this offset won't point to data that can be read following the column data.

rowId is the absolute row id, so a simple way to map these in whatever you're doing is to convert the list of data offsets in this file to a key value map, where the key is the rowId and the value is the offset. Then you can directly index rowIds on any given data page.

offset is the absolute offset to where the data is located in the file. It can be used as is.

Row Header

Once you seek to a row offset by following the offset list after the header, the first thing you'll encounter is the row header.

The dataSize is the entire size of the row, including any data for subrows (if they exist). You can use this field to copy out the exact amount of data for a row (or subrows) to then later parse if you choose not to do it in place.

rowCount is always 1 on variant 1 sheets and you can ignore that field entirely if you choose to. However, on variant 2 sheets, the rowCount is how many subrows belong to a row.

Therefore, on variant 1 sheets, immediately after the row header is your row data. You can then read columns directly out of the data given a column offset that you read from the header.

On the other hand, variant 2 sheets, following the header is the first subrow, or subrow 0. You can calculate the offset to n subrow with the following:

To clear up a few things:

1. The rowOffset is the offset from the offset list.

2. rowOffset + 6 is the skipping the size of the row header. You could just store the offset once you read the row header and use that.

3. header.dataOffset

There are some intricacies to reading certain types of columns which we'll cover in the next section.

Reading Row Data

Reading data out of a row depends a bit on the type of the column that you're reading. Most don't require any additional logic and you can read them out of the row and use them as is.

All of the types are as follows:

String

As mentioned previously, variable length data is stored past the end of the fixed length data segment of a row. So to access a string, you need to read a uint32 where there string column is. You can then obtain the offset of the string by doing the following:

Where rowOffset is the offset of the first column of a row, the dataOffset from the header and the uint32 that you read out from the column.

Packed Bools

Packed bools are always 8 bits/1 byte long. To each type is basically which bit you need to bitwise and against to read the correct bool out.

A simple way of doing this for all of them is something like the following:

Alternatively, you can handle each one indivdually, but it's better to be lazy and do it the lazy way instead.

Everything Else

Read and use it as is. It just works™ - no magic required. Just make sure the endianness is correct.