AoE4 World Data

Hosted data and icons on all AoE 4 units in a developer friendly format.

[ GitHub ]


Provide statically hosted data on all units, buildings, technologies, upgrades and other games objects in a json format which developers can use. Use these files to speed up your creation of awesome tools, charts and other apps!

Both the format and the data itself are open source, anyone can improve/correct it or add other useful properties. Additionally, automations and scripts could update data by reading game files or other sources.



  "id": "man-at-arms-4",
  "baseId": "man-at-arms",
  "type": "unit",
  "name": "Man-at-Arms",
  "age": 4,
  "civs": ["en", "hr", "fr", "de", "ab", "mo", "ru"],
  "description": "Tough infantry with good damage.\n\n+ High armor\n\n- Slow movement",
  "icon": "",
  "producedBy": ["barrack", "burgrave-palace"],
  "classes": ["Heavy Melee Infantry"],
  "unique": false,
  "hitpoints": 180,
  "movement": {
    "speed": 1.13
  "costs": {
    "food": 100,
    "wood": 0,
    "stone": 0,
    "gold": 20,
    "total": 120,
    "popcap": 1,
    "time": 22
  "weapons": [
      "type": "melee",
      "damage": 14,
      "speed": 1.25,
      "range": {
        "min": 0,
        "max": 0.3
  "armor": [
      "type": "ranged",
      "value": 5
      "type": "melee",
      "value": 5
  "sight": {
    "line": 36,
    "height": 10

Important This project is in its early days. The data format might change slightly, we recommend downloading the JSON files or reference a specific commit if you’re including them at runtime (example)


Category Status
Land Units ✅ Done
Naval Units ✅ Done
Buildings ✅ Done
Technologies ✅ Done, pending effects
Passive Civ Bonuses  


The format in which data is stored follows the following conventions:


Unified Units

While there may be variations of units (i.e. a stronger unit in each age) you may want to refer by them as their core unit. All units are stored in a unified format, which contains info on the unit with a variations array of all different versions of that unit.

Unified units are generated from their variations and stored in ./units/unified


For convenience we create a few bigger JSON files that group units of the same civ together, in both a normal array and a unified format.

Collection List Unified
All units in the game all.json all-unified.json
Abbasid abbasid.json abbasid-unified.json
Chinese chinese.json chinese-unified.json
Delhi Sultanate delhi.json delhi-unified.json
English english.json english-unified.json
French french.json french-unified.json
Holy Roman Empire hre.json hre-unified.json
Mongols mongols.json mongols-unified.json
Rus rus.json rus-unified.json

Contributing and development

Feel free to open PRs or issues for data that is incorrect or missing, if possible please provide a rationale or source. Even more helpful, add automations or scripts inside the ./.scripts folder which can update the data automatically. At the games current state, data is in a large part gathered by playing the game. For this reason, any automations for now are tools to help us create the files rather than a single source of truth.

AOE 4 Quicksheet Sync

Currently data is pulled in from the manually curated AOE 4 Quicksheet. To sync the data you will need to a (free) Google API Key which you can set using the environment variable AOE4_GOOGLE_SHEET_API_KEY. Then run yarn install && yarn run sync-quicksheet to update the data.

Image Sync Script

yarn sync-images loops over all unit files and sees if an image with a similair name exists in /images, if it does, it will set the icon field for that unit with the hosted url location and update the json file.

Compile Script

yarn build will compile index and bulk json files based on the unit files.

Adding new scripts

Can be added in a subfolder of .scripts, ideally using TypeScript. Common functionalitiy is stored in .scripts/lib


Initial data genoursly provided and collected by u/-MugenNoSora- in the AOE 4 Quicksheet with help from u/massrieen. Repository created and maintained by Robert van Hoesel.

License and rights

All of this data is open source, you may use it in your projects, websites and apps. However, Microsoft owns the Copyright on the game, and for this reason you can’t use this data in commercial contexts, excepts as described in Microsoft’s Game Content Usage Rules. Whenever you are using the data in this repository or other media from Age of Empires 4, please make sure to abide by the rules.

Age Of Empires 4 © Microsoft Corporation. Aoe4world/data was created under Microsoft’s “Game Content Usage Rules” using assets from Age Of Empires 4, and it is not endorsed by or affiliated with Microsoft.