Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.1.0] - 2026-10-18

SDK Version: *.20.*

Added

Code Generation: Added the json-gd template, which generates GDScript config code.
Code Generation: Added the godot-editor-gd template, which generates a Godot editor plugin in GDScript. The plugin loads the configs in the editor, shows config ID properties as dropdowns, and reloads them from the Tool menu.
Code Generation: Added the ARCHMAGE_GD_STRING_L10N environment variable, which makes json-gd keep l10n fields as String instead of the L10n type, to save memory.
Code Generation: Added the ARCHMAGE_GD_FLOAT_DURATION environment variable, which makes json-gd generate durations as float seconds.
Project Initialization: init now accepts -l gd, which generates a Godot project.

Changed

Code Generation: The godot-editor template is renamed to godot-editor-cs.
Type System: A string, path, or l10n value in a spreadsheet that is the unquoted text <null> is now rejected. It was previously read as the literal text. Quote it to use "<null>" as text.

Fixed

Code Generation: The Inspector of the godot-editor-cs plugin now updates its property editors when the plugin is enabled or disabled, instead of keeping the old ones until the editor restarts.
XML: An element without attributes, text, or child elements is now exported as null and dropped. It was previously exported as an empty string.

[1.0.0] - 2026-10-13

SDK Version: *.20.*

Added

Data Export: --l10n-output-formats now accepts xlsx and outputs l10n.xlsx with Key and Text columns.
Data Export: Added the --csv-bom flag, which outputs l10n.csv with a UTF-8 BOM so that Excel detects the encoding.
XML: A list whose parent has only one such element can now be declared as an array using the __array__="true" attribute.

Changed

Localization: l10n keys are now delimited with |, so that different values never share a key.
Naming: Typical names and variable names must now start with a letter. A leading underscore, such as _hp, is rejected.
Spreadsheets: A cell that holds an Excel error value, such as #N/A or #DIV/0!, is now reported as an error. It was previously treated as a comment.
Spreadsheets: A lookback operator that points to the superheader column or to a column before it is now rejected.
Type System: Integers with leading zeros, such as 010, are now read as decimal instead of octal.
Type System: datetime values with fractional seconds are now rejected.
Type System: whitelist and blacklist now ignore letter case for bool, enum, ref, and rgba values.
Type System: Objects that share a pubtype can now declare their fields in any order.
Filtering: An empty environment variable in env@VAR is now treated as false.
YAML: Numbers now follow YAML 1.2. A YAML file with a tag, infinity, NaN, more than one document, or a non-UTF-8 encoding is now rejected.
Data Export: export now fails before writing anything if an output file would overwrite or delete an input file.
Error Messages: JSON syntax errors now report the line and column.

Fixed

YAML: A file that uses a merge key (<<) no longer converts to JSON with duplicate keys.
Enum: The name and shorthand of an enum item excluded by xflags can no longer be used in data.
Enum: A bitflags enum item without an explicit value now takes the bit above the highest bit used so far, so it no longer overlaps flags after a combined value such as read | write.
Type System: A compact vector with the scale option no longer causes a panic.
Code Generation: With --float-bit-size 32 and --int-bit-size 32, cs-unity-vector and cs-godot-vector now also map float and int vectors to engine vectors.
Code Generation: struct now removes the version.json of an earlier run when it runs without --semver and --vcs.
Data Export: With --crlf, line breaks inside the fields of l10n.csv are no longer converted to CRLF.

[0.20.0] - 2026-10-11

SDK Version: *.20.*

Added

Type System: Added the maxChars option, which limits the number of characters (Unicode code points) in string and l10n values.
Type System: Added the asL10n option for tree objects, which treats every value in the object’s subtree that is inferred as string as l10n.
Type System: The scale option now accepts a fraction of positive integers, such as scale=1/1000.
Type System: datetime values in spreadsheets can now be quoted, such as datetime="08:00:00".
Type System: l10n can now be the item type of a weighted pool (wtpool).
Code Generation: Added the --manifest flag to the enum and struct subcommands. The flag records generated files in a manifest; the next run deletes any files listed in the manifest but not generated during that run. Pass --keep-stale to keep them.

Changed

Weighted Pool (wtpool): A non-empty l10n value anywhere in a weighted pool, including the fields of object items, must now be a reference to a shared l10n string.
Localization: In a property sheet, the l10n key of a value in a named value column now has the column name in brackets, such as game[hard].title instead of game.hard.title.
Data Export: export now deletes the data files and .schema files listed in the previous atlas.json but not generated by the current run.
Code Generation: CodeVersion is now always generated and returns nil if no version information is available.

Fixed

