Naming Rules

Archmage enforces a small set of naming rules across files, worksheets, types, fields, flags, and other identifiers.

Typical Naming Rules

A typical name must:

• Start with a letter (a-z, A-Z) or an underscore (_)
• Contain only letters, digits, underscores (_), and hyphens (-)

hp              valid
_hp             valid
hp-max          valid
hp_max          valid
2hp             invalid — starts with a digit
hp!             invalid — contains a forbidden character

Reserved Field Name: ID

In regular tables, the name ID is reserved exclusively for the first column (Config ID) and may not be used as a standalone field name or as the first crumb of a dotted field name. However, using it as a subsequent crumb or in other contexts is unrestricted.

Regular Table Field Name	Allowed?	Reason
ID	No	Reserved for the config ID column
foo.ID	Yes	ID is not the first crumb

File Names

A file name must:

• Start with a letter (a-z, A-Z)
• Contain only letters, digits, underscores (_), hyphens (-), and dots (.)

Tip

Use singular form for file names. This improves readability in generated code: item.xlsx yields the type name ItemTable, while items.xlsx yields ItemsTable.

Worksheet Names

A worksheet name must NOT contain the following characters: |, +, or ,. It is highly recommended to follow the above file naming rules.

Tip

Use singular form for worksheet names. This improves readability in generated code: hero yields the type name HeroTable, while heros yields HerosTable.

Conflict Detection

Archmage detects potential naming conflicts by normalizing names and checking for collisions.

Input	Normalized
helloWorld	helloworld
hello-world	helloworld
HELLO_WORLD	helloworld

Note

When Archmage looks up identifiers (fields, references, anchors, enums, etc.), it matches against raw names or lowercase variants. Aggressive normalization is lossy and would cause false positives during lookup.

Case Sensitivity in Matching

Case sensitivity depends on the identifier type:

Identifier	Case-Sensitive?
Enum type/item/shorthand name (definition)	Yes
Enum type/item/shorthand name (in config data)	No
Config ID (string)	Yes
Field name	Yes
Virtual table name	Yes
Data type name (int, RGBA, etc.)	No
switch, case value	Yes
anchor value	No
ref target	No
backref, backref-n source	No
l10n reference	Yes
Option name (minLen, pubtype, etc.)	No
brace flags, xflags, tags, cflags value	No
synclen group name	Yes
pubtype name	Yes