Basic Types

Basic types are atomic value types. Each represents a self-contained value with well-defined syntax, specific constraints, and export encoding.

Type Availability

Category	Regular Table	Property Sheet	Tree-Structured Data
Basic Types	✓	✓	✓

Type List

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

bool

The bool type holds a boolean value.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	isEnabled	isHero	isRunning
Type	bool	bool=/	bool=TRUE
1	1	TRUE	FALSE
2	0

YAML

# Equivalent configuration in YAML.

"1":
  isEnabled: true
  isEnabled__meta__:
    type: bool
  isHero: true
  isHero__meta__:
    type: bool=/
  isRunning: false
  isRunning__meta__:
    type: bool=TRUE

"2":
  isEnabled: false

Value Syntax

Value	Meaning	Case-sensitive?
1, T, TRUE	true	No
0, F, FALSE	false	No

Default Export Value

bool        →  no default export value
bool=/      →  zero value (false)
bool=TRUE   →  true
bool=1      →  true

See Default Export Value for more information.

datetime

The datetime type stores a date, a time, or both.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	createdAt	birthDate	dailyResetTime
Type	datetime	datetime=/	datetime="04:00:00"
1	2024-06-15T14:30:00+08:00	1995-06-15	04:30:00
2	2024-06-16T09:00:00Z

YAML

# Equivalent configuration in YAML.

"1":
  createdAt: "2024-06-15T14:30:00+08:00"
  createdAt__meta__:
    type: datetime
  birthDate: "1995-06-15"
  birthDate__meta__:
    type: datetime=/
  dailyResetTime: "04:30:00"
  dailyResetTime__meta__:
    type: 'datetime="04:00:00"'

"2":
  createdAt: "2024-06-16T09:00:00Z"

Value Syntax

• Date only: 2024-06-15
• Time only: 14:30:00
• Both: 2024-06-15 14:30:00
• RFC 3339 timestamp (with timezone): 2024-06-15T14:30:00+08:00

Default Export Value

datetime                           →  no default export value
datetime=/                         →  zero value (null)
datetime="2020-01-02 06:30:00"     →  parsed and converted datetime

See Default Export Value for more information.

Timezone

When parsing datetime values, explicit timezones are preserved; otherwise, --timezone is used, falling back to UTC if unspecified.

archmage export --timezone UTC+08:00 ...
archmage export --timezone UTC-07:30 ...

Export Format

Archmage exports datetime values as RFC 3339 strings:

2024-06-15T14:30:00Z
2024-06-15T22:30:00+08:00

duration

The duration type stores a time span. The syntax follows Go’s time.Duration format to eliminate ambiguity about units.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	cooldown	castTime	lifetime
Type	duration	duration=/	duration=1s
1	300ms	1.5s	2d12h
2	5s

YAML

# Equivalent configuration in YAML.

"1":
  cooldown: "300ms"
  cooldown__meta__:
    type: duration
  castTime: "1.5s"
  castTime__meta__:
    type: duration=/
  lifetime: "2d12h"
  lifetime__meta__:
    type: duration=1s

"2":
  cooldown: "5s"

Value Syntax

300ms          →  300 milliseconds
1h30m          →  1 hour 30 minutes
2d12h          →  2 days 12 hours
-1.5h          →  negative 1.5 hours

Unit Suffixes

Suffix	Unit
ns	nanoseconds
us or µs	microseconds
ms	milliseconds
s	seconds
m	minutes
h	hours
d	days

Default Export Value

duration      →  no default export value
duration=/    →  zero value (0)
duration=0    →  0
duration=1s   →  1 second

See Default Export Value for more information.

Export Format

Archmage exports duration values as a custom integer array rather than a string. String format is human-readable but requires per-language parser code; the integer array is more portable.

enum

The enum type restricts a value to a set of predefined items from a specific enum type.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	itemType	status	flags
Type	enum@ItemType	enum@++Status=/	enum@ItemFlags=None
1	Sword	Active	Destructible+Repairable
2	Shield

YAML

# Equivalent configuration in YAML.

"1":
  itemType: "Sword"
  itemType__meta__:
    type: enum@ItemType
  status: "Active"
  status__meta__:
    type: enum@++Status=/
  flags: "Destructible+Repairable"
  flags__meta__:
    type: enum@ItemFlags=None

"2":
  itemType: "Shield"

Type Definition Syntax

enum@<enumType>

Value Syntax

You can express enum values in the following formats:

