Triggers

A trigger watches the game for text you choose and acts when that text appears. It might send a command, for example. Once you set up a trigger, it keeps working every time you play.

Unlike a script, which you start and which eventually ends, a trigger stays on and waits for its text to appear.

In this guide, when a trigger sees its text and acts, it fires.

Find your triggers in Settings > Triggers.

Add a trigger

1. Go to Settings > Triggers, then click the New trigger button (+).
2. Fill in the two parts of the editor, which reads like a sentence:
   • If the game text contains: too dark to see anything
   • then send: ready torch
3. Click Save.

For example, when you walk into a dark place, the game prints It's too dark to see anything! Ready a torch. This trigger readies your torch the moment that line appears.

The next time it happens, you see:

1
2

It's too dark to see anything!  Ready a torch.
> ready torch

The game printed its line, the trigger saw it, and ready torch went out before you’d read the sentence. That’s what triggers are for: a reaction that shouldn’t wait for you to notice.

How matching works

A trigger checks its pattern against every line the game prints. The menu beside the pattern box sets how it checks:

Contains is the default, and it’s the right choice most of the time.

Whole words

A trigger on rat doesn’t fire on this line, because rat is only part of rations:

1

You take a bite of your hard rations.

• A plural needs its own trigger. A trigger on hound fires on The dark hound claws at you!, but not on 2 dark hounds just wandered in behind you at 3 UDs!
• Numbers count as words. 10 doesn’t match 10th.
• Is exactly is already the whole line.
• A Regex matches inside a word too.

Stars

With the first three choices (contains, starts with, and is exactly), a star (*) in the pattern stands for any text, including no text at all. To match a real star the game printed, write \*.

Whole words apply at the two ends of the pattern, not beside a star. rat* fits “the rat runs” and “rations”, and never “Brat”. Several stars in a row count as one star.

The action gets the text each star matched. The first star arrives as $arg1, the second as $arg2, and so on through $arg9, the same names a Regex trigger’s parentheses use.

• If the game text contains: * hits you for * damage
• then run this script line: echo $arg1 hit me for $arg2

When the game prints The dark hound hits you for 12 damage., you see Merlin Client: The dark hound hit me for 12.

A star at the start takes everything from the start of the line. A star in the middle takes as little as it can. A star at the end takes the rest of the line.

A space at the start or end of the pattern is ignored. To match a space beside punctuation, such as > , use a Regex, which keeps its spaces.

A pattern needs words

A pattern has to have some words in it. A pattern that’s only spaces, or only *, would match every line the game prints, so the editor marks it in red and it never fires. A Regex that would match an empty line, such as ^ or .*, is marked the same way.

A Regex that could take forever on one long line is marked too, and the tip under it says what to change: write it without the lookahead or backreference, or without the repeated group, or with fewer open-ended repeats (* and +). Merlin runs most patterns with a safety net that cannot freeze, and marks only the few shapes the net cannot catch.

Capitalization

Capital letters must match. A trigger on the dark hound doesn’t fire on The dark hound claws at you!, because the game wrote a capital T. Copy the words as the game prints them.

To catch both, use a Regex and put both letters in brackets: [Tt]he dark hound.

What a trigger can do

The second part of the trigger is what it does. It’s one action:

A trigger has one action on purpose. If it needs several steps, put the steps in a script and have the trigger run the script.

Use the matched line in the action

When a trigger fires, it passes the line it saw to the action. Inside the action, $args is that whole line.

A Regex trigger can also pass along part of the line. Put parentheses around the part you want, and it arrives as $arg1. A second pair arrives as $arg2, and so on. A star in a contains, starts with, or is exactly pattern does the same (see Stars above). These are the same names scripts use. See Arguments in the Scripting Manual.

Example

• If the game text matches a Regex: You pick up (\d+) silver coins
• then run this script line: echo I just picked up $arg1 coins!

When the game prints You pick up 12 silver coins., you see:

1

Merlin Client: I just picked up 12 coins!

The parentheses captured the 12, and the action received it as $arg1.

Learn Regex, one symbol at a time

Regex is a small pattern language. Most of a pattern is plain text, and plain text matches itself. The pattern coins matches any line with coins in it, inside a word too, which contains doesn’t do. Symbols are for the things plain text can’t say.

You need five symbols.

| means “or”

1

claws at you|lashes its tail at you

This reads as “claws at you, or lashes its tail at you.” The line matches if either one is in it.

• Matches: The dark hound claws at you!
• Also matches: The dark minion lashes its tail at you!

\d means “any one digit”

