Meta Nodes

When processing tree-structured data files, Archmage infers the data type for each node automatically. A meta node can override that inference and supply additional settings the data itself cannot express.

Tip

Add a meta node only where a data node needs a different type, a description, validation options, or other settings. Nodes without such needs are best left alone.

Where Meta Information Is Set

Location	Key	Target
In a {} node	__meta__	The {} node
Beside a named field foo	foo__meta__	The field foo
In a meta node	elem	The child nodes of the container described by the meta node

A node takes its meta information from exactly one of these (the single-source rule). Setting it twice, in any combination of the three forms, is an error.

When a container holds multiple objects of the same shape, Archmage merges them into a single definition. The single-source rule then applies per node: the meta information for the object itself, or for any one of its fields, can be set in any of the three forms, but at most once.

Every meta node must bind to a data node that actually exists and contains valid data. Meta nodes annotate data; they cannot impose structure the data does not support.

Caution

When a data file has no demo file, it holds its own meta nodes. When it has one, the meta nodes reside exclusively in the demo file, and the data file must contain none.

Meta Fields

All fields are optional.

Field	Description
type	The data type of the target node
desc	A field description
options	Field options, written as a nested object
elem	Meta information for the child nodes. Only valid when type is [], [N], or map

Setting options or elem requires type to be set explicitly.

Examples

icon__meta__

YAML

name: Flame Sword
attack: 120
icon: weapons/flame_sword.png
icon__meta__:
  desc: Inventory icon
  type: path
  options:
    root: Assets/Textures

JSON

{
  "name": "Flame Sword",
  "attack": 120,
  "icon": "weapons/flame_sword.png",
  "icon__meta__": {
    "desc": "Inventory icon",
    "type": "path",
    "options": {
      "root": "Assets/Textures"
    }
  }
}

Without the meta node, Archmage would not know icon was a path and would not check that the file exists.

__meta__ and elem

YAML

dropRates:
  __meta__:
    type: map[int]
    elem:
      type: int16
  "101": 30
  "102": 70

JSON

{
  "dropRates": {
    "__meta__": {
      "type": "map[int]",
      "elem": {
        "type": "int16"
      }
    },
    "101": 30,
    "102": 70
  }
}

The __meta__ node describes dropRates itself, and the elem field describes the two values, 30 and 70.