Modes and clocks

Optional

When real time meets a pause or a turn structure, 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 never 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 discrete 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 at the end of a heading limits that section to one mode. Capitals are the custom, but case does not matter. The tag must name a mode your clocks.json declares. Square brackets only mean something at the end of a heading. In a paragraph they are just 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 behaviour, 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.