A digit is a number character, 0 through 9. \d matches exactly one of them and doesn’t care which.

1

You pick up \d silver coins

• Matches: You pick up 4 silver coins.
• Doesn’t match: You pick up 12 silver coins. Why not? \d is one digit, and 12 is two.

+ means “one or more of the thing before me”

Put + after \d, and it matches 4, 12, or 1250.

1

You pick up \d+ silver coins

This reads as “You pick up, then one or more digits, then silver coins.”

It matches You pick up 4 silver coins. and You pick up 12 silver coins. alike. One pattern covers every amount.

( ) means “save this part”

Parentheses save part of a match. The saved text becomes $arg1, which the action can use. A second pair saves as $arg2.

1

You pick up (\d+) silver coins

This is the pattern from the earlier example. The parentheses save the digits, so $arg1 is the saved number, 12 in the example. Saving it lets the action use the real number every time, instead of one fixed number that would be wrong the next time.

\. means “a real period”

A bare . is a symbol too: it means “any one character.” When a pattern needs a real period, write \. instead.

1

You open the closed purse\.

This matches the game’s sentence, period and all. The backslash means “treat the next thing differently”: it turns the plain letter d into the symbol \d, and it turns the symbol . back into a plain period.

Try a pattern in the test box

At the bottom of the trigger editor is the Test with game text box. Paste a real line there, set the trigger to matches a Regex, and change the pattern until it matches. Nothing is sent while you test, so a wrong pattern costs nothing.

That’s the whole starter kit: |, \d, +, ( ), and \.. Nearly every trigger you’ll ever want is built from these five. For a fuller table, for the day you outgrow them, see Patterns in the Scripting Manual.

Trigger options

The trigger editor has extra settings below the pattern and action. Each changes when, or for whom, the trigger fires. Most triggers use none of them. A trigger with no options simply watches for its pattern, then acts.

Pause a trigger for the character you’re playing

Your triggers are one list, shared by every character you play in a game. The Pause button on a trigger’s row turns the trigger off for the character you’re playing and leaves it on for everyone else. Click it again to turn the trigger back on for that character. The button’s tooltip says Pause for, followed by the character’s name.

For example, Belka can see in the dark, so she doesn’t need torch triggers. Log in as Belka and click Pause on each torch trigger, or on the whole Torch group (see Groups, below). The triggers stay off for her and keep working for every other character, including any you make later.

A paused row is dimmed, and its Pause button changes to Resume. To see who the trigger is off for, hover over the button; the tooltip reads, for example, “Off for Belka — click to resume.” To turn the trigger back on, click Resume.

• You can pause only for the character you’re playing.
• At the login menu, the Pause button doesn’t do anything yet, because Merlin doesn’t know who you are.

Disable a trigger for everyone

Sometimes you want a trigger off for every character at once, for example while you fix it. Select Disable trigger for everyone in the trigger’s editor, or right-click its row and choose Disable trigger for everyone. The row shows the disabled icon (a circle with a line through it) in place of its Pause button.

To turn the trigger back on, click the disabled icon. Anyone who had paused it for themselves keeps it paused. Turning the trigger back on for everyone only undoes the disable, not anyone’s own pause.

Fire once per arrival with On room entry

A room’s name is printed again every time you look or the screen redraws. That means a plain trigger on a room name fires over and over the whole time you stand there. When you select On room entry, the pattern is checked against the room’s name instead, and the trigger fires once when you arrive.

For example:

• If the game text contains: Healer's Shack, with On room entry selected
• then send: shop heal

When you walk into the Healer’s Shack, > shop heal goes out a couple of seconds later, once.

• The short wait lets the room settle. If you walk straight through, the trigger doesn’t fire, and its sound or spoken alert waits for the settle too, so a walk-through makes no noise.
• It doesn’t repeat while you stay. Stand there looking around all day, and it never fires again.
• It fires again on your next arrival. Leave and come back, and it fires once more.
• Two rooms with the same name are two arrivals. Walk from one Forest Path room into the next, and a trigger on that name fires again.

Groups: turn several triggers on or off at once

A group gathers triggers under a heading in the list. To put a trigger in a group, open the trigger and type a name in Assign to group, such as hunting. Do the same for each trigger that belongs together.

• To open or close a group, click the arrow next to its heading.
• Triggers that aren’t in a group appear at the bottom of the list, below the groups.

A script can keep a group off while it runs, with hold trigger group and the group’s name. The group comes back when the script ends. Nothing is saved, and your own Pause and Disable settings stay as they are. See hold, release in the Scripting Manual.

