# Variables

A variable is a name that holds a value. Write the name with a `$` in front, and Merlin puts the value in its place.

```
echo My health is $health.
```

The result, printed only on your screen:

```
Merlin Client: My health is 87.
```

Find your variables in Settings > Variables.

## Three kinds of variables

**Game variables** come with the game's module. The game reports your health, your room, what is in your hands, and Merlin keeps the latest report under a name. You read them; the game writes them. Settings > Variables lists every one under **Merlin managed variables**, with its current value and what it means. The game's own variables page in Help lists them too.

**Saved variables** are yours, and they last. Add one in Settings > Variables, or let a script create one with `keep`. Quit Merlin, come back next week, and the value is still there. They live in the Config folder, in the file variables.txt, one per line:

```
#var {patient} {Marcus}
```

**Local variables** are a script's own. A `set` line makes one, and it lasts only for that run of that script.

```
set prey rat
send kill $prey
```

The result:

```
> kill rat
```

## How a value is read

- **A `$name` is replaced with its value at the moment the line runs.** If the value changes later, lines already run do not change.
- **A name with no value stays as typed.** `echo $nothing` prints `$nothing`.
- **In a condition, a name with no value is an error, not a false.** An `if` line, a trigger's condition or a timer's line that cannot be read stops and says why. Ask `is set` first when the game may not have spoken yet: `if $target is set then send attack $target`. The game's page says which variables start unset and which start with a value such as `no` or `none`.
- **`set` can give a game variable a new value for the rest of a run.** `keep` cannot write a game variable at all.
- **Some game variables take a name in brackets.** `$remain(Swimming)` is the uses left before Swimming can train. The name can come from a variable: `$remain($skill)`.
- **A variable can hold a list.** Separate the items with `|`. `$list(2)` is the second item, `foreach` walks them, and `in` asks whether a value is on the list. See the [Scripting Manual](https://merlinclient.com/manuals/scripting.md).

## Names

- Letters, numbers and underscores, and the first character is not a number.
- A name ignores case. `$hpMax` and `$hpmax` are one variable.
- Merlin's own names, listed below, cannot be written.
- A game variable's name cannot be used as a script argument. `set` can replace its value inside a script; `args` cannot.

## Merlin's own variables

These come with Merlin, whatever game you play. Merlin writes them; you read them.

| Variable | What it holds |
|---|---|
| `$args` | Everything typed after a script's or an alias's name. In a trigger, the whole line that fired it. |
| `$arg1` to `$arg9` | The single words typed after a script's or an alias's name. In a trigger or a substitute, the parts the stars or parentheses caught. |
| `$match` | In a substitute, the whole text the pattern matched. |
| `$moved` | After a `move` line: `yes` when you reached the new room, `no` when you were blocked. |
| `$time` | The clock, as hours and minutes on the 24-hour clock: `14:05`. |
| `$date` | Today, as year, month and day: `2026-11-01`. |
| `$unixtime` | The clock as whole seconds, a number you can do arithmetic on. |
| `$timer_<name>` | The seconds a stopwatch has run since `timer start <name>`: `$timer_errand`. |

## Where a variable works

| Place | What you can write |
|---|---|
| **Scripts** | Any `$name`, in any line that takes text or a condition. `$args` is everything typed after the script's name, `$arg1` to `$arg9` the single words. |
| **Triggers** | In the action, any `$name`. `$args` is the line that fired the trigger; `$arg1` to `$arg9` are the parts a star or parentheses caught. With **If a value** at the top, the trigger watches a condition instead of text: `$health < 50`. The spoken alert reads `$arg1` to `$arg9` and `$args` only. |
| **Timers** | The timer's lines are script lines, so any `$name` works. |
| **Aliases** | In the Sends field, `$args` and `$arg1` to `$arg9` are what you typed after the alias, and any other `$name` is filled when you press Enter. |
| **Substitutes** | In the replacement, `$arg1` to `$arg9` are what the stars matched, `$match` is the whole match, and any other `$name` is the variable's value when the line arrives. `\$` is a dollar sign. |

A variable does not work in these places, and a `$` there is just a dollar sign:

- **A trigger's pattern, a gag, a highlight.** These match the game's text as typed.
- **A macro.** It sends its words as typed. To use a variable from a key, make the key run a script or an alias.
- **The command line.** `say $health` goes to the game as written. Put it in an alias to have it filled.

## Two rules worth knowing

- **Watch a variable from one place.** A trigger with **If a value** and a script's `action … when eval` can both watch your health. Set both and you drink two potions. Pick one for each job.
- **A trigger on a value fires once, when the condition first comes true.** Use **Fire again only after** to say when it may fire again. See the [Triggers Manual](https://merlinclient.com/manuals/triggers.md).

## See also

- [Scripting Manual](https://merlinclient.com/manuals/scripting.md): `set`, `keep`, `args`, lists, conditions and the game variables that take a name.
- [Triggers Manual](https://merlinclient.com/manuals/triggers.md): captures and **If a value**.
- [Aliases Manual](https://merlinclient.com/manuals/aliases.md) and [Gags and Substitutes Manual](https://merlinclient.com/manuals/gags-and-substitutes.md): the fields that take a variable.