# Storyline variables a simulation or coach writes

> A simulation or coach writes completion, results and your own custom variables into the Articulate Storyline course that hosts it.

- Plans: All plans
- Canonical: https://docs.devlin.ai/publish-and-embed/storyline-variables

A simulation or coach can write values into the course that hosts it while the learner works: custom variables you define, plus built-in variables for completion, turns, time and results. In Articulate Storyline those values land in course variables with the same names, so your triggers can react to what happens in the conversation. Variables are available on every plan.

## Two kinds of variable

- Custom variables are the ones you define. Each has a name, a type, a description of when it should change, and the values it can take. The character decides during the conversation when the moment has come and writes the value.
- System variables are written automatically by the simulation or coach itself, for example when the session starts or ends. You do not describe when they change. You can rename most of them.

## Where you define variables

- For a simulation, open the simulation and, in the **Design** stage, choose the **Variables** section. The **Simulation Variables** card holds **Custom Variables** and **System Variables and Settings**. Save your changes for them to take effect.
- For a coach, open the coach and, in the **Design** stage, choose the **Variables** section. The **Session Variables** card holds **Custom Variables**, **Character mood**, **System Variables and Settings** and a **Storyline variable reference** table. Select **Save Changes** on the card. A coach starts writing its custom variables and its mood variable once you have saved this card.

## Custom variables

Select **+ Add Variable**, then fill in the card:

- **Name**: The name of the Storyline variable to write. Use only letters, digits and underscores. A name with a space, a hyphen or any other character is not recognized when the character tries to write it, so that variable is never written. In a simulation, the editor shows a warning under such a name, and under a name that matches a system variable or another custom variable. The warning does not block saving. A coach's editor does not check custom variable names, so check them yourself.
- **Type**: **True/False**, **Number** or **Text**. A new variable starts as **Text**.
- **Allowed change**: Shown for a **True/False** variable only. **Can change in both directions** is the default. **One-way: can only change to true** and **One-way: can only change to false** stop the variable from flipping back for the rest of the session. This is enforced: a write in the blocked direction is discarded even if the character attempts it.
- **When should this variable change?**: a plain-language description of the moment. There is no keyword matching: the character judges from the conversation whether the moment has happened.
- **Values**: Select **+ Add value** for each value the variable can take. With one value, the character writes that value when the moment happens. With several, the character picks whichever fits best. With none, the character writes `true`.

Select **Remove** on a card to delete the variable. A variable with a blank name is dropped when you save, and so is any blank entry in a variable's Values list. The editor does not cap how many custom variables you add.

The values you list are instructions to the character. For a custom variable, devlin.ai does not check what the character writes against the list.

## Character mood

Every simulation and coach has a mood variable, a **Text** variable that holds the character's current emotional state. Its values are fixed to the portrait moods (neutral, happy, sad, angry, afraid, surprised, disgusted), and a value outside that set is never sent. In the **Character mood** block you can:

- Rename it under **Mood variable name**. This name must use letters, digits and underscores and start with a letter or underscore, and it cannot match another variable in the same simulation or coach. A save with a clashing name is rejected.
- Choose the **Starting mood**.
- Describe the turning points under **When should the mood change?**
- Turn individual moods off under **Values**. The character is never offered a mood you turn off, and the starting mood always stays on.

The default name is `Sim_CharMood` for a simulation and `Coach_CharMood` for a coach. The mood variable also drives the character portrait's expression. See [Appearance and branding](https://docs.devlin.ai/simulations/appearance-and-branding).

## System variables a simulation writes

Each row is a field under **System Variables and Settings**. The field holds the variable's name, which you can change.