Group buttons

A group heading has the same buttons a trigger has:

• Pause: Turns the whole group off for the character you’re playing. Its tooltip also reads Pause for, followed by the character’s name. If you pause Torch while playing Belka, every torch trigger goes off for her alone.
• Disable group for everyone: Right-click the heading and choose Disable group for everyone to turn every trigger in the group off for every character. The heading shows the disabled icon. To turn the group back on, click the disabled icon. Characters who had paused the group for themselves keep it paused.
• Pencil: Renames the group. The name turns into a text box in the list. Type the new name and press Enter or click away, or press Esc to keep the old name. Every trigger in the group moves to the new name, and so do the group’s pause and disable-for-everyone settings.

When a group is paused or disabled

While a group is paused for you, each trigger in it is dimmed and shows Resume, as the heading does.

• Click Resume on the heading, and each trigger is exactly as it was: one you had paused yourself stays paused, and the rest come back on.
• Click Resume on one trigger instead, and only that trigger comes back on: the heading turns back on, and the group’s other triggers stay paused, each on its own.

While a group is disabled for everyone, each trigger in it is dimmed, and the heading shows the disabled icon.

Rename a group to a name you already use

Merlin asks first, for example: “Light already exists. Merge Torch into it?”

• Merge puts all the triggers in Light, and anything either group had switched off stays switched off.
• Cancel keeps the old name.

If a group is left empty

A group’s pause and disable-for-everyone settings belong to the group, not to the triggers in it. If you move every trigger out of a group one by one by changing each trigger’s group name, those settings are left behind. When that happens:

• The empty group stays in the list and says so, for example: “Torch is now empty. It was off for Belka.”
• If every trigger went to the same group, Merlin offers to move the settings there.
• If you don’t want the settings, click Remove, and the empty group goes away.

Tip: The easier way to move a whole group is to rename it with the pencil. That moves the triggers and settings together and never leaves an empty group.

Match two lines as one event with Within N lines after

Some events take more than one line. For example, this is what the game prints when a lesser spirit lands a hit:

1
2
3
4

The lesser spirit claws at you!
The attack is a strong blow to the head.
  Your simple leather armor absorbs a bit of the damage!
    Your thick skin absorbs a bit of the damage.

This is what it prints when the spirit misses:

1
2

The lesser spirit claws at you!
The attack misses.

To retreat whenever the spirit lands a strong blow, no single line is enough. claws at you! comes before a miss too. And strong blow also appears when your own swing lands: The swing is a strong blow to the head. What you want is two lines together: the spirit’s attack, then a strong blow on the next line.

The trigger’s sequence fields say exactly that:

• If the game text contains: strong blow
• within 1 line after: spirit claws at you
• then send: retreat

This reads as: after seeing “spirit claws at you,” watch the next line. If “strong blow” is there, retreat.

• On the hit above: “strong blow” is on the very next line, so > retreat goes out.
• On the miss: The claw line comes, but “strong blow” doesn’t. Nothing fires, and the watch just runs out.

Each new “claws at you” starts the watch over.

Watch a variable with If a value

A trigger can watch a variable, such as your health, instead of the text the game prints. At the top of the editor, change If the game text to If a value. The box then takes a condition, the same kind you’d write in an if line in a script, read the same way: $target is set fires the moment the value appears, and a condition on a value Merlin has no reading for yet, such as your health before the first vitals line, waits, neither true nor false. An empty list is a reading, so a test on it reads false. The trigger fires when the condition becomes true.

For example:

• If a value: $health < 50
• Fire again only after: $health > 55
• then send: drink potion

This reads as: when my health drops below 50, drink a potion. Don’t drink another until my health goes back above 55.

$health is one of the game’s variables. Any of them, or one you made yourself, works the same way.

A game value that takes a name works too. $remain(Swimming) = 0 fires when Swimming has no uses left before it can train. These values move when a script sends skills, and the moment the game says a skill is full. Until the skills list has been read once, the condition is not known, and the trigger waits.

How it behaves

• It fires once, when the condition first becomes true. Health drops from 60 to 45: one potion. Health keeps dropping, 45, 40, 35: no more potions.
• Fire again only after keeps it from firing over and over when health wobbles. Health going 49, 51, 49 fires once. It fires again only after health has gone back above 55 and then dropped below 50 again. If you leave the box empty, the trigger is ready again as soon as health is back to 50 or more.
• Logging in already hurt doesn’t fire it. The first reading Merlin gets is the starting point, not a drop. The trigger fires the next time health falls below 50. Logging out and back in starts over the same way, and so does changing the condition.
• It waits until the value is known. Right after you log in, before the game has sent your health, the trigger does nothing.
• Its action waits out the delay first. After some actions, such as an attack, the game makes you wait a few seconds before you can act again. That wait is the delay, also called roundtime. If the trigger fires during a delay, the potion is sent when the delay ends, not before. Every trigger whose action sends a command waits this way. A trigger that only records a value acts right away.
• Pause, disable for everyone, and groups work the same as on any trigger.

