Names and addresses

Required

Write each number 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 organised.

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

OpenGDD uses this pattern everywhere. 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 colour names and contract names. Tuning keys use dots between parts and usually underscores inside a part. The specification gives the exact grammar for each kind of name.

A name carries no meaning on its own. What the number means, and when it is read, lives in the sentence around the citation and in the tuning file.

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

← Who decides · All chapters · Tuning →