Option sets

Description: Define fixed named values for variables, fields, and objective types.

Use an option set when a value must come from a fixed list. Quest objective types, character roles, and faction relationships are common uses. A fixed list prevents spelling differences from breaking conditions.

Narratyr calls these lists option sets in the editor and enumerations in the data model. Define an option set once in the Option Sets view, then select it as the type for a variable or entity field. It works like an enum in a programming language.

QuestObjectiveType
  Fetch
  GoToLocation
  Kill
  TalkTo
  Return
  Generic

New projects include the QuestObjectiveType option set. Add entries when your game needs other objective types. The objective editor includes the new entries.

Benefits

Validated values: the editor shows a list of entries instead of a text field. You can't select a value that the option set doesn't contain.
Consistent conditions: expressions such as ObjectiveKind == QuestObjectiveType.Kill refer to the same entry. Renaming an entry in the editor updates its references.
Stable keys: each entry has a key such as InProgress. Conditions and exported code use this key as the entry's identity.
Separate display text: an entry can also have a display name for players. Text directives show the display name, and localization can translate it without changing the key.

Entries

An option set has a name, an optional description, and entries. Each entry contains these values:

Key: an identifier that can contain letters, numbers, and underscore characters. It must start with a letter or underscore. Expressions use SetName.Key, such as QuestObjectiveType.Kill.
Value: the whole number used at runtime. Option set entries always use numeric values.
Display name: an optional player-facing label.

Automatic values

By default, Narratyr assigns 0 to the first entry, 1 to the second entry, and higher values in sequence. Arrange entries in the order you want.

Turn off automatic values when the numbers must match values in your game code or reserve specific ranges. You can then enter each value. The editor prevents duplicate values within the option set.

Uses for option sets

Variables can use an option set as their type. Lists and sets can also use an option set as their item type, such as a VisitedFactions set.
Entity fields can use an option set. A Character type might define a Role field with the CharacterRole option set.
Entity types can map to an entry. The objective editor uses this map to select the fields for an objective type.
Objective groups in quests use option set entries for group identity and translated display names.

Rename or reorder entries

The key identifies an entry, while the display name provides player-facing text. Change a display name when only the wording needs to change. Rename a key when you intend to update its references in expressions and exported code.

Reordering entries while automatic values are active changes their numeric values. Export the project again after a reorder so your game receives the updated values.

Variables explains state that uses option sets. Entity types covers option-set fields and type mappings. Expressions describes comparisons, and Text directives explains how to show an entry's display name.