Skip to content

feat(variables): add a random operation to updateVariable - #391

Merged
han4wluc merged 3 commits into
mainfrom
feat/update-variable-random-operation
Nov 18, 2026
Merged

han4wluc merged 3 commits into
mainfrom
feat/update-variable-random-operation

Conversation

@han4wluc

@han4wluc han4wluc commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

Rolling a number today needs the random action in its integer form. That form has rules that are awkward for authors: a line can hold only one, it always runs after every updateVariable operation whatever order the line is written in, and it continues to the next line by itself. It also cannot write text or true/false values.

A roll is "set this variable to something", which is what updateVariable is for.

What changed

An updateVariable operation can now be op: random:

updateVariable:
  id: rollDice
  operations:
    - variableId: dice
      op: random
      distribution: { type: integer, min: 1, max: 6 }
    - variableId: dice
      op: increment
      value: 2
    - variableId: weather
      op: random
      distribution:
        type: weighted
        values:
          - { weight: 60, value: sunny }
          - { weight: 40, value: rain }
  • Operations run in list order, so later operations of the same action see the drawn value, and one action can hold any number of rolls.
  • integer draws a uniform integer between inclusive bounds into a number variable, with the same bounds rules as the random action.
  • weighted stores the value of one entry, chosen in proportion to the weights, with the same weight rules as weighted random outcomes. A value is a string, a finite number or a boolean and must match the variable's type.
  • The variable must be declared and writable, in any scope.
  • A random operation takes only variableId, op and distribution, all fixed authored values. An operation that an action template changes is refused, so a weighted text value cannot hold template syntax such as ${...}. Every random operation of an action is checked before the first one is drawn.
  • Templates in the other operations of the action are rendered before the action runs, as they already are, so they read the variables from before the roll.
  • A random operation does not continue to the next line.

Rollback and save/load:

  • A roll that a line makes into a context variable is recorded in the existing randomOutcomes ledger, under the path of its operation (for example updateVariable.operations.0), and is replayed without rerolling. The persisted format and its version are unchanged.
  • A recorded roll that no longer matches its operation after a project update (range, variable type, operation removed) is dropped, and replaying the line then leaves that operation out. This is the policy the random action already has.
  • A roll made from an interaction is recorded as the value it set, like any other interaction variable update.
  • Rolls into device and account variables are not recorded, because rollback does not restore those variables.

The random action is unchanged. The weighted sampler now shares its weight validation and selection with the new weighted values.

The version is bumped to 1.53.0.

Testing

Engine tests:

  • New spec/RouteEngine.updateVariableRandom.test.js (32 tests):
    • Behaviour: list order, several rolls in one action, weighted text, number and true/false values, the direct action API, no automatic continue, every word of a range mapped to its own integer, and weighted values selected in proportion to their weights.
    • Refusals: invalid operations before anything is drawn, also when an earlier roll of the same action is valid, operations that a template changes or produces, and no partial write or recorded roll when a later operation fails.
    • Rollback and save/load: line rolls replayed without drawing, a new roll after rolling back past the line, same-line re-entry as its own roll, interaction rolls, device and account variables, two rolls into one variable, confirm dialog actions, a conditional of the same batch reading the roll, and a roll inside a weighted random outcome.
    • Project updates and saves: recorded rolls dropped or kept across project updates, a save loaded into a changed project, and a save with no recorded rolls, which is never rerolled.
    • 150 generated cases with random ranges and weights, each replayed across save, load and rollback with no new draw.
  • spec/RouteEngine.form.test.js covers a roll in a form's submit actions, and spec/RouteEngine.sceneReplay.test.js covers rolls during a scene replay (context allowed, account refused).
  • With the replay lookup inverted, the replay tests fail.
  • spec/random.test.js covers sampling and validation of the two variable distributions, and spec/projectDataSchema.test.js covers accepted and rejected operation shapes.
  • bun run test, bun run lint, bun run check:test-markers and bun run build pass.

Browser (VT), two new robustness specs that run in CI:

  • variable-random-line-rollback: a line rolls a number, adds 10 to it and rolls a weighted text value. Pressing Back shows the same roll with no new draw. Rolling back past the line restores the defaults, and entering it again draws a new roll. Loading a save made after the first roll shows the first roll again with no new draw.
  • variable-random-choice-branch: a choice click rolls a number and a conditional in the same click routes on it. Back returns to the choice with no new draw, and a second click draws again and routes the other way.
  • Both pass the CI VT flow locally (capture and report, 0 mismatched images). With the engine built from main, both fail on their first roll assertion.
  • The VT harness accepts vtRandomUint32Sequence, a list of words drawn in order, and counts draws in __vtRandomCalls, so a spec can tell a replayed roll from a new one. The existing random/choice-integer-branch spec still matches its reference.

An updateVariable operation with op: random sets its variable to a
randomly drawn value: a uniform integer between inclusive bounds, or one
of several weighted values. Operations run in list order, so later
operations of the same action see the drawn value, and one action can
hold any number of rolls. A random operation does not continue to the
next line.

A roll that a line makes into a context variable is recorded in the
randomOutcomes ledger under the path of its operation, so rollback and
save/load replay it without rerolling. A roll made from an interaction
is recorded as the value it set.

Bumps the version to 1.53.0.
…e cases

Two robustness specs, both run in CI:

- variable-random-line-rollback: a line rolls a number and a weighted
  text value. Back and Load show the recorded roll again without
  drawing, and entering the line again after rolling back past it draws
  a new roll.
- variable-random-choice-branch: a choice click rolls a number and a
  conditional in the same click routes on it. Back draws nothing and a
  second click draws again.

The VT harness accepts vtRandomUint32Sequence, a list of words drawn in
order, and counts the draws in __vtRandomCalls, so a spec can tell a
replayed roll from a new one.

More engine tests: every word of a range, weighted proportions, a
conditional reading the roll in the same batch, a roll inside a
weighted random outcome, same-line re-entry, templates next to a roll,
saves loaded into a changed project, saves with no recorded rolls, and
150 generated cases replayed across save, load and rollback.
Every random operation of an updateVariable action is now checked
before the first one is drawn, including the variable's scope, so an
invalid later roll no longer consumes a draw.

Weighted random outcomes again report an unsupported key before a
missing weight, as they did before the sampler was shared.

More tests: several rolls with one invalid, a roll and a failing
operation on a line, two rolls into one variable next to device and
account rolls, confirm dialog actions, form submit actions, scene
replay, and template syntax in a weighted value. The docs state the
template rules.
@han4wluc
han4wluc merged commit cec9056 into main Nov 18, 2026
50 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant