Wiki home

Lua

Logs and running

Lua · Updated 09 November 2026

Log with bwu.log, find your run logs, and run scripts from the GUI or a console.

Log with bwu.log

Use bwu.log rather than print:

bwu.log.debug("checking bank at", tile)
bwu.log.warn("no food left")

bwu.log.debug, info, warn and error take any values and join them with spaces. print and io.write still work, and their output shows in the GUI's log view and in the run log.

Run logs

Under bwu_host, every run of a script writes one file under:

~/.botwithus/logs/scripts/<script-slug>/
  • It holds DEBUG and up: bwu.log, print, io.write and io.stderr:write. The console shows INFO and up.
  • It is redacted before it reaches disk: account and character names, emails, tokens, IP addresses and your user folder are removed.
  • When a run stops on an error, the file ends with a crash block: the phase (on_start, on_loop with its loop number, or on_stop), the traceback from where the error was raised, the innermost frame in your code, and the last 200 host calls the script made.
  • Tracebacks use short file names, such as myscript.lua:12, rather than full paths that could contain your Windows user name.

Running

In the GUI. Start bwu_host with no arguments, pick a script from ~/.botwithus/scripts/lua and a client, and start it.

  • A file that returns its script table is a plugin. The GUI shows its manifest and settings and drives its lifecycle.
  • A file that returns anything else is self-running. The GUI lists it by file name with no settings and runs it like the command line does. Such a script should check bot.stopping() in its own loops.

From a console.

bwu_host --lua $HOME\.botwithus\scripts\lua\woodcutter.lua

The file is called with no arguments, so the self-run guard starts the script.

Common problems

Symptom Cause
The script waits far longer than expected on_loop returns a delay written in milliseconds. In Lua the number is server ticks.
The script starts when the GUI only lists it The self-run guard is missing.
attach during load: guard the self-run The same: the file attaches at its top level.
version is refused It is a number. Write it as a string: "1.0".
Stopping takes 10 seconds, then the process ends A busy loop never calls ctx:sleep_ticks or checks ctx:stopping().