State API: History, Variables, Metadata, and the PRNG

State.active.title     // title of the present moment
State.active.variables // variables of the present moment

State.bottom.title     // title of the oldest moment in the full history
State.bottom.variables // variables of the oldest moment in the full history

State.current.title     // title of the current full-history moment
State.current.variables // variables of the current full-history moment

if (State.length === 0) {
  // No past moments — this is the very start
}

State.passage // e.g., "The Dark Forest"

if (State.size === 0) {
  // The full history is completely empty
}

State.temporary // e.g., { _count: 3, _label: "hero" }

State.top.title     // title of the most recent full-history moment
State.top.variables // variables of the most recent full-history moment

if (State.turns === 1) {
  // The starting passage is being displayed for the first time
}

State.variables          // the live story variables object
State.variables.health   // e.g., 100
State.variables.name = 'Eveline'; // write a variable

State.getVar("$charName") // returns the value of $charName
State.getVar("_count")    // returns the value of _count

State.has("The Ducky") // true if "The Ducky" is in the past history

State.hasPlayed("The Ducky") // true if "The Ducky" was ever played

State.index(0)                 // least recent past moment
State.index(1)                 // second least recent past moment
State.index(State.length - 1)  // most recent past moment

if (State.isEmpty()) {
  // the full in-play history is empty
}

State.peek()                  // most recent past moment
State.peek(0)                 // same as above
State.peek(1)                 // second most recent past moment
State.peek(State.length - 1)  // least recent past moment

State.random() // e.g., 0.7321948...

State.setVar("$charName", "Jane Doe") // assigns "Jane Doe" to $charName
State.setVar("_count", 0)             // assigns 0 to _count

if (State.metadata.size > 0) {
  // the store contains at least one entry
}

State.metadata.clear();

State.metadata.delete('achievements');

State.metadata.entries().forEach(([key, value]) => {
  // process each pair
});

var achievements = State.metadata.get('achievements');

if (State.metadata.has('achievements')) {
  // the key exists
}

State.metadata.keys().forEach((key) => {
  // process each key
});

State.metadata.set('achievements', { ateYellowSnow: true });
State.metadata.set('ngplus', true);

State.prng.init()                        // auto-seed (recommended)
State.prng.init("aVeryLongSeed")         // explicit seed (not recommended)
State.prng.init("aVeryLongSeed", true)   // explicit seed + entropy padding

State.prng.isEnabled() // true after State.prng.init() has been called

State.prng.pull // e.g., 42 (or NaN if PRNG not initialized)

State.prng.seed // e.g., "aVeryLongSeed" (or null)