[Lib] PredictableRandom

Overview

Produces random numbers that stay repeatable across undo / turn reset by storing seeded randomizers on GAME.Randomizers. Useful when preview and execution must agree, or when you need to reroll on turn advance while keeping mid turn results stable.

See Treeherders forestUtils:floraformNumOfRandomSpaces for a simple usage example.

Any issues or concerns? Join the Redacted Rice Discord and @Das Keifer

Setup

1. (Optional) Set a global seed for cross-game consistency with seedGlobally
2. Pick a stable id per random stream (e.g. skill id + pawn id)
3. (Optional) Seed that instance with seed
4. Call getNextValue / roll / resetToLastRoll with that id

Event subscriptions (auto roll all on next turn) register via onModsInitialized. Set PredictableRandom.DebugLog = true to log rolls/resets/values.

 

API

• PredictableRandom
  • seedGlobally
  • seed
  • getNextValue
  • roll
  • resetToLastRoll

 

PredictableRandom

A library providing deterministic random streams keyed by string id, stored on GAME.Randomizers.

 

seedGlobally

Argument name	Type	Description
seed	number	(optional) Global seed. If omitted, uses os.time()

Sets the internal seed used when instance seeds are not provided. Called once at load with os.time() by default.

Example:

PredictableRandom:seedGlobally(12345)

 

seed

Argument name	Type	Description
id	string	Randomizer id
seed	number	(optional) Instance seed. If omitted, consumes/increments the global seed

Creates or resets the randomizer for id on GAME.Randomizers. When GAME is missing (e.g. squad-select tooltips), still returns a local randomizer table without persisting. Returns the randomizer table.

Example:

local randId = "Treeherders_Passive_WakeTheForest" .. tostring(Pawn:GetId())
PredictableRandom:seed(randId)
-- or with an explicit seed:
-- PredictableRandom:seed(randId, 42)

 

getNextValue

Argument name	Type	Description
id	string	Randomizer id
minVal	number	Inclusive minimum
maxVal	number	Inclusive maximum
randSalt	number	(optional) Extra salt for variation while staying deterministic (e.g. hashed target tile). If resetting and reusing the id, this allows variation while keeping randomness

Advances the stream and returns a bounded random value. Same id + count + salt always yields the same result until roll advances the saved seed.

Example:

local n = PredictableRandom:getNextValue(randId, 1, 3)
local salted = PredictableRandom:getNextValue(randId, 0, 1, BoardUtils.getSpaceHash(target))

 

roll

Argument name	Type	Description
id	string	Randomizer id

Advances the randomizer to a new saved seed/count (refresh the stream). All randomizers are also rolled automatically on onNextTurn.

Example:

PredictableRandom:roll(randId)

 

resetToLastRoll

Argument name	Type	Description
id	string	Randomizer id

Restores currSeed/currCount to the last rolled/initial saved values so subsequent getNextValue calls repeat the previous sequence (e.g. after undo).

Example:

PredictableRandom:resetToLastRoll(randId)