| Name | age-alyser JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | None |
| Summary | A python package for extracting key features of an AOE2 recorded games |
| upload_time | 2025-02-09 18:06:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
statistics
aoe2
age of empires
parsing
mgz
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# The Age-2-Alyser
This python package mines out key strategic choices and statistics from a recorded Age of Empires 2 game. The intention is to enable for further data analysis, including at scale. The package takes in a .AOE2RECORD file as input and produces a Pandas Series with statistical data about the match. This data includes:
- The military strategy choices of both players throughout the game, including unit and strategy choices, production numbers, timings of openings, and so on.
- The economic choices of each player through the game.
- An analysis of the players' maps.
- And some other miscellaneous data, such as elo difference and civilisations.
The package is built on top of the [mgz parser](https://github.com/happyleavesaoc/aoc-mgz/tree/master/mgz) to parse in recorded games - see also [this fork](https://github.com/aoeinsights/aoc-mgz) maintained by aoe insights.
The goal is to create an open source project that enables large scale analytics of the game. Capture Age provides incredible analysis tools for watching replays, however there is a gap in terms of being able to extract statistical data from games en masse for analytics purposes. The task is difficult, given the structure of an mgz file (see appendices below for a more detailed technical explanation).
Aside from this package, some other great projects I have come across which perform something similar are:
- [Rec Opening Analysis by dj0wns](https://github.com/dj0wns/AoE_Rec_Opening_Analysis/tree/main)
- [AOE insights](https://www.aoe2insights.com/)
- [AOE Pulse made by dj0wns](https://www.aoepulse.com/home)
The goal of this package is to flesh out the statistical data we can mine from replays, and deliver it en masse to anyone who can bash up a python script. Feel free to contribute in any way (including a code review or building out tests or documentation).
## Installation
```
pip install age-alyser
```
## Usage and Documentation
Currently only the advanced parser is implemented - in the future I intend to flesh out the API with some other options.
```
import pandas as pd
from agealyser import AgeGame
g = AgeGame("file/path/to/game.aoe2record")
stats: pd.Series = g.advanced_parser() # optional - include_map_analysis = False
```
#### Limitations
Given that:
1. This package is dependant on the [mgz package](https://github.com/happyleavesaoc/aoc-mgz) (and I'm not planning on maintaining a fork or anything)
2. Updates to the game can often break mgz's parsing of a .aoe2record file
3. This package is an WIP/unfinished alpha release
There may be a number of inaccuracies, errors, and bugs.
I would recommend wrapping the the above code in a try-except block. In the future I also intend to improve the error handling so the whole package fails more gracefully.
#### Modeling Structure and package API
**AgeMap**
- Models the map itself and the resources/objects within
- Identifies hills, resources, treelines, etc.
- Attempts to extract relevant features from this, e.g. resources on front/hills, distance to opponent and so on.
**GamePlayer**
- Models the decisions/strategies/tactics made by individuals
- Identifies strategies, choices, etc.
- Two key lines of analysis - Military and Economic
**AgeGame**
- Central object, contains key data for the game (for example the GamePlayer and AgeMap objects), also houses mgz parsing behaviour.
## Appendices
#### AOE Devleopment Utilities
- [Siege Engineers GitHub](https://github.com/SiegeEngineers)
- [Relic/MS Documentation](https://wiki.librematch.org/librematch/data_sources/start)
- [Download Recs Manually @ aoe2recs.com](https://aoe2recs.com/)
- [AOE 2 rules for content](https://www.xbox.com/en-GB/developers/rules)
- https://api-dev.ageofempires.com/
- https://wiki.librematch.org/librematch/design/backend/authentication/start
#### MGZ file/recorded game structure
The .AOE2RECORD file type only contains the starting state of the game and the series of actions made by both players. This is extremely limiting when it comes to mining out statistics for a game.
For example, my original idea was to map growth in total resources as a proxy for player development and analyse the decisions that contributed to that. However, resources collected are not stored in the game files, and any modelling of villagers collecting resources would be difficult and woefully inaccurate (Modelling villager gather rates is extremely hard, what with their pathing, bumping, getting stuck, and the changing efficiency as the shape of a resource changes, etc. causing fluctuations in gather rates).
In general, what can be mined out of the .aoe2record file is limited.
As such, things like up times might be imprecise, as the game only records when a player clicks the research button, and I have had to completely model the production of each Town Centre to identify when research would be complete, based on queued villagers/techs etc. Currently, the mgz package does not seem to handle unqueing units particularly well, which trickles down into further inaccuracies in this package.
This package has turned into an exploration into what the mgz package can produce, and trying to gleam from that as much as possible.
#### MGZ Parser version to use
If the original aoc-mgz is behind the current game update and therefore not functional, check aoeinsights version and use that fork:
```
git clone https://github.com/aoeinsights/aoc-mgz
```
then
```
python setup.py install
```
Raw data
{
"_id": null,
"home_page": null,
"name": "age-alyser",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "statistics, AOE2, Age of Empires, parsing, mgz",
"author": null,
"author_email": "Benjamin Byrnes <b.byrnesy@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/13/e6/fb235e25e2dd89881abd9b8f249a9890490edf010ac0f5deb69e9e738011/age_alyser-0.0.4.tar.gz",
"platform": null,
"description": "# The Age-2-Alyser\r\nThis python package mines out key strategic choices and statistics from a recorded Age of Empires 2 game. The intention is to enable for further data analysis, including at scale. The package takes in a .AOE2RECORD file as input and produces a Pandas Series with statistical data about the match. This data includes:\r\n- The military strategy choices of both players throughout the game, including unit and strategy choices, production numbers, timings of openings, and so on.\r\n- The economic choices of each player through the game.\r\n- An analysis of the players' maps.\r\n- And some other miscellaneous data, such as elo difference and civilisations.\r\nThe package is built on top of the [mgz parser](https://github.com/happyleavesaoc/aoc-mgz/tree/master/mgz) to parse in recorded games - see also [this fork](https://github.com/aoeinsights/aoc-mgz) maintained by aoe insights. \r\n\r\nThe goal is to create an open source project that enables large scale analytics of the game. Capture Age provides incredible analysis tools for watching replays, however there is a gap in terms of being able to extract statistical data from games en masse for analytics purposes. The task is difficult, given the structure of an mgz file (see appendices below for a more detailed technical explanation).\r\n\r\nAside from this package, some other great projects I have come across which perform something similar are: \r\n- [Rec Opening Analysis by dj0wns](https://github.com/dj0wns/AoE_Rec_Opening_Analysis/tree/main)\r\n- [AOE insights](https://www.aoe2insights.com/)\r\n- [AOE Pulse made by dj0wns](https://www.aoepulse.com/home)\r\n\r\nThe goal of this package is to flesh out the statistical data we can mine from replays, and deliver it en masse to anyone who can bash up a python script. Feel free to contribute in any way (including a code review or building out tests or documentation).\r\n\r\n## Installation\r\n```\r\npip install age-alyser\r\n```\r\n\r\n## Usage and Documentation\r\nCurrently only the advanced parser is implemented - in the future I intend to flesh out the API with some other options.\r\n```\r\nimport pandas as pd\r\nfrom agealyser import AgeGame\r\n\r\ng = AgeGame(\"file/path/to/game.aoe2record\")\r\nstats: pd.Series = g.advanced_parser() # optional - include_map_analysis = False\r\n```\r\n#### Limitations\r\nGiven that:\r\n1. This package is dependant on the [mgz package](https://github.com/happyleavesaoc/aoc-mgz) (and I'm not planning on maintaining a fork or anything)\r\n2. Updates to the game can often break mgz's parsing of a .aoe2record file\r\n3. This package is an WIP/unfinished alpha release\r\n\r\nThere may be a number of inaccuracies, errors, and bugs.\r\n\r\nI would recommend wrapping the the above code in a try-except block. In the future I also intend to improve the error handling so the whole package fails more gracefully.\r\n\r\n#### Modeling Structure and package API\r\n**AgeMap** \r\n- Models the map itself and the resources/objects within\r\n- Identifies hills, resources, treelines, etc.\r\n- Attempts to extract relevant features from this, e.g. resources on front/hills, distance to opponent and so on.\r\n\r\n**GamePlayer**\r\n- Models the decisions/strategies/tactics made by individuals\r\n- Identifies strategies, choices, etc.\r\n- Two key lines of analysis - Military and Economic\r\n\r\n**AgeGame**\r\n- Central object, contains key data for the game (for example the GamePlayer and AgeMap objects), also houses mgz parsing behaviour.\r\n\r\n\r\n## Appendices\r\n#### AOE Devleopment Utilities\r\n- [Siege Engineers GitHub](https://github.com/SiegeEngineers)\r\n- [Relic/MS Documentation](https://wiki.librematch.org/librematch/data_sources/start)\r\n- [Download Recs Manually @ aoe2recs.com](https://aoe2recs.com/)\r\n- [AOE 2 rules for content](https://www.xbox.com/en-GB/developers/rules)\r\n- https://api-dev.ageofempires.com/\r\n- https://wiki.librematch.org/librematch/design/backend/authentication/start\r\n\r\n#### MGZ file/recorded game structure\r\nThe .AOE2RECORD file type only contains the starting state of the game and the series of actions made by both players. This is extremely limiting when it comes to mining out statistics for a game. \r\n\r\nFor example, my original idea was to map growth in total resources as a proxy for player development and analyse the decisions that contributed to that. However, resources collected are not stored in the game files, and any modelling of villagers collecting resources would be difficult and woefully inaccurate (Modelling villager gather rates is extremely hard, what with their pathing, bumping, getting stuck, and the changing efficiency as the shape of a resource changes, etc. causing fluctuations in gather rates). \r\nIn general, what can be mined out of the .aoe2record file is limited.\r\n\r\nAs such, things like up times might be imprecise, as the game only records when a player clicks the research button, and I have had to completely model the production of each Town Centre to identify when research would be complete, based on queued villagers/techs etc. Currently, the mgz package does not seem to handle unqueing units particularly well, which trickles down into further inaccuracies in this package.\r\n\r\nThis package has turned into an exploration into what the mgz package can produce, and trying to gleam from that as much as possible.\r\n\r\n#### MGZ Parser version to use\r\nIf the original aoc-mgz is behind the current game update and therefore not functional, check aoeinsights version and use that fork:\r\n```\r\ngit clone https://github.com/aoeinsights/aoc-mgz\r\n```\r\nthen \r\n```\r\npython setup.py install\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python package for extracting key features of an AOE2 recorded games",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/byrnesy924/AgeAlyser_2",
"Issues": "https://github.com/byrnesy924/AgeAlyser_2/issues"
},
"split_keywords": [
"statistics",
" aoe2",
" age of empires",
" parsing",
" mgz"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e0ab0550065472c2f5219c73816e0bcdfd6f02dcfd1f8fc8ba01555c2e603306",
"md5": "6b731dabc8821007c89224b2b1623c70",
"sha256": "f5b6ab909228509537f1003777d5f380ed68cfc69cf335193f59f367a9be20c3"
},
"downloads": -1,
"filename": "age_alyser-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6b731dabc8821007c89224b2b1623c70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 30317,
"upload_time": "2025-02-09T18:06:14",
"upload_time_iso_8601": "2025-02-09T18:06:14.354970Z",
"url": "https://files.pythonhosted.org/packages/e0/ab/0550065472c2f5219c73816e0bcdfd6f02dcfd1f8fc8ba01555c2e603306/age_alyser-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "13e6fb235e25e2dd89881abd9b8f249a9890490edf010ac0f5deb69e9e738011",
"md5": "0c11a2898562cba140e0022d41856602",
"sha256": "786ff58eec50529886d16b0c1450f6ea917c8039424bda49108174b53a1b0409"
},
"downloads": -1,
"filename": "age_alyser-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "0c11a2898562cba140e0022d41856602",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 29672,
"upload_time": "2025-02-09T18:06:16",
"upload_time_iso_8601": "2025-02-09T18:06:16.184496Z",
"url": "https://files.pythonhosted.org/packages/13/e6/fb235e25e2dd89881abd9b8f249a9890490edf010ac0f5deb69e9e738011/age_alyser-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-09 18:06:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "byrnesy924",
"github_project": "AgeAlyser_2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "age-alyser"
}
