Variables

Variables let your lesson remember something while a learner is working.

That might be a score, a choice, a state like hint_used, or a piece of personalized text. Variables are what turn a one-way lesson into a responsive experience.

One kind of variable: lesson-wide

Every variable belongs to the whole lesson and stays available from the first scene to the last. There is no per-scene variable to choose between — one list, one behavior, nothing to get wrong.

Good things to track:

• Total score or points earned
• Whether a challenge was unlocked
• Which path the learner chose
• Whether a hint has already been used
• How many attempts a learner has made

Want something to start over partway through? Reset it yourself with a Set variable behavior — for example, a "Start this section" button that sets attempts back to 0. That gives you the reset exactly where you want it, instead of tying it to a scene boundary.

Variable types

Variables can store:

• text
• number
• yes or no

Choose the type that matches the job. This keeps conditions and actions easier to reason about.

Managing variables in the studio

Variables are managed from the variable manager in the studio — open the ⋯ menu in the top bar and choose Variables.

From there, you can:

• Create variables
• Give them clear names
• Add a description
• Choose the value type
• Set a default value
• Update or delete variables as the lesson evolves

Typical variables:

• score
• attempts
• path_choice
• passed_checkpoint
• hint_used

Renaming a variable

Select a variable in the variable manager and type a new name. Everything that uses the variable switches to the new name with it:

• behaviors that set it, add to it, toggle it or clear it
• conditions that check it — on behaviors, Show when… and Hide when… rules, spin wheel segments and router rules
• text that shows it, like {{ score }} or {{ variables.score }}

So renaming points to stars keeps a "+1 point" button counting, a hint that waits for 3 points still appearing, and a line like You have {{ stars }} stars still showing the count. Undo puts the old name back everywhere at once.

Two places keep the old name, because changing them would change the answers: a Text Highlighter's passage (the answers are marked by position in it) and a dropdown's choices (conditions compare against the choice students pick). If either uses the variable in {{ }}, update it by hand after renaming.

The new name has to be one no other variable has. While the box is empty, or holds another variable's name, the variable keeps the name it had, and nothing changes until you type a name it can take.

A few words can't be variable names at all, because text reads them as something else: true, false, nil, null, empty, blank, and, or, not, contains, forloop, tablerowloop and variables.

Deleting a variable

Click the trash icon next to a variable in the variable manager. If nothing in the lesson uses it, it's deleted straight away.

If the lesson still uses it, the variable manager asks first and lists every place that does: each widget (by name, with its scene) and each router with rules that check it. Choose Keep variable to go and change those places first, or Delete variable to delete it anyway. Deleting doesn't change those places: they keep the old name, which the lesson no longer has. Behaviors, conditions and router rules get the warning below; text that shows the variable, like {{ score }}, doesn't, so check it yourself. Undo brings the variable back.

If a behavior or condition still uses a name that isn't in your list (say, a variable you deleted), the validation issues badge in the top bar shows the warning Uses a Variable the Lesson Doesn't Have. Add the variable again, or pick one the lesson has. It's a warning only: it doesn't stop you publishing.

What variables are good for

Personalization

Variables can be used in text so a lesson feels more specific and responsive.

Examples:

• Show a learner name
• Display a selected topic
• Reuse a result message in multiple places

Progress tracking

Variables are a strong way to keep score without needing every widget to explain the state on its own.

Examples:

• Count correct answers
• Track attempts
• Unlock a reward after a threshold is reached

Controlling what appears

Variables work well with visibility rules.

Examples:

• Show a hint only if hint_used is false
• Reveal an explanation after submitted becomes true
• Display a success state once score reaches a target

Variable naming advice

Good variable names are short and functional.

Examples:

• score
• hint_used
• selected_topic
• attempts
• passed_scene_2

Bad variable names usually fail because they are vague or too tied to design language instead of behavior.

Using variables in interactions

Variables become powerful when an interaction changes them.

Common variable actions include:

• Set a variable
• Increment a variable
• Toggle a yes or no variable
• Clear a variable

Examples:

• A button sets hint_open to true
• An unsuccessful submission increments attempts
• A completion action sets passed_scene_2 to true
• A reset button clears a temporary variable so a section can be retried

Toggle Variable flips a yes-or-no variable: Yes becomes No, and No becomes Yes. One button can then switch something on and off. Step-by-step: Let students turn picture clues on and off uses a show_clues variable and one Picture clue button to show or hide a picture on every question.

Increment Variable counts down too: give it an amount of -1. A hearts variable that starts at 3 and loses 1 on every wrong answer turns a quiz into a game with three lives. When two behaviors run on the same moment, Berdee checks both conditions before either one runs, so a behavior that ends the game on the last heart checks hearts is at most 1 (the value before this answer took one away), not 0. Step-by-step: Make a quiz game with three hearts.

Using variables in conditions

Conditions let widgets and actions respond to variable state.

Examples:

• Show a hint only if attempts is greater than 0
• Reveal a success panel only if passed_scene_2 is true
• Navigate to a bonus scene only if score meets a threshold

This is usually the cleanest way to build progressive disclosure, branching, and retries. Step-by-step: Show a hint after two wrong tries counts wrong answers with Increment Variable and reveals a hint once the count reaches 2.

Using variables in text and templates

Variables can also appear directly in learner-facing text through Liquid templates.

Examples:

Nice work, you found {{ stars_found }} stars.

Current score: {{ variables.score }}

That means a variable can do three different jobs in the same lesson:

• Store state
• Control logic
• Display live information to the learner

A real classroom example

Suppose you are building a branching reading activity.

• When a learner chooses an animal topic, you store that choice in a variable.
• Later scenes use that variable to show a matching heading and example text.
• A lesson-level score variable tracks how many checks they answered correctly.
• A final scene shows different feedback depending on the final score.

That is a strong use of variables because they support clarity, continuity, and feedback.

When not to use variables

Do not add variables just because you can.

If a scene works perfectly well with clear text and a simple button, keep it simple. Variables are most valuable when they:

• Reduce repetition
• Support personalization
• Track meaningful state
• Or make feedback smarter

Recommended next reads

• Events, Actions, and Conditions
• Liquid Templates and Variables
• Visibility and Personalization
• Interaction Recipes
• Build Your First Lesson
• Scene Settings