read and write age of empires .dat files

Usage no npm install needed!

<script type="module">
  import genieDat from '';



read and write age of empires .dat files

Install - Usage - Supported Formats - Limitations - API - License: LGPL-3

npm travis standard


npm install genie-dat


var genieDat = require('genie-dat')
var buffer = require('fs').readFileSync('/path/to/empires2_x1_p1.dat')
genieDat.load(buffer, (err, dat) => {
  console.log( =>

Supported Formats

The data file format differs slightly between game versions. Versions supported by this library are:

  • aoc - All AoC-style formats, such as empires2_x1.dat of AoC 1.0 and empires2_x1_p1.dat of AoC 1.0c (the most common version). UserPatch and UserPatch based mods like WololoKingdoms and Portuguese Civ Mod also use this format. HD Edition versions before 5.0 also use this format.
  • african-kingdoms - The release of African Kingdoms changed the file format slightly; HD Edition versions 5.0 and up use this format. Note that this is used regardless of whether the African Kingdoms DLC is actually installed.


Age of Kings, SWGB, and the AoE1 and AoE:DE files are not yet supported. The goal is to expand support for these formats in the future.

Parsing a large binary file like this is quite slow, it takes about 6 seconds on my machine. This is probably not inherent and just has to do with the way this library is implemented on top of awestruct. Hopefully awestruct's performance can be improved in the future. You should cache the result if you need it often.


genieDat.load(buffer, opts={}, cb)

Decompress and load buffer, eg. a raw .dat file.

opts can be an object with properties:

cb is a Node-style callback receiving (err, dat). dat is a plain object representing the dat file contents. console.log() it to find out what's in it. There is a lot of junk, some of the more useful properties are:

  • playerColors - Player colours, mostly offsets into the main palette file
  • techs - Technology effects
  • terrains - Lists terrains
  • civilizations - Lists available civilizations
    • civilizations[i].objects - Lists unit statistics for each civ
  • researches - Lists available researches—this refers to the technology effects a lot

genieDat.loadRaw(buffer, opts={}, cb)

Load an already decompressed buffer. Use this if you manually did zlib.inflateRaw or got an uncompressed buffer through some other means. Otherwise it is identical to genieDat.load.


This project is based heavily on genieutils by apreiml and Tapsa, and on the openage conversion script.