If Merlin can’t read the condition, the box is marked in red, and the reason shows when you hover over it. A trigger with a broken condition never fires.

Important: Don’t watch the same variable from two places. A script can watch a variable too, with its action … when eval line (see the Scripting Manual). If a script and a trigger both watch your health, both fire at the same moment, and you drink two potions. Use one or the other for each job.

Add an alert: speak or play a sound

A trigger can also get your attention with sound, using the and row in the editor. Choose speak this text or play this sound from the menu.

• Speak this text: Reads words aloud when the trigger fires. Type * to have it read the matched line word for word. Type anything else to have it read that instead. If the pattern saved part of the line with parentheses, you can use it: $arg1 is whispering to you reads out whatever name the parentheses caught. A new spoken alert cuts off the one before it.
• Play this sound: Plays a sound you choose. A trigger with a sound shows a speaker icon on its row; click the icon to hear the sound. A sound can be the whole trigger, with no action at all.

Both follow the app’s volume and mute setting. For no alert, leave the row empty. A spoken alert cuts off anything else being said, a script’s speak line included. A spoken line is cut at 500 characters.

Make a trigger wait: Not if the script is already running, and Cooldown

Most triggers should fire every time their words appear; every dark room needs the torch lit. Some triggers should wait. These two options make a trigger wait. Both are off until you turn them on, one trigger at a time.

Not if the script is already running

When you select this option, the trigger skips a firing while the script it started is still going. The checkbox is under the script’s name when the trigger’s action is run script or run this script line. It works for a trigger that watches a value too.

For example:

• If the game text contains: You are hungry.
• then run script: Eat, with Not if the script is already running selected

The game says “You are hungry.”, and Eat starts. The game says it again while Eat is still opening your pack. Eat keeps going, and that second line is skipped. Once Eat is done, the next “You are hungry.” starts it again.

• A skipped firing is gone. It doesn’t wait in line for later.
• It watches the script itself, whoever started it. If you started Eat by hand, the trigger still waits for it to finish.
• A long script means a long wait. A trigger that starts a long script, such as a hunt, won’t fire again until that script ends. That can be an hour.
• A running script is never started over. Even without this option, a trigger’s run script does nothing while that script is still going. The option also holds back the rest of the trigger: its sound, its spoken alert and any other line in its action.

Cooldown in seconds

Type a number, and after the trigger fires, it stays quiet for that many seconds. Its sound and spoken alert stay quiet too. For no cooldown, leave the box empty.

For example:

• If the game text contains: whispers, with play this sound: arcade-notification-01
• Cooldown in seconds: 30

Tam whispers five times in a minute. The sound plays for the first whisper, then waits 30 seconds before it can play again.

A room-entry trigger can have a cooldown too. With 30 on the Healer’s Shack trigger, walking out and straight back in doesn’t heal you twice.

Test a trigger before you rely on it

The Test with game text box is at the bottom of the trigger editor. It lets you try the trigger you have open, including changes you haven’t saved yet, without waiting for the real thing to happen in the game.

Paste some game text into the box. It can be one line or several lines copied from the Game panel. Merlin checks the trigger against that text the same way it would check live text and tells you what would happen: which line fires and what the trigger would do.

Nothing is sent to the game when you test. No sound plays, and nothing is spoken.

Test special triggers

• Within N lines after: Paste both lines, the earlier one and the one that should fire. The answer then reads like line 1 arms · line 2 fires → send retreat. If the earlier line is there but the pattern doesn’t follow it in time, the box says that instead.
• If a value: There’s no text to paste. Instead, the box tells you whether the condition is true right now, whether the trigger has already fired and is waiting to be ready again, and whether its script is still running, for example: “Right now: true. Heal is still running, so it would not fire.”

When a trigger wouldn’t fire

When a trigger is waiting right now, the box says so first, for example: “Right now: cooling down, 42 s left, so it would not fire.” or “Right now: Eat is still running, so it would not fire.”

The box also tells you when a trigger matches but wouldn’t fire, and why, for example: “off for Belka, would not fire live”. The reasons it can give are:

