Readability & AI

By default, the exported config data is full of opaque numbers. A damage type is 1, a weapon reference (to another table) is 10, and a cooldown is [0, 90] — these values cannot be understood without further inspection.

--readable changes that. It turns those numbers into readable text: the damage type becomes fire, the weapon reference resolves to Shadowfang, and the cooldown becomes 1m30s. The file now makes sense on its own.

This matters most when an AI consumes the data. To review your game’s balance, catch a wrong value, or iterate on core mechanics, an AI needs the values to mean something on their own. The clearer the values are, the less it guesses and the more it knows.

What --readable Changes

Enum Value

Default:

{ "damageType": 2, "defenseType": 0, "aura": 5 }

With --readable:

{ "damageType": "water", "defenseType": "none", "aura": "protection" }

Reference

Default:

{ "weaponRune": 7, "gems": [21, 56] }

With --readable:

{ "weaponRune": "EndlessRage", "gems": ["FlawlessDragonEye", "StarRuby"] }

Note

A reference resolves to a name only when both conditions are met: the target table has an anchor field, and the target config entry has its anchor specified.

Anchor

By default, anchors are dropped from the exported data. With --readable, anchors are preserved.

Default:

{ "102": { "power": 60, "range": 2 } }

With --readable:

{ "102": { "anchor": "ember-lance", "power": 60, "range": 2 } }

Config ID

Default:

{ "100": { "power": 45, "range": 3 } }

With --readable:

{ "100": { "id": 100, "power": 45, "range": 3 } }

Each config entry then contains its own ID, which makes a single config entry readable without checking the surrounding key. Only regular tables have config IDs.

Duration

Default:

{ "castTime": [1, 1500], "cooldown": [0, 90] }

With --readable:

{ "castTime": "1.5s", "cooldown": "1m30s" }

Localization (l10n)

By default, l10n text is moved into the generated l10n file(s) for translation, leaving a lookup key in its place. With --readable, the text stays inline.

Default:

{ "name": "weapon[100].name" }

With --readable:

{ "name": "Dragon Slayer" }

File Path

Input:

{ "mapData": "maps/Stormwind.dat" }

Assume mapData has the replaceExt=.bytes option. By default, the exported path uses that extension. With --readable, the path is kept unchanged.

Default:

{ "mapData": "maps/Stormwind.bytes" }

With --readable:

{ "mapData": "maps/Stormwind.dat" }

Weighted Pool

Default:

{
  "dropPool": {
    "items": ["gold", "gem", "nothing"],
    "weights": [50, 10, 40]
  }
}

With --readable:

{
  "dropPool": [
    { "item": "gold", "weight": 50 },
    { "item": "gem", "weight": 10 },
    { "item": "nothing", "weight": 40 }
  ]
}

A Schema for Every File

Readable values explain the data; a schema explains its shape. --schema writes a .schema file beside each exported file, naming every field once — its path, its type, and the description you gave it. Nothing about the structure is left to guess. An AI understands the exported file without ever opening the original spreadsheet.

spell.schema

---
name: spell
source: spell.xlsx
---
$                 map[int64]
$.*               {}
$.*.id            int64             # entry id
$.*.name          l10n              # spell display name
$.*.element       enum@magicType    # damage element
$.*.rune          ref@weapon-rune   # bound rune
$.*.power         int               # base power
$.*.cooldown      duration          # time between casts
$.*.channeled     bool              # whether it channels
$.*.mountPoint    vector3           # effect mount point
$.*.mountPoint.x  float32
$.*.mountPoint.y  float32
$.*.mountPoint.z  float32

spell.json (readable)

{
  "101": {
    "id": 101,
    "name": "Fireball",
    "element": "fire",
    "rune": "emberstrike",
    "power": 45,
    "cooldown": "1m30s",
    "channeled": false,
    "mountPoint": { "x": 0, "y": 1.2, "z": 0 }
  }
}

spell.json (default)

{
  "101": {

    "name": "spell[101].name",
    "element": 1,
    "rune": 3,
    "power": 45,
    "cooldown": [0, 90],
    "channeled": false,
    "mountPoint": { "x": 0, "y": 1.2, "z": 0 }
  }
}

Note

--schema needs --format json.

Two Flags

--readable puts the meaning back into values. --schema hands over the blueprint. Two flags, and your config is ready to be read, questioned, and improved — for humans and AI alike.

archmage export --readable --schema -o ./cooked "*.xlsx" "*.yaml"