Physis is a framework for interacting with FFXIV data. Designed for reading (and writing) the relevant game formats of FFXIV, as well as making documentation readily accessible for other developers hoping to do the same. Although this library works best as a Rust crate, libphysis is a C API wrapper designed for other languages.
Warning: The API will not be truly stable until 1.0. However, the API is stable between patch versions.
If you intend to use this in your Rust project, you can simply include this crate directly.
[dependencies] physis = "0.1"
You can view the documentation at docs.xiv.zone! It's automatically updated as new commits are pushed to the main branch.
If you're interested to see how these formats work in more detail, see xiv.dev and docs.xiv.zone! They explain the file formats in more detail, but I also encourage reading the ibrary code as well if you can.
One of the main goals of Physis is to avoid accidental regressions, this is especially important when handling game data that might take hours to redownload.
There are a set of basic unit tests you can run via
cargo test. You can also find the relevant test resources in
This does NOT contain copyrighted material, but actually fake game data created by physis itself. These tests are
run automatically by the CI.
There are some tests and benchmarks require the environment variable
FFXIV_GAME_DIR to be set. By default, these are disabled
since they require a legitimate copy of the retail game data. These tests can be turned on via the
Patching is an extremely sensitive operation since it is not easily reversible if done wrong. Repairing the game files is an option, but it's time-consuming and not yet implemented in physis. To prevent regressions in patching the game, I have set up a testing bed for cross-checking our implementation with others. Currently, this is limited to XIVLauncher's implementation, but I will eventually adopt a way to test the retail patch installer as well.
FFXIV_PATCH_DIRis the directory of patches to install. It should be structured as
FFXIV_XIV_LAUNCHER_PATCHERshould be the path to the XIVLauncher patcher executable. If you're running on Linux, we will handle running Wine for you.
FFXIV_INSTALLERis the path to the installer executable. This will be installed using the usual InstallShield emulation physis already includes.
As you can see, you must have the previous patches downloaded first as well as the installer before running the tests. This is left up to the developer to figure out how to download them legally.
Note: These tests create the
game_test_xivlauncher folders in
$HOME and does not
delete them on exit, in case you want to check on the results. You may want to remove these folders as they
are full game installations and take up a considerable amount of space.
Even though package management in Rust is easier, it's a double edged sword. I try to prevent getting carried away
from including crates - but the ones we do include, have to get checked often. I use
cargo deny to check my
dependencies for mismatched versions, deprecation warnings, updates and more. This is also run on the CI!
Making sure that the library is semver-compliant is also important, and I use
cargo semver for this task. This is to ensure the API does not break when moving between patch
The best way you can help is by monetarily supporting me or by submitting patches to help fix bugs or add functionality.
And everyone else who writes FFXIV tools!