Multi-Column Types

Multi-column types span multiple columns to form a single logical field. Each column holds one element; Archmage aggregates them — whether adjacent or not — into a single value using a defined column layout, blank region handling, and export encoding.

Type Availability

Category	Regular Table	Property Sheet	Tree-Structured Data
Multi-Column Types	✓

Type List

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

Common Rules

• Columns forming a single logical field share a common name.
• Each column holds one element; nested types must be Basic Types or Compact Types.
• Two default export value shorthands are supported: / exports null; {} exports an empty container or a zero-valued object.

Tip

It is recommended to use merged cells in the header region to group columns that belong to the same multi-column field. Alternatively, you may use lookback operators (<1, <2, <3) to reuse values from preceding columns.

See Also

• The Double Hash

[]T

A multi-column array spreads a variable-length array across multiple columns sharing a common field name.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Unlock levels			Bonus items
Name	levels			bonuses
Type	[]int			[]string={}
1	10	30		sword	shield
2	10		30	potion

Exported

{
  "1": {
    "levels": [10, 30],
    "bonuses": ["sword", "shield"]
  },
  "2": {
    "levels": [10, 30],
    "bonuses": ["potion"]
  }
}

Type Definition Syntax

[]T

T can be any Basic or Compact Type.

[]int
[]string
[]>>vector|2|float32

Column Layout

Each column contributes one element. []T accepts any number of columns.

Note

For each config entry, blank cells in a column span are skipped silently and do not affect the result. Use [N]T instead if this behavior is undesirable.

Default Export Value

[]int            →  no default export value
[]int=/          →  null
[]int={}         →  empty array []

See Default Export Value for more information.

Related Types

• [N]T
• >>[]T

[N]T

A multi-column array of fixed length — exactly N elements.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Drop weights			Stat bonuses
Name	weights			bonuses
Type	[3]float			[2]int={}
1	0.3	0.59	0.11	5	3
2	1.0	0.0	0.0

Type Definition Syntax

[N]T

T can be any Basic or Compact Type.

[3]float
[2]int
[4]duration

Column Layout

Each column contributes one element. Exactly N columns are required.

Default Export Value

[3]int           →  no default export value
[3]int=/         →  null
[3]int={}        →  [0, 0, 0]

Note

When a default export value is set, blank cells in a column span are filled with T’s zero value rather than causing an error.

See Default Export Value for more information.

Related Types

• []T
• >>[N]T

map[K]V

A multi-column map spreads key-value pairs across multiple columns sharing a common field name.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Quest rewards				Quest penalties
Name	rewards				penalties
Type	map[string]int				map[enum@attribute]int32={}
1	gold	100	exp	50	hp	30
2	gem	5

Type Definition Syntax

map[K]V

K must be string, an integer type, or an enum type; V can be any Basic or Compact Type.

map[string]int
map[int]float
map[enum@attribute]int8
map[string]>>vector|2|int

K cannot have any options.

Column Layout

Columns alternate between keys and values by position: the 1st column is a key, the 2nd its value, the 3rd a key, and so on. Therefore, a map must occupy an even number of columns.

Note

For each config entry, paired blank cells in a column span are skipped silently and do not affect the result.

Default Export Value

map[string]int            →  no default export value
map[string]int=/          →  null
map[string]int={}         →  empty map {}

Note

When a default export value is set, missing values within key-value pairs are filled with V’s zero value rather than causing an error.

See Default Export Value for more information.

Option keyOnly

Allowed only for maps whose value type is bool.

keyOnly         →  equivalent to keyOnly=true
keyOnly=true

When enabled:

• Each column holds a key, so the map no longer needs an even number of columns.
• Omitted map values are coerced to true.

This semantically “turns” a map into a set — yet still it exports as a map.

keyOnly

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Unlocked skills
Name	skill-set
Type	map[string]bool
Options	keyOnly
1	fireball	heal	dash
2	fireball

Exported

{
  "1": {
    "skill-set": {
      "fireball": true,
      "heal": true,
      "dash": true
    }
  },
  "2": {
    "skill-set": {
      "fireball": true
    }
  }
}

Related Types

• >>map[K]V

minmax

A multi-column minmax occupies two columns sharing a common field name to represent a min–max pair.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	HP range		Damage range
Name	hpRange		dmgRange
Type	minmax|int		minmax|int={}
1	10	20	5	15
2	5	5

Type Definition Syntax

minmax|T

T must be an integer type, a floating-point type, or duration.

minmax|int
minmax|float32
minmax|int64
minmax|duration

Column Layout

Exactly two columns are required: the first holds min, the second holds max.

Note

• When T is an integer type, max - min must not exceed 1,000,000,000.
• When T is duration, max - min must not exceed 1,000,000,000 milliseconds.

Default Export Value

minmax|int            →  no default export value
minmax|int=/          →  {min: 0, max: 0}
minmax|int={}         →  {min: 0, max: 0}

