Querying the Age of Empires 1997 database (`empires.dat`) with jq and a custom `empires2json` tool

empires-helper.jq

# Requires: jq 1.5

##########
# Hello and welcome!
# Quick note: Comments in a jq program file (which this is!) begin with a '#'.
#
# The comments in this file assume you have ran `empires2json` on your AoE's `empires.dat` file
# and stored the result in a `empires-dat.json` file on disk.
#
# To make use of this file you will need `jq` 1.5 (or a later version) installed (see https://stedolan.github.io/jq/).
#
# Below is an example invocation of jq (do not type the '$' into your shell):
# $ jq -f empires-helper.jq empires-dat.json
#
# How to use this file:
#   Uncomment the filter you would like to use by removing the leading '#'s on each line (keep the double # lines as they explain what the filter does)
#   then run the command given above (the line starting with "jq -f").
#
# I recommend starting with this first filter so you can get a feel for what exactly is happening.
#
# When you run this filter jq will output a JSON array of objects
# containing the `id`, `name`, `short_name`, `slp_id`, and `frame_count` properties
# of all of the graphic objects in the input JSON whose name contains the string "Arrow".
#
# Please feel free to email me with questions, comments, concerns, etc. here: taryn@phrohdoh.com
##########

## Find all graphics with "Arrow" in the name
# [
#     .graphics[]
#     | select(.name | contains("Arrow"))
#     | {id, name, short_name, slp_id, frame_count}
# ]

## Find all graphics with associated delta graphics and get the delta graphic's `slp_id` property
#. as $root |
# [
#     .graphics[]
#     | [ .deltas[] | .graphic_id ] as $delta_graphic_ids
#     | [ $root | .graphics[] | select(.id | in($delta_graphic_ids)) | .slp_id ] as $delta_slp_ids
#     | select($delta_slp_ids | length > 0)
#     | { id
#       , name
#       , slp_id
#       , delta_slp_ids: $delta_slp_ids }
# ]

## Find all units with `fly_mode` set to `false`
# [
#     .civilizations[]
#     | .units
#     | to_entries[]
#     | .value
#     | select(.fly_mode == false)
#     | {id, name, standing_graphic}
# ]

## Find all units with at least 1 value in the `damage_graphics` array
# [
#     .civilizations[]
#     | .units
#     | to_entries[]
#     | .value
#     | select((.damage_graphics | length) > 0)
#     | { id,
#         name,
#         graphic_ids: ([.damage_graphics[] | .graphic_id]) }
# ]

## Find the first 10 units with a name containing the string "Chariot"
# [
#     limit(10; .civilizations[]
#     | .units
#     | to_entries[]
#     | .value
#     | select(.name | contains("Chariot"))
#     | { id
#       , name
#       , standing_graphic }
#     )
# ]

## Calculate how many `graphics` objects have a `short_name` of "None"
# [
#     .graphics[]
#     | select(.short_name == "None")
# ] | length

## NOTE: To use this filter you must provide the value via the command-line. An example `jq` invocation follows (exclude the '$').
##       $ jq -f empires-helper.jq empires-dat.json --arg RESOURCE_TYPE "Gold"
##
##       If you omit `--arg RESOURCE_TYPE "your value"` you will get an error similar to the following.
##       jq: error: RESOURCE_TYPE/0 is not defined at <top-level>, line 78:

## Find all researches that have some amount of a resource cost (exactly which resource is provided on the command-line [see above])
# [
#     .research[]
#     | select(.resource_costs | any(.resource_type == $RESOURCE_TYPE))
#     | { id, name, required_techs }
# ]

Real-world data

My local empires.dat has the following sha256:

$ sha256sum /mnt/aoe1/GAME/DATA/EMPIRES.DAT
8c28f83df77bb23174f85b0bd5281d2f0a2f3539a0e47342a2ed757d6252502e  /mnt/aoe1/GAME/DATA/EMPIRES.DAT

Running the following filter against the JSON produced from my local empires.dat file

[
    .graphics[]
    | select(.name | contains("Arrow"))
    | {id, name, short_name, slp_id, frame_count}
]

results in the following JSON

[
  {
    "id": 0,
    "name": "Arrow",
    "short_name": "arrow",
    "slp_id": 243,
    "frame_count": 1
  },
  {
    "id": 1,
    "name": "Arrow B fire",
    "short_name": "bolt_flm",
    "slp_id": 265,
    "frame_count": 3
  },
  {
    "id": 2,
    "name": "Arrow Bolt",
    "short_name": "arr_bolt",
    "slp_id": 242,
    "frame_count": 1
  },
  {
    "id": 3,
    "name": "Arrow Fire",
    "short_name": "arw_flm",
    "slp_id": 252,
    "frame_count": 3
  },
  {
    "id": 838,
    "name": "Arrow Bolt shad",
    "short_name": "s_abolt",
    "slp_id": 709,
    "frame_count": 1
  },
  {
    "id": 840,
    "name": "Arrow shadow",
    "short_name": "s_arrow",
    "slp_id": 710,
    "frame_count": 1
  }
]