{
  "contract": "timed-window",
  "version": 2,
  "origin": "https://opengdd.org/contracts/timed-window-2",
  "summary": "This contract covers named timed windows, such as invulnerability, cooldowns, status effects, and restart locks. It says what happens when a window's opening occurs again while the window is open (a repeat opening), when play is suspended, when the window ends early, and when it expires. This contract does not cover what opens each window or how long each window lasts.",
  "mechanism": [
    "Each row declares one timed window. The row cites the game's own Fixed material for what opens it, its duration, and the clock that advances it; the contract owns none of those game-specific rules or numbers. An opening is an event of the entity the window is given to. Each entity that the game's rules give the window has its own copies of the window, and that entity's own events open, advance, and close them, unless the adoption's Fixed prose explicitly names the window as shared. Every sentence and every generated check that speaks of open copies means the copies of one entity, unless the window is named as shared. The validator cannot check this; a reviewer does.",
    "When the cited opening occurs, the duration is read once and the window opens for that duration; later changes to the cited number or calculation do not move an open copy's endpoint. A fixed duration cites its tuning number; a duration computed from game state cites the Fixed prose that defines the calculation. A window includes its named last moment: it is still open exactly when the cited clock has advanced by that duration, and closed at any point after that, unless its row says it can end early.",
    "A repeat opening occurs when a row's opening occurs again while that window is open. The row's on-retrigger answer applies at a repeat opening. ignore leaves the open copy unchanged. new-duration replaces its remaining time with the newly granted duration. keep-longer keeps whichever is longer: the remaining time or the newly granted duration. extend-to-cap adds the newly granted duration to the time remaining, but never leaves more than the row's cited cap. The same open copy continues under ignore, new-duration, keep-longer, and extend-to-cap, and its history shows one opening; only stack creates a new copy. stack opens another independent copy and leaves every open copy unchanged. A game whose extension has a largest permitted duration names that duration as its cap; a game that permits no largest duration states the exception in its own prose and adopts this contract as promised rather than checked. A game whose stacking has a largest number of open copies states that limit in its own prose and adopts this row as promised rather than checked; this contract does not count copies.",
    "Under expiry-only, nothing closes any open copy before its duration ends; when a repeat opening changes an open copy's remaining time, that change is not an early closure. Under declared-ending, the event or condition cited by the row closes every open copy on the entity the ending happens to, unless the cited prose names more copies; this covers copies being used, canceled, dispelled, or otherwise ended by the game.",
    "stops means the row's clock does not advance while ordinary play is suspended. keeps-running means it does. The cited clock definition decides what ordinary play being suspended means; this contract does not define suspension or catch-up behavior.",
    "The answers belong to each window row, not to the game as a whole. If one apparent window follows different repeat-opening rules for different opening causes, this version does not model those causes separately; the game must name them as separate windows or state the exception in its own prose."
  ],
  "questions": {},
  "declares": {
    "rows": {
      "windows": {
        "description": "List every named window. An empty list states that the game has no timed window. A person who reviews the design checks that statement. A cap uses the window's unit and cannot be shorter than its normal duration. The duration unit must match the clock. A real-time window cannot use turns to avoid the suspension choice. No automatic check covers these rules. A person who reviews the design checks them.",
        "record": {
          "id": {
            "type": "string",
            "required": true,
            "pattern": "kebab-case",
            "unique": true,
            "description": "A short name for the window in your game's words, such as poison."
          },
          "opens-at": {
            "type": "citation",
            "required": true,
            "description": "Where your game's rules say what opens the window. A poison window might open when a poisoned attack hits."
          },
          "duration": {
            "type": "citation",
            "required": true,
            "description": "Where your game's rules say how long the window lasts. Cite a number for a duration that does not change, or the rule that calculates the duration from game state. The value is read when the window opens. For example, poison may read its turn count when the attack hits."
          },
          "duration-unit": {
            "type": "string",
            "required": true,
            "options": [
              "seconds",
              "frames",
              "ticks",
              "turns"
            ],
            "description": "The unit used by the duration and its clock. Seconds measure real time. Frames count updates. Ticks count clock steps. Turns count game turns. A poison effect might use turns."
          },
          "clock": {
            "type": "citation",
            "required": true,
            "description": "Where your game's rules name the clock that closes this window. A poison effect may use the turn clock."
          },
          "while-suspended": {
            "type": "string",
            "when": {
              "row": {
                "duration-unit": [
                  "seconds",
                  "frames",
                  "ticks"
                ]
              }
            },
            "options": [
              "stops",
              "keeps-running"
            ],
            "description": "Does the window's clock stop while ordinary play is suspended? This choice applies only to a window that counts seconds, frames, or ticks. If the clock stops, an invulnerability window keeps all its remaining time while play is suspended. If the clock keeps running, the window can expire before play resumes."
          },
          "on-retrigger": {
            "type": "string",
            "required": true,
            "options": [
              "ignore",
              "new-duration",
              "keep-longer",
              "extend-to-cap",
              "stack"
            ],
            "description": "What a new opening does while this window is already open (a repeat opening). Ignore leaves the poison window unchanged. New duration replaces its remaining time with the duration from the new poison hit. Keep longer uses whichever time is longer. Extend to cap adds time without passing its cap. Stack opens another independent poison copy. Only stacking creates a new copy. Every other choice continues the current copy and keeps one opening in its history."
          },
          "retrigger-cap": {
            "type": "citation",
            "when": {
              "row": {
                "on-retrigger": [
                  "extend-to-cap"
                ]
              }
            },
            "description": "Where your game's rules state the largest amount of time that can remain after an extension. A poison effect may cap all extensions at its maximum duration. Add this only when repeat openings extend up to a cap. Use the same unit as the duration."
          },
          "ends-early": {
            "type": "string",
            "required": true,
            "options": [
              "expiry-only",
              "declared-ending"
            ],
            "description": "Whether the window can close before its duration ends. Expiry only keeps a poison effect open until time runs out. A declared ending lets a cure close every open poison copy on the entity it cures, unless the cited rules name more copies."
          },
          "early-end": {
            "type": "citation",
            "when": {
              "row": {
                "ends-early": [
                  "declared-ending"
                ]
              }
            },
            "description": "Where your game's rules name every event or condition that ends this window early. This includes using or canceling it. For poison, this may be an antidote or cleansing the target. Add this only when the window can end early."
          }
        }
      }
    }
  },
  "pack": "sha256:17a5a688b1156f0eb450003d53e006d9d200942120d829376abff01587728044",
  "answers": {},
  "values": {},
  "rows": {
    "windows": [
      {
        "id": "poison",
        "opens-at": "02-mechanics.md#poison",
        "duration": "combat.poison_duration_turns",
        "duration-unit": "turns",
        "clock": "02-mechanics.md#turn-clock",
        "on-retrigger": "extend-to-cap",
        "retrigger-cap": "combat.poison_duration_cap_turns",
        "ends-early": "declared-ending",
        "early-end": "02-mechanics.md#poison-removal"
      }
    ]
  },
  "verification": {
    "declared-window-set": {
      "scope": "the poison window named in the game's Fixed combat rules"
    }
  }
}