• “disabled for everyone”
• “group disabled for everyone”
• “group off for” the character you’re playing
• “off for” the character you’re playing
• “not this character” (a who= in the file names someone else)
• “off while Hunt runs” (a running script is holding the group; see hold, release in the Scripting Manual)

Safety nets

Two protections are always on, and both show a message when they act:

• The loop guard: If a trigger fires more than 30 times in 10 seconds, Merlin pauses it for 10 seconds and shows a message naming the trigger. Its action, its sound, and its spoken alert all pause. Every kind of trigger is under the guard: text, On room entry, and If a value. A trigger fires that fast only when it’s reacting to its own output, for example, a send whose reply matches the trigger. Without the guard, it would loop forever. A slower loop, such as two room-entry triggers walking you back and forth, is not caught.
• The slow-pattern ban: If a Regex takes far too long to check one line, Merlin turns off that trigger for the rest of the session and shows a message naming it. Editing the pattern turns it back on. A bad pattern gets one chance to freeze the app, not thousands, and most patterns never get that chance: see A pattern needs words above.

A trigger’s action can’t overlap itself

If the trigger fires again while its action is still running, the action starts over from the beginning, and whatever was left of the first run is dropped, unless Not if the script is already running is selected.

There is one exception. If the trigger fires again before its action has run its first line, for example two matching lines in one burst while the action waits out a delay, the second firing waits its turn and starts as soon as that first line is done. The same line arriving twice in that moment counts once. Up to ten firings wait; past that, they are dropped.

For example, the trigger runs a script that says send stand, then pause 2, then send attack. If the trigger fires twice within those two seconds, the script starts again from send stand, and the first run’s attack never goes out. A line the first run booked with later is dropped the same way.

A script line whose condition cannot be read, such as a variable nothing has set, stops that firing and says why. It says so again each time the trigger fires, until the variable exists. Check it with is set first, or set it before the condition reads it.

Tip: Keep a trigger’s action short, and this never matters.

Edit the triggers file

Triggers are stored one per line in triggers.txt. Find it in the game’s Config folder inside your Merlin folder:

1
2
3
4
5

#group {Torch} {except=Belka}
#trigger {too dark to see anything} {send ready torch}
#trigger {strong blow} {send retreat} {after={spirit claws at you}, within=1}
#trigger {Healer's Shack} {send shop heal} {on=enter}
#trigger {Your spent flaming wooden torch flickers} {run Torch} {group=Torch}

Each trigger line starts with #trigger, followed by three parts in braces. Using the second line above as an example:

Options

The options are:

• match=starts
• match=exact
• match=regex
• paused
• on=enter
• on=value
• again={<condition>}
• group=<name>
• who=<name> or who={<name>,<name>}
• except=<name> or except={<name>,<name>}
• after={<earlier line>}
• within=<n>
• speak={<text>}
• sound=<name>
• skipifbusy
• cooldown=<seconds>

Three of these need explaining:

• except= lists who a trigger is paused for.
• paused means disabled for everyone.
• who= makes a trigger work only for the characters it names. There’s no box for who= in the editor, only in this file, because the Pause button covers the same need from the character’s own side.

Group lines

A #group line holds a group’s pause and disable-for-everyone settings: except= lists who the group is paused for, and paused means disabled for everyone, as in #group {Hunting} {paused}. Merlin writes a #group line only while a group has something switched off and puts it above the triggers.

Important: If you use Merlin on two computers, both need this version of Merlin before you use group settings. An older version drops these lines when it saves.

Comments

A line beginning with // is a comment. Merlin skips it when it reads the file.

Important: Merlin doesn’t keep comments. The next change you make in Merlin rewrites the whole file with only the triggers in it, under Merlin’s own two lines at the top, so keep any notes you want to save somewhere else. Saving the file itself doesn’t rewrite it.

A line Merlin can’t read, one that isn’t a trigger, a group, a comment, or blank, is kept at the end of the file and does nothing. When Merlin loads the file, it says which lines those are, for example: “triggers.txt: 1 line could not be read (line 7); it is kept but does nothing.”

Keep the file and Merlin in sync

You can edit the file or edit in Merlin; each keeps the other up to date. When you save the file, the running app updates within a moment.

Note: If a settings editor is open when you save the file, the change takes effect the next time you click back into Merlin.

Choose a trigger, timer, or script

The three work together. A trigger can start a script with its run script action. A script can have triggers of its own while it runs, using the action verb; those stop when the script stops, while the triggers in this guide are always on.

To learn more, see the Scripting Manual.