#gamedev #parser #ao-e2de

aoe2-probe

A rust library for editing aoe2scenario files from AoE2 DE

15 releases

Uses new Rust 2021

new 0.2.12 Aug 9, 2022
0.2.11 Aug 8, 2022
0.1.1 Jul 27, 2022

#177 in Game dev

Download history 52/week @ 2022-07-27 262/week @ 2022-08-03

314 downloads per month

GPL-3.0-or-later

86KB
2K SLoC

CircleCI Crates.io GPL-3.0 licensed

What is aoe2-probe?

This is a rust library for editing aoe2scenario files from AoE2 DE.

WARNING

  • aoe2-probe is currently in the very early stage. APIs may change dramatically in following updates. Please don't use this project in serious development.
  • Due to the zlib implementation difference, the exported file cannot be as same as the imported file, while the content of files is constant(Don't worry, AoE2 DE still understand it).Backing up the original is always recommended.

Design Goals

  • Full ability to access every byte in aoe2scenario files.
  • Editing every bit with a reliable correctness check. todo!()
  • Provides constant API compatibility across game versions. todo!()

Getting Started

Under the directory ./examples/, you can find several simple showcases.

Import and export files:

use aoe2_probe::scenario::Scenario;

//Reading scenario content from the .aoe2scenario file
let scenario = Scenario::from_file("./resources/chapter_1.aoe2scenario");
//saving content to a new .aoe2scenario file
scenario.to_file("./resources/temp.aoe2scenario");

Update attributes:

use aoe2_probe::scenario::Scenario;

//versio's structure definition can be found in the folder /src/prebuilt/ver1_46/versio.rs
let mut scenario = Scenario::from_file("./resources/chapter_1.aoe2scenario");

let author = scenario.versio.get_by_path_mut("/file_header/creator_name");
//Update the creator name.
author.try_mut_str32().set_content("Arian");

Customize a structure:

//Define a score record
let mut root = PatchedMap::new();
root.push_back("score", Token::Int16(100));
root.push_back("name", Token::Str32(DynString::with_capacity(12, "anonymous")));

//serialize
root.to_le_vec();

//deserialize
root.from_le_vec();

Serialize/Deserialize to any formats that serde support:

let scenario = Scenario::from_file("./resources/chapter_3.aoe2scenario");
let json = serde_json::to_string(&scenario.versio).unwrap();
println!("{}", json);

Run examples with the following command:

cargo run --example read_write

Every member of versio and itself implements fmt::Debug trait. Print them if you want to know more.

let scenario = Scenario::from_file("./resources/chapter_1.aoe2scenario");
println!("{:?}", &scenario.versio())

More detailed information can be found in Docs.

Supports

Version Support
ver.1.46 Support
ver.1.47 Experimental

Currently, only version 1.46 and newer will be firstly supported.

Libraries Used

  • miniz_oxide: Pure rust Rust replacement for the miniz deflate/zlib encoder/decoder using no unsafe code.
  • serde: Serde is a framework for serializing and deserializing Rust data structures efficiently and generically.
  • log: A lightweight logging facade.

Acknowledgment

This library is inspired by AoE2ScenarioParser and Trigger Craft

Dependencies

~0.6–1.2MB
~27K SLoC