Type System: An object in a regular table or property sheet that holds a placeholder field is no longer removed from exported data and generated code.
Code Generation: With ARCHMAGE_ALL_PUBLIC, the Go type of a nested object now keeps the underscore after its base name.
Data Export: --dry-run no longer deletes orphaned output files.
Data Export: A value that is a string in a data file and a number or bool in its demo file, or the reverse, is now rejected.
Data Export: An XML element that contains both text and child elements is now rejected.
Format Conversion Utility: conv now rejects input files with the same name, which overwrote each other’s output.

[0.19.0] - 2026-10-09

SDK Version: *.20.*

Added

Type System: Added the scale option, which multiplies float, float32, and float64 values by a factor during data export.
Type System: Added the dir option, which requires path values to refer to directories.

Changed

Type System: switch|enum values and case labels are now matched by enum value, so an enum item name, its shorthand, and any letter case of either match the same label.
Type System: Numeric switch|enum values, including 0, are now rejected.

Fixed

Code Generation: Discarded fields are no longer compared when Archmage checks that objects sharing a pubtype have the same structure.

[0.18.0] - 2026-10-07

Added

Type System: Added the addPrefix option, which prepends a relative directory to path values.
Data Export: Added the ARCHMAGE_SKIP_PATH_CHECK environment variable, which skips the checks of path values.
Virtual Tables: Added the schema-identical flag, which requires every partition of a virtual table to have the same structure.
Weighted Pool (wtpool): The element objects of wtpool|>>object can now declare a pubtype.
Code Generation: Added the --suffix-entry and --suffix-props flags to the struct subcommand.
Code Generation: Added the ARCHMAGE_ALL_PUBLIC environment variable, which makes all generated types public or exported.

Changed

Type System: The root option of path now accepts only root=env@<VarName>. A path field without root uses ARCHMAGE_PATH_ROOT, or the working directory if that variable is not set.
Type System: path values are now checked by default. They must refer to existing files with matching letter case, and must not contain ...
Type System: Objects that share a pubtype must have the same spelling and structure. A pubtype on the config entry of a regular table or on a top-level property of a property sheet is now rejected.
Type System: A fixed-size multi-column array ([N]T) with a default export value now fills blank cells with the element default.
Weighted Pool (wtpool): Options can now apply to the item.
Virtual Tables: The default origin value is now the export name. Partitions that share an origin value must have the same structure, and a virtual table can have at most one origin field.
Code Generation: Objects with the same structure in the same file no longer share the same type.
Code Generation: Top-level {} types now use --suffix-props instead of --suffix.
Code Generation: The root map key of a tree-backed regular table is now inferred as int64, matching its config ID.

Fixed

Virtual Tables: A field discarded in one partition is no longer removed from the generated type when another partition exports it.
Type System: ## on a **[N]={}{} subtable array now exports the same zero-valued objects as a blank block.
Type System: A tree-backed regular table is no longer rejected for two anchor fields when brace flags or xflags remove one of them.
Data Export: Errors in condition columns, tree files and anchor fields are now reported before later checks can stop the export with a misleading error.

[0.17.0] - 2026-10-01

Added

Code Generation: Added the cs-godot-vector template override for Godot vector types.
Code Generation: Added the godot-editor template, which generates a Godot editor plugin that loads the configs in the editor and shows config ID properties as searchable dropdowns in the Inspector. It also generates the CfgIdPropHint and CfgIdPropType constants for exporting config IDs from game code.
Code Generation: The unity-editor template now registers a dropdown for every table that has a config ID, with the ID as its display name.
Code Generation: Added the ARCHMAGE_JAVA_OUTER_CLASS_NAME_SUFFIX and ARCHMAGE_GD_CLASS_NAME_SUFFIX environment variables for the enum code templates.

Changed

Code Generation: The Java outer class name and the GDScript class_name now end with Enum by default.
Code Generation: The generated C# ConfigAtlas registers the type converter of each CfgId type in a static constructor.
Code Generation: The C# JSON templates mark generated files with <auto-generated />.

[0.16.0] - 2026-09-24

Added

Type System: Added switch|enum@<enumType> to hold enum items in switch columns. Data export (including --human-enum) and code generation treat the values as enum@<enumType>.

Changed

C# Code Generation: String config IDs now treat null as an empty ID in equality, hashing, conversion, and JSON output, and absent ref fields no longer serialize as null.

Fixed

Code Generation: ref fields that target a virtual table now generate reference types instead of plain value types.
Code Generation: The generated L10n text accessors now return an empty string for blank l10n fields instead of failing.

[0.13.0] - 2026-09-23

Added

Installation: Added a Windows installer for Windows 10 or later.

[0.10.0] - 2026-09-07

Added