• Enum item name or shorthand — case-insensitive
• A numeric value — any integer in a supported base (0x80, 255, etc.)
• Multiple flags (bitflag enums only) — separated by + or ,

Sword
sword          (same as Sword, case-insensitive)
2
0x02           (same as 2)
Frost+Fire     (Frost bitwise OR Fire)
Frost,Fire     (same, comma form)

Note

The separator for bitflag combinations is not |, because the pipe character is reserved for compact types and cannot be used here.

Default Export Value

enum@ItemType                              →  no default export value
enum@ItemType=/                            →  zero value (0)
enum@ItemType=0                            →  0
enum@ItemType=Destructible+Repairable      →  bitwise OR of both flags

See Default Export Value for more information.

Strict Mode

Prefix the enum type name with ++ to enable strict mode:

enum@++ItemType

In strict mode, only item names and shorthands are accepted. Numeric values are rejected, except for 0, which is permitted as the zero value.

Export Format

Enum values are exported as integers.

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

• bitflags

Floating-Point Numbers

Supported types include float, float32, and float64.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	weight	score	ratio
Type	float	float64=/	float32=1.0
1	65.4	12345.6789	0.875
2	70.5

YAML

# Equivalent configuration in YAML.

"1":
  weight: 65.4
  weight__meta__:
    type: float
  score: 12345.6789
  score__meta__:
    type: float64=/
  ratio: 0.875
  ratio__meta__:
    type: float32=1.0

"2":
  weight: 70.5

Value Syntax

Decimal and scientific notation are both supported.

3.14
6.67428e+3
-1.5e-2

Default Export Value

float          →  no default export value
float=/        →  zero value (0.0)
float32=0      →  explicit 0.0
float64=3.14   →  3.14

See Default Export Value for more information.

float Bit Size

The bit size of float is configurable. Use the --float-bit-size CLI flag to choose between 32 and 64 bits:

archmage export --float-bit-size 32 ...
archmage export --float-bit-size 64 ...   # default

Integers

Supported types include signed integers (int, int8, int16, int32, int64) and unsigned integers (uint, uint8, uint16, uint32, uint64).

Table

Copy Table to Clipboard

Desc	-	-	-
Name	maxHP	defence	attack
Type	int	int16=/	uint64=1
1	100	2	5
2	120

YAML

# Equivalent configuration in YAML.

"1":
  maxHP: 100
  maxHP__meta__:
    type: int
  defence: 2
  defence__meta__:
    type: int16=/
  attack: 5
  attack__meta__:
    type: uint64=1

"2":
  maxHP: 120

Value Syntax

You can express integers in decimal, hexadecimal, octal, or binary form:

• Decimal: 1024
• Hexadecimal: 0x10A8
• Octal: 0o755
• Binary: 0b1010

Underscores can be inserted freely to improve readability and do not affect the actual value.

1_024      →  1024
0xFF_FF    →  0xFFFF

Note

In tree-structured data (JSON, YAML, etc.), non-decimal or underscored numbers may need to be represented as strings (e.g., "0xFF_FF", "1_024") to avoid syntax errors. Archmage will still parse them as integers.

Default Export Value

int          →  no default export value
int=/        →  zero value (0)
int32=0      →  explicit 0
int64=-1     →  -1
uint8=255    →  255

See Default Export Value for more information.

Overflow Checks

Archmage validates that every value stays within the range of its declared type:

Type	Range
int8	-128 to 127
int16	-32,768 to 32,767
int32	-2,147,483,648 to 2,147,483,647
int64	-999,999,999,999,999 to 999,999,999,999,999
uint8	0 to 255
uint16	0 to 65,535
uint32	0 to 4,294,967,295
uint64	0 to 999,999,999,999,999

Note

Archmage caps 64-bit values at ±999,999,999,999,999 so that they survive a round trip through a spreadsheet cell.

int and uint Bit Size

The bit size of int and uint is configurable. Use the --int-bit-size CLI flag to choose between 32 and 64 bits:

archmage export --int-bit-size 32 ...
archmage struct --int-bit-size 64 ... # default

l10n

The l10n (short for localization) type represents a localizable string. It is intended for text that requires translation. Multi-line text is supported.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	name	story	dialogue
Type	l10n	l10n=/	l10n=abc
1	{{npc1_name}}	On a dark and stormy night...	Open the door!
2	{{npc2_name}}

YAML

# Equivalent configuration in YAML.

