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.

1
2

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.

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.

Themes

Fantasy

Sci-Fi

Accessibility

Seasonal