redstrate/physis
1
Fork 0
mirror of https://github.com/redstrate/Physis.git synced 2025-05-05 10:17:45 +00:00
Code Activity

Remove fluff from the README

Browse source
This commit is contained in:
Joshua Goins 2025-04-28 16:50:24 -04:00
parent 26c4041b68
commit 053cae89a2
2 changed files with 54 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,50 @@
# Contributing
If you're interested to read how these formats work in more detail, see [xiv.dev](https://xiv.dev/) and
[docs.xiv.zone](https://docs.xiv.zone).
## Testing
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 download.
### Unit Testing
There are a set of basic unit tests you can run via `cargo test`. You can also find the relevant test resources in `resources/tests`.
This does **NOT** contain copyrighted material, but actually fake game data created by Physis itself. These tests are
run automatically by the CI.
### Retail Testing
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 `retail_game_testing`
feature.
### Patch Testing
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.
1. Enable the `patch_testing` feature.
2. Set a couple of environment variables:
* `FFXIV_PATCH_DIR` is the directory of patches to install. It should be structured as `$FFXIV_PATCH_DIR/game/D2017.07.11.0000.0001.patch`.
* `FFXIV_XIV_LAUNCHER_PATCHER` should be the path to the XIVLauncher patcher executable. If you're running on Linux, we will handle running Wine for you.
* `FFXIV_INSTALLER` is 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` and `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.
### Semver and Dependency Checks
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
versions.

69
README.md
View file

@ -4,19 +4,6 @@
Physis is a library for reading and writing FFXIV data. Physis is a library for reading and writing FFXIV data.
Even though this library was written with and for [Rust](https://www.rust-lang.org/) in mind, Physis has bindings for other languages:
* [PhysisSharp](https://github.com/redstrate/PhysisSharp) can be used in any C# application, and is built on top of libphysis.
* [libphysis](https://github.com/redstrate/libphysis) can be used for anything that can interface with the C FFI. [Novus](https://github.com/redstrate/Novus) and [Astra](https://github.com/redstrate/Astra) is built on top of libphysis, for example.
## Goals
Physis should:
* ... Make it easy for developers to tinker around with game data.
* ... Document file formats along the way, to make writing future and applications libraries easier.
* ... Make parsing data safe, and create automated tests when possible.
* ... Aim for minimal dependencies, and should be easy to use regardless of platform.
## Features ## Features
Here is a list of supported formats and their status: Here is a list of supported formats and their status:
@ -79,64 +66,16 @@ C/C++ projects (or anything that can interface with C libraries) can use [libphy
## Building ## Building
Physis only has a few dependencies, and very little if nothing is turned on by default. You need to set up [Rust](https://www.rust-lang.org/learn/get-started) and then run `cargo build`. You need to set up [Rust](https://www.rust-lang.org/learn/get-started) and then run `cargo build`. Although Physis is a library, we have a few examples you can run.
## Development
If you're interested to read how these formats work in more detail, see [xiv.dev](https://xiv.dev/) and
[docs.xiv.zone](https://docs.xiv.zone).
### Testing
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 download.
#### Unit Testing
There are a set of basic unit tests you can run via `cargo test`. You can also find the relevant test resources in `resources/tests`.
This does **NOT** contain copyrighted material, but actually fake game data created by Physis itself. These tests are
run automatically by the CI.
#### Retail Testing
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 `retail_game_testing`
feature.
#### Patch Testing
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.
1. Enable the `patch_testing` feature.
2. Set a couple of environment variables:
* `FFXIV_PATCH_DIR` is the directory of patches to install. It should be structured as `$FFXIV_PATCH_DIR/game/D2017.07.11.0000.0001.patch`.
* `FFXIV_XIV_LAUNCHER_PATCHER` should be the path to the XIVLauncher patcher executable. If you're running on Linux, we will handle running Wine for you.
* `FFXIV_INSTALLER` is 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` and `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.
#### Semver and Dependency Checks
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
versions.
## Contributing & Support ## Contributing & Support
Feel free to submit patches to help fix bugs or add functionality. Filing issues is appreciated, but I do this in my free time so please don't expect professional support. Feel free to submit patches to help fix bugs or add functionality. Filing issues is appreciated, but I do this in my free time so please don't expect professional support.
See [CONTRIBUTING](CONTRIBUTING.md) for more information about the project.
## Credits & Thank You ## Credits & Thank You
* [goatcorp](https://goatcorp.github.io) (XIVQuickLauncher, docs.xiv.dev, and even more) * [goatcorp](https://goatcorp.github.io) (XIVQuickLauncher, docs.xiv.dev, and even more)
* [Ioncannon](http://ffxivexplorer.fragmenterworks.com/research.php) (FFXIV Data Explorer) for the first documenting the file formats * [Ioncannon](http://ffxivexplorer.fragmenterworks.com/research.php) (FFXIV Data Explorer) for the first documenting the file formats
* [binrw team](https://binrw.rs) for an awesome Rust library! * [binrw team](https://binrw.rs) for an awesome Rust library!