Timed window

timed-window-2

Tests included

This contract defines the behavior of timed windows: invulnerability frames, a cooldown, or a status effect.

This contract decides what a timed window, such as invulnerability frames, a cooldown, or a status effect, does when its opening occurs again while it is open, when play is suspended, and when it ends.

4 questions
no numbers
1 list
7 tests

Use in your package

The first button opens the authoring tool with this contract added and its questions unanswered. You can also download the zip file and add the contract later.

Open in the authoring tool Download zip file

What is in the zip file

The zip file holds the contract and its acceptance tests. In the authoring tool, choose Add contract and pick this zip file. If you edit your package outside the authoring tool, unpack the zip file in your package folder. The files of the zip file go into contracts/. Fill in the answers there.

Download contract JSON · Download verification pack

4 questions per window

You answer these once for each window.

The unit used by the duration and its clock.
Does the window's clock stop while ordinary play is suspended?
What a new opening does while this window is already open (a repeat opening).
Whether the window can close before its duration ends.

Lists1 list

Some settings are lists of rows.

A reference points to a number or a rule in your design. For a number, use the address of a decided number in your tuning, not an open one. For a rule, use its file and heading, such as 02-mechanics.md#recovery. The reference must match exactly one heading in that file. No > DELEGATED: or > PERSONALIZATION: tag may cover any part of the section under that heading. Each field's description says what it needs.

Windows

windows

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.

Each row is: id, opens-at, duration, duration-unit, clock, while-suspended, on-retrigger, retrigger-cap, ends-early, early-end.

Every field

Field	Kind	When it appears	Meaning
`id`	string	Required	A short name for the window in your game's words, such as poison.
`opens-at`	reference	Required	Where your game's rules say what opens the window. A poison window might open when a poisoned attack hits.
`duration`	reference	Required	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`	choice: seconds, frames, ticks, turns	Required	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`	reference	Required	Where your game's rules name the clock that closes this window. A poison effect may use the turn clock.
`while-suspended`	choice: stops, keeps-running	Present when row duration unit is Seconds or Frames or Ticks.	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`	choice: ignore, new-duration, keep-longer, extend-to-cap, stack	Required	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`	reference	Present when row on retrigger is Extend to cap.	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`	choice: expiry-only, declared-ending	Required	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`	reference	Present when row ends early is Declared ending.	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.

For builders

Exact wording for builders and 7 pack tests

Exact wording for builders

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.

Verification pack

sha256:17a5a688b1156f0eb450003d53e006d9d200942120d829376abff01587728044

The format calls an adoption that has its matching pack Checked. The tests are included, but this does not mean that a game has passed them. An adoption without the pack is Promised. The builder must still build the chosen behavior.

7 pack tests

Placeholders are filled from the adoption's answers, numbers, rows, and test inputs.

the declared window list matches the game

declared-window-set

generalonce

Applies for every adoption

The window list in Instance is complete for Inputs scope: every window in scope has one row, no window has two rows, and no row names something outside the scope.

Scope: Inputs scope
Holds: every timed window in scope has exactly one row in Instance, and every row in Instance names a timed window in scope

Row.id opens and expires on its declared clock

opens-and-expires

scenarioper windows row

Applies for every adoption

Row.id opens on the occurrence defined at Row.opens at, reads its Row.duration unit duration from Row.duration, and closes after that much progress on the clock defined at Row.clock.

Given: the Row.id window closed, with its opening defined at Row.opens at, its duration at Row.duration in Row.duration unit, and its clock at Row.clock
When: the opening defined at Row.opens at occurs once, with no repeat opening and no declared early ending
Then: Row.id becomes open when that occurrence happens
a change to the value or calculation at Row.duration after that moment does not move this copy's endpoint; the copy still closes after the duration read at opening
it is still open when the clock at Row.clock has advanced by exactly that duration
it is closed at the first observable step after the clock has advanced beyond that duration
Diagnostics: Instance-Row.id-open-close-trace
Instance-Row.id-clock-trace

Row.id handles a repeat opening in the declared way

retrigger-behavior

generalper windows row

Applies when row on retrigger is Ignore or New duration or Keep longer or Stack.

Repeat openings of Row.id follow one rule: Bind retrigger claim. The worked arithmetic makes the meaning exact, even when the game's own duration uses another number or unit.

Scope: repeat openings of Row.id while at least one copy is open
Holds: Bind retrigger claim
Diagnostics: Instance-Row.id-trigger-trace
Instance-Row.id-remaining-time-trace
Instance-Row.id-open-copy-count

Row.id extends at a repeat opening without passing its cap

retrigger-extends-to-cap

generalper windows row

Applies when row on retrigger is Extend to cap.

Repeat openings extend Row.id without passing the cap at Row.retrigger cap. The worked cases leave twelve units when four remain and ten are added under a cap of twelve, and nine when four remain and five are added. Together the two cases check both the addition and the cap.

Scope: repeat openings of Row.id while one copy is open
Holds: a repeat opening adds the newly granted duration to the remaining time without passing the cap at Row.retrigger cap; the arithmetic gives twelve units when four remain, ten are added, and the cap is twelve, and gives nine units when four remain, five are added, and the cap is twelve
Diagnostics: Instance-Row.id-trigger-trace
Instance-Row.id-remaining-time-trace

Row.id cannot end early

expiry-is-the-only-ending

generalper windows row

Applies when row ends early is Expiry only.

Row.id has no early ending: using it, removing related state, or changing the world does not close it. When a repeat opening changes the remaining time, that change is not an early closure. Only the end of its duration closes the copy.

Scope: the finite list of events and world changes that the game's Fixed prose associates with Row.id, plus its game-local acceptance-test sample of ordinary play while a copy is open with time remaining
Holds: no event or world change in scope closes any open Row.id copy before its duration ends; a copy's remaining time changes only through ordinary progress on the clock at Row.clock or through this row's declared repeat-opening behavior; when a repeat opening changes the remaining time, that change is not an early closure
Diagnostics: Instance-Row.id-open-close-trace

Row.id closes at its declared early ending

declared-ending-closes

scenarioper windows row

Applies when row ends early is Declared ending.

Every open Row.id copy on the entity the ending happens to closes when the event or condition defined at Row.early end occurs, unless the cited prose names more copies. Remaining duration does not delay an affected copy's ending.

Given: one or more Row.id copies open with time remaining, with their early ending defined at Row.early end
When: one early-ending event or condition defined at Row.early end occurs
Then: every open Row.id copy on the entity the ending happens to closes at that occurrence, unless the prose at Row.early end names more copies
no remaining duration keeps any affected copy open
Diagnostics: Instance-Row.id-early-ending-trace

Row.id treats suspended play in the declared way

suspension-behavior

scenarioper windows row

Applies when row duration unit is Seconds or Frames or Ticks.

Suspended play leaves an observable answer for every Row.id copy: Bind suspension result. Each remaining-time trace is read during the suspension so the two answers cannot pass on the same later state.

Given: one or more Row.id copies open, with an observed copy having four Row.duration unit left and a remaining-time trace for every copy
When: ordinary play is suspended for an interval that would advance the clock at Row.clock by six Row.duration unit during ordinary play, while that clock and every open copy are observed
Then: Bind suspension result
the remaining-time trace shows whether time advanced during the suspension, even if the stored open state after play resumes could look the same
Diagnostics: Instance-Row.id-remaining-time-trace
Instance-Row.id-suspension-trace

Use this contract in your package ↑