Ordfoss

Variable.h header

#include <ew/core/Variable.h>

Namespace ew::core

Variable class

class ew::core::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.

VariableValue class

class ew::core::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.