Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/happyleavesaoc/aoc-mgz
Age of Empires II recorded game parsing and summarization in Python 3.
https://github.com/happyleavesaoc/aoc-mgz
aoc aoe2 aoe2record mgz parser python
Last synced: about 21 hours ago
JSON representation
Age of Empires II recorded game parsing and summarization in Python 3.
- Host: GitHub
- URL: https://github.com/happyleavesaoc/aoc-mgz
- Owner: happyleavesaoc
- License: mit
- Created: 2015-02-26T18:49:05.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2024-11-14T18:40:33.000Z (2 months ago)
- Last Synced: 2025-01-11T18:03:28.400Z (8 days ago)
- Topics: aoc, aoe2, aoe2record, mgz, parser, python
- Language: Python
- Homepage:
- Size: 17 MB
- Stars: 200
- Watchers: 18
- Forks: 45
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-aoe2 - mgz
README
# mgz
Age of Empires II recorded game parsing and summarization in Python 3.
## Supported Versions
- Age of Kings (`.mgl`)
- The Conquerors (`.mgx`)
- Userpatch 1.4 (`.mgz`)
- Userpatch 1.5 (`.mgz`)
- HD Edition >= 4.6 (`.aoe2record`)
- Definitive Edition (`.aoe2record`)
## Architecture
The core functionality of `mgz` is a parser that produces a Python data structure based on a recorded game file. It also offers abstracted representations that make it easier to use the data.
### Parsers
`mgz` offers two parsers, `fast` and `full`. The `fast` parser skips data that is rarely needed, while the `full` parser tries to parse as much as possible. Naturally, the `fast` parser is faster than the `full` parser.
The `full` parser can do just about everything, the `fast` only maybe 80-90%. The `summary` will automatically try the `fast` parser and fall back to the `full` parser if needed.
### Abstractions
Abstractions take parser output as input and return an object with normalized data that is easier to use for most cases. There are two abstractions available, `summary` and `model`. The `summary` abstraction attempts to expose the maximum amount of usable data. The `model` abstraction is more limited but automatically performs more lookups.
## Support
| Version | model | summary | fast (header) | fast (body) | full (header) | full (body) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: |
| Age of Kings (`.mgl`) | | ✓ | | ✓ | ✓ | |
| The Conquerors (`.mgx`) | | ✓ | | ✓ | ✓ | |
| Userpatch <= 1.4 (`.mgz`) | | ✓ | | ✓ | ✓ | ✓ |
| Userpatch 1.5 (`.mgz`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| HD Edition >= 4.6 | | ✓ | | ✓ | ✓ | ✓ |
| HD Edition 5.8 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Definitive Edition <= 13.34 (`.aoe2record`) | | ✓ | | ✓ | ✓ | ✓ |
| Definitive Edition > 13.34, <= 26.21 (`.aoe2record`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Definitive Edition > 26.21 (`.aoe2record`) | ✓ | ✓ | ✓ | ✓ | ✓ | |
## Examples
#### Full Parser (header) + Fast Parser (body)
```python
import os
from mgz import header, fast
with open('/path/to/file', 'rb') as data:
eof = os.fstat(data.fileno()).st_size
header.parse_stream(data)
fast.meta(data)
while data.tell() < eof:
fast.operation(data)
```
### Summary
```python
from mgz.summary import Summary
with open('/path/to/file', 'rb') as data:
s = Summary(data)
s.get_map()
s.get_platform()
# ... etc
```
### Model
```python
from mgz.model import parse_match
with open('/path/to/file', 'rb') as data:
match = parse_match(data)
match.map.name
match.file.perspective.number
# ... etc
```
## To JSON
```python
import json
from mgz.model import parse_match, serialize
with open('/path/to/file', 'rb') as h:
match = parse_match(h)
print(json.dumps(serialize(match), indent=2))
```
## Frequently Asked Questions
**Q:** Where are the end-of-game achievements/statistics?
**A:** In the `postgame` action, available only from Userpatch version.
**Q:** How can I tell the number of resources/kills/etc at a certain point?
**A:** You can't, without replaying the match in-game.
**Q:** How does a recorded game file work?
**A:** The first portion (the `header`) is a snapshot of the initial game state. The second portion (the `body`) is a list of moves made by players. The game loads the header, then applies each move to mutate the state according to the game rules.
**Q:** How can I install this package?
**A:** `pip install mgz`
## Contribution
- Pull requests & patches welcome
## Resources
- aoc-mgx-format: https://github.com/stefan-kolb/aoc-mgx-format
- recage: https://github.com/goto-bus-stop/recage
- recanalyst: http://sourceforge.net/p/recanalyst/
- genie-rs: https://github.com/SiegeEngineers/genie-rs/tree/default/crates/genie-rec
- bari-mgx-format: https://web.archive.org/web/20090215065209/http://members.at.infoseek.co.jp/aocai/mgx_format.html