# Timers

A timer runs one command over and over on a schedule you set. Every so many seconds, it sends the command whether or not anything is happening in the game.

Find your timers in Settings > Timers.

## Add a timer

1. Go to Settings > Timers, then click the **New Timer** button.
2. Fill in the fields described below.
3. Click **Save**. The timer starts right away.

### Timer fields

- **Name:** A word for the timer, like a script’s name. The field removes spaces as you type. Two timers can’t share a name. Scripts use the name to turn the timer on or off; see [Turn a timer on or off from a script](#turn-a-timer-on-or-off-from-a-script).
- **Interval in seconds:** How many seconds between runs. Use whole seconds only, from 5 up to one day.
- **Run:** What to send.
- **Run once:** Makes the timer run one time, then pause itself. See [Run a timer once](#run-a-timer-once).
- **Assign to group:** Optional. Type a name, such as `Upkeep`, and the timer appears under an Upkeep heading in the Timers list. A group doesn’t change when the timer runs.

To open or close a group, click the arrow next to its heading. To rename it, click the pencil. Timers with no group appear below the headings.

**Example: Check your health every minute**

- **Interval in seconds:** `60`
- **Run:** `send health`

In the Run field, `send` means send the command to the game, as if you typed it.

## Remove a timer

1. Go to Settings > Timers, then click the timer you want to remove.
2. In the Timer dialog, click **Delete**.

## What a timer can run

The Run field takes one line, written the same way as a line in a script. The first word says what kind of line it is. These three kinds cover most timers:

| Run | What happens each time the timer goes off |
|---|---|
| `send look` | Sends `look` to the game, as if you typed it |
| `run CheckWounds` | Runs your script named CheckWounds |
| `echo An hour has passed` | Shows that message on your screen; the game doesn’t see it |

To do more than one thing, put the steps in a script and have the timer run it.

## Run a timer once

When you select **Run once**, the timer waits its interval one time, runs, then pauses itself. It doesn’t run again until you start it: click the **Resume** button on its row, or turn it on from a script.

**Example: Stand up in 30 seconds**

- **Name:** `StandUp`
- **Interval in seconds:** `30`
- **Run:** `send stand`
- **Run once:** Selected

Thirty seconds after you save the timer, `> stand` goes out once, and the timer’s row shows paused.

## Turn a timer on or off from a script

A script can pause a timer and start it again using the timer’s name:

```
turn off timer StandUp
turn on timer StandUp
```

`turn off timer StandUp` pauses the timer named StandUp. `turn on timer StandUp` starts it again. Capitalization in the name doesn’t matter.

- **A timer that’s already on is left alone.** Its countdown doesn’t start over.
- **Other timers aren’t affected.** Turning one timer on or off never restarts another timer’s countdown.
- **Unknown names are reported.** If no timer has that name, Merlin reports it and the script keeps going.

## How timers work when the game is busy

A timer doesn’t cut in front of what you’re already doing. It follows the same rules as a script.

- **It waits for the last command to be answered.** If your hunting script just sent an attack, the timer’s command goes out after the game replies to that attack.
- **It waits out the delay.** 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 timer goes off during a delay, it waits until the delay ends, then sends. A timer that sends nothing, one that only records a value, starts right away.
- **It takes turns.** If a timer and a script are both waiting to send, the one that sent least recently goes first, so neither can take over the game.

### Late and overlapping runs

A timer can run a few seconds late when you’re busy, but it’s never skipped.

Each time a timer goes off, it starts fresh. If the last run hasn’t finished, it’s stopped and the new run takes its place.

A script line whose condition cannot be read, such as a game value the game has not reported yet, stops that run and says why. It says so again at every tick until the value exists. Check the value with `is set` first, or set it before the condition reads it.

**Tip:** Set the interval long enough for one run to finish.

## When a timer doesn’t run

- **You’re not in the game.** At the login menu or while you’re switching characters, timers wait. Otherwise, a command like `health` would go to the menu instead of the game.
- **The timer is paused.** The **Pause** button on the timer’s row stops it, and so does `turn off timer` in a script. The row dims and shows a paused tag. To start it again, click **Resume** or use `turn on timer`.
- **The Run field is empty.** There’s nothing to send.

## Edit the timers file

Timers are stored one per line in `timers.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` |

```
#timer {60} {send health} {name=Health}
#timer {600} {run CheckWounds} {paused, group=Upkeep, name=WoundsCheck}
#timer {30} {send stand} {paused, once, name=StandUp}
```

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

| Braces | What they hold | Example |
|---|---|---|
| First | The seconds between runs | `60` |
| Second | The command to run | `send health` |
| Third | The options | `name=Health` |

### Options

- `name=` is the timer’s name. Merlin uses it in messages about the timer, and scripts use it to turn the timer on or off.
- `paused` appears when the timer is paused.
- `once` appears when Run once is selected.
- `group=` is the heading the timer appears under.

`paused`, `once`, and `group=` appear only when they’re different from the default.

### 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 timers in it, so keep any notes you want to save somewhere else.

### 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, close the editor and save the file again.

## Choose a timer, trigger, or script

| Use a | When |
|---|---|
| Timer | Something should happen on a schedule, no matter what the game is saying, such as a periodic check, reminder, or refresh |
| Trigger | The game’s own words should cause it |
| Script | It has steps |

To do several steps on a schedule, put the steps in a script and have a timer run it.

To learn more, see the [Triggers Manual](MANUAL-TRIGGERS.md) and [Scripting Manual](MANUAL-SCRIPTING.md).