Data Export

Games use config data to shape every mechanic and gameplay experience. Config data has to be easy for designers to edit and fast for a machine to parse. No single format does both. So designers work in one format, the game loads another, and a tool is needed to convert the former into the latter. Archmage is that tool.

Archmage supplies architectural blueprints, flexible parts, and a lightning-fast export pipeline. Both spreadsheets and tree-structured data share a rich, unified type system alongside practical filtering and validation options.

With contracts made explicit in the data, what you define becomes a shared understanding across your team — self-explanatory to anyone who opens it, today and long after.

As a result, anyone can export all config data using Archmage without having to ask around.

archmage export -o ./cooked "configs/*.xlsx" "configs/*.yaml"

To integrate exported data into AI workflows, Archmage offers two useful CLI flags: --readable turns opaque numbers into clear text, while --schema hands over the blueprint of each config file — no lookup, no guessing, just clarity.

Pipeline

1. Discover — Archmage scans for spreadsheets and tree-structured data files matching the specified paths or patterns.

   Archmage also provides advanced table resolvers: an index table allows a single Excel file to export multiple worksheets, while a virtual table allows several regular tables to act as a unified logical table.

2. Build Type Tree — Archmage parses input files to extract data types and establish the underlying type tree.

3. Prune — Archmage applies filters to trim structural nodes from the type tree and discard unwanted data from the raw input.

4. Parse, Validate and Transform — Archmage parses raw data against the pruned type tree, converts it into typed data, and enforces validation options throughout.

5. Write — Archmage writes configurations and the l10n aggregate to the output directory, alongside atlas.json.

Enum Types

During data export, Archmage validates enum values against their definitions. Supply enum definition files using the --enum-files CLI flag.

Config Files

Input to output:

• Each regular table and tree-structured data file produces a single output file.
• Depending on its marker, a property sheet produces one output file per value column ($@) or bundles all value columns into one (>>$@).
• Each partition of a virtual table exports independently.

Each output file is bound to an export name derived from its input file name, worksheet name, or index table configuration.

atlas.json

atlas.json is the manifest file for the Archmage SDK. It maps each export name to one or more output files, eliminating the need for manual path mappings. Archmage updates this file in the output directory on every successful export.

Each export name (key) adopts one of the three mapping strategies:

Strategy	Shape	Produced by	Runtime
unique	key → "file.json"	Regular table, tree-structured data file, >>$@ property sheet	Load the one file
variant	key → { "/": "file.json", "alt": "file.alt.json" }	$@ property sheet	Load one of them, / by default
many	key → ["foo.json", "bar.json"]	Virtual table	Load all of them and merge in order

atlas.json

{
  "version": {
    "semver": "v1.0.0",
    "branch": "main",
    "shortId": "7f3a2b9",
    "timestamp": "2025-02-09T10:23:45Z"
  },
  "unique": {
    "hero": "hero.json",
    "item": "clutter/item.json"
  },
  "variant": {
    "game": { "/": "game.json", "hard": "game.hard.json" }
  },
  "many": {
    "weapon": ["vtbl/weapon-sword.json", "vtbl/weapon-staff.json"]
  }
}

Version Information

The version block in atlas.json is included when --semver or --vcs is set. --semver specifies the semantic version for this build. --vcs resolves version control information from the current working directory, a specific repository path, or a custom file. The game can then read this data from atlas.json at runtime to identify the exact configuration build, making it easier to diagnose live issues.

L10n Files

During data export, Archmage collects all localizable strings from every input — l10n.xlsx, config files, and enum items. It then emits l10n.json, l10n.yaml, or l10n.csv, according to --l10n-output-formats, for downstream translation.

See the L10n Pipeline for details.

Further Control

Archmage provides a wide range of flags to control export behavior, including essential settings, filtering options, readability controls, and data-type defaults.

For the complete list of flags, see archmage export.