Gags & Substitutes

Use a gag to hide text and a substitute to replace it. Both use the same matching rules.

Find them in Settings > Gags and Settings > Substitutes.

How gags work

When a line contains a gag’s text, Merlin removes the matching text and leaves the rest of the line.

• To hide a whole line, use the entire line as the gag. If nothing remains, the line disappears.
• When a gag removes a whole line, Merlin also removes the blank line above it, if there is one. Games often print a blank line before a message, and this keeps it from being left behind as an empty gap.

Gags hide text; they don’t delete it. They apply only to the Game (Filtered) panel. The Game panel always shows the original text.

Tip: Keep gags specific. A gag removes its text from every line that contains it, so short gags may match more lines than expected. If text seems to be missing, check the Game panel.

Gags and your gameplay log

The gameplay log contains the filtered text you see on screen, with gags removed and substitutes applied.

The log is stored in the game’s Logs folder inside your Merlin folder:

To keep an unfiltered record, turn on Settings > General > Capture raw logs. Merlin saves a second file beside the gameplay log with the same name and the extension .raw.log.

Note: Raw logs contain everything the game sends, including color codes, but not commands you type. The color codes can make them harder to read in a text editor.

Add or remove a gag

1. Choose Settings > Gags.
2. Type the text in the empty row.
3. Press Enter to add another gag.

Merlin saves gags as you type. Gags appear alphabetically; a new row moves into place when you click away from it. If you leave a new row empty, it disappears when you click away.

To remove a gag, clear its row and click away, or click its More button and choose Delete.

Replace text with a substitute

Each substitute has two fields: the text to find and the text to show instead. Substitutes use the same matching rules as gags.

1. Choose Settings > Substitutes.
2. In the left field of the empty row, type the text to find.
3. Click the right field, then type the replacement text.
4. Press Enter to add another substitute.

Merlin saves substitutes as you type. New substitutes move into alphabetical order when you click away from them. If you leave a new row empty, it disappears when you click away.

Reuse the text a star matched

A replacement can include text matched by a star (*). Use $arg1 for the first star, $arg2 for the second, and so on through $arg9. These are the same names a trigger or a script uses for the text it catches.

For example, the game prints:

1

The dark hound claws at you!

• Text to substitute: The * claws at you!
• Substitute: >> $arg1 is attacking! <<

You see:

1

>> dark hound is attacking! <<

Reuse the whole match

Use $match for the whole match. When the text to find uses |, $match keeps whichever side matched.

• Text to substitute: claws at you|lashes its tail at you
• Substitute: $match (OUCH)

The dark hound claws at you! becomes The dark hound claws at you (OUCH)!

Show variables and dollar signs

• Variables: Use $ followed by a variable name, such as $health, to insert the variable’s value when the line arrives. The line doesn’t change if the variable changes later. A variable with no value stays as typed.
• Dollar signs: Use \$ to show a real dollar sign, so \$5 each appears as $5 each. A $ followed by a digit, such as $5 or $1, is not allowed in a substitute. The row is marked and does nothing until you fix it.

Note: If the replacement is empty, Merlin leaves the line unchanged.

How text is matched

These rules apply to gags and substitutes.

• Whole words: A gag of rat leaves You take a bite of your hard rations. alone, because rat is only part of rations.
• Plurals are separate words: A gag of hound removes hound from The dark hound claws at you!, but not hounds from 2 dark hounds just wandered in behind you at 3 UDs!
• Numbers are words: A gag of 10 doesn’t match 10th.
• Capitalization matters: A gag of Taath doesn’t match taath.
• Spaces matter: A gag containing > followed by a space removes the mark and the space. A gag containing only > leaves the space.
• Color doesn’t matter: Text still matches when its color changes within the line.
• Overlaps are handled once: Overlapping gags remove the text once. For overlapping substitutes, Merlin uses the match that starts first, or the longer match if both start in the same place.

Match changing text with a star

A star (*) matches changing text within a line. Use it for parts such as names, numbers, or weapons.

Special characters

