Ogre  

A rusty, dual-wielding Quake and Half-Life texture WAD parser

ogre is a rust representation and nom parser for Quake and Half-Life WAD files.

It's written in pure Rust, and enforces the use of safe code crate-wide via #![forbid(unsafe_code)].

Rust Representation

The Rust represention lives in the repr module, and is a set of structs representing the contents of a parsed WAD file.

WAD files contain certain intermediary structures - such as a header, and metadata directory - that are specific to parse-time, and thus don't show up in the final representation. For cases where you want to inspect these elements of a WAD, the parser module contains its own parser::repr submodule, as well as nom functions for parsing into the structures therein.

Parsing

The simplest way to parse a WAD file into AST is via the parser::parse_wad function:

let wad = include_bytes!("../../ogre/test_data/wad2/medieval.wad");
let (_, wad) = ogre::parser::parse_wad(wad).expect("Failed to parse WAD");
assert!(wad.len() > 0);
println!("{:#?}", wad);

This will parse a complete Wad, and block the calling thread until completion. Internally, it calls the rest of functions parser module to assemble its final output. These can also be used directly in cases where more granular parsing is desired.

For better performance, a parallelized implementation is recommended. See the Async header below for more.

Format Support

ogre supports the Quake WAD2 and Half-Life WAD3 formats.

Currently, the original Doom WAD format is not supported on account of its different data structure and significantly larger scope.

Serde Support

For cases where serializing and deserializing the rust representation is required, ogre includes serde::Serialize and serde::Deserialize derives for all types inside the repr and parser::repr modules.

This functionality is gated behind the serde_support feature flag, which is enabled by default.

Async

ogre includes a parallelized implementation that uses async_std::task to multiplex the routines inside parser over some source of WAD bytes. This approach scales better than single-threading, and is generally more performant - especially for large WAD files. An explanation and usage guide can be found inside the parser_async module.

This functionality is gated behind the async feature flag, which is enabled by default.