"1":
  name: "{{npc1_name}}"
  name__meta__:
    type: l10n
  story: "On a dark and stormy night..."
  story__meta__:
    type: l10n=/
  dialogue: "Open the door!"
  dialogue__meta__:
    type: l10n=abc

"2":
  name: "{{npc2_name}}"

Default Export Value

l10n        →  no default export value
l10n=/      →  empty string ""
l10n=""     →  empty string ""
l10n=abc    →  "abc"

See Default Export Value for more information.

Quoting and Escape Rules

Same as string.

Reference a Shared L10n String

A value using the {{...}} syntax is treated as a reference to a shared l10n string in l10n.xlsx. For example, {{npc1_name}} references the npc1_name entry.

About l10n.xlsx

l10n.xlsx is a special regular table for shared localizable strings.

• It uses string config IDs, identified by the $% marker in any cell of the first row.
• It has only one exportable data column, named localizable, of type l10n.
• If a referenced entry does not exist in l10n.xlsx, Archmage reports an error at export time.

See L10n Pipeline for details.

Data Export

All l10n strings across all config files are gathered into l10n.json, l10n.yaml, l10n.csv, or any combination of these. The resulting files form the basis for translating your project. Archmage performs a full refresh on each run, overwriting them.

Each original l10n value is exported as a localization key used for runtime translation lookup.

path

The path type represents a relative file path.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	prefab	icon	portrait
Type	path	path=/	path=imgs/dot.png
1	prefabs/hero.prefab	imgs/hero_icon.png	imgs/circle.png
2	prefabs/monster.prefab

YAML

# Equivalent configuration in YAML.

"1":
  prefab: "prefabs/hero.prefab"
  prefab__meta__:
    type: path
  icon: "imgs/hero_icon.png"
  icon__meta__:
    type: path=/
  portrait: "imgs/circle.png"
  portrait__meta__:
    type: path=imgs/dot.png

"2":
  prefab: "prefabs/monster.prefab"

Default Export Value

path                →  no default export value
path=/              →  empty string ""
path=""             →  empty string ""
path=icons/dot.png  →  "icons/dot.png"

See Default Export Value for more information.

Quoting and Escape Rules

Same as string.

Option root

This is a path-only option. It sets a root directory for validation. During data export, Archmage joins the root with the stored value and checks if the resulting path exists.

root=Assets/Textures
root=env@GAME_ASSET_ROOT

With root=env@VarName, the root comes from an environment variable:

• If the variable does not exist, Archmage raises an error.
• If the variable exists but is empty, the validation is skipped.

If root is not set, Archmage uses the ARCHMAGE_PATH_ROOT environment variable as a fallback.

Option stripDir

This is a path-only option. It removes N directory segments from the left side of the path on data export, after all checks have been made.

stripDir=N

Assume the path value is foo/bar/qux/fireball.png:

Option	Result
stripDir=0	foo/bar/qux/fireball.png
stripDir=1	bar/qux/fireball.png
stripDir=2	qux/fireball.png
stripDir=9	fireball.png (removes all segments, no error)

If N is greater than the actual number of segments, all segments are removed and only the filename remains.

Option replaceExt

This is a path-only option. On data export, it replaces the file name extension in each path.

replaceExt=""           →  simply remove the extension
replaceExt=.bin         →  replace the extension with .bin
replaceExt=.json.bin    →  replace the extension with .json.bin

For example, hero.png with replaceExt=.bin exports as hero.bin.

ref

The ref type represents a reference to a single config entry in the specified regular table.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	demo1	demo2	demo3
Type	ref@demo	ref@demo=/	ref@demo=seed
1	101	102	sprout
2	201

YAML

# Equivalent configuration in YAML.

"1":
  demo1: 101
  demo1__meta__:
    type: ref@demo
  demo2: 102
  demo2__meta__:
    type: ref@demo=/
  demo3: sprout
  demo3__meta__:
    type: ref@demo=seed

"2":
  demo1: 201

Type Definition Syntax

ref@<target>

The <target> after @ specifies the regular table being referenced:

Target type	Target syntax
Excel file (no index table in it)	File name
Worksheet (with index table in that file)	Worksheet name, or fileName::sheetName
Tree-structured data file	File name
Virtual table	Virtual table name

These are the common notations; see Referent Syntax for the complete syntax.

Note

<target> is resolved by name, not by file system path.

Caution

Only regular tables and tree-backed regular tables can be referenced.

Value Syntax

The actual value must have the same data type as the target table’s config ID.