• >* matches a prompt line, whatever comes after >.
• Your*takes*damage! matches a damage line, whatever appears between Your, takes, and damage!.
• \* matches a real star the game printed.
• \\ matches a real backslash.
• SHOP|TRAIN matches either SHOP or TRAIN.
• \| matches a real bar the game printed.

Where you put the star

How much a star matches depends on where you put it. The match includes the text you type as well as the text matched by the star.

For example:

1

Belka waves at Tam and Tam waves back

After Belka*Tam, this remains:

1

 and Tam waves back

What a star can’t do

• It needs the text after it. If that text isn’t present, there is no match.
• It matches to the end of the line, not the end of a word. hound* removes hound and everything after it. To match hounds too, add another gag.
• It stays on one line. To match multiple lines, see Hide a block of lines.
• Several stars count as one. *** is the same as *.

Match any of several phrases

A bar (|) means “or.” Use it to match any of several phrases with one gag.

For example:

1
2

The dark hound claws at you!
The dark minion lashes its tail at you!

This gag hides either line:

1

The dark hound claws at you!|The dark minion lashes its tail at you!

Each side of the bar works as a gag of its own, with its own stars and its own whole-word matching. Use \| to match a real bar the game printed.

Escape stars the game prints

Use \* to match a real star printed by the game.

For example:

1

 ** Belka just arrived in the world.

You might try this gag:

1

 ** *just arrived in the world.

That doesn’t do what you want. The two real stars become wildcards too. The gag may still hide the intended line, but it can also match other lines and take longer to check.

Escape the stars the game printed instead:

1

 \*\* *just arrived in the world.

Now only the final star is a wildcard for the name.

Tip: If a gag seems slow, check for real stars that need to be escaped.

If Merlin turns off a slow gag

If a gag takes long enough to slow the window, Merlin disables it for the rest of the session and tells you which gag it was.

To fix it:

• Escape real stars the game printed.
• Add more fixed text so each star has less text to match.

Merlin tries the gag again after you change it. If it’s still too slow, Merlin disables it again. Restarting Merlin also enables the gag until it proves slow again.

Hide a block of lines

After the text for the first line, add the number of following lines to hide between double stars.

For example:

1
2
3
4

Your inventory:
  a rusty dagger
  a torch
  a loaf of bread

This gag hides the first line and the three lines after it:

1

Your inventory:**3**

• The number can be up to 20. You give a number instead of an ending phrase because the last line of a block often isn’t something you can name.
• The lines don’t have to arrive together. After the first line matches, Merlin hides each following line as the game sends it, until the count is used up.

Organize gags and substitutes into groups

1. Click the More button for a gag, then choose Move to group.
2. Choose New group and enter a name, such as Combat, or choose an existing group.

The gag appears under the group heading.

• To expand or collapse a group, click the arrow next to its heading.
• To rename a group, click the pencil on its heading.
• To remove a gag from a group, choose More > Move to group > No group.

Ungrouped gags appear below the group headings. Gags within a group are listed alphabetically.

Groups don’t affect matching. A gag matches the same text whether or not it belongs to a group.

Substitutes use groups the same way.

How gags and substitutes work with highlights

When Enable Highlights is on, highlights take priority over gags and substitutes.

• Gags: If a gag and highlight match the same text, the highlighted text remains on screen. For example, with a gag of Belka* and a highlight of Belka, Belka remains highlighted in Belka waves at Tam and Tam waves back, while the rest of the line is removed.
• Substitutes: If a substitute would change any highlighted text, the substitute doesn’t run because it can’t replace only part of what it matched.

When Enable Highlights is off, gags and substitutes treat that text normally.

Edit the gag and substitute files

Gags and substitutes are stored one per line in the plain-text files gags.txt and substitutes.txt. You can edit these files by hand.

Find them in the game’s Config folder inside your Merlin folder:

A group appears at the end of its line in braces:

1

#gag {Your*takes*damage!} {group=Combat}

Gags and substitutes are stored separately for each game, preventing text from one game from matching text in another.