See Default Export Value for more information.

Export Format

On data export, a minmax becomes an object with min and max fields.

Related Types

• >>minmax

wtpool

A multi-column weighted pool spreads a sequence of item-weight pairs across multiple columns sharing a common field name.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Drop pool				Reward pool
Name	dropPool				rewardPool
Type	wtpool|string				wtpool|>>object|Id int|Qty int={}
1	gold	50	gem	10	Id:101|Qty:2	5
2	nothing	100

Type Definition Syntax

wtpool|T

T is the item type. It can be any Basic Type except for l10n, or a >>object.

Weights are int32 values; the data type is fixed and never needs to be specified.

wtpool|string
wtpool|int
wtpool|>>object|Id int|Qty int

Column Layout

Columns alternate between items and weights by position: the 1st column is an item, the 2nd its weight, the 3rd an item, and so on. Therefore, a weighted pool must occupy an even number of columns.

Note

Each weight must be ≥ 0. The total must be > 0 and ≤ 1,000,000,000.

Note

For each config entry, paired blank cells in a column span are skipped silently and do not affect the result.

Default Export Value

wtpool|int            →  no default export value
wtpool|int=/          →  null
wtpool|int={}         →  empty pool {items: [], weights: []}

See Default Export Value for more information.

Export Format

On data export, a weighted pool becomes an object with two parallel arrays, items and weights. Each weight corresponds to the item at the same index.

Related Types

• >>wtpool

vector

A multi-column vector spreads a geometric vector across multiple columns sharing a common field name.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Spawn position			Facing direction
Name	pos			dir
Type	vector|3|int			vector|2|float32={}
1	10	20	30	1.0	0.0
2	0	5	0

Type Definition Syntax

vector|Dim|T

Dim must be 2, 3, or 4; T must be an integer or a floating-point type.

vector|2|int
vector|3|float32
vector|4|int32

Column Layout

Columns map to the x, y, z, w coordinates in order. Exactly Dim columns are required.

Default Export Value

vector|3|float            →  no default export value
vector|3|float=/          →  {x: 0, y: 0, z: 0}
vector|3|float={}         →  {x: 0, y: 0, z: 0}

Note

When a default export value is set, missing fields are populated with T’s zero value rather than causing an error.

See Default Export Value for more information.

Export Format

On data export, a vector becomes an object with x and y fields, extended with z and w according to Dim.

Related Types

• >>vector

tuple

A multi-column tuple spreads a positional struct across multiple columns sharing a common field name.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Loot entry			Drop meta
Name	entry			meta
Type	tuple|int|string|bool			tuple|string|bool=/
1	100	warrior	true	rare	true
2	101	mage	false

Type Definition Syntax

tuple|T0|T1|T2|...

All field types (T0, T1, …) must be Basic Types.

tuple|int|string|bool
tuple|datetime|duration

Column Layout

Columns bind to fields strictly by position. The column count must equal the field count.

Default Export Value

tuple|int|string|bool            →  no default export value
tuple|int|string|bool=/          →  null
tuple|int|string|bool={}         →  {item0: 0, item1: "", item2: false}

Note

When a default export value is set, missing fields are populated with their respective zero values rather than causing an error.

See Default Export Value for more information.

Export Format

On data export, Archmage represents tuples as objects. Keys follow the pattern item0, item1, item2, and so on.

Related Types

• >>tuple

bitflags

A multi-column bitflags expands a bitflag enum across multiple columns sharing a common field name.

Table

Copy Table to ClipboardCopy Table (Spread Merged Cells)

Desc	Quest flags			Difficulty flags
Name	flags			diffFlags
Type	bitflags@QuestSched			bitflags@DiffType=/
Options	e=Daily	e=Weekly	e=Event	e=Hard	e=Expert
1	1		1	1
2	True				True

Type Definition Syntax

bitflags@<enumType>

<enumType> must be a bitflag enum.

bitflags@QuestSched

Column Layout

Each column represents a single bitflag and must have an e option with a unique value binding it to an enum item. Input values follow the bool semantics (1/0, True/False, T/F). A True input sets the associated enum item’s bit to 1.

Option e

This is a bitflags-only option. Its value must be the name or shorthand of an enum item belonging to <enumType>.

Default Export Value

bitflags@QuestSched         →  0
bitflags@QuestSched=/       →  0

If the default export value is omitted, Archmage treats it as /, meaning explicit specification is unnecessary.

See Default Export Value for more information.

Export Format

On data export, Archmage combines all flag bits into a single integer.

Providing Enum Sources

Enum types must be defined in external definition files before they can be used. Pass these files via the --enum-files CLI flag:

archmage export --enum-files "idl/*.enum.yaml" ...
archmage struct --enum-files "idl/*.enum.yaml" ...

For how to define enum types, see Enum Definition.

Related Types

• enum