Config ID data type	Fill with	“No reference” value
Integer	An integer	0
String	A string	Empty string ""

When the target table uses integer IDs, you can reference a config entry by its anchor if the table has an anchor field. Replacing opaque integers with meaningful names makes configurations far easier to read. See Cross-Table References for details.

Archmage validates all non-zero references at export time. If a referenced config entry does not exist, the export fails.

Default Export Value

ref@demo         →  no default export value
ref@demo=/       →  zero value (0 or "")
ref@demo=0       →  0
ref@demo=seed    →  123 (assume anchor "seed" maps to 123)

See Default Export Value for more information.

Preferred Reference

Prefix the target with ++ to mark a field as a preferred source of back-references:

ref@++demo

A backref binds only one referring config entry, so a table that reaches the same target through several ref values easily overshoots that quota. The mark settles which fields are eligible before the count is taken:

Explicitly Marked Fields	Eligible Fields
None	All fields
Some	Marked fields only
All	All fields

Filtering is all the mark does, and the same rule applies to backref-n.

Code Generation

For a field of type ref@<target>, Archmage generates a corresponding <field> of type XRef:

• <field>.CfgID holds the raw config ID (integer or string).
• <field>.Ref holds a typed pointer to the referenced config entry. It is populated automatically during config loading and remains null when CfgID is zero (0 or "").

Option crude

This option applies only to reference types. When crude=true, Archmage generates the field as a plain integer or string instead of the XRef type.

This is useful when you do not need runtime reference binding.

Related Types

• backref
• backref-n

rgba

The rgba type represents a hexadecimal color value.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	color	outline_color	theme_color
Type	rgba	rgba=/	rgba=#FF0000
1	#00FF00FF	#FFFFFFAA	#00FF00
2	#FF0000FF

YAML

# Equivalent configuration in YAML.

"1":
  color: "#00FF00FF"
  color__meta__:
    type: rgba
  outline_color: "#FFFFFFAA"
  outline_color__meta__:
    type: rgba=/
  theme_color: "#00FF00"
  theme_color__meta__:
    type: "rgba=#FF0000"

"2":
  color: "#FF0000FF"

Value Syntax

Values start with #. Two formats are supported:

• #RRGGBB — 6-digit RGB
• #RRGGBBAA — 8-digit RGBA

Both are case-insensitive on input. Archmage normalizes letters to uppercase on data export.

Default Export Value

rgba                →  no default export value
rgba=/              →  empty string ""
rgba=#FF0000        →  #FF0000

See Default Export Value for more information.

Blank Value Handling

A value starting with ## (two hash signs) is treated as blank. See The Hash # for details.

Constraints

rgba cannot be used in the following contexts:

• As the element type of a >>[]T, >>[N]T, or >>wtpool
• As the data type of the first field in a >>tuple

Note

These constraints come from parsing ambiguity: rgba values starting with # conflict with the general comment syntax.

string

The string type holds a text value. Multi-line text is supported.

Table

Copy Table to Clipboard

Desc	-	-	-
Name	name	title	tag
Type	string	string=/	string=abc
1	Hero	Warrior	foo
2	Villager

YAML

# Equivalent configuration in YAML.

"1":
  name: "Hero"
  name__meta__:
    type: string
  title: "Warrior"
  title__meta__:
    type: string=/
  tag: "foo"
  tag__meta__:
    type: string=abc

"2":
  name: "Villager"

Default Export Value

string         →  no default export value
string=/       →  empty string ""
string=""      →  empty string ""
string=abc     →  "abc"

Note

The quoted string "/" is the string literal /, not the zero-value shorthand.

See Default Export Value for more information.

Quoting and Escape Rules

String literals are parsed according to the following rules:

Format	Example	Escape Support	Allows Backticks
Unquoted (plain text)	a\b"c	✕	✓
Double-quoted ("...")	"a\\b\"c"	✓	✓
Backtick-quoted (`...`)	`a\b"c`	✕	✕

The three examples above represent the exact same string value.

When escape processing is enabled, Archmage uses standard JSON escape sequences (\\, \", \n, \t, etc.).

Caution

When parsing tree-structured data, string escaping is disabled. The tree parser’s syntax rules always take priority.

Whitespace Trimming

Unquoted values in spreadsheets are trimmed on data export. To preserve leading or trailing spaces, wrap the value in quotes:

   hello     →  "hello"     (spaces trimmed)
"  hello  "  →  "  hello  " (spaces preserved)