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 pipeline.

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 --namespace 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 'conf' item.xlsx

Note

Some code templates require --namespace. If omitted, the command will fail with an error.

--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#
json-gd	JSON + GDScript
unity-editor	JSON + Unity Editor
godot-editor-cs	JSON + Godot Editor (C#)
godot-editor-gd	JSON + Godot Editor (GDScript)

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 version.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).

--keep-stale

Keep the files that --manifest would delete.

--manifest

Path of the manifest file listing generated files. On the next run, Archmage deletes any files listed in the manifest that are not generated during that run. A relative path is resolved from the output directory.

--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
cs-godot-vector	C# with Godot Vector

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

--skipped-log

Path of a log file recording only files and worksheets that were skipped for being structurally empty. A relative path is resolved from the output directory.

--suffix

Suffix for generated element types of top-level tables and arrays (default: _cfg).

--suffix-array

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

--suffix-entry

Suffix for generated element types of non-top-level tables and arrays (default: _entry).

--suffix-props

Suffix for the generated top-level types of $@ property sheets and of tree-structured data whose root is a tree object (default: _cfg).

--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 that <dir> belongs to. If <dir> is a subdirectory of the repository, only the last commit affecting that subdirectory is collected.
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	Description
ARCHMAGE_FILE_NAMING_STYLE	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	Indentation style: tab or space. Each template has its own default. Not applicable to the Go template — Go output is always formatted by gofmt.
ARCHMAGE_INDENT_TAB_SIZE	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.
ARCHMAGE_ALL_PUBLIC	When set to true, makes all generated types public or exported, depending on the target language.

Template-specific

Variable	Description
ARCHMAGE_GD_CLASS_NAME_SUFFIX (Template: json-gd)	Suffix of the enum class names that the generated code refers to (default: Enum). Set it to the value used with archmage enum -t gd.
ARCHMAGE_GD_FLOAT_DURATION (Template: json-gd)	When set to true, generates each duration as a float that holds seconds, instead of an Archmage.Duration. to_json then gives a duration as a number of seconds, which load_json cannot read back, and MinMax.sample() draws from a duration range as from any float range, not in whole milliseconds.
ARCHMAGE_GD_STRING_L10N (Template: json-gd)	When set to true, generates each l10n field as a String that holds the l10n key, instead of an L10n object, to use less memory. Code then reads the text with L10n.text(key) instead of the text property of L10n.
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.