| Field | Default name | Type | When it is written |
|---|---|---|---|
| **Completion variable name** | `Sim_Complete` | True/False | Set to `true` when the simulation ends, before any evaluation result arrives. |
| **Session start variable name** | `Sim_SessionStart` | True/False | Set to `false` when the simulation loads, and to `true` when the learner sends the first message (text) or the voice session connects. |
| **Turn counter variable name** | `Sim_Turn` | Number | Updated with the current turn at the start of each exchange. It matches the count the turn limit uses. |
| **Session timer variable name** | `Sim_Timer` | Number | Updated once per second with the elapsed seconds, starting at the learner's first message (text) or when the voice session starts. |
| **Speaking variable name** | `Sim_CharSpeaking` | True/False | In voice mode, `true` while the character is speaking and `false` the rest of the time. Not written in text mode. |
| **Attempts remaining variable name** | `Sim_AttemptsRemaining` | Number | Written when an attempt starts, with the number of attempts left. The field appears only while an attempt limit is set, and the name is fixed. |
| **Eval complete variable name** | `Sim_EvalComplete` | True/False | Set to `true` when the evaluation finishes. If the evaluation fails, it is set to the text `failed` instead. |
| **Pass/Fail variable name** | `Sim_Pass` | True/False | Written after the evaluation with the pass or fail result. |
| **Score variable name** | `Sim_Score` | Number | Written after the evaluation with the score as a whole-number percentage. |
| **Feedback text variable name** | `Sim_Feedback` | Text | Written after the evaluation with the written feedback for the learner. |

The last four fields appear only when evaluation is turned on for the simulation, and those variables are written only then. In feedback-only mode the pass/fail and score variables are never written, so build your course logic on the feedback, evaluation-complete and completion variables instead. See [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring).

**Feedback text character limit** sets the length the written feedback aims for. It is a target the evaluation is asked to stay close to, not a cut-off. The default is 500 characters.

A system variable name left blank is written under its default name. Clearing a name does not stop the variable from being written. The completion variable is the exception: a cleared completion name is written as `simulationComplete`, which is also what the field shows when empty.

The same name applies in one more case. A simulation with no completion name stored writes completion to `simulationComplete`. This can happen when its **Variables** and **Evaluation** sections have never been saved. A simulation generated from a description stores the default completion name when it is created. Saving either section stores the name shown in **Completion variable name**, and the simulation writes that name from then on. The Step 2 table on the Publish stage always lists the name that is written at that moment.

After evaluation, the result variables are written first and the evaluation-complete variable last, so a trigger that waits for `Sim_EvalComplete` can read the score and feedback as soon as it fires.

