mgx 0.1.5

A parser for Age of Empires II recorded games.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# mgx
`mgx` is a parser for **Age of Empires II** recorded games.

## Supported version
* AoK(`.mgl`)
* AoC 1.0(`.mgx`)
* AoC 1.0c(`.mgx`)
* Userpatch 1.5 or earlier(`.mgz`)

**Note:** `mgx` doesn't support game records of HD/DE versions.

## Usage(as a binary)
```text
# mgx --help

A parser for Age of Empires II recorded games.

Usage: mgx [OPTIONS] <RECORD_PATH>

Arguments:
  <RECORD_PATH>  Path to the record file. Only AoK(.mgl)/AoC(.mgx)/UP1.5(.mgz) are supported

Options:
  -m <MAP>               Generate a map image as a .png image. Rotated 45° counterclockwise and change height to 50% to get a in-game look
  -j, --json             Dump game info into a JSON string
      --zh               Use Chinese language for output
      --header <HEADER>  Dump header section to specified file
      --body <BODY>      Dump body section to specified file
  -h, --help             Print help
  -V, --version          Print version
```

## Usage(as a library)

> Parse from a buffer if you need more control over the parsing.   
> Create a `Record` manually and pass it to a `Parser`. Extracted data will persists in the `Record` even if the `Parser` returns an error.
> `mgx::from_file()` will result in nothing if any error occurs.

### Parse a file directly
```rust
let filename = "path-to-test-record.mgx";
let (mut rec, parser) = mgx::from_file(filename).unwrap();

// See src/record.rs for more available fields
println!(" Version: {:?}", rec.ver.unwrap());

// Generate a map image as a .png image.   
// Rotated 45° counterclockwise and change height to 50% to get a in-game look.
mgx::draw_map(&rec, &parser, &format!("{}.png", filename)).unwrap();

// Encoding of in game strings are guessed from instructions, may not be correct. `GBK` is used as a fallback.
println!("Encoding: {:?}", rec.detect_encoding().unwrap());

// .convert_encoding() calls .detect_encoding() first.
rec.convert_encoding();

// Some info like civilizations are stored as numeric raw data, `.translate()` converts these to human-readable strings. Only "zh"/"en" are supported now.
rec.translate();

// Dump comprehensive info into a JSON string. Check `null` values before using them.   
// This method calls .convert_encoding() first.
println!("{:?}", rec.dump_json().unwrap());
```
### Parse a memory buffer
```rust
use mgx::{Parser, Record};

let mut buffer = Vec::new();

// Prepare filename and last_modified manually
let mut record = Record::new(filename, buffer.len(), last_modified);

// Parsing process won't start until `parse_to()` is called.
let mut parser = Parser::new(buffer).unwrap();
parser.parse_to(&mut record)?;
```

## References
* <https://github.com/goto-bus-stop/recanalyst.git>
* <https://github.com/happyleavesaoc/aoc-mgz.git>
* <https://github.com/lichifeng/MgxParser.git>
* <https://github.com/stefan-kolb/aoc-mgx-format>