Modes and clocks

Optional

When a game mixes real time with a pause or with turns, clocks.json says which clocks run in which situation. A time mode is one situation, such as diving or reading the map. A clock is one source of passing time, such as elapsed dive time. Writing this down keeps timing promises clear for the builder and for acceptance tests. The example is the same diving game as the Runtime values chapter.

clocks.json, two clocks: diving, and reading the map

{
  "dive_clock": {
    "unit": "seconds",
    "advances": ["runtime.dive_seconds"],
    "modes": {
      "dive": "running",
      "map": "paused"
    }
  },
  "oxygen_clock": {
    "unit": "seconds",
    "advances": ["runtime.oxygen_seconds"],
    "modes": {
      "dive": "running",
      "map": "paused"
    }
  }
}

Here the modes are dive and map, and the clocks are dive_clock and oxygen_clock. While the player reads the map, both clocks pause. You choose each clock's unit, such as seconds, turns or beats. The format has no fixed list.

A clock name uses letters, digits, _ and -, and does not start or end with a hyphen. A mode id is lowercase words joined by hyphens. Two clocks must not advance the same runtime value.

Every clock covers every mode#

The set of time modes is every mode that any clock names. If one clock names a mode and another leaves it out, validation reports the clock and the missing mode. In this excerpt, … marks fields left out.

clocks.json, one clock missing map

{ "dive_clock": { "unit": "seconds", "modes": { "dive": "running", "map": "paused" } },
  "oxygen_clock": { "unit": "seconds", "modes": { "dive": "running" } },
  … }

The validator (the checking tool) reports:

ERROR [CLOCKS_MODE_MISSING] clocks.json — clock "oxygen_clock" is missing mode "map" (SPEC §4b)

The name in brackets is the code for this exact rule. Quote it when asking for help. The filename, message and section say where to fix it.

Each mode uses one of four words:

running: the clock moves continuously.
paused: it keeps its value without moving.
steps: it moves only when a turn or another single step is taken.
none: the clock has no value at all in that mode, such as a turn counter outside a mission.

advances lists the runtime values this clock moves forward. The Runtime values chapter explains that runtime.oxygen_seconds is a changing value named by the design.

Rules that apply in one mode#

A mode tag in a heading limits that section to one mode. The tag can stand anywhere in the heading. Capital letters are usual, but small letters work too. The tag must name a mode your clocks.json declares. Square brackets have this meaning only in a heading. In a paragraph they are ordinary text.

02-mechanics.md, a section that applies only while the map is open

## Reading the map [MAP]

Leave a heading untagged when its section applies in every mode.

Tests about a mode#

A test can say that some values stay unchanged during a mode:

05-build-plan.md, inside a test block

{
  …
  "unchanged": {
    "modes": ["map"], "values": ["runtime.oxygen_seconds"]
  }
}

Every value it names must be declared in a chapter or in a clock's advances. An unknown value is reported.

Clocks do not program the game. A clock with unusual behavior, such as one that runs only while the player moves, is written as a rule in prose. clocks.json says only which clocks run, pause, step or do not exist in each mode.

Full rules: OpenGDD specification, §4b.