Skip to content
ArchmageDocs

Enum Definition

Archmage provides typed enum code generation for 12 languages — Go, C#, Java, Python, TypeScript, JavaScript, Lua, GDScript, C++, Rust, PHP, and Protocol Buffers.

A definition file defines one or more enum types, each comprising a set of enum items backed by integer values. It also includes metadata — namespaces, filters, options, shorthands, and documentation — that controls code generation and makes the enums easier to reference.

See archmage enum for code generation details.

Supported File Formats

Section titled “Supported File Formats”

Archmage accepts enum definition files in six formats. File names must follow the pattern <name>.enum.<ext> (e.g., demo1.enum.yaml):

Format Extension
YAML .enum.yml or .enum.yaml
JSON .enum.json
JSON5 .enum.json5
JavaScript .enum.js
TOML .enum.toml
XML .enum.xml

File Structure

Section titled “File Structure”

An enum definition file is a flat object. Its top-level keys define either enum types or metadata blocks identified by __double-underscore__ names, such as __options__.

# File-level documentation — appears in the generated code header.
__desc__: 'Definitions for the combat system.'


# File-level settings.
__options__:
    xflags: 'c,s'
    underlyingType: int32


# Language-specific namespace/package/module paths.
__namespace__:
    go: 'github.com/example/game/enums'
    cs: 'Example.Game.Enums'


# External enum references (optional).
__external__: {}


# Each remaining key defines an enum type.
weapon:
    unarmed: 0
    sword:   1
    axe:     2


unitType:
    __desc__: 'Playable unit categories.'
    __options__:
        underlyingType: int8
    undefined: 0
    human:     1
    orc:       2
    elf:
        value: 3
        desc: 'High elves only.'
    count:
        value: iota
        sentinel: true

File-Level Blocks

Section titled “File-Level Blocks”

__desc__

Section titled “__desc__”

Stores a documentation string. Archmage writes it as a comment block at the top of the generated file. __desc__ accepts a single string or an array of strings. No line breaks allowed.

# Single string:
__desc__: 'Definitions for the combat system.'


# Multiple lines:
__desc__:
    - 'Definitions for the combat system.'
    - 'See design doc: docs/combat.md'

__options__

Section titled “__options__”

Defines default options for all enum types in the file, allowing per-type overrides.

Field Type Default Description
underlyingType string int32 Default underlying type for all enum types. Valid values: int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64.
xflags string — Comma-separated scenario flags.

xflags marks enum types and items for specific scenarios. Types and items are excluded only when their xflags explicitly fail to satisfy the --xflags CLI flag. A ++ prefix overrides this: they are included only when their xflags explicitly satisfy --xflags.

--xflags not set --xflags match
(e.g. c)		 --xflags mismatch
(e.g. z)
xflags not set included included included
xflags: c,s included included excluded
xflags: ++c,s excluded included excluded 
__options__:
    # Default: included in both client and server builds.
    xflags: 'c,s'


weapon:
    # No explicit xflags — inherits the file-level 'c,s'.
    unarmed: 0
    sword:   1


debugMode:
    # Server only — excluded when --xflags c.
    __options__:
        xflags: 's'
    off:     0
    verbose: 1

__namespace__

Section titled “__namespace__”

Associates language identifiers — such as go, cs, java, cpp, php, or proto — with their respective namespace, package, or module paths.

__namespace__:
    go:    'github.com/example/game/enums'
    cs:    'Example.Game.Enums'
    java:  'com.example.game.enums'
    cpp:   'example.game.enums'
    php:   'Example\\Game\\Enums'
    proto: 'example.game.enums'

Some code templates require a specific key. For example, the C# template requires cs. Archmage reports an error at generation time if a required key is missing. That said, any identifier can be used as long as the corresponding template supports it.

Enum Types

Section titled “Enum Types”

Any top-level key that is not a metadata key defines an enum type. The key serves as the type name and must be a valid identifier.

weapon:
    unarmed: 0
    sword:   1
    axe:     2

Type-Level __desc__

Section titled “Type-Level __desc__”

Documents the enum type. Archmage writes it as a comment above the type definition in the generated code. __desc__ accepts a single string or an array of strings. No line breaks allowed.

# Single string:
weapon:
    __desc__: 'Weapon types available to units.'
    # ...


# Multiple lines:
armor:
    __desc__:
        - 'Armor class worn by the unit.'
        - 'Combine flags freely.'
    # ...

Type-Level __options__

Section titled “Type-Level __options__”

Overrides file-level defaults and adds type-specific settings.