When the learner selects Try Again, the simulation resets the completion, session start and evaluation-complete variables to `false` and clears the feedback text. It also clears pass/fail and score, except in feedback-only mode. For what ends a simulation, see [How a simulation ends](https://docs.devlin.ai/simulations/ending-a-simulation). For the attempt limit, see [Criteria breakdown and attempt limits](https://docs.devlin.ai/results-and-analytics/learner-results-and-attempts).

## System variables a coach writes

A coach has no evaluation, so it writes no result variables.

| Field | Default name | Type | When it is written |
|---|---|---|---|
| **Completion variable name** | `Coach_Complete` | True/False | Set to `true` when the conversation with the coach ends. |
| **Session start variable name** | `Coach_SessionStart` | True/False | Set to `false` when the coach loads, and to `true` when the learner sends the first message or the voice session connects. |
| **Session timer variable name** | `Coach_Timer` | Number | Updated once per second with the elapsed seconds, starting when the conversation begins. |
| **Turn counter variable name** | `Coach_Turn` | Number | Updated with the current turn at the start of each exchange. |
| **Speaking variable name** | `Coach_CharSpeaking` | True/False | In voice mode, `true` while the coach is speaking and `false` the rest of the time. |

When a new session starts after a coach session has ended, the completion and session start variables are set back to `false`. See [Coach sessions across slides, reloads, and course restarts](https://docs.devlin.ai/coaches/coach-sessions-and-restarts).

## How a value reaches Storyline

1. For a custom variable or the mood variable, the character adds a command to its reply in the form `[[SET_VAR:name=value]]`.
2. devlin.ai removes the command from the reply before the learner sees it, so the learner only reads the character's words. Only the variables defined for that simulation or coach, plus its mood variable, are accepted. A command for any other name is removed and ignored.
3. The simulation or coach sends the name and value as a message to the page that contains it.
4. In Storyline, the JavaScript trigger from the Publish stage receives the message and calls `player.SetVar()` with that name and value.

System variables skip the first two steps: the simulation or coach sends them itself.

In a text conversation a custom variable is written while the reply that set it is arriving. In a voice session it is written when the character speaks that reply.

### Value types

The value decides the type that is sent, not the **Type** you picked: `true` and `false` are sent as true/false values, anything numeric is sent as a number, and everything else is sent as text. Give a **Number** variable numeric values and a **True/False** variable the values `true` and `false`, so the Storyline variable receives the type it expects.

## What to create in Storyline

The Storyline variable must exist, with exactly the same name. For a simulation, open the **Publish** stage, expand **Storyline 360** and find **Step 2: Create Matching Variables in Storyline**. The table lists each custom and system variable under **Variable Name**, with the type to choose in Storyline and the default value to give it (`false` for True/False, `0` for Number, blank for Text). The exception is the attempts remaining variable, whose default value is your attempt limit. For a coach, the same table is the **Storyline variable reference** at the bottom of the **Session Variables** card.

Both tables include the mood variable as a Text variable, with the starting mood as its default value. A coach writes its mood variable once the **Session Variables** card has been saved.

For a simulation, the table also notes two values that do not match a variable's type: the evaluation-complete variable receives the text `failed` when scoring could not finish, and the pass/fail and score variables are cleared to blank when the learner selects Try Again.

Storyline also needs the Web Object and the JavaScript trigger from **Step 3: Add a JavaScript Trigger**. See [Embedding a simulation in Articulate Storyline](https://docs.devlin.ai/publish-and-embed/storyline-web-object-setup).

Storyline variables are not reset when the learner revisits the slide. Calling `restartSimulation()` from an Execute JavaScript trigger sets every variable written so far back to `false`, `0` or blank, according to the type of the last value written, and reloads the simulation.

## Check the values before you publish

In the **Test** stage of a simulation or coach, the **Variables** table under the preview lists every variable the simulation or coach can write and shows each value as it changes during your test run, with no Storyline course needed.

If the values change there but not in your course, see [The simulation isn't updating my Storyline variables](https://docs.devlin.ai/troubleshooting/variable-bridge-troubleshooting).

## Outside Storyline

The simulation or coach sends its variables to whatever page contains it. What happens next depends on that page:

- A web page that embeds the simulation: nothing is written unless the page listens for the messages. Each one is a browser message with the type `SIM_SET_VAR`, a `name` and a `value`, which the page's own script can read.
- Rise 360: the **Rise 360** section of the Publish stage has no variable steps. See [Rise 360](https://docs.devlin.ai/publish-and-embed/rise-360).
- LMS reporting: course variables are separate from the score, pass/fail and completion reported to an LMS.

On a page with the devlin.ai script but no Storyline player, the script does not write variables.

## Editing over MCP

An AI tool connected through the [MCP server and AI tool connectors](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) can read and change a simulation's or a coach's custom variables when it updates that simulation or coach. It sends the full list of variables, each with a name, type, description of when it changes, and values.

## Related

- [Embedding a simulation in Articulate Storyline](https://docs.devlin.ai/publish-and-embed/storyline-web-object-setup)
- [The simulation isn't updating my Storyline variables](https://docs.devlin.ai/troubleshooting/variable-bridge-troubleshooting)
- [How a simulation ends](https://docs.devlin.ai/simulations/ending-a-simulation)
- [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring)
- [Publish a simulation](https://docs.devlin.ai/publish-and-embed/publish-a-simulation)
- [Rise 360](https://docs.devlin.ai/publish-and-embed/rise-360)
- [LMS packages: SCORM and xAPI reporting](https://docs.devlin.ai/publish-and-embed/lms-packages-scorm-and-xapi)
- [Coach sessions across slides, reloads, and course restarts](https://docs.devlin.ai/coaches/coach-sessions-and-restarts)