Data Types

At the core of Archmage lies a rich, unified type system that governs how configuration data is parsed, validated, and transformed. Whether it is a column in a regular table, a row in a property sheet, or a node in a tree-structured data file, each is bound to one of these types.

Type Availability Matrix

Category	Regular Table	Property Sheet	Tree-Structured Data
Basic Types	✓	✓	✓	View
Passive Types	✓		⁕	View
Compact Types	✓	✓		View
Multi-Column Types	✓			View
Subtable Types	✓			View
Behavior Types	✓	△	△	View
Non-Leaf Types			✓	View

⁕: Passive types are supported in tree-backed regular tables.
△: placeholder is supported in property sheets and tree-structured data; anchor is supported in tree-backed regular tables.

Categories

Basic Types

The foundational data types.

Group	Types
Integers	`int`, `int8`, `int16`, `int32`, `int64` `uint`, `uint8`, `uint16`, `uint32`, `uint64`	View
Floating-Point Numbers	`float`, `float32`, `float64`	View
String	`string`	View
Boolean	`bool`	View
Enumeration	`enum`	View
Datetime	`datetime`	View
Duration	`duration`	View
Cross-Table Reference	`ref`	View
Localization	`l10n`	View
File Path	`path`	View
Color	`rgba`	View

Passive Types

Passive types do not require manual input; their values are derived from references or context.

Type	Description
`backref`	A single back-reference to the source config entry	View
`backref-n`	An array of back-references to the source config entries	View
`origin`	The source of a config entry	View

Compact Types

Compact types encode structured data into a single cell using a concise text format.

Type	Description
`>>[]T`	Compact array	View
`>>[N]T`	Fixed-size compact array	View
`>>map[K]V`	Compact map	View
`>>object`	Compact object	View
`>>minmax`	Compact minmax	View
`>>wtpool`	Compact weighted pool	View
`>>vector`	Compact vector	View
`>>tuple`	Compact tuple	View

The >> prefix is part of the type name.

Element types of these composite types must be Basic Types, such as >>[]int or >>map[int]float32.

Element values are separated by |, such as 1|2|3.

Multi-Column Types

Multi-column types span multiple columns to form a single logical field, with each column holding only one element.

Type	Description
`[]T`	Multi-column array	View
`[N]T`	Fixed-size multi-column array	View
`map[K]V`	Multi-column map	View
`minmax`	Multi-column minmax	View
`wtpool`	Multi-column weighted pool	View
`vector`	Multi-column vector	View
`tuple`	Multi-column tuple	View
`bitflags`	Multi-column bitflags	View

Element types of these composite types must be Basic Types or Compact Types, such as []int or map[int]>>vector|2|float32.

Subtable Types

Subtable types define embedded subtables within a regular table. For each config entry, a subtable spans multiple rows and columns, where each row maps to a single object (for **[], **[N]) or a key-object pair (for **map).

Type	Description
`**[]`	Subtable array	View
`**[N]`	Fixed-size subtable array	View
`**map`	Subtable map	View

The ** prefix is part of the type name.

Fields of subtable objects must be of Basic Types, Compact Types, Multi-Column Types, or specific Behavior Types (assert, placeholder).

Behavior Types

Behavior types act as functional directives that guide the processing pipeline for data export and code generation.

Type	Description
`anchor`	Allows using names instead of integer IDs for cross-table references	View
`assert`	Validates a boolean; raises an error if it fails	View
`condition`	Determines whether to export a config entry; supports expressions and rich matching rules (e.g., `cflags=james`, `v1.2.3`)	View
`switch`	Multi-branch selector in conjunction with the `Case` header to determine active fields	View
`placeholder`	Prevents structurally empty objects from being removed	View

Fields of most Behavior Types are omitted from exported data and do not participate in code generation, except for:

switch is treated as string.
anchor is treated as string when the --emit-anchors CLI flag is set.

Non-Leaf Types

Non-leaf types apply exclusively to [] or {} tree-structured data nodes, determining how Archmage processes these nodes and their children.

Type	Description	Target Node
`[]`	Tree array	`[]`	View
`[N]`	Fixed-size tree array	`[]`	View
`map`	Tree map (key-value pairs)	`{}`	View
`{}`	Tree object	`{}`	View
`minmax`	Tree minmax	`{}`	View
`wtpool`	Tree weighted pool	`[]`	View
`vector`	Tree vector	`{}`	View