{ "contract": "ranged-value", "version": 2, "summary": "This contract covers health, stamina, oxygen, XP and other values with a marked bottom and top. It decides what happens to a change at those limits, how named lines fire (report that the value crossed them), how costs are paid, and how the value can move on its own. This contract does not cover the sources of changes, their rates, the display of the value, or the effects of its reports.", "questions": { "number-kind": { "asks": "Can this value hold a fraction, or is it always a whole number?", "rationale": "Whole and fractional values handle small changes differently. A health bar may show only whole points while oxygen keeps decimals.", "options": { "whole-number": { "meaning": "The stored value is always whole. A health bar can show 7 or 8, never 7.5.", "semantics": "A change with a fractional part passes through small-change before any limit or mark reads it. Every absolute stored target and mark must resolve to a whole number." }, "fractional": { "meaning": "Fractions stay exactly as sent. An oxygen meter can rest at 7.5.", "semantics": "Every finite change lands at full precision. No saved-fraction store exists." } } }, "small-change": { "asks": "A change contains part of a point. What happens to that part?", "when": { "flag": { "number-kind": [ "whole-number" ] } }, "otherwise": "This value keeps fractional changes exactly as sent.", "options": { "nearest": { "meaning": "Use the nearer whole change, with an exact half going to the higher number. A health gain of 2.5 becomes 3.", "semantics": "Round the signed change to the nearest integer; ties go toward positive infinity. Discard the difference." }, "nearest-away-from-zero": { "meaning": "Use the nearer whole change, with an exact half going away from zero. A karma loss of 2.5 becomes −3.", "semantics": "Round to the nearest integer; ties choose the integer with the greater absolute magnitude. Discard the difference." }, "drop-the-fraction": { "meaning": "Drop the fractional part toward zero. A poison drain of 0.7 health does nothing that step.", "semantics": "Remove the signed fractional part toward zero and discard it." }, "always-a-whole-unit": { "meaning": "Every nonzero change moves at least one whole point. Chip damage of 0.1 removes 1 health.", "semantics": "Round every non-integer signed change away from zero and discard the difference." }, "save-the-fraction": { "meaning": "Save the fractional parts until they make a whole point. Two hits worth 0.5 poise each add 1 poise together.", "semantics": "Move the whole part now. Add only the signed fractional remainder to one saved-fraction store. Remove complete multiples of fraction-step toward zero, move by that many whole units, and keep the remainder. Sets always clear the store; named resets and starting over at a limit use their own clearing choices." } } }, "exact-landing": { "asks": "The value lands exactly on a line or a limit. Does the value count as having reached it?", "options": { "at-the-line-counts": { "meaning": "Yes, landing exactly on it counts. Health falling to exactly 25 fires a warning set at 25.", "semantics": "A rising mark at t is reached at value greater than or equal to t; a falling mark is reached at value less than or equal to t. An exact landing may consume a limit." }, "must-pass-the-line": { "meaning": "No, the value must pass it. Health must fall below 25 before a warning set at 25 fires.", "semantics": "A rising mark at t is reached only above t; a falling mark is reached only below t. An exact landing does not consume a limit." } } }, "at-the-ceiling": { "asks": "A change would push this value above its marked top. What happens?", "options": { "stop-at-the-ceiling": { "meaning": "Stop at the top and drop the extra. A large health pickup fills the bar, and the rest of the pickup is dropped.", "semantics": "Store max. Drop the extra and do not report it. In every other respect the change counts as applied." }, "refuse-the-whole-change": { "meaning": "Refuse the whole gain. A health pickup that would overfill the bar adds no health.", "semantics": "Leave the value and saved fraction unchanged and report the refusal. Fire no mark." }, "hand-back-the-extra": { "meaning": "Fill to the top and hand back the extra. A healing rule can pass unused healing to a shield.", "semantics": "Store max and report the positive extra to the caller. This contract does not decide where the extra goes. A change with nobody acting has no caller, so its extra is dropped." }, "no-ceiling": { "meaning": "The marked top does not stop the value. It stays a named point that other rules can refer to. A score can keep rising after it passes its goal.", "semantics": "Store the complete result above max. The declared top remains citable and still defines shares." }, "start-a-lap": { "meaning": "Start a lap at the top. In a lap, the value starts again from a number that you name. Filling an XP bar reports a level and returns the bar to that number.", "semantics": "Reaching is decided by exact-landing. Report a lap and move to lap-lands-on. The mechanism text alone defines leftover handling and report order (see its numbered steps and its paragraph Lap loop)." } } }, "at-the-floor": { "asks": "A change would pull this value below its marked bottom. What happens?", "options": { "stop-at-the-floor": { "meaning": "Stop at the bottom and drop the shortfall. A lethal hit leaves health at zero, and the rest of the damage is dropped.", "semantics": "Store min. Drop the shortfall and do not report it." }, "refuse-the-whole-change": { "meaning": "Refuse the whole loss. A hit that would cross the bottom deals no damage.", "semantics": "Leave the value and saved fraction unchanged and report the refusal. Fire no mark." }, "hand-back-the-extra": { "meaning": "Empty to the bottom and hand back the shortfall. A shield can report how much damage is left for another rule.", "semantics": "Store min and report the positive shortfall to the caller. This contract does not decide where the shortfall goes. A change with nobody acting has no caller, so the shortfall is dropped." }, "no-floor": { "meaning": "The marked bottom does not stop the value. It stays a named point that other rules can refer to. A debt meter can keep falling below zero.", "semantics": "Store the complete result below min. The declared bottom remains citable." }, "start-a-lap": { "meaning": "Start a lap at the bottom. In a lap, the value starts again from a number that you name. Losing the last combo point can report a break and refill the meter.", "semantics": "Reaching is decided by exact-landing. Report a lap and move to lap-lands-on. The mechanism text alone defines leftover handling and report order (see its numbered steps and its paragraph Lap loop)." } } }, "jumped-lines": { "asks": "One move passes more than one mark (a line or a band edge). Which marks report?", "when": { "any": [ { "row-count": { "lines": "non-empty" } }, { "row-count": { "bands": "non-empty" } } ] }, "otherwise": "No mark exists, so no move can pass one.", "options": { "all-in-order": { "meaning": "Report every crossed mark in travel order. One large hit can report wounded, critical, then empty health.", "semantics": "Report every armed line and band edge whose reached state changes in its direction. Order by position along the path; row order decides a tie. Update all mark state." }, "only-the-nearest": { "meaning": "Report only the crossed mark nearest the landing value. One large hit can report empty health and suppress earlier warnings.", "semantics": "Among the crossed lines and band edges, find the one nearest to the landing value. Row order decides a tie. Report only that mark, but update every reached, arm, and band state along the full path." } } }, "when-a-limit-moves": { "asks": "The bottom or top moves while this value holds a number. What happens to the value?", "when": { "any": [ { "value-form": { "min": [ "citation" ] } }, { "value-form": { "max": [ "citation" ] } } ] }, "otherwise": "The bottom and top are fixed numbers, so neither limit moves.", "options": { "refill-to-the-new-ceiling": { "meaning": "Follow a moving top by filling to it. Raising maximum health from 100 to 120 also raises current health to 120.", "semantics": "A max change stores the new max. A min-only change keeps the value unless it falls below the new min, then stores that min." }, "keep-the-number": { "meaning": "Keep the current number while it is still inside the range. Raising maximum health from 100 to 120 leaves current health at 70.", "semantics": "Preserve the value inside the new range; otherwise clamp it to the limit it is outside, even if an ordinary change may pass that limit." }, "keep-the-share": { "meaning": "Keep the same share of the range. Raising a half-full health bar from 100 to 200 moves its health from 50 to 100.", "semantics": "Compute the old normalized share immediately before the limit move and store the same share of the new range. An empty old range uses the new min. Whole-number targets round to nearest with ties away from zero. Saved fraction is unchanged." }, "pull-it-to-a-declared-number": { "meaning": "Keep the number if it is still inside the range. Otherwise move the value to a number that you name. When the stamina top is lowered, a value that is now outside the range can move to 80.", "semantics": "Preserve the value inside the new range. Otherwise store out-of-range-lands-on, which must resolve inside the new range." }, "leave-the-number-alone": { "meaning": "Do not move the held number now. Lowering a score's marked top to 100 can leave a held score of 120 unchanged.", "semantics": "A held number outside a moved limit is legal only where the at-the-ceiling or at-the-floor answer for that limit lets the value pass the limit." } } }, "a-set-outside-the-range": { "asks": "Something sets this value to a number outside its range. What happens?", "when": { "row-count": { "sets": "non-empty" } }, "otherwise": "No named set puts this value directly at a target number.", "options": { "pull-it-to-the-nearer-limit": { "meaning": "Move to the limit the target passed. A refill aimed at 120 leaves a 100-point health bar at 100.", "semantics": "Above max store max; below min store min. The target outside the range is not a raw result. A set does not hand back extra or start a lap." }, "refuse-the-set": { "meaning": "Refuse the set and keep the old number. An invalid checkpoint refill leaves health unchanged.", "semantics": "Leave the value and saved fraction unchanged, fire no mark, and report refusal to the caller." }, "store-it-as-sent": { "meaning": "Store the target even outside the range. A score set to 120 can stay above its marked top of 100.", "semantics": "Store the target exactly. It is legal beyond a limit only where the at-the-ceiling or at-the-floor answer for that limit lets the value pass the limit." } } }, "does-a-set-fire-lines": { "asks": "A set jumps across one or more marks. Do they report?", "when": { "row-count": { "sets": "non-empty" } }, "otherwise": "No named set crosses a line or changes a band.", "options": { "treat-it-as-a-change": { "meaning": "Report crossed marks after a successful set. Refilling oxygen to full can clear the low-air warnings on the way up.", "semantics": "After storing the accepted target, test lines and band edges along the movement. jumped-lines selects reports. A refused or clamped target is never a raw result." }, "silent": { "meaning": "Update mark state without reports. Respawning at full health does not replay every health warning.", "semantics": "Recompute line reached state and line-geometry band state from the stored target. Event-edged bands keep their state. Report nothing." } } }, "the-extra-after-a-lap": { "asks": "Starting over at a limit is a lap. After a lap, what happens to the extra?", "when": { "any": [ { "flag": { "at-the-ceiling": [ "start-a-lap" ] } }, { "flag": { "at-the-floor": [ "start-a-lap" ] } } ] }, "otherwise": "Neither limit starts this value over, so no lap leaves extra.", "options": { "carry-it-onto-the-new-value": { "meaning": "Keep using the extra after the lap. An XP award of 120 can fill a 100-point bar and put 20 into the next level.", "semantics": "Keep the amount past the consuming limit and apply it in the same direction after the lap movement. The mechanism text defines the sequence (see its numbered steps and its paragraph Lap loop)." }, "drop-it": { "meaning": "Drop the extra after the lap. A 120-point stagger hit fills one 100-point meter, and the remaining 20 are dropped.", "semantics": "Drop the leftover after one lap and do not report it (see the numbered steps and the paragraph Lap loop of the mechanism text)." } } }, "more-than-one-lap": { "asks": "After a lap, the extra can reach the same limit again. Can one change cause more than one lap?", "when": { "any": [ { "flag": { "at-the-ceiling": [ "start-a-lap" ] } }, { "flag": { "at-the-floor": [ "start-a-lap" ] } } ] }, "otherwise": "Neither limit starts this value over, so one change cannot lap it.", "options": { "lap-again-while-it-fits": { "meaning": "Start over again while enough extra remains. A 250-point XP award can report two levels on a 100-point bar.", "semantics": "Repeat while carried leftover reaches the limit, up to the cap of 32 laps in the paragraph Lap loop of the mechanism text. This requires carrying the extra." }, "one-lap-per-change": { "meaning": "Allow at most one lap from each change. A 250-point combo gain reports one lap even if more would fit.", "semantics": "The originating change causes at most one lap (see the numbered steps and the paragraph Lap loop of the mechanism text)." } } }, "a-lap-clears-saved-fraction": { "asks": "Does a lap clear any saved fraction?", "when": { "any": [ { "flag": { "small-change": [ "save-the-fraction" ], "at-the-ceiling": [ "start-a-lap" ] } }, { "flag": { "small-change": [ "save-the-fraction" ], "at-the-floor": [ "start-a-lap" ] } } ] }, "otherwise": "No lap can clear saved fractions; either this value does not lap or it does not save fractions.", "options": { "clear-it": { "meaning": "Clear the saved fraction after every lap. Breaking a stagger meter removes the 0.4 poise that was saved.", "semantics": "A lap clears the saved fraction." }, "keep-it": { "meaning": "Keep the saved fraction across a lap. Leveling up keeps the 0.4 XP that was saved.", "semantics": "A lap leaves the signed saved-fraction store unchanged." } } }, "not-enough-room": { "asks": "This value cannot pay the full cost of an action, because not enough room is left before the limit. What happens?", "when": { "row-count": { "costs": "non-empty" } }, "otherwise": "No cost checks this value before changing it; every change simply happens, and bands and limits still apply.", "options": { "refuse-the-action": { "meaning": "Refuse the action and spend nothing. A tired player cannot dodge without the full stamina cost.", "semantics": "Report refusal and shortage to the caller. Leave the value, saved fraction, and every mark unchanged." }, "take-what-fits": { "meaning": "Spend what remains and report the amount paid. A tired player can use the last stamina for a weaker dodge.", "semantics": "Move to the limit in the direction of the cost, test marks normally, and report the approved positive magnitude. The game's rule decides the partial action." } } }, "drifts-together": { "asks": "A drift is a change that happens with nobody acting. Two or more drifts can run in the same step. How do they combine?", "when": { "row-count": { "drifts": "at-least-two" } }, "otherwise": "Fewer than two drifts can run together, so no combination choice applies.", "options": { "add-them-up": { "meaning": "Add the drifts' signed amounts and move once. Oxygen drain of 3 and recovery of 1 produce one loss of 2.", "semantics": "Clip each eligible contribution to its own stop, sum the clipped amounts, resolve small-change once, and test marks once." }, "only-the-largest": { "meaning": "Run only the largest drift. With health regeneration of 4 and poison damage of 2, only the regeneration runs in that step.", "semantics": "Compare clipped absolute magnitudes; row order decides a tie. A skipped drift whose amount grows while it runs does not advance its growth for that step." }, "in-row-order": { "meaning": "Run each drift in written order. Poison can damage health before regeneration heals it in the same step.", "semantics": "Settle every eligible row separately in row order. Each row follows the numbered steps of the mechanism text from step 1 to step 8." } } }, "lines-read": { "asks": "A change would pass a limit. Are marks tested against the number before the limit is applied, or against the number that the value keeps?", "when": { "any": [ { "row-count": { "lines": "non-empty" } }, { "row-count": { "bands": "non-empty" } } ] }, "otherwise": "No line or band exists, so nothing reads a result beyond a limit.", "options": { "the-final-value": { "meaning": "Marks are tested against the number that the value keeps. A hit aimed at −20 leaves health at 0, so warnings are tested against 0.", "semantics": "The outward part of the move tests its stored endpoint, or the consuming limit on a lap. It never tests beyond a limit." }, "the-raw-result": { "meaning": "Marks are tested against the number before the limit is applied. A hit aimed at −20 lets health warnings be tested against −20 before health returns to 0.", "semantics": "The outward part of the move tests the raw candidate. It may observe a number the value never stores. A refused change has no observable raw result." } } } }, "declares": { "values": { "min": { "description": "This value's marked bottom. Keep it even when the value may fall lower.", "forms": [ "number", "citation" ] }, "max": { "description": "This value's marked top. Keep it even when the value may rise higher.", "forms": [ "number", "citation" ] }, "initial": { "description": "The number that this value holds when it is created. When you point to a number in your game's rules instead, that number is read at creation. Later resets are listed separately.", "forms": [ "number", "citation" ] }, "fraction-step": { "description": "How much saved fraction releases one whole point.", "when": { "flag": { "small-change": [ "save-the-fraction" ] } } }, "anchor": { "description": "The resting point a drift approaches from either side.", "forms": [ "number", "citation" ], "when": { "row-has": { "drifts": { "direction": [ "toward-the-anchor" ] } } } }, "lap-lands-on": { "description": "Where the value lands during a lap.", "forms": [ "number", "citation" ], "when": { "any": [ { "flag": { "at-the-ceiling": [ "start-a-lap" ] } }, { "flag": { "at-the-floor": [ "start-a-lap" ] } } ] } }, "out-of-range-lands-on": { "description": "Where the value lands when a moved limit leaves it outside the new range.", "forms": [ "number", "citation" ], "when": { "flag": { "when-a-limit-moves": [ "pull-it-to-a-declared-number" ] } } } }, "rows": { "reading-notes": { "description": "List the part of your game's rules that a reader needs before relying on this adoption. Use at most one row.", "when-empty": "No advance reading is required.", "record": { "read-first": { "type": "citation", "required": true, "description": "Where your game's rules say what a reader needs first, such as which of a soft top and a hard top the game calls full." } } }, "quantity-unit": { "description": "Name the unit that your game uses for absolute numbers. Use at most one row.", "when-empty": "This contract gives the quantity no named unit.", "record": { "unit": { "type": "string", "required": true, "description": "The unit of every absolute number, whether you give the number or point to it, such as kg or XP. This contract neither interprets nor converts the unit." } } }, "lines": { "description": "List the named marks this value reports crossing.", "when-empty": "No crossing is reported.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this mark in your game's words, such as low-health or full." }, "value-kind": { "type": "string", "required": true, "options": [ "number", "citation" ], "description": "Whether this mark uses a fixed number, or points to a number in your game's rules. When it points to a number, the mark moves when that number changes." }, "value": { "type": "number", "when": { "row": { "value-kind": [ "number" ] } }, "description": "The fixed number where this mark sits." }, "value-key": { "type": "citation", "when": { "row": { "value-kind": [ "citation" ] } }, "description": "Where your game's rules state the number of this mark. The number is read again at each comparison." }, "line-unit": { "type": "string", "options": [ "number", "share-of-the-ceiling" ], "description": "Use a fixed number or a share of the marked top. A share is a part of the marked top, such as 0.25 for a quarter. The top is read again at each comparison. The resulting position can be between whole points. It is only compared and never stored. When this field is absent, number applies." }, "direction": { "type": "string", "required": true, "options": [ "rising", "falling", "both" ], "description": "The direction of movement in which this mark reports a crossing." }, "refire": { "type": "string", "required": true, "options": [ "every-crossing", "once", "a-set-number-of-times" ], "description": "How often this line reports: at every crossing, once per arm, or a fixed number of times per arm. To arm a line is to make it ready to report." }, "times": { "type": "integer", "within": [ 1, 2147483647 ], "when": { "row": { "refire": [ "a-set-number-of-times" ] } }, "description": "The positive whole number of reports allowed per arm." }, "rearm": { "type": "string", "when": { "row": { "refire": [ "once", "a-set-number-of-times" ] } }, "options": [ "on-reset", "on-event", "after-a-wait", "never" ], "description": "What re-arms this line. To re-arm a line is to make it ready to report again, with its full number of reports." }, "rearm-declared-in": { "type": "citation", "when": { "row": { "rearm": [ "on-reset", "on-event", "after-a-wait" ] } }, "description": "Where your game's rules name the reset, event, or wait that re-arms this line." }, "repeat": { "type": "string", "when": { "row": { "rearm": [ "after-a-wait" ] } }, "options": [ "restart-the-wait", "keep-the-first-wait", "add-to-the-wait" ], "description": "Choose what another crossing does while the wait is running." }, "counts-at-line": { "type": "string", "options": [ "at-the-line-counts", "must-pass-the-line" ], "description": "The default answer is the answer to exact-landing. Leave this field out to use the default answer, or choose another answer for this line." }, "starts-armed": { "type": "string", "options": [ "armed", "disarmed" ], "description": "Whether this line starts able to report. When this field is absent, the line starts armed." } } }, "sets": { "description": "List each refill, direct assignment, or recomputed total. Use a set when lines and bands must be able to react to the movement.", "when-empty": "Nothing sets the value directly; laps, resets and limit moves remain their own movements.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this set in your game's words, such as surface-refill or inventory-total." }, "mode": { "type": "string", "required": true, "options": [ "set-to-target", "recompute" ], "description": "Use a named target or a rule's computed result." }, "target-key": { "type": "citation", "required": true, "description": "Where your game's rules state the target number or the rule that computes it." }, "trigger-declared-in": { "type": "citation", "required": true, "description": "Where your game's rules name the event or rule that offers this set." }, "enabled-while": { "type": "citation", "description": "Where your game's rules state a condition that allows this set. This field is optional." } } }, "bands": { "description": "List named on-or-off states between marks, such as overheated or low-warning.", "when-empty": "This value keeps no named state.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this state in your game's words, such as overheated or low-warning." }, "enter-on": { "type": "string", "required": true, "options": [ "line", "event" ], "description": "Whether a line or named event turns the state on." }, "enter-value-kind": { "type": "string", "when": { "row": { "enter-on": [ "line" ] } }, "options": [ "number", "citation" ], "description": "Whether the entering line uses a fixed number, or points to a number in your game's rules. When it points to a number, the line moves when that number changes." }, "enter-value": { "type": "number", "when": { "row": { "enter-value-kind": [ "number" ] } }, "description": "The fixed number of the entering line." }, "enter-value-key": { "type": "citation", "when": { "row": { "enter-value-kind": [ "citation" ] } }, "description": "Where your game's rules state the number of the entering line. The number is read again at each comparison." }, "enter-unit": { "type": "string", "when": { "row": { "enter-on": [ "line" ] } }, "options": [ "number", "share-of-the-ceiling" ], "description": "Use a fixed number or a share of the marked top. A share is a part of the marked top, such as 0.25 for a quarter. The top is read again at each comparison. The resulting position can be between whole points. It is only compared and never stored." }, "enter-direction": { "type": "string", "when": { "row": { "enter-on": [ "line" ] } }, "options": [ "rising", "falling" ], "description": "The direction that turns the state on." }, "enter-declared-in": { "type": "citation", "when": { "row": { "enter-on": [ "event" ] } }, "description": "Where your game's rules name the event that turns the state on." }, "leave-on": { "type": "string", "required": true, "options": [ "line", "event", "after-a-wait" ], "description": "Whether a line, event, or wait turns the state off." }, "leave-value-kind": { "type": "string", "when": { "row": { "leave-on": [ "line" ] } }, "options": [ "number", "citation" ], "description": "Whether the leaving line uses a fixed number, or points to a number in your game's rules. When it points to a number, the line moves when that number changes." }, "leave-value": { "type": "number", "when": { "row": { "leave-value-kind": [ "number" ] } }, "description": "The fixed number of the leaving line." }, "leave-value-key": { "type": "citation", "when": { "row": { "leave-value-kind": [ "citation" ] } }, "description": "Where your game's rules state the number of the leaving line. The number is read again at each comparison." }, "leave-unit": { "type": "string", "when": { "row": { "leave-on": [ "line" ] } }, "options": [ "number", "share-of-the-ceiling" ], "description": "Use a fixed number or a share of the marked top. A share is a part of the marked top, such as 0.25 for a quarter. The top is read again at each comparison. The resulting position can be between whole points. It is only compared and never stored." }, "leave-direction": { "type": "string", "when": { "row": { "leave-on": [ "line" ] } }, "options": [ "rising", "falling" ], "description": "The direction that turns the state off." }, "leave-declared-in": { "type": "citation", "when": { "row": { "leave-on": [ "event", "after-a-wait" ] } }, "description": "Where your game's rules name the event that turns the state off, or state the length of the wait." }, "repeat": { "type": "string", "when": { "row": { "leave-on": [ "after-a-wait" ] } }, "options": [ "restart-the-wait", "keep-the-first-wait", "add-to-the-wait" ], "description": "Choose what another entry does while the wait is running." }, "starts": { "type": "string", "required": true, "options": [ "in", "out", "read-from-initial" ], "description": "Whether this state starts on (in), starts off (out), or is read from the starting value (read-from-initial)." }, "blocks-change": { "type": "string", "options": [ "none", "blocks-rises", "blocks-falls", "blocks-all" ], "description": "Which incoming plain changes, costs, or drifts are blocked while this state is on. When this field is absent, none applies." }, "counts-at-line": { "type": "string", "options": [ "at-the-line-counts", "must-pass-the-line" ], "description": "The default answer is the answer to exact-landing. Leave this field out to use the default answer, or choose another answer for the line edges of this state." } } }, "costs": { "description": "List each action that checks whether this value can pay before it changes.", "when-empty": "No action checks this value before it changes; every change simply happens, and bands and limits still apply.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this cost in your game's words, such as dodge or cast-spell." }, "direction": { "type": "string", "required": true, "options": [ "rising", "falling" ], "description": "Whether paying moves the value toward the top or toward the bottom." }, "amount-key": { "type": "citation", "required": true, "description": "Where your game's rules state the cost. The cost is not negative." }, "action-declared-in": { "type": "citation", "required": true, "description": "Where your game's rules name the action that receives the reports of refusal, shortage, or amount paid." }, "answer": { "type": "string", "options": [ "refuse-the-action", "take-what-fits" ], "description": "The default answer is the answer to not-enough-room. Leave this field out to use the default answer, or choose another answer for this action." } } }, "drifts": { "description": "List each drift, such as draining, recovery, or cooling.", "when-empty": "This value never changes on its own.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this drift in your game's words, such as recovery or cooling." }, "direction": { "type": "string", "required": true, "options": [ "rises", "falls", "toward-the-anchor" ], "description": "Whether the value moves upward, downward, or toward the shared resting point." }, "cadence": { "type": "string", "required": true, "options": [ "per-game-step", "per-real-second", "per-turn", "at-a-named-moment" ], "description": "Choose when one contribution is made." }, "moment-declared-in": { "type": "citation", "when": { "row": { "cadence": [ "at-a-named-moment" ] } }, "description": "Where your game's rules name the moment." }, "step-amount-key": { "type": "citation", "required": true, "description": "Where your game's rules state the amount for each occurrence. The amount is positive." }, "amount-kind": { "type": "string", "required": true, "options": [ "fixed", "depends-on-state", "grows-while-it-runs" ], "description": "Whether the amount stays fixed, depends on state, or grows while the drift runs." }, "amount-declared-in": { "type": "citation", "when": { "row": { "amount-kind": [ "depends-on-state", "grows-while-it-runs" ] } }, "description": "Where your game's rules state how the amount depends on state, or how it grows." }, "stops-at-key": { "type": "citation", "required": true, "description": "Where your game's rules state the number at which this drift stops." }, "at-stop": { "type": "string", "required": true, "options": [ "lands-exactly", "overshoots-then-returns" ], "description": "Whether the value lands exactly on the stop, or passes the stop for a short time and then returns. The value passes the stop only when this drift runs alone." } } }, "interrupts": { "description": "List the conditions and pauses that control a drift. Every row for one drift must allow it before it runs.", "when-empty": "No listed condition or pause controls a drift.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this interruption in your game's words, such as after-a-hit or only-underwater." }, "drift": { "type": "string", "required": true, "description": "Name the drift this row controls." }, "kind": { "type": "string", "required": true, "options": [ "off-while-condition", "runs-only-while-condition", "paused-after-event" ], "description": "Whether the drift stays off during a condition, runs only during a condition, or pauses after an event." }, "condition-declared-in": { "type": "citation", "when": { "row": { "kind": [ "off-while-condition", "runs-only-while-condition" ] } }, "description": "Where your game's rules state the condition. For a condition that is a named state of this value, such as a band, cite the chapter section that states it." }, "event-declared-in": { "type": "citation", "when": { "row": { "kind": [ "paused-after-event" ] } }, "description": "Where your game's rules name the event that starts the pause." }, "pause-length-key": { "type": "citation", "when": { "row": { "kind": [ "paused-after-event" ] } }, "description": "Where your game's rules state the length of the pause." }, "pause-length-kind": { "type": "string", "when": { "row": { "kind": [ "paused-after-event" ] } }, "options": [ "fixed", "depends-on-state" ], "description": "Whether the length of the pause stays fixed or depends on state." }, "pause-length-declared-in": { "type": "citation", "when": { "row": { "pause-length-kind": [ "depends-on-state" ] } }, "description": "Where your game's rules state how the length of the pause depends on state." }, "repeat-event": { "type": "string", "when": { "row": { "kind": [ "paused-after-event" ] } }, "options": [ "restart-the-wait", "keep-the-first-wait", "add-to-the-wait" ], "description": "Choose what another event does while the pause is running." } } }, "resets": { "description": "List named moments that put this value back, such as respawn, a new day, or turn start. Use a reset when this return must never make a report.", "when-empty": "Only creation applies the starting value.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "A short name for this reset moment in your game's words, such as respawn or new-day." }, "happens-at": { "type": "citation", "required": true, "description": "Where your game's rules name the moment." }, "sets-value-to-key": { "type": "citation", "description": "Where your game's rules state the number that this reset stores. When this field is absent, the reset stores the starting value. When the starting value points to a number in your game's rules, the reset stores the number that was read at creation." }, "clears-saved-fraction": { "type": "string", "when": { "flag": { "small-change": [ "save-the-fraction" ] } }, "options": [ "yes", "no" ], "description": "Whether this reset clears the saved fraction." }, "re-arms-lines": { "type": "string", "required": true, "options": [ "yes", "no" ], "description": "Whether this reset re-arms every line whose rearm-declared-in points to this reset's moment." }, "resets-bands": { "type": "string", "options": [ "return-to-starts", "recompute-from-target", "keep" ], "description": "Choose what the named states do at this reset. With return-to-starts, every named state goes back to its declared start. With recompute-from-target, every named state that has a line at both ends is worked out again from the reset target, and every other named state keeps its state. With keep, every named state keeps its state. None of the three answers makes a report. When this field is absent, keep applies." } } } } }, "rules": { "range-nonempty": "max > min", "initial-not-below-min": "initial >= min", "initial-not-above-max": "initial <= max", "fraction-step-positive": "fraction-step > 0", "anchor-not-below-min": "anchor >= min", "anchor-not-above-max": "anchor <= max", "lap-lands-not-below-min": "lap-lands-on >= min", "lap-lands-not-above-max": "lap-lands-on <= max", "out-of-range-lands-not-below-min": "out-of-range-lands-on >= min", "out-of-range-lands-not-above-max": "out-of-range-lands-on <= max", "share-needs-two-walls": { "forbid": { "any": [ { "flag": { "when-a-limit-moves": [ "keep-the-share" ], "at-the-ceiling": [ "no-ceiling" ] } }, { "flag": { "when-a-limit-moves": [ "keep-the-share" ], "at-the-floor": [ "no-floor" ] } } ] }, "message": "The answer keep-the-share needs a bottom and a top that the value cannot pass. Change the answer no-ceiling or no-floor, or choose another answer to when-a-limit-moves." }, "moving-refill-cannot-lap": { "forbid": { "any": [ { "flag": { "when-a-limit-moves": [ "refill-to-the-new-ceiling" ], "at-the-ceiling": [ "start-a-lap" ] } }, { "flag": { "when-a-limit-moves": [ "refill-to-the-new-ceiling" ], "at-the-floor": [ "start-a-lap" ] } } ] }, "message": "The answer refill-to-the-new-ceiling can put the value exactly on a limit whose answer is start-a-lap. A moving limit never starts a lap. Change one of these two answers." }, "another-lap-needs-extra": { "forbid": { "flag": { "more-than-one-lap": [ "lap-again-while-it-fits" ], "the-extra-after-a-lap": [ "drop-it" ] } }, "message": "The answer lap-again-while-it-fits needs the extra that remains after the first lap. Choose carry-it-onto-the-new-value, or choose one-lap-per-change." } }, "pack": "sha256:7a5cc40f34b4ff0c89b9c577964f8b396f1b04ec8003ca286c73a5f3ffdf5fc1", "origin": "https://opengdd.org/contracts/ranged-value-2", "mechanism": [ "This text decides the order of the steps for a plain change, a cost, a set, a drift, a lap movement, a limit move, and a reset. The questions and rows supply choices and cited game rules. They do not change the order.", "An **operation** is one change that this contract settles from start to finish: a plain change, cost, set, drift step or composed drift batch, lap movement, limit move, or reset. An **imposed change** is a plain change that happens without checking whether the value can pay it. **Residue** is the signed fraction saved for later. A **mark** is a line or one edge of a band. A **bare line** is a line that is not an edge of a band. A **leg** is one visible stretch of movement with its own start and end. A **consuming limit** is a limit whose answer is `start-a-lap`. An operation **consumes** that limit when it starts a lap there. The **leftover** is the amount of the change that is past the consuming limit. Each operation has an id supplied by its row or cited game rule and settles fully before the next begins. A lap sequence's outward, lap, and leftover legs retain their originating operation id; leg position and lap count distinguish their reports.", "A band is **line-geometry** only when both its edges are lines. A band with any event or wait edge is **event-edged**. An event-edged band keeps its state under every silent recompute (a set, a reset, or a limit move). A reset's explicit `return-to-starts` is a restore, not a recompute, and applies to every band.", "1. **Block.** If an active band blocks the operation's direction and the operation is an imposed change, cost, or drift, discard it. Report `blocked` to its source; a drift records the block but has no receiver. Stop this operation. Remove a blocked drift before several drifts combine. Blocks never stop sets, resets, limit moves, or lap movements.", "2. **Resolve provisionally.** Fractional handling computes a provisional movement and new residue without committing either. A whole change leaves residue untouched. An absolute repositioning computes its destination and applies its own clearing rule; it does not pass through `small-change`.", "3. **Check capacity for a cost.** Compare provisional movement with the room toward the named limit. Refusal discards movement and residue together. `take-what-fits` recomputes both from the approved amount and never keeps a fraction from the refused part.", "4. **Find the raw candidate.** A change adds provisional movement to the held value. A set uses its accepted or clamped stored target. A lap movement, limit move, or reset uses its own absolute destination.", "5. **Apply the limit.** A raw candidate strictly past a limit uses that limit's answer. Exact landing is ordinary unless `start-a-lap` applies, in which case `exact-landing` decides whether it consumes the limit. Refusing the whole change discards provisional movement and residue, leaves the store untouched, reports refusal, and stops. Sets, resets, and limit moves use their own target rules. Drifts use the clipping exception below.", "6. **Commit.** Store the final value and new residue together. No partly settled state is visible.", "7. **Test marks for each leg.** The outward leg ends at the final value or consuming limit. A lap then has a lap leg, followed by each carried leftover as a new lap operation returning to step 1. Test lines and band edges on every leg. Recompute reached state from each stored endpoint in both directions; only a false-to-true transition in the row's direction reports. A `both` line keeps one reached state per direction. With raw reading, only the outward leg tests the raw candidate; lap and leftover legs test stored values. At a consuming limit, report outward marks, including a line on the limit, then the lap, then lap-leg marks. Apply `jumped-lines` separately to every leg.", "8. **Report.** Every report carries before, after, direction, leg position, and operation id. A crossing or band transition also carries its row id. A lap carries its count. `lap-cap-reached` carries committed state. Returned extra carries its amount. A cost or block carries refusal, shortage, approved amount, or `blocked` as applicable. Raw-reading reports use the tested raw candidate as `after`; other reports use the stored endpoint. Direction is `rising`, `falling`, or `unchanged`.", "Every comparison reads the stored value at full precision, never a rounded display number. Every cited limit, mark and stop is read again at each comparison. Creation is not a movement or report. At creation, line and band-edge reached state is stored without reporting; lines use their declared arm state, and bands use their declared starting state. A share mark sits at the declared share multiplied by the value at `max`, read again at that comparison; that position may be fractional and is compared, never stored. A line-geometry band that answers `read-from-initial` starts in exactly when the initial value sits on the reached side of its entering edge and not on the reached side of its leaving edge, each side read per that edge's declared direction, with an exact landing counted as this value's `exact-landing` answer or the row's `counts-at-line` override directs. An event-edged band that answers `read-from-initial` starts out. A silent recompute of a line-geometry band's state (a set, a limit move, or `recompute-from-target`) applies the same two-sided test against the value it recomputes from.", "**Lap loop.** A single originating operation may settle at most 32 laps. Before lap 33, refuse the continuation, report `lap-cap-reached`, drop the remaining leftover, and keep the state committed by lap 32. A statically provable repeated lap state is a package error, but the runtime cap remains the termination guard. After each lap report, re-read either cited limit and check the lap target against the re-read range. If a limit moved, apply the limit-move ruling below; any `limit-moved` band report occurs before the lap leg. A limit move never repositions the value during this loop. Under `clear-it`, a lap clears the saved fraction after the consuming movement and before carried leftover is applied. Under `one-lap-per-change`, a second reach of the same consuming limit is stored without consuming and the amount past that limit is dropped.", "**Drift clipping.** A rising drift is eligible only below its stop; a falling drift only above it; a drift toward the anchor uses the matching test for its current direction. Clip each contribution to its stop before combining drifts. `overshoots-then-returns` is observable only when that row settles alone: its raw path may expose the overshoot, then a silent correction stores the stop, reports no mark, and recomputes reached state from the stored stop. A drift reaching a consuming limit clips there without consuming it.", "**Sets.** A set has no raw result. Marks see only a successful stored outcome. Clamping a target stores the nearer limit; raw reading never sees the target outside the range. A successful set clears residue. A refused set does not.", "**Resets.** A reset stores its target, recomputes and stores every line's reached state from that target, and applies its arm, band, and fraction choices silently. Band state follows the row's `resets-bands` answer, not an automatic recompute. For a band that answers `read-from-initial`, `return-to-starts` restores the state stored at creation. A reset reports no crossing.", "**Limit moves.** A moving limit never fires a bare line. After the limit and any resulting current-value change settle, recompute and store every line's reached state and every line-geometry band's state against the new positions. Event-edged bands keep their state. A line-geometry band that enters or leaves this way reports the state change with cause `limit-moved`; a bare line reports nothing. The saved fraction is not cleared. A limit move that lands the value exactly on a consuming limit does not consume it.", "**Continuous drift.** A `per-real-second` drift accrues continuously. Each settlement contributes its rate multiplied by elapsed cited-clock time, and fractional accrual passes through `small-change`.", "Sets, resets, and limit moves at one moment settle in the order in which the citing game rules trigger them. A game rule that triggers several at once must state their order.", "**Share-preserving limit moves.** `keep-the-share` is one absolute repositioning. A whole-number target rounds to nearest, with ties away from zero. Residue is unchanged.", "A band has no address of its own. Where this adoption's own game asks for a condition that is a band, cite the Fixed chapter section that states the band. Another adoption cannot cite a band." ], "answers": { "number-kind": "whole-number", "small-change": "save-the-fraction", "exact-landing": "at-the-line-counts", "at-the-ceiling": "start-a-lap", "at-the-floor": "stop-at-the-floor", "jumped-lines": "all-in-order", "the-extra-after-a-lap": "drop-it", "more-than-one-lap": "one-lap-per-change", "a-lap-clears-saved-fraction": "clear-it", "lines-read": "the-final-value" }, "values": { "min": 0, "max": 100, "initial": 0, "fraction-step": 1, "lap-lands-on": 0 }, "rows": { "lines": [ { "id": "stagger-warning", "value-kind": "number", "value": 70, "direction": "rising", "refire": "every-crossing" }, { "id": "stagger-break", "value-kind": "citation", "value-key": "contracts.boss-stagger.max", "direction": "rising", "refire": "every-crossing" }, { "id": "poise-settled", "value-kind": "number", "value": 0, "direction": "falling", "refire": "every-crossing" } ], "bands": [ { "id": "stagger-lockout", "enter-on": "line", "enter-value-kind": "number", "enter-value": 100, "enter-unit": "number", "enter-direction": "rising", "leave-on": "after-a-wait", "leave-declared-in": "tuning.stagger.lockout-seconds", "repeat": "restart-the-wait", "starts": "out", "blocks-change": "blocks-rises" } ], "drifts": [ { "id": "poise-decay", "direction": "falls", "cadence": "per-real-second", "step-amount-key": "tuning.stagger.poise-decay-rate", "amount-kind": "grows-while-it-runs", "amount-declared-in": "02-mechanics.md#poise-decay-ramp", "stops-at-key": "contracts.boss-stagger.min", "at-stop": "lands-exactly" } ], "interrupts": [ { "id": "after-a-hit", "drift": "poise-decay", "kind": "paused-after-event", "event-declared-in": "02-mechanics.md#poise-hit-landed", "pause-length-key": "tuning.stagger.poise-decay-delay", "pause-length-kind": "fixed", "repeat-event": "restart-the-wait" }, { "id": "while-locked", "drift": "poise-decay", "kind": "off-while-condition", "condition-declared-in": "02-mechanics.md#stagger-lockout-band" } ], "reading-notes": [], "quantity-unit": [], "sets": [], "costs": [], "resets": [] } }