Names and addresses

Required

When your prose needs a number, write it once, give it a name, and use the name everywhere else. A name like stamina.dash_cost is an identifier. The whole name with its dots is its address: what you type to point at it. An address written in backticks in prose is a citation.

in a mechanics chapter

A dash costs stamina.dash_cost, and cannot start when the bar holds less than that.

tuning.json, the numbers file

{
  "values": {
    "stamina.dash_cost": 25
  }
}

The sentence does not repeat the cost. It points at the value, so a balance change happens in one place and every sentence stays correct. The Tuning chapter explains how the numbers file is organized.

A citation must point at something the package declares. If it points at nothing, validation fails and names that citation. Runtime values are the one exception: writing runtime. and a name in a chapter declares the runtime value. The authoring tool shows where each name is defined, reports missing ones, and can create a missing value while you write.

A backticked file name such as tuning.json is a file mention, not a citation. A file whose name starts with a word OpenGDD reserves, such as clocks.json, is the exception: in backticks it reads as an address that names nothing, and validation fails. Write such a file name without backticks.

OpenGDD uses this pattern in many parts of the format. Collections, palettes, runtime values and contracts all define a name once and refer to it by address. Most ids are lowercase words joined by hyphens, such as kiln-building: package ids, collection and record ids, rule names, clock mode names, palette color names and contract names. Tuning keys use dots between parts and usually underscores inside a part. The OpenGDD specification gives the exact grammar for each kind of name.

A name has no meaning by itself. The sentence around the citation, and the tuning file, say what the number means and when it is read.

Full rules: OpenGDD specification, §1 and §4.