Ordfoss

Variable.h header

#include <ew/core/branching/Variable.h>

Namespace ew::core::branching

Variable class

class ew::core::branching::Variable

A named piece of story state that branching conditions can test and branching effects can set.

Holds the DECLARATION – what the variable is called, what it holds, how long it lives, and what it starts as. What it currently holds during a playthrough is the simulator's business (K3), not the project's: a project that stored live values would make "open the file" and "play the story" the same act, and the writer could no longer tell what a reader would actually see.

Members

ew::core::branching::Variable::Variable(ew::core::foundation::VariableId id, QString name, VariableValue initialValue, VariableScope scope)

Creates a variable with id, called name, holding initialValue.

ew::core::foundation::VariableId ew::core::branching::Variable::id() const

Its stable identity. Conditions reference this, never the name.

const QString & ew::core::branching::Variable::name() const

What the author calls it. Display text: renaming it must not break anything.

void ew::core::branching::Variable::setName(QString name)

Renames it.

VariableType ew::core::branching::Variable::type() const

What it holds, and therefore what a condition may compare it against.

const VariableValue & ew::core::branching::Variable::initialValue() const

The value it starts at – at the beginning of the story for a Global, at the beginning of each scene for a Scene.

void ew::core::branching::Variable::setInitialValue(VariableValue value)

Sets the initial value.

VariableScope ew::core::branching::Variable::scope() const

How long its value survives. See VariableScope.

void ew::core::branching::Variable::setScope(VariableScope scope)

Sets the scope.

const QString & ew::core::branching::Variable::description() const

A note to the author about what this is for; never shown to a reader.

void ew::core::branching::Variable::setDescription(QString description)

Sets the description.

bool ew::core::branching::Variable::isExternal() const

Whether the HOST supplies this variable at runtime rather than the story declaring its value.

Real dialogue conditions test things the game owns – inventory, player class, faction standing, level, world flags. Without this an author has to declare a local variable that shadows the game's, keep the two in step by hand, and discover the drift in playtesting.

Orthogonal to scope, which is about how long a value LIVES. An external is supplied for the whole run; what makes it external is WHO OWNS IT. The story may read it in any condition and must never write it – an effect that does is reported, because the write would be silently discarded by any host that is the real authority on the value.

void ew::core::branching::Variable::setExternal(bool external)

Sets whether the host supplies it.

const QString & ew::core::branching::Variable::bindingKey() const

The key the host supplies it under – "player.level", "faction.thieves_guild".

The CONTRACT, and the reason an external variable is worth declaring rather than left as an unbound name: the export lists it, the engine implements it, and both sides can point at the same string. Empty on a local variable, and on an external one whose author has not written it yet – which the validator reports, since a contract with no key is one no host can satisfy.

void ew::core::branching::Variable::setBindingKey(QString bindingKey)

Sets the key the host supplies it under.

VariableValue class

class ew::core::branching::VariableValue

One story variable's value, of whichever type the variable holds.

A closed set of three alternatives rather than a string that every reader parses: a value that has to be re-parsed at each use is a value that can be parsed differently at each use, and the disagreement shows up as a condition that quietly never fires.

Members

ew::core::branching::VariableValue::VariableValue()

A value holding false – what a variable defaults to before anyone sets one.

VariableType ew::core::branching::VariableValue::type() const

Which of the three this holds.

bool ew::core::branching::VariableValue::asFlag() const

The flag, or false when this holds something else.

std::int64_t ew::core::branching::VariableValue::asNumber() const

The number, or 0 when this holds something else.

QString ew::core::branching::VariableValue::asText() const

The text, or empty when this holds something else.

bool ew::core::branching::VariableValue::operator==(const VariableValue &other) const =default

Whether two values hold the same type and the same contents.

static VariableValue ew::core::branching::VariableValue::flag(bool value)

A flag value.

static VariableValue ew::core::branching::VariableValue::number(std::int64_t value)

A number value.

static VariableValue ew::core::branching::VariableValue::text(QString value)

A text value.

Enumerations

enum class VariableScope { Global, Scene }

How long a variable's value survives.

This is a LIFETIME, not a namespace. It is the distinction a simulation needs: when a scene begins, Scene variables start again from their initial value while Global ones carry whatever the story has done to them. Nothing here scopes visibility – every variable is visible to every condition, because an author writing "if the gate is open" should not have to think about which file the fact was declared in.

enum class VariableType { Flag, Number, Text }

What kind of value a story variable holds.

Functions

QString ew::core::branching::toToken(VariableType type)

Returns the stable serialization token for type ("flag", "number", "text").

QString ew::core::branching::toToken(VariableScope scope)

Returns the stable serialization token for scope ("global", "scene").

std::optional< VariableScope > ew::core::branching::variableScopeFromToken(QStringView token)

Parses a variable scope from its serialization token; std::nullopt if unrecognized or absent.

std::optional< VariableType > ew::core::branching::variableTypeFromToken(QStringView token)

Parses a variable type from its serialization token; std::nullopt if unrecognized or absent.