Type System: Added the ref@++ mark to designate preferred reference candidates when multiple ref values point to the same target entry, determining back-reference eligibility.
Type System: Added support for empty rgba color values, corresponding to implicit tree-node defaults.
Version Info: Added the --semver flag to specify the semantic version for the build, embedding it into the exported output (atlas.json / version.json).

Changed

Google Drive Integration: Wildcard pattern matching for Drive files now supports standard path matching semantics anywhere in the pattern.

[0.9.0] - 2026-08-05

Added

Google Drive Pull Command: Added a major new archmage drive command suite (login, logout, list, download) to pull and sync spreadsheets from Google Drive to a local directory.
Data Export: Added the --omit-zero flag to automatically drop zero-valued object fields from the exported data payloads.
Logging: Added the --verbose / -v flag to raise selected debug logs to the info level.

Changed

Type System: The minmax data type now natively supports duration as a valid element type.
Type System: Added validation support for backref and backref-n fields.

[0.8.0] - 2026-07-01

Added

Schema Generation: Added the --schema flag to generate .schema sidecar files that describe the exact types and structures of the parsed data.
Type System: Added support for using enum types as map keys.
Data Traversal: Introduced --jq and --jq-code flags to render jq-compatible node paths for easier downstream data traversal.

[0.7.0] - 2026-06-02

Added

Weighted Pool (wtpool): Added support for using tree object ({}) and compact object (>>object) as item types within weighted pools.
Weighted Pool (wtpool): Added support for the synclen validation option.
Type System: Added the keyOnly option for both compact (>>map[K]V) and multi-column (map[K]V) map types.
Data Export: Added the --readable flag to emit human-friendly data formats during export.
Data Export: Added --human-wtpool to export weighted pools in an intuitive key-value structure instead of raw arrays.
Data Export: Added the --human-ref flag to output readable reference and back-reference values.
Data Export: Added the --human-duration and --human-enum flags for human-friendly output of durations and enumerations.
Data Export: Added the --emit-anchors flag to export configuration anchors as string literals.
Data Export: Added the --l10n-literal flag to disable l10n aggregation.
Data Export: Added the --path-as-is flag to preserve exact path values during export.
Data Export: Added --tree-float-type and --tree-int-type flags to explicitly control the type of numeric values in tree data structures.
Data Export: Added yaml as a natively supported output format for localization (l10n) data exports.
Data Export: Added support for configuring the JSON export indentation style via environment variables.
Logging: Added the --flush-on-progress flag to flush logs upon progress updates.

[0.6.0] - 2026-05-01

Added

Minmax Type: Added support for the minmax data type across compact, multi-column, and tree structures, including full code generation support for C# and Go.
Spreadsheet Conventions: Added lookback operators (<1, <2, <3) in the header region to reuse values from preceding columns.
Data Constraints: The nonzero validation option is now fully supported for compact vectors and multi-column tuples/vectors.
Data Constraints: Added the synclen option to enforce equal-length containers.

[0.5.0] - 2026-04-06

Added

Type System: Added the anchor type to enable named config-id lookups within reference fields.
Type System: Added support for hex color rgba values (e.g., #RRGGBB / #RRGGBBAA).
L10n Key Access: Added built-in L10nKey() / GetL10nKey() accessor methods to the generated enum code across all supported languages.
C# Code Generation: Added ConfigAtlas.Instance for global atlas singleton access.
C# Code Generation: Enabled direct configuration lookup using strongly-typed Config ID structs (e.g., id.Cfg).
C# Code Generation: Added support for mapping to external C# vector types and enabled nullable reference types.
Code Generation: Added the --unity flag to support mapping to Unity’s built-in vector types.
Data Bundling: Added the --add-meta flag to the bundle subcommand to inject __meta__ root nodes into the final output.

[0.4.0] - 2026-03-03

Added

Virtual Tables: Added extensive support for virtual tables, including conflict checking and cross-file reference/backref resolution.
Data Export: Added the --no-atlas flag to the export subcommand to skip atlas.json generation.

Changed

Export Capabilities: The --l10n-output-formats option now accepts multiple comma-separated formats, generating them simultaneously in a single pass.

[0.3.0] - 2026-02-03

Added

Format Conversion Utility: Added the conv subcommand to explicitly convert tree-structured config files to JSON.
Type System: Added the switch behavior type as a multi-branch selector to determine active fields in conjunction with the Case header.
Type System: Added the discard option to drop fields from the output while keeping them available for validation.
External Enums: Added code generation support for mapping external enum types across all language templates.
Version Info: Introduced the --vcs flag, automatically bundling Git branch, commit ID, and author metadata directly into the output.

[0.2.0] - 2026-01-01

Added

Data Bundling Utility: Added the bundle subcommand to merge multiple tree-structured data files into a single JSON file.

[0.1.0] - 2025-12-05

Added

Initial release.