Option sets

A quest objective is one of a few kinds — fetch an item, kill someone, talk to someone. A faction has a relationship to the player. A character has a role. Each of these is a value that can only ever be one of a small, known set of things — and writing it as free text is one typo away from a condition that silently never matches.

An option set (called an enumeration in the data model — same thing) is that fixed list, defined once in the Option Sets view and then used to type any variable or entity field that should be restricted to it. It is the editor's equivalent of a programming-language enum: a name, and a list of named entries.

QuestObjectiveType
  Fetch
  GoToLocation
  Kill
  TalkTo
  Return
  Generic

That's the QuestObjectiveType option set that ships in the default document, and it's there for you to customise: add an entry when your game needs a new kind of objective, and the objective editor picks it up.

Why use one

• The editor can help you. A variable or field typed to an option set gets a dropdown of its entries instead of a text box. You can't pick a value that doesn't exist, and you can't typo one.
• Conditions stay in agreement. Every condition that checks ObjectiveKind == QuestObjectiveType.Kill references the same entry. Change what an entry means — or rename it — and every place that reads it updates with it, instead of half the project quietly comparing against the old spelling.
• Entries are stable handles. Each entry has a key, an identifier-shaped name (InProgress, not "In Progress") that conditions and exported code reference. Keys are the stable identity of an entry; the display name is the decoration.
• Player-facing wording is separate. Each entry can carry a display name — the wording shown to the player. The key is what your conditions branch on; the display name is what a plain @{MyColor} text directive shows, and it can be included in the string translation system, so localisers can reword it without touching your graph.

Entries

An option set has a name, an optional description, and a list of entries. Each entry has:

• Key — the identifier name: letters, digits and underscores, no leading digit. This is what expressions reference, as SetName.Key — for example QuestObjectiveType.Kill.
• Value — the whole number the entry evaluates to at runtime. Every option set is number-backed; there are no text-valued entries.
• Display name — optional. The human-readable label used when the value is shown to a player.

Values: auto-computed or manual

By default an option set auto-computes entry values: the first entry is 0, the second 1, and so on. You don't see the numbers, and you don't need to think about them — just keep entries in the order you like.

Switching off auto-compute lets you set each entry's value by hand. That's for when the numbers have meaning outside Narratyr — mirroring an enum that already exists in your game code, or reserving specific values. The editor will not let two entries share a value.

Where option sets are used

• Variables can be typed to an option set, so the whole game's state holds one of its entries. Lists and sets of an option set work too — a VisitedFactions set, for instance.
• Entity fields can be typed the same way, so every entity of a type holds one of the entries — a Role field on Character typed to a CharacterRole set.
• Entity types can be associated with a specific entry of a set. That's how the editor knows that the KillObjective type represents the Kill entry of a QuestObjectiveType set — picking "Kill" in the objective UI then shows you the fields of the associated type.
• Objective groups on quests use an option set to bucket objectives under a translatable heading — the group's player-facing name comes from the entry's display name.

Renaming and reordering

The key is the stable handle, the display name is decoration — so renaming an option set or an entry's key is a deliberate act, while changing a display name touches nothing but player-facing wording. Reordering entries in auto-compute mode changes their numeric values, which is fine while you're authoring but something to remember if you've already exported: the numbers are part of what ships to your game.

Related

Variables is where option-set-typed state usually lives, and Entity types covers the fields and type associations above. Expressions covers the full syntax for comparing and setting these values, and Text directives covers showing an entry's display name in player-facing text. rs the full syntax for comparing and setting these values, and Text directives covers showing an entry's display name in player-facing text. player-facing text. covers showing an entry's display name in player-facing text. rs the full syntax for comparing and setting these values, and Text directives covers showing an entry's display name in player-facing text.