Links

Optional

A link is a field that holds another record's id. It connects items in your collections. If a link names a record that does not exist, validation reports it and names the record and the field that hold the link. The examples below continue the technology tree from the Collections chapter.

collections/technologies/_collection.json, one link field

{
  "record": {
    "requires": {
      "type": "link",
      "to": "technologies",
      "many": true,
      "loops": false
    }
  }
}

collections/technologies/kiln-building.json, one technology record

{
  "title": "Kiln Building",
  "era_order": 2,
  "requires": ["fire-making"]
}

to names the target collection, here the same one. One link field points into one collection. When records need links to two kinds of target, such as units and buildings, use one field for each kind. many: true makes the field a list of ids. fire-making.json exists in technologies/, so the link points at a real record. loops: false says a technology can never require itself, directly or through a chain. Validation reports the loop if one appears. The field name requires is yours, and your chapters explain what requiring means in the game.

More link options#

Add required: true when a record must carry at least one link. loops only works for links inside one collection. Leave it out when loops are allowed or when the link points at another collection.

Use mirrored_by when both records must name the relationship. Here every technology-to-recipe link must have an unlocked_by link back from the recipe:

collections/technologies/_collection.json, the forward link

{
  "record": {
    "unlocks": {
      "type": "link",
      "to": "recipes",
      "many": true,
      "mirrored_by": "unlocked_by"
    }
  }
}

The recipes schema declares unlocked_by as a link back to technologies. A link present in only one direction is reported with both record ids.

A list field holds several small entries, such as the ingredients of a recipe. Its of object describes the fields in each entry, and those fields can be links:

collections/recipes/_collection.json, one field inside record

{
  "ingredients": {
    "type": "list",
    "of": {
      "item_id": { "type": "link", "to": "items", "required": true },
      "qty": { "type": "integer", "required": true }
    }
  }
}

The schema checks the ids that the links name, and the fields of each entry. It says nothing about what a requirement or an ingredient does in play. The builder reads your chapters for that.

Full rules: OpenGDD specification, §1b.

← Collections · All chapters · Runtime values →