9 unstable releases (3 breaking)
new 0.4.2 | Nov 19, 2024 |
---|---|
0.4.1 | Nov 19, 2024 |
0.3.1 | Oct 21, 2024 |
0.2.2 | Sep 9, 2024 |
0.1.0 | Aug 26, 2024 |
#518 in Parser implementations
359 downloads per month
705KB
10K
SLoC
infinite-rs
Simple and fast deserialization library for Halo Infinite.
This crate currently is in early-development. Please let me know via Github issues about any issues you encounter using this project.
Documentation
- Documentation on this project can be found at docs.rs.
Examples/Usage
Getting Started: Loading a Module file
Modules are the file format that store "tags" in Halo Infinite. These files are used to store all the assets in the game, including models, textures, metadata, and more. infinite-rs
provides a simple interface to load these tags, starting with loading the module files themselves.
use infinite_rs::{ModuleFile, Result};
fn load_modules() -> Result<()> {
// Create new instance of a Module file.
// These are the main archive files used in Halo Infinite.
let mut module = ModuleFile::new();
// Reads to the module file given a file path.
// Note: the path can be anything that implements AsRef<Path>.
module.read("C:/XboxGames/Halo Infinite/Content/deploy/any/globals-rtx-new.module")?;
Ok(())
}
Loading a tag file
After we have loaded a module file, we can now use the read_tag
function to load a specific tag by index from the module file. This populates the data_stream
and tag_info
properties in a module entry that we can use later.
The read_tag_from_id
function is also available to load a tag by its global ID, returning the index in which it was found in the module file.
use infinite_rs::{ModuleFile, Result};
fn load_tags() -> Result<()> {
let mut module = ModuleFile::new();
module.read("C:/XboxGames/Halo Infinite/Content/deploy/any/globals-rtx-new.module")?;
// Load a specific tag from the module file.
let tag_index = 0;
module.read_tag(tag_index)?;
// We can now access the data stream and tag info.
let tag_data = module.files[tag_index as usize].data_stream.as_ref().unwrap();
let tag_info = module.files[tag_index as usize].tag_info.as_ref().unwrap();
Ok(())
}
Creating a custom structure and reading it
infinite-rs
also allows you to read data directly into structures, using the read_metadata
function. This functionality requires the derive
feature.
Defining Structures
To define a structure that can be read from a tag data stream, you must first derive the TagStructure
trait. To ensure proper padding and alignment, you can use the data
attribute to specify the size of the structure in bytes. Each field also must contain a data
attribute specifying the offset in bytes from the start of the structure.
[!TIP] Padding between fields are automatically calculated. Any data between two offsets are skipped.
use infinite_rs_derive::TagStructure;
use infinite_rs::tag::types::common_types::{
AnyTag, FieldReference,
};
#[derive(Default, Debug, TagStructure)]
#[data(size(0x88))] // Size can be any u64 value.
struct MaterialTag {
#[data(offset(0x00))] // Offset can be any u64 value within the range of the size.
any_tag: AnyTag,
#[data(offset(0x10))]
material_shader: FieldReference,
}
Reading structures
use infinite_rs_derive::TagStructure;
use infinite_rs::tag::types::common_types::{
AnyTag, FieldReference,
};
use infinite_rs::{ModuleFile, Result};
#[derive(Default, Debug, TagStructure)]
#[data(size(0x88))] // Size can be any u64 value.
struct MaterialTag {
#[data(offset(0x00))] // Offset can be any u64 value within the range of the size.
any_tag: AnyTag,
#[data(offset(0x10))]
material_shader: FieldReference,
}
fn load_tags() -> Result<()> {
let mut module = ModuleFile::new();
module.read("C:/XboxGames/Halo Infinite/Content/deploy/any/globals-rtx-new.module")?;
// We now want to find the material tags in the module file.
let material_indices = module.files.iter()
.enumerate()
.filter(|(_, file)| file.tag_group == "mat ")
.map(|(index, _)| index)
.collect::<Vec<_>>();
// And for each material tag, we want to read the metadata associated.
for index in material_indices {
// We first have to populate data_stream and tag_info.
module.read_tag(index as u32)?;
let mut mat = MaterialTag::default();
// We pass in our structure as a generic parameter.
module.files[index].read_metadata(&mut mat)?;
// We can now access the fields in our structure.
// For instance, `any_tag.internal_struct.tag_id` is always equal to the tag id of our file.
assert_eq!(module.files[index].tag_id, mat.any_tag.internal_struct.tag_id);
}
Ok(())
}
Credits
- libinfinite by Coreforge, which this project is mostly based on.
- Reclaimer by Gravemind2401, which helped me get familiar with Blam file formats.
- AusarDocs by Shockfire, a very useful resource on Ausar/Slipspace file formats.
- Kraken by WolvenKit team, a re-implementation of Oodle Kraken, removing the need for any binary blobs being required for decompression.
- TagFramework by Codename Atriox, which was a common reference point for Slipspace internals.
- red4lib by rfuzzo, acting as the main inspiration for this project.
- HIRT by urium1186, which was very useful in debugging and verifying output from this project.
Dependencies
~0.4–1.7MB
~36K SLoC