archmage struct

The struct subcommand parses configurations from spreadsheets and tree-structured data files, prunes each configuration tree, applies transformations, and emits fully-typed struct definitions and auxiliary code.

See Code Generation for the complete workflow.

Usage

archmage struct -t <template> -o <output-dir> [flags] <file1> [<file2> ...]

Input files may be specified as literal paths or glob patterns.

# Generate Go code from a single spreadsheet
archmage struct -t json-go -o ./conf item.xlsx

# Generate C# code from all config files with a template override
archmage struct -t json-cs --overrides cs-unity-vector -o ./Conf \
  "configs/*.xlsx" "configs/*.yaml"

# Work with enum definitions
archmage struct -t json-go -o ./conf \
  -e "enum/*.enum.yaml" \
  "configs/*.xlsx" "configs/*.json"

Flags

Essential

--enum-files / -e

Comma-separated list of enum definition files or glob patterns. Required to resolve the enum types used in configurations.

archmage struct -t json-go -o ./conf -e "enum/*.enum.yaml" item.xlsx

--l10n

Path to l10n.xlsx. Required when any input uses the l10n data type. l10n.xlsx contains all shared localizable strings to be reused across files.

See the L10n Pipeline for details.

--namespace

Namespace, package, or module path for the generated code.

archmage struct -t json-go -o ./conf --namespace 'game/conf' item.xlsx

--output-dir / -o

The directory where generated files are written.

--template / -t

The code template to use. Accepts either a built-in template name listed below or a path to a custom template file.

Name	Use Case
json-go	JSON + Go
json-cs	JSON + C#
unity-editor	JSON + Unity Editor

archmage struct -t json-go -o ./conf item.xlsx
archmage struct -t ./custom.tpl -o ./conf item.xlsx

--vtables-config

Path to the virtual table manifest, which defines multiple virtual tables.

A virtual table is a logical construct that groups similar regular tables, allowing Archmage to resolve them as a single unit during pipeline execution.

See Virtual Tables for details.

---

Filtering

These flags control which fields take part in code generation.

See Filtering Mechanisms for more information.

--brace-flags / -b

Comma-separated brace flags for config set activation, evaluated against the Brace Flags embedded in field names.

--cflags

Comma-separated condition flags for config entry and tree node inclusion, evaluated against the cflags specified within conditions.

--semver

The config files’ semantic version (e.g., v1.0.0).

Archmage also writes it to the semver field in atlas.json, and embeds it in the generated code.

See minver for more information.

--tags

Comma-separated general-purpose flags for field inclusion, evaluated against all tags from options and conditions.

--tags-xx

Comma-separated general-purpose flags for field exclusion, evaluated against all tags from options and conditions.

--xflags / -x

Comma-separated scenario flags for field inclusion, evaluated against all xflags from options and conditions.

---

Data Type

--float-bit-size

The bit size for float types — 32 or 64 (default: 64).

--int-bit-size

The bit size for int and uint types — 32 or 64 (default: 64).

--tree-float-type

Default floating-point type for tree nodes (default: float64).

Valid values: float, float32, float64.

--tree-int-type

Default integer type for tree nodes (default: int64).

Valid values: int, int32, int64.

---

Others

--banner

Print the Archmage banner on startup.

--crlf

Write all output files with CRLF (\r\n) line endings instead of LF (\n).

--cwd

Change the working directory before running. Relative paths are resolved from this directory.

--dotenv

Load environment variables from the specified file before running. If omitted and a .env file exists in the working directory, it’s loaded automatically.

--dry-run

Process all input files and validate them without writing any output.

--emit-anchors

Generate code for anchor fields.

--flush-on-progress

Flush logs immediately when progress updates.

--jq

Render node paths in error messages as jq expressions (.rewards[0].name) instead of JSONPath ($.rewards[0].name), ready to paste into a jq command.

--jq-code

Render the node paths embedded in generated code comments as jq expressions (.rewards[].name) instead of JSONPath ($.rewards.*.name).

--overrides

Template fragments to apply on top of the base template. Accepts either a built-in template name listed below or a path to a custom template file.

Name	Use Case
cs-unity-vector	C# with Unity Vector

archmage struct -t json-cs --overrides cs-unity-vector -o ./Conf \
  "configs/*.xlsx"

--skipped-log

Log skipped files and worksheets to the specified file.

--suffix

Suffix for generated top-level types (default: _cfg).

--suffix-array

Suffix for generated top-level array types (default: _array).

--suffix-table

Suffix for generated top-level table types (default: _table).

--vcs

Collect version control information, embed it in the generated code, and write a version.json file to the output directory.

Value	Source
git	The Git repository in the current working directory
git@<dir>	The Git repository at <dir> (may be a subdirectory of the repo)
A file path	A custom JSON file describing the version

A custom JSON file takes this shape:

{
  "workspace": "",
  "tags": [],
  "branch": "main",
  "id": "7f3a2b9c8e1d4f6a5b2c9e8d7f3a2b9c8e1d4f6a",
  "shortId": "7f3a2b9",
  "timestamp": "2025-02-09T10:23:45Z",
  "message": "feat: add i18n support with language fallback",
  "author": "Alice Wang <[email protected]>",
  "status": [],
  "extra": {}
}

Examples:

archmage struct -t json-go -o ./cooked --vcs git configs/*.xlsx
archmage struct -t json-go -o ./cooked --vcs ./version.json configs/*.xlsx

--verbose / -v

Print extra status messages.

Environment Variables

Environment variables fine-tune output behavior for things that require cross-layer penetration — file naming, indentation style, language-specific options, etc.

Common

These variables are recognized by all or most built-in templates.

Variable	Default	Description
ARCHMAGE_FILE_NAMING_STYLE	Varies by template	Naming style for output files. Common values: snake, kebab, pascal, camel. When omitted, each template falls back to its own default (e.g. pascal for C#).
ARCHMAGE_INDENT_STYLE	Varies by template	Indentation style: tab or space. Not applicable to the Go template — Go output is always formatted by gofmt.
ARCHMAGE_INDENT_TAB_SIZE	Varies by template	Number of spaces per indent level when ARCHMAGE_INDENT_STYLE is space. Each template has its own default (commonly 2 or 4). Not applicable to the Go template.
ARCHMAGE_OUTPUT_ENV	—	When set to true, generates an archmage.env file alongside the enum output. It records all environment variables used by the current template, which is useful for build reproducibility and debugging.

Language-specific

Variable	Default	Description
ARCHMAGE_UNITY_BURST (Template: json-cs)	—	When set to true, injects [BurstDiscard] to discard managed Equals calls during Burst compilation, preventing unsupported managed-boxing compiler errors.