Collections

Optional

Games are full of lists: technologies, recipes, cards, levels. A collection keeps one kind of content in one folder, with one JSON file per item. The example is the technology tree of a survival crafting game.

collections/, at the package root

collections/
  technologies/
    fire-making.json
    kiln-building.json
    stone-tools.json
  recipes/
    recipe-charcoal.json
  items/
    charcoal.json

Each folder under collections/ is one collection. The folder name is its id, and each other file is one record, named by its filename. Making the folder is enough: there is no index file to update.

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

{
  "title": "Kiln Building",
  "era_order": 2,
  "note": "Fire held in a shape, instead of loose on the ground."
}

The fields are yours. title is what the game shows; kiln-building is the id the package refers to. In prose:

collections.technologies means the whole collection;
collections.technologies.kiln-building means this record.

If you rename a record, the validator (the checking tool) points at every reference that still uses the old id.

Records may use whatever fields they need. When every record should use the same fields, add the optional schema file to the folder.

collections/technologies/_collection.json

{
  "record": {
    "title": {
      "type": "string",
      "required": true,
      "description": "the name shown in the technology tree"
    },
    "era_order": {
      "type": "integer",
      "required": true,
      "unique": true,
      "description": "the technology's place in the era, counting from 1"
    }
  }
}

Each description says how to use the field. With a schema, the validator reports missing fields, wrong value types, unexpected fields, and repeated values in a field marked unique.

A field can point at another record. The Links chapter shows the link field type and its checks.

Leave _collection.json out when the records do not need the same fields. Both forms are complete collections.

Full rules: OpenGDD specification, §1b.