Field Type Default Description
underlyingType string file-level Overrides the file-level underlyingType for this type. Valid values: int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64.
bitflags bool false Marks this type as a bitflag enum to allow bitwise combinations.
xflags string file-level Comma-separated scenario flags applied to this type and its items. See xflags for details.
prefix string type name The prefix for generated constant names. Only applies to specific languages, such as Go and C++. 
armor:
    __options__:
        underlyingType: uint16
        prefix: ArmorKind
    none:    0
    cloth:   1
    leather: 2
    mail:    3
    plate:   4

With prefix: 'ArmorKind', Archmage may generate constants like ArmorKindNone, ArmorKindCloth, and so on.

Enum Items

Section titled “Enum Items”

Each key inside an enum type (other than __desc__ and __options__) defines an enum item. An item is written in either the simple form or the object form.

Simple Form

Section titled “Simple Form”

Assign a value directly to the item name:

weapon:
    unarmed: 0        # zero
    sword:   1        # decimal
    axe:     0x02     # hexadecimal
    spear:   iota     # auto-assign from previous; value 3
    blade:   '255'    # string-encoded integer
    swiss:   'sword | axe | 32'  # bitwise combination; value: 35

Object Form

Section titled “Object Form”

Use an object when you need to set fields beyond the simple value.

armor:
    cloth:
        value:       0x01
        blankBefore: true
    plate:
        value:       0x08
        desc:        'Heavy plate armor, full body coverage.'
        shorthand:   pl
        string:      PLATE
        l10n:        'Heavy Plate Armor'
        sentinel:    false
        xflags:      s
Field Description
value Required. The integer value. Accepts the same formats as the simple form. Duplicate values are allowed.
desc Documentation comment for this item.
shorthand Shorthand for easy data input in external tools. Has no effect on code generation.
string Overrides the item’s string representation at runtime. When omitted, the item name is used.
l10n Localizable text for this item. Collected by archmage export for localization pipelines.
sentinel true marks this item as a boundary or count marker. These items are purely informational and are not considered valid enum values.
blankBefore true inserts a blank line before this item in the generated constant block, for visual grouping only.
xflags Comma-separated scenario flags applied to this item. See xflags for details.

Auto-Numbering (iota)

Section titled “Auto-Numbering (iota)”

Use 'iota' to auto-assign a number based on the previous enum item.

Its behavior varies by enum type:

  • Regular enum — increments by 1 from the last value, starting at 0.
magicType:
    none:  iota   # 0
    fire:  iota   # 1
    water: 10     # explicit reset
    earth: iota   # 11
    wind:  20     # explicit reset
    light: iota   # 21
  • Bitflag enum — shifts left after each assignment (0 → 1 → 2 → 4 → 8 …).
permission:
    __options__:
        bitflags: true
    none:    iota    # 0x0
    read:    iota    # 0x1
    write:   iota    # 0x2
    execute: iota    # 0x4

External Enums

Section titled “External Enums”

__external__ declares, on a per-language basis, which enum types in this file are defined externally in that language. It serves two purposes:

  • Informs Archmage which types to skip during code generation.
  • Enables other code generators, such as archmage struct, to emit correct imports and type names for externally defined enums.

An enum type can be external in one language and native in another. If a type is external in multiple languages, each maps to its target type independently.

__external__:
    # renderMode is external in Go — Archmage skips the Go type definition.
    # renderMode is not listed under cs — C# gets its own generated definition.
    # weather is external in both Go and C#, mapping to different types.
    go:
        - decl: 'import "github.com/example/game/gfx"'
          mapping:
              renderMode: gfx.RenderMode
        - decl: 'import "github.com/example/game/world"'
          mapping:
              weather: world.Weather
    cs:
        - decl: 'using Example.Game.World;'
          mapping:
              weather: World.Weather

Each language entry is an array. Each array element has the following fields:

Field Description
decl A raw string emitted at the top of the generated file — typically an import, include, or using statement. Archmage does not parse it.
mapping Maps type names in this file to their target-language type names. Values are raw strings and are used as-is.

All mapped types must exist in this file.

Constraints & Validation

Section titled “Constraints & Validation”
  • Zero value required. Every enum type must have a non-sentinel item with value 0. This zero-value item must not have xflags.
  • Unique names required. All names must be unique after normalization (e.g., foo_bar and FooBar conflict and are rejected). This rule operates at two levels: enum type names are unique across all files; item names and shorthands are unique within their type.
  • Valid identifiers. Type names and item names must start with a letter and contain only letters, digits, and underscores.