Choices, Conditions & Variables

The core logic for branching narratives is managed through a combination of choices, variables, and conditions. This documentation outlines how these systems function, both from the user's perspective in the editor and how they are structured in the underlying story.json file.

High-Level Overview

The system is designed around three interconnected concepts:

• Variables: These are the story's memory. They are simple boolean (true/false) flags that can be created by the author (e.g., has_key, is_angry). They track the player's progress, decisions, or inventory.
• Choices: These are the interactive elements presented to the player within a scene. A choice typically appears as a button. When clicked, it performs an action, such as navigating to another scene or changing the state of a variable.
• Conditions: These are rules that determine if a choice is visible to the player. A choice with a condition will only appear if the specified rule is met. This allows authors to create dynamic paths that react to the player's previous actions.

---

Variables

Variables are global, boolean flags that can be toggled between true and false.

Through the Interface

1. Creation and Management:

   • Variables are managed through the "Manage Variables" modal, opened by clicking the variable icon ({...}) to the left of the "Add Choice" button.
   • Inside this modal, you can create a new variable by typing its name (spaces and special characters are not allowed) and clicking "Add".
   • All existing variables are displayed in a list, where they can also be removed by clicking the '✕' icon next to their name.

2. Usage:

   • Variables are used in two places: as the action of a choice (to set its value) and as the condition for a choice (to check its value).

In the JSON File

All defined variables are stored in an array of strings within the meta object.

Example story.json snippet:

{
  "meta": {
    "title": "My Story",
    "startSceneId": "start",
    "variables": [
      "has_talked_to_guard",
      "knows_secret_password"
    ],
    "styles": { ... }
  },
  "scenes": { ... }
}

---

Choices

Choices are the primary mechanism for player interaction and story progression. A choice is defined by an action it performs, which can be conditional.

Through the Interface

1. Creation: A new choice is added to the currently edited scene by clicking the circular "+" button below the choices list.

2. Configuration (The Action):

   • Button Text: The text that appears on the choice button for the player to read. This is entered in the first text input field.
   • Destination/Action: The dropdown menu next to the text field determines what the choice does. It contains two groups of options:
     • Scenes (Go To): Selecting a scene ID (e.g., castle_gate) makes the choice a simple navigation link. When the player clicks the button, they will be taken to that scene. A "Go to scene" button (▶) appears, allowing the author to quickly jump to the linked scene in the editor.
     • Variables: Selecting a variable (e.g., has_key) changes the choice's function. Instead of navigating, it sets the state of that variable. A second dropdown appears to select whether the variable should be set to True or False.
   • Silent Actions: If the "Button Text" field is left empty, the choice becomes a "silent action." If its conditions are met, its action (navigating or setting a variable) will execute instantly when the scene loads, without displaying a button to the player. This is useful for setting variables automatically upon entering a scene.

In the JSON File

Choices are stored as an array of objects within each scene object. Each choice object has a condition and an action.

Example story.json snippet:

"forest_path": {
  "id": "forest_path",
  "text": "The path splits in two.",
  "choices": [
    {
      "condition": null,
      "action": {
        "text": "Go left towards the river.",
        "target": "river_bank",        // Navigates to the "river_bank" scene
        "set_variable": null,
        "set_value": false
      }
    },
    {
      "condition": null,
      "action": {
        "text": "Pick up the shiny rock.",
        "target": null,
        "set_variable": "has_shiny_rock", // Sets the "has_shiny_rock" variable
        "set_value": true                // to true
      }
    },
    {
      "condition": null,
      "action": {
        "text": "",                        // No text makes this a silent action
        "target": "game_over_ambush",
        "set_variable": null,
        "set_value": false
      }
    }
  ],
  ...
}

• action.text: The string for the button's label.
• action.target: The ID of the scene to navigate to. It is null if the action sets a variable.
• action.set_variable: The name of the variable to change. It is null if the action is navigational.
• action.set_value: The boolean value (true or false) to assign to the variable.

---

Conditions

Conditions act as a gate, hiding or showing choices based on the story's state.

Through the Interface

1. Adding a Condition: To add a condition to a choice, click the fork icon (<--) on the left of the choice editor. This toggles the conditional UI.

2. Configuration: The conditional UI adds a new set of dropdowns:

   • If Dropdown: This selects what to check. It contains two types of options:
     • Variables: (e.g., has_key) checks the current state of a story variable.
     • Scenes (Visited?): (e.g., throne_room) checks if the player has previously visited the specified scene.
   • Is Dropdown: This determines the required state. It has two options: True or False.

   Example: To make a choice appear only if the player has the key, you would set the condition to If [has_key] Is [True]. To make a choice appear only if the player has not visited the dungeon, you would set If [dungeon] Is [False].

In the JSON File

When a condition is added, the condition property of the choice object is populated. If there is no condition, this property is null.

Example story.json snippet:

"locked_door": {
  "id": "locked_door",
  "text": "A large, locked door bars your way.",
  "choices": [
    {
      "condition": {
        "variable": "var_has_key",  // The variable to check, prefixed with "var_"
        "value": true               // The required value
      },
      "action": {
        "text": "Use the key to unlock the door.",
        "target": "treasure_room",
        ...
      }
    },
    {
      "condition": {
        "variable": "visited_scene_library", // Checks a scene visit, prefixed with "visited_scene_"
        "value": true
      },
      "action": {
        "text": "Recall a hint from the library to pick the lock.",
        "target": "unlocked_passage",
        ...
      }
    },
    {
      "condition": null, // This choice has no condition and will always appear
      "action": {
        "text": "Turn back.",
        "target": "hallway",
        ...
      }
    }
  ]
}

• condition.variable: The item to check. The JSON format uses prefixes to distinguish between types:
  • var_: Prefixes a story variable name.
  • visited_scene_: Prefixes a scene ID to check if it has been visited.
• condition.value: The required boolean state (true or false) for the condition to be met.