BranchScene.h header

ew::core::foundation::VariableId ew::core::branching::BranchEffect::variableId

The variable it writes.

By id, never by name, for the same reason a Condition tests by id: renaming gold to coins must not silently break what writes to it. A null id is a defect the validator reports rather than something applied to nothing.

BranchEffectOperation ew::core::branching::BranchEffect::operation =

What it does to that variable.

VariableValue ew::core::branching::BranchEffect::value

The value for BranchEffectOperation::Set, or the amount for BranchEffectOperation::Add. Unused by every other operation.

ew::core::foundation::VariableId ew::core::branching::BranchEffect::sourceVariableId

The variable READ by BranchEffectOperation::SetFromVariable; null for every other operation.

A second id rather than a VariableValue alternative holding one: a value is what a variable currently contains, and "the contents of `currentTown`" is not a value – it is an instruction to go and look, which is exactly what distinguishes this operation from Set.

bool operator==(const BranchEffect &, const BranchEffect &)=default

Effects compare equal when all four fields match.

ew::core::foundation::BranchNodeId ew::core::branching::BranchLink::from

The node the reader leaves.

ew::core::foundation::BranchNodeId ew::core::branching::BranchLink::to

The node the reader arrives at.

BranchLinkGuard ew::core::branching::BranchLink::guard =

When this link is taken. Always except for the two leaving a Condition.

QString ew::core::branching::BranchLink::label

What the reader is offered, for a link leaving a Choice ("Go left"); empty otherwise.

This is why a canvas connection could not carry a branch: it stores two endpoints and nothing else, and a choice with no label is not a choice.

QString ew::core::branching::BranchLink::condition

Whether this way onward is offered at all, as an expression over the story's variables – hasKey, gold >= 50 AND NOT metRhys. Empty means always offered.

**Independent of guard, and they answer different questions.** The guard says which side of a Condition node this link leaves; the condition says whether the option exists for this reader at all. A link can have both: the false branch of a Condition, offered only when the reader is carrying the amulet.

It exists because the alternative was a Condition node per option. Three options with three requirements meant three extra nodes and six extra links, and a graph that tripled in size for a reason the author never chose. Written in the language ew::core::expression::evaluate reads, over the story's variables – the same language a node's conditionExpression uses.

UnavailableOption ew::core::branching::BranchLink::whenUnavailable =

What the reader sees when condition does not hold. Ignored when there is no condition.

QString ew::core::branching::BranchLink::requirementLabel

Why the option cannot be taken, shown with it when whenUnavailable is ShownDisabled – "Requires 10 Charisma".

The author's own words rather than the expression: charisma >= 10 is what the story tests and "Requires 10 Charisma" is what a reader is told, and showing the expression would leak a variable name into the fiction. Empty shows the option greyed with no explanation, which is a legitimate choice – some games say only that a door is locked.

ew::core::foundation::BranchNodeId ew::core::branching::BranchNode::id

Stable identity. Links reference this.

BranchNodeType ew::core::branching::BranchNode::type =

What the node does.

QString ew::core::branching::BranchNode::text

The prose shown to a reader (Line, Hub), or the author's label for the fork (Choice, Condition, Jump). Never empty in a finished scene, and the validator says so.

ew::core::foundation::ContentId ew::core::branching::BranchNode::speakerId

The codex entity saying this line; null when nobody in particular does (narration, or a node that is not spoken).

By id, never by name. An author renaming a character must not silently orphan every line they speak – the same rule Variable references follow, for the same reason. A speaker pointing at an entity that has been deleted is reported as a dangling reference rather than quietly becoming narration.

Localisation carries it as translator context (a line reads differently depending on who says it), voice extraction derives the cast list from it, and the graph shows it – three things that were each maintained by hand beside a script that already knew the answer.

ew::core::foundation::ContentId ew::core::branching::BranchNode::listenerId

The codex entity being spoken TO, when it matters; null otherwise.

Separate from the speaker because a translator, a director and a camera all need both, and because a line addressed to one of three people present is a different line.

QString ew::core::branching::BranchNode::speakerDisplayName

What the reader sees the speaker called here, when it differs from the entity's name – "the hooded figure" before a reveal, "Father" from one character and "the King" from another.

The entity is still the speaker: casting, the cast list and every reference keep working while the reader is told something else. Empty means the entity's own name.

QString ew::core::branching::BranchNode::delivery

How the line is delivered – "weary", "shouted", "under her breath".

Free text rather than a fixed set: no vocabulary of emotions survives contact with a real script, and a closed list would send authors back to writing it in the line itself. It reaches the voice line list, where a director reads it.

QString ew::core::branching::BranchNode::notes

The author's own note about this node; never shown to a reader.

Direction the line needs and the prose cannot carry – "VO: weary, he has said this before", "check this against the treaty date". It travels with the node, is searchable, and is not a comment: a comment is a conversation ABOUT the line and gets resolved, a note is part of writing it. Variable::description is the same idea on a variable, and the editor asks for both with the same words.

