Skip to main content

dayzmake_core/
lib.rs

1//! File format handling for DayZ: PBO archives, rapified configs, P3D models, PAA textures and BI
2//! keys and signatures, plus the preprocessor and `__EVAL` evaluator the config pipeline needs.
3//!
4//! # Modules
5//!
6//! - [`pbo`]: read, build, pack, unpack and selectively read PBO archives ([`pbo::PBO`]).
7//! - [`extract`]: extract a whole install or mod into one tree by prefix.
8//! - [`config`], [`preprocess`]: config parsing, rapification and derapification.
9//! - [`p3d`]: MLOD model reading and inspection (ODOL is only detected there).
10//! - [`odol`]: binarized ODOL v56 models, read for what a listing needs (LODs, textures, materials, proxies).
11//! - [`paa`]: PAA textures, with conversion from and to images (feature `image`).
12//! - `sign`: BI keys and `.bisign` signatures (feature `sign`).
13//! - `navmesh`: DayZ navmesh generation: data-server client, tile builder and `.nm` reader and writer (feature `navmesh`).
14//! - [`binarize`]: BI's `binarize.exe`, natively on Windows or under Proton.
15//! - [`warning`]: the warnings library calls raise.
16//!
17//! The library never prints and never exits the process; every reader treats its input as hostile and
18//! returns errors instead of panicking.
19//!
20//! # Warnings
21//!
22//! Calls that can warn take a `&mut dyn` [`warning::WarningSink`]. [`warning::Warnings`]
23//! is the ready-made sink: it collects [`warning::Warning`]s (and plain notes), can mute
24//! warnings by name and caps repeats. Warnings are never global: give every thread or job its own sink and
25//! its warnings stay with it.
26//!
27//! # Binarizing
28//!
29//! [`binarize::Binarizer`] owns the Proton sandbox, if any. Pass it to
30//! [`pbo::PBO::from_directory`] and call [`binarize::Binarizer::close`] when done so the
31//! sandbox is removed and its warnings reach your sink; dropping it also cleans up, but cannot report.
32//!
33//! # Features
34//!
35//! - `sign` (default): the `sign` module.
36//! - `image` (default): `Paa::from_dynamic_image`, `Paa::to_dynamic_image` and the
37//!   re-exported `image` crate.
38//! - `navmesh` (default): the `navmesh` module.
39//!
40//! # Licence
41//!
42//! GPL-2.0-or-later, inherited from armake2. Projects under GPLv3 or AGPL-3.0 may link it.
43//!
44//! # Example
45//!
46//! Generate a key, convert an image to PAA, pack and sign a mod folder, and verify the result:
47//!
48//! ```
49//! # #[cfg(all(feature = "sign", feature = "image"))]
50//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
51//! use std::fs::{self, File};
52//! use dayzmake_core::image::{DynamicImage, RgbaImage};
53//! use dayzmake_core::paa::{Paa, PaaFormat};
54//! use dayzmake_core::pbo::{PBO, PackOptions};
55//! use dayzmake_core::sign::{BIPrivateKey, BISignVersion, signature_path};
56//! use dayzmake_core::warning::Warnings;
57//!
58//! let tmp = tempfile::tempdir()?;
59//! let stage = tmp.path().join("stage");
60//! fs::create_dir_all(stage.join("data"))?;
61//!
62//! // A satellite tile as DXT1.
63//! let image = DynamicImage::ImageRgba8(RgbaImage::new(64, 64));
64//! let paa = Paa::from_dynamic_image(&image, PaaFormat::Dxt1)?;
65//! paa.write(&mut File::create(stage.join("data/s_0.paa"))?)?;
66//!
67//! // Pack, sign, verify. Each job has its own warnings.
68//! let mut warnings = Warnings::new();
69//! let pbo = PBO::from_directory(&stage, &PackOptions::pack(), None, &mut warnings)?;
70//! let key = BIPrivateKey::generate(1024, "example".to_string())?;
71//! let signature = key.sign(&pbo, BISignVersion::V3)?;
72//! let pbo_path = tmp.path().join("example.pbo");
73//! pbo.write(&mut File::create(&pbo_path)?)?;
74//! signature.write(&mut File::create(signature_path(&pbo_path, key.name())?)?)?;
75//! key.to_public_key()?.verify(&pbo, &signature)?;
76//! # Ok(())
77//! # }
78//! # #[cfg(not(all(feature = "sign", feature = "image")))]
79//! # fn main() {}
80//! ```
81
82#![cfg_attr(docsrs, feature(doc_cfg))]
83
84/// The `image` crate the PAA conversion API uses, so consumers build against the same version.
85#[cfg(feature = "image")]
86#[cfg_attr(docsrs, doc(cfg(feature = "image")))]
87pub use image;
88
89/// Binarization through BI's `binarize.exe` (Windows or Proton).
90pub mod binarize;
91/// Config parsing and rapification/derapification.
92pub mod config;
93/// Error types and the `error!` macro.
94pub mod error;
95/// Evaluator for config `__EVAL` / `__EXEC` expressions.
96pub(crate) mod eval;
97pub mod extract;
98/// File identity (the same file under different spellings).
99pub mod fileid;
100/// I/O helpers for the binary formats.
101pub(crate) mod io;
102/// Bohemia's LZSS compression.
103pub(crate) mod lzss;
104#[cfg(feature = "navmesh")]
105#[cfg_attr(docsrs, doc(cfg(feature = "navmesh")))]
106pub mod navmesh;
107/// Binarized ODOL v56 model reading.
108pub mod odol;
109/// P3D model reading and inspection.
110pub mod p3d;
111/// PAA texture conversion.
112pub mod paa;
113/// PBO archive packing, unpacking and inspection.
114pub mod pbo;
115/// Config preprocessing (macros, includes, conditionals).
116pub mod preprocess;
117/// BI signature (`.bisign`) creation and verification.
118#[cfg(feature = "sign")]
119#[cfg_attr(docsrs, doc(cfg(feature = "sign")))]
120pub mod sign;
121/// Warnings raised by library calls and the sinks that receive them.
122pub mod warning;