# Aliases

An alias is a short word that sends a longer command. You type the word, and Merlin sends the command. A macro does this from a key; an alias does it from a word.

Find your aliases in Settings > Aliases.

## Add an alias

1. Go to Settings > Aliases, then click **Add alias**. A new empty row opens at the top of the list.
2. Fill in the two fields:
    - **Alias:** The word you’ll type. Use one word, in any case.
    - **Sends:** The command Merlin sends when you type the word.
3. Click away from the row when you’re done.

Merlin saves each alias as you type. To add another alias, press Enter; a new blank row opens at the top of the list.

Aliases are listed 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.

**Example: Type rest instead of sit**

1. In the **Alias** field, type `rest`.
2. In the **Sends** field, type `sit`.
3. In the command line, type `rest` and press Enter.

The game receives `sit`, and the Game panel shows `> sit`, because that’s the command that actually went out.

When you press the Up Arrow key, you get `rest` back, because that’s what you typed.

## Remove an alias

Click the **More** button at the end of the alias’s row, then choose **Delete**.

## Pass along what you type

Most aliases need something from you. In the Sends field, `$args` stands for everything you type after the alias.

| Alias | Sends | You type | The game receives |
|---|---|---|---|
| `hm` | `cast heal $args` | `hm Marcus` | `cast heal Marcus` |
| `give` | `give $arg1 to $arg2` | `give sword guard` | `give sword to guard` |
| `att` | `attack $monster` | `att` | `attack rat` (whatever `$monster` is right now) |
| `hunt` | `.hunt $args` | `hunt rats` | Runs your Hunt script with `rats` as its argument |

Here’s how to read each one:

- **hm:** Cast heal on whatever you type after `hm`. When you type `hm Marcus`, the game receives `cast heal Marcus`.
- **give:** The first word goes before `to`, and the second goes after it. When you type `give sword guard`, the game receives `give sword to guard`.
- **att:** Attack whatever you’re already fighting. When you type `att` by itself, the game receives `attack rat`, using whatever `$monster` already holds.
- **hunt:** Run your Hunt script and pass it what you typed. When you type `hunt rats`, it runs your Hunt script with `rats` as its argument.

### Words and variables

- **Single words:** `$arg1` through `$arg9` are the single words you type after the alias.
- **Variables:** Any other `$name` is a variable, the same kind your scripts read, filled in when you press Enter. `$monster` in the table above is one of the game’s variables. To see the full list, go to Settings > Variables.

### If something is missing

If an alias needs something after it and you type the word by itself, Merlin tells you and sends nothing. For example, typing `hm` by itself shows:

```
hm needs something after it — its alias uses $args
```

If an alias uses numbered words and you type too few, the message names the one that’s empty. For example, typing `give sword` shows:

```
give needs more after it — its alias uses $arg2
```

An alias that’s missing what it needs never sends anything.

## Do several things with one word

An alias sends one command. To make a word do several things, put the steps in a script and have the alias run it, the way `hunt` does in the table above.

A script waits for the game between each step. Sending several commands at once doesn’t wait: the game queues them and runs them later, whether you still want them or not.

## Where aliases work

- **Only in the command line.** Scripts, triggers, macros, and timers don’t use aliases. If a script says `hm Marcus`, the game receives `hm Marcus`, not `cast heal Marcus`. In a script, write the full command.
- **Only once per command.** For example, make an alias `l` that sends `look`. When you type `l`, `look` goes to the game. Merlin doesn’t check `look` for another alias, so one alias can never set off another.

## Alias names

- **One word.** `heal me` isn’t an alias name.
- **Any case.** `HM` and `hm` are the same alias.
- **Can’t start with `/` or a period.** Merlin reserves these for its own commands and for running scripts.
- **Must be unique.** Two aliases can’t share a name. If you make one anyway, the older alias keeps working, and the new one is marked in red so you can see why it does nothing.

If a name breaks one of these rules, it’s marked in red where you typed it, and the alias does nothing until you fix it. Merlin doesn’t change anything you typed.

### Use a game command as an alias name

An alias can use the same word as a game command. If you name an alias `look`, typing `look` runs your alias instead of the game’s `look` command until you delete the alias.

This is intentional. Sometimes you want a game word to do something different for a while.

## Organize aliases into groups

1. Click the **More** button at the end of an alias’s row.
2. Choose **Move to group**, then choose an existing group or **New group** and enter a name.

The alias appears under the group heading.

To open or close a group, click the arrow next to its heading.

To remove an alias from a group, choose **More** > **Move to group** > **No group**.

## Edit the aliases file

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

| Platform | Location |
|---|---|
| macOS | `~/Library/Merlin` |
| Windows | `%APPDATA%\Merlin Files` |
| Linux | `~/Documents/Merlin` |

```
#alias {hm} {cast heal $args}
#alias {att} {attack $monster}
```

You can edit the file in Merlin or in a text editor. A change made in one appears in the other.

If an alias belongs to a group, the group appears at the end of its line:

```
#alias {hm} {cast heal $args} {group=Heal}
```

### Comments

A line beginning with `//` is a comment, the same as in a script. Merlin keeps comments where you put them.

**Important:** In this file, `#alias` is how a real alias line starts, so always start a comment with `//`, never `#`.

## Choose an alias, substitute, or macro

These three look alike but do different jobs:

| Use a | To |
|---|---|
| Alias | Change what you type before it goes to the game |
| Substitute | Change what the game says before you read it |
| Macro | Send a command when you press a key |

An alias never changes what the game says, and a substitute never sends anything.