Wait for a line to appear in a log
log_watchBlock until a log line matches the given text in a tModLoader log, then return it. Offset tracking prevents missed or duplicate lines; a timeout returns matched: false.
Instructions
Block until a log line matches, instead of polling log_since by hand.
Args:
name: A log filename from log_files.
contains: Case-insensitive text to wait for. REQUIRED — without one
this matches the first line written and is log_since wearing a
longer name.
offset: Where to start reading. 0 includes the log's HISTORY, which is
usually what you want ("did the mod load" is a question about a
line that is already there). Pass a previous call's next_offset
to watch only what comes after it.
fingerprint: The fingerprint from an earlier log_since/log_watch,
when resuming — see log_since for the rotation it catches.
Within one call the polls carry it themselves.
timeout: Seconds for the WHOLE call, spent across every poll.
poll: Seconds between reads.
THE OFFSET IS THE MECHANISM. Each poll resumes where the last stopped, so a line is matched exactly once — never missed in the gap between two polls, and never re-reported on the next. A watch that re-read the file from the top would match a line written before the wait began and call it news, which is how "wait for the crash" passes on the crash from the PREVIOUS run.
Not matching is an ANSWER, not an error: it returns matched: false with
the resume point, so "nothing was logged for 30s" is as expressible as
waiting for something. A MISSING log still raises, because that is nobody
having been asked rather than a line failing to arrive.
restarted means the log rotated during the wait — tModLoader zips the
previous run's logs and starts fresh, so your offset stopped meaning
anything and the lines you are holding came out of a different file.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| poll | No | ||
| offset | No | ||
| timeout | No | ||
| contains | Yes | ||
| fingerprint | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lines | Yes | ||
| polls | Yes | ||
| elapsed | Yes | ||
| matched | Yes | ||
| restarted | Yes | ||
| fingerprint | Yes | ||
| next_offset | Yes |