BGE/Story
Alias: BGE.Story
Static Methods
evaluateConditions(
conditions: Array.<StoryCondition>,
state: StoryState,
): boolean
True when every condition passes. An empty or missing list passes.
Parameters
conditions(Array.<StoryCondition>) — or invalidstate(StoryState)
Returns
boolean
conditionPasses(
condition: StoryCondition,
state: StoryState,
): boolean
Never compares a stored flag with = directly - a missing one is invalid, and invalid = 2 can crash.
Parameters
condition(StoryCondition)state(StoryState)
Returns
boolean
flagEquals(
flags: StoryFlags,
key: string,
expected: boolean | integer | string,
): boolean
Parameters
flags(StoryFlags)key(string)expected(boolean | integer | string)
Returns
boolean
isBuiltInConditionKey(key: string): boolean
The keys that name a built-in condition (modifiers like eq and gte don't count).
Parameters
key(string)
Returns
boolean
newStoryResult(): StoryResult
Returns
StoryResult— an empty result
mergeStoryResult(into: StoryResult, source: StoryResult): void
Adds source's changes, posts and messages to into.
Parameters
into(StoryResult)source(StoryResult)
Returns
void
applyEffects(
effects: Array.<StoryEffect>,
state: StoryState,
): StoryResult
Applies effects in order.
Parameters
effects(Array.<StoryEffect>) — or invalidstate(StoryState)
Returns
applyEffect(
effect: StoryEffect,
state: StoryState,
result: StoryResult,
): boolean
Parameters
effect(StoryEffect)state(StoryState)result(StoryResult)
Returns
boolean— true if story state changed
isBuiltInEffectKey(key: string): boolean
The keys that name a built-in effect (modifiers like value and amount don't count).
Parameters
key(string)
Returns
boolean
runEventRules(
rules: Array.<EventRule>,
eventName: string,
data: roAssociativeArray,
state: StoryState,
): StoryResult
Runs every rule for this event whose match and when pass, in order.
Parameters
rules(Array.<EventRule>)eventName(string)data(roAssociativeArray) — the event's datastate(StoryState)
Returns
ruleMatches(
match: roAssociativeArray,
data: roAssociativeArray,
): boolean
Parameters
match(roAssociativeArray)data(roAssociativeArray)
Returns
boolean— true if every key of match equals the same field of data (match values must be scalars)
settleRules(
rules: Array.<EventRule>,
state: StoryState,
): StoryResult
Runs "storyChanged" rules until nothing more changes, at most STORY_SETTLE_MAX_PASSES times.
Parameters
rules(Array.<EventRule>)state(StoryState)
Returns
StoryResult— across every pass
getCandidates(entry: dynamic): dynamic
Parameters
entry(dynamic) — a story.nodes value
Returns
dynamic— its candidate list, or invalid for a single node
getSelectMode(entry: dynamic): string
Parameters
entry(dynamic)
Returns
string— "first" (the default), "random", whatever string was written, or "" for a non-string
isEligibleNode(
node: dynamic,
key: string,
state: StoryState,
): boolean
Parameters
node(dynamic)key(string)state(StoryState)
Returns
boolean
selectNode(
id: string,
story: StoryData,
state: StoryState,
random: function,
): SelectedNode
Picks the node to play for an id: the node itself, or one of its candidates.
Parameters
id(string)story(StoryData)state(StoryState)random(function)
Returns
SelectedNode— or invalid if nothing passes
resolveNodeKey(key: string, story: StoryData): StoryNode
Parameters
key(string)story(StoryData)
Returns
StoryNode— the node a visit key names, or invalid
defaultRandom(count: integer): integer
Parameters
count(integer)
Returns
integer— a random index from 0 to count - 1
newFrame(key: string, node: StoryNode): RunnerFrame
Parameters
key(string)node(StoryNode)
Returns
lineCount(node: StoryNode): integer
Parameters
node(StoryNode)
Returns
integer
isLabelled(choice: StoryChoice): boolean
Parameters
choice(StoryChoice)
Returns
boolean
choiceKey(
nodeKey: string,
choice: StoryChoice,
index: integer,
): string
The visit key for a choice, used by once.
Parameters
nodeKey(string)choice(StoryChoice)index(integer)
Returns
string
loadStory(path: string): StoryData
Reads a story from a JSON file. Node and item ids are case-insensitive. Check it with validateStory() once your game's own conditions and effects are registered.
Parameters
path(string) — e.g. "pkg:/story/jokes.json"
Returns
StoryData— the story, or invalid (with a warning) if it can't be read or has no nodes
validateStory(story: dynamic, state: StoryState): Array.<string>
Checks a story for mistakes: jumps to nodes that don't exist, conditions and effects nothing handles (or with two keys, of which only one would run), items the story doesn't declare, mistyped fields, empty or malformed nodes. Run it in a test over your real story data.
Parameters
story(dynamic)state(StoryState) — with your game's conditions and effects registered
Returns
Array.<string>— one message per problem; empty when the story is fine
validateStoryNode(
where: string,
node: dynamic,
story: StoryData,
state: StoryState,
errors: Array.<string>,
): void
Parameters
where(string)node(dynamic)story(StoryData)state(StoryState)errors(Array.<string>)
Returns
void
validateStoryChoiceFields(
where: string,
choice: roAssociativeArray,
errors: Array.<string>,
): void
Parameters
where(string)choice(roAssociativeArray)errors(Array.<string>)
Returns
void
validateStoryBooleanField(
where: string,
item: roAssociativeArray,
key: string,
errors: Array.<string>,
): void
Reports item[key] if it's present but not true or false.
Parameters
where(string)item(roAssociativeArray)key(string)errors(Array.<string>)
Returns
void
validateStoryTarget(
where: string,
target: dynamic,
story: StoryData,
errors: Array.<string>,
): void
Parameters
where(string)target(dynamic)story(StoryData)errors(Array.<string>)
Returns
void
validateStoryConditions(
where: string,
conditions: dynamic,
story: StoryData,
state: StoryState,
errors: Array.<string>,
): void
Parameters
where(string)conditions(dynamic)story(StoryData)state(StoryState)errors(Array.<string>)
Returns
void
validateStoryEffects(
where: string,
effects: dynamic,
story: StoryData,
state: StoryState,
errors: Array.<string>,
): void
Parameters
where(string)effects(dynamic)story(StoryData)state(StoryState)errors(Array.<string>)
Returns
void
validateBuiltInCondition(
where: string,
condition: roAssociativeArray,
story: StoryData,
errors: Array.<string>,
): void
Built-in conditions read these fields directly, so a mistyped one fails (or crashes) at runtime.
Parameters
where(string)condition(roAssociativeArray)story(StoryData)errors(Array.<string>)
Returns
void
validateBuiltInEffect(
where: string,
effect: roAssociativeArray,
story: StoryData,
errors: Array.<string>,
): void
Parameters
where(string)effect(roAssociativeArray)story(StoryData)errors(Array.<string>)
Returns
void
validateStoryItemId(
where: string,
item: roAssociativeArray,
key: string,
story: StoryData,
errors: Array.<string>,
): void
Reports item[key] if it's a string naming an item the story's items don't declare. (A non-string id is reported by validateStoryFieldKind, and malformed items by validateStory.)
Parameters
where(string)item(roAssociativeArray)key(string)story(StoryData)errors(Array.<string>)
Returns
void
validateStoryFieldKind(
where: string,
what: string,
item: roAssociativeArray,
key: string,
kinds: Array.<string>,
kindText: string,
errors: Array.<string>,
): void
Reports item[key] if it's present but not one of the kinds.
Parameters
where(string)what(string)item(roAssociativeArray)key(string)kinds(Array.<string>)kindText(string)errors(Array.<string>)
Returns
void
validateStoryRuleMatch(
where: string,
match: dynamic,
errors: Array.<string>,
): void
Parameters
where(string)match(dynamic)errors(Array.<string>)
Returns
void
interpolateFlags(text: string, flags: StoryFlags): string
Replaces each ${key} in text with that flag's value. A missing flag reads as "", a boolean as true/false, and a ${ with no closing } is left as written.
Parameters
text(string)flags(StoryFlags)
Returns
string
valueKind(value: dynamic): string
The kind of a story value, the same on a real Roku and the simulator (which name boxed types differently, e.g. roInt vs roInteger).
Parameters
value(dynamic)
Returns
string— "integer", "float", "boolean", "string", "invalid", or the lowercased type name
isScalar(value: dynamic): boolean
True for a value that can be compared with = and <>: an integer, float, boolean, string or invalid.
Parameters
value(dynamic)
Returns
boolean
isTrue(value: dynamic): boolean
True only for a boolean true - safe on a missing (invalid) or non-boolean value.
Parameters
value(dynamic)
Returns
boolean
Other
RUNNER_MAX_STEPS
Stops a story whose nodes keep jumping without ever showing a line or a choice.
Default: 200
DialogueRunner
Plays a story's nodes - lines, then choices or jumps - for your dialogue UI to show. It draws nothing: ask it for currentLine() or choices(), and tell it advance() or choose(index). Each of start/advance/choose returns a StoryResult: settle the story (StoryState.settle()), save and act on its posts and messages as your game needs.
Parameters
state(StoryState)story(StoryData) — the same story the state was built from
Properties
backlog(Array.<StoryLineView>) — Lines shown so far, oldest first, with each choice taken (isChoice true).backlogLimit(integer) — The most entries kept in the backlog.random(function) — Picks the index (0 to count - 1) of a random candidate. Replace it for repeatable tests.
Returns
BGE.Story.DialogueRunner
STORY_SETTLE_MAX_PASSES
Default: 4
Inventory
What the player is carrying: item id -> count, capped by each item's definition.
Parameters
definitions(roAssociativeArray) — item id -> ItemDefinition (at least a max)
Returns
BGE.Story.Inventory
StoryFlags
The story's blackboard: named values (booleans, integers, floats, strings) that story data reads with conditions and changes with effects - quest stages, who you've talked to, what you chose.
Returns
BGE.Story.StoryFlags
StoryState
A story's state - flags, the inventory and how often each node was visited - and the conditions and effects its data can use. Built-in vocabulary is in the Story guide; add your game's own with registerCondition() and registerEffect().
Parameters
story(StoryData, optional, default: "invalid") — its items and rules are used; may be invalid
Properties
flags(StoryFlags)inventory(Inventory)items(roAssociativeArray) — item id -> ItemDefinition, from the story's itemsrules(Array.<EventRule>)
Returns
BGE.Story.StoryState
StoryCondition
Extends: roAssociativeArray
One entry in a when list. Identified by its first known key: flag (optionally with eq, gte or lt), notFlag, hasItem, notItem, visited (optionally with gte), notVisited, any - or a key your game registered with StoryState.registerCondition().
Properties
flag(string)eq(boolean | integer | string)gte(integer)lt(integer)notFlag(string)hasItem(string)notItem(string)visited(string)notVisited(string)any(Array.<StoryCondition>)
StoryEffect
Extends: roAssociativeArray
One entry in an effects list: set (with value), add (with amount), giveItem, takeItem, post, message (with an optional speaker) - or a key your game registered with registerEffect().
Properties
set(string)value(boolean | integer | float | string)add(string)amount(integer)giveItem(string)takeItem(string)post(string)message(string)speaker(string)
ItemDefinition
Extends: roAssociativeArray
An item the inventory can hold. Add any fields your game needs (name, icon) alongside these.
Properties
max(integer) — how many can be carriedonAcquire(Array.<StoryEffect>) — effects run each time one is gained
EventRule
Extends: roAssociativeArray
A story change that happens on a game event. Every rule whose event, match and when pass runs.
Properties
event(string)match(roAssociativeArray) — each key must equal the same field of the event's datawhen(Array.<StoryCondition>)effects(Array.<StoryEffect>)
StoryLine
Extends: roAssociativeArray
A line written as an object. Any other keys (a portrait, a background) are left for your game.
Properties
text(string)speaker(string)
StoryChoice
Extends: roAssociativeArray
A button at the end of a node. A choice with no label is a fallback, taken automatically when no labelled choice is available. It may also have "goto" or "call" (read with brackets - they're reserved words) and any keys your game reads itself.
Properties
label(string)id(string) — names the choice foronce(defaults to its label)when(Array.<StoryCondition>)once(boolean)showDisabled(boolean) — listed but not selectable whenwhenfails, instead of hiddeneffects(Array.<StoryEffect>)
StoryNode
Extends: roAssociativeArray
One node: lines to show, then effects, then choices, "call", "goto" or "end" (bracket keys).
Properties
when(Array.<StoryCondition>)once(boolean)speaker(string) — the speaker of lines that don't name their ownlines(Array.<dynamic>) — each a string or a StoryLineeffects(Array.<StoryEffect>)choices(Array.<StoryChoice>)
StoryData
Extends: roAssociativeArray
A whole story. Each node id maps to a StoryNode, a list of candidate StoryNodes (the first whose when passes is used), or {select: "first" | "random", candidates: StoryNode[]}.
Properties
nodes(roAssociativeArray)rules(Array.<EventRule>)items(roAssociativeArray) — item id -> ItemDefinition
StoryMessage
A message effect: text to show, and who says it ("" for nobody).
Properties
text(string)speaker(string)
StoryResult
What a batch of effects or rules did.
Properties
changed(boolean) — true if any story state changed (save, and settle the rules)posts(Array.<string>) — event names from post effects, in ordermessages(Array.<StoryMessage>)
StorySaveData
Extends: roAssociativeArray
StoryState.toSaveData(): plain values, safe to write with BGE.registryWrite().
Properties
flags(roAssociativeArray)inventory(roAssociativeArray)visits(roAssociativeArray)
StoryLineView
A line as DialogueRunner shows it.
Properties
text(string) — with ${flags} filled inspeaker(string)line(roAssociativeArray) — the line as written ({text} for a plain string), for your game's own keysisChoice(boolean) — true for a choice the player took (in the backlog)
ChoiceView
A choice as DialogueRunner lists it.
Properties
label(string) — with ${flags} filled inenabled(boolean) — false for a showDisabled choice whosewhenfailschoice(StoryChoice) — the choice as written, for your game's own keysindex(integer) — its index in the node's choices
StoryHandler
A registered condition or effect.
Properties
fn(function)context(dynamic)
RunnerFrame
One node in the runner's stack (internal).
Properties
key(string) — the node's visit key: an id, or "#" for a candidate ("" for startNode())node(StoryNode)line(integer)shownLine(integer) — the last line added to the backlogphase(string) — lines, choices, choosing, choiceCall, call, afterCall, runOut
RunnerFrameData
A saved RunnerFrame.
Properties
key(string)line(integer)phase(string)
RunnerPosition
Extends: roAssociativeArray
DialogueRunner.getPosition(): plain values, safe to save.
Properties
stack(Array.<RunnerFrameData>)
SelectedNode
A node picked by selectNode().
Properties
key(string)node(StoryNode)