ew::core::foundation::VariableId ew::core::branching::BranchNode::variableId

For a Condition, the variable it tests; null otherwise.

By id, never by name – an author renaming gold to coins must not silently break the branch that tests it. K2 recorded the same rule for the same reason.

BranchComparison ew::core::branching::BranchNode::comparison =

For a Condition, how its variable is compared against comparand.

VariableValue ew::core::branching::BranchNode::comparand

For a Condition, the value its variable is compared against.

A whole value rather than a string, so gold >= 50 compares two NUMBERS rather than two spellings of a number – the same reason VariableValue is a closed set of three alternatives instead of text everyone re-parses.

QString ew::core::branching::BranchNode::conditionExpression

For a Condition, the expression it tests – gold >= 50 AND NOT hasKey – instead of the single variable/comparison/comparand above.

When this is non-empty it is what the condition means, and the three fields above are ignored. They are kept, not replaced: every scene ever saved holds them, a fork on one variable is still what most conditions are, and the editor writes whichever form the author chose. Written in the language ew::core::expression::evaluate reads, over the story's variables (see ew::app::expression::VariableBindings for how they are named).

ew::core::foundation::BranchNodeId ew::core::branching::BranchNode::jumpTarget

For a Jump, the node it sends the reader to; null otherwise.

ew::core::foundation::ContentId ew::core::branching::BranchNode::jumpSceneId

For a Jump that leaves this scene, the scene jumpTarget is in; null for a jump within the same scene.

Null means "here", and that is deliberate: every jump ever authored is a local one, and a field that had to be filled in to mean what it already meant would rewrite every scene file in every project on first save. It also keeps the common case – most jumps are local – free of ceremony.

The target node must be one the other scene declares in BranchScene::entryPointIds. Jumping into the middle of a scene nobody opened up is how a story acquires a path its author never sanctioned, and the validator says so.

std::vector<BranchEffect> ew::core::branching::BranchNode::effects

What passing this node does to the story's state, in order.

Applied when the reader ARRIVES, before this node's outgoing links are chosen – so a Condition that also carries an effect tests the state it arrived with, and the node after it sees the change. Ordered, so two effects on one variable compose the way they are written.

They live on the NODE rather than on a Choice's option link. An effect per option would save a node in some scenes; it would also be a second placement to validate, serialise, edit and explain, and the node behind an option already exists – it is where the consequence prose goes ("You hand over the coins").

double ew::core::branching::BranchNode::x = 0.0

Where the node sits on the canvas. Presentation only – the story does not depend on it, and a scene with every node at the origin still plays correctly (the editor can lay it out).

double ew::core::branching::BranchNode::y = 0.0

The node's y position.

ew::core::branching::BranchScene::BranchScene(ew::core::foundation::ContentId id, QString title)

Creates an empty scene with identity id and title.

const QString & ew::core::branching::BranchScene::title() const

The scene's title.

void ew::core::branching::BranchScene::setTitle(QString title)

Sets the title.

ew::core::foundation::BranchNodeId ew::core::branching::BranchScene::startNodeId() const

The node the reader starts at; null when the scene has no entry point yet.

void ew::core::branching::BranchScene::setStartNodeId(ew::core::foundation::BranchNodeId id)

Sets the starting node.

const std::vector< BranchNode > & ew::core::branching::BranchScene::nodes() const

The nodes, in insertion order.

void ew::core::branching::BranchScene::setNodes(std::vector< BranchNode > nodes)

Replaces every node.

const BranchNode * ew::core::branching::BranchScene::findNode(ew::core::foundation::BranchNodeId id) const

The node with id, or null when the scene has none.

const std::vector< BranchLink > & ew::core::branching::BranchScene::links() const

The links, in insertion order.

void ew::core::branching::BranchScene::setLinks(std::vector< BranchLink > links)

Replaces every link.

std::vector< BranchLink > ew::core::branching::BranchScene::linksFrom(ew::core::foundation::BranchNodeId id) const

The links leaving id, in order – a Choice's options, in the order the reader sees them.

const std::vector< ew::core::foundation::BranchNodeId > & ew::core::branching::BranchScene::entryPointIds() const

The nodes another scene's Jump may enter this one at, in declaration order.

The author's sanctioned ways in. A jump from another scene may land only here – not in the middle of a conversation, where a reader would arrive without the state the surrounding nodes assume. startNodeId is always an entry in effect and does not need declaring.

They are also what makes the Unreachable finding survive cross-scene jumps. Reachability is walked forwards from the start node; a node entered only from elsewhere has nothing leading to it inside its own scene, so without a declaration it would be reported as orphaned prose. Declaring it says "this is reached from outside" once, rather than every validator having to scan every scene in the project for a jump that might land here.

void ew::core::branching::BranchScene::setEntryPointIds(std::vector< ew::core::foundation::BranchNodeId > ids)

Replaces the declared entry points.

bool ew::core::branching::BranchScene::isEntryPoint(ew::core::foundation::BranchNodeId id) const

Whether id may be entered from another scene – the start node, or a declared entry point.