Praetor Scripts¶
What a mode is¶
A mode is a single Lua file that watches your game text as it scrolls by and sends commands on your behalf: auto-attacking, looting corpses, running a training loop, or walking a route. Only one mode runs at a time. Starting a new one stops whatever was running before it. To stop everything and return to manual play:
/mode disable
Not every file in a scripts folder is a mode. Files whose names start with lib_ are shared helpers that modes load for common logic. They never appear in the mode list and there's no reason to start one.
Install the shared scripts¶
The shared library lives on GitHub as praetor-scripts. Praetor 0.6.0 can install and update it directly:
- Press Esc, choose Automation, then Script Manager.
- Choose Add praetor-scripts.
- The source installs disabled and Restricted. Review the source, then choose Enable and confirm the Restricted permissions.
Praetor follows the highest stable version tag. If a repository has no stable semantic-version tag, it follows that repository's default branch instead. The built-in Git client means this works even when the computer does not have a separate git command installed.
The suggested praetor-scripts source checks for updates in the background at startup. A startup check only reports that an update is available; it never installs one. Other repositories can opt in with Check at startup.
To update, choose Check for updates. When no Lua mode is active, that one button temporarily unloads the source, downloads and validates the update, reloads the scripts, and restores the source's previous enabled state. A failed update rolls back to the working checkout. You do not need to disable, update, reload, and re-enable it yourself.
Script Manager also accepts other anonymously readable HTTPS Git repository URLs. Authentication, private repositories, ZIP sources, and prerelease tracking are not supported in 0.6.0.
Local script directories¶
Keep your own scripts in a local directory so a managed update can never overwrite them. The default directory is:
~/.config/praetor/scripts/
On Windows that is:
C:\Users\<you>\.config\praetor\scripts\
In Script Manager → Local directories, add or browse to a folder, reorder it if needed, and choose Save directories. Saving reloads the available modes. Existing local directories remain fully Trusted for compatibility, so only add code you trust.
Restricted and Trusted sources¶
Every managed source starts Restricted and runs in its own isolated Lua environment. It receives Praetor's documented automation APIs plus Lua's base, table, string, math, and coroutine libraries. It can load Lua helpers only from its own managed checkout. It cannot access files, processes, environment variables, debugging APIs, dynamic loaders, native modules, or another source's libraries.
You can explicitly choose Make Trusted… for code you have reviewed. Trusted sources receive the legacy full Lua environment, including os, io, debug, and normal package.path imports, and can act with Praetor's permissions. Changing trust or enablement rebuilds the Lua runtime transactionally. If a mode is active, Praetor asks before stopping it.
Restricted code can still send game commands through Praetor's automation functions. Restricted means isolated from the computer and other script sources; it does not mean the script cannot play the game for you.
Run a mode¶
Start a mode with /mode followed by its name and any arguments it takes. Names are matched regardless of case, and /sm is a shorter alias:
/mode loot bronze|alanti
/sm idle
As you type the mode's name, the hint line above the input shows that mode's arguments and a one-line description, so you never have to open the file to check. Type the name, a space, and read the hint before pressing Enter.

/list opens Automation → Switch mode, which shows every loaded mode with its description. Use it to browse what you have. Clicking a mode there starts it with no arguments, so for anything that takes arguments, use /mode and the hint line instead.

To stop the running mode:
/mode disable
Alt+M steps through a short list of modes you choose, useful for the ones you switch between often. To pick them:
- Press Esc
- Choose Automation, then Quick-cycle modes
- Toggle the modes you want in the cycle
- Save
To watch what a running mode is doing, turn on Echo script commands under Esc → Input & commands → Input behavior. Every command the mode sends then shows in the output in italics.
Completion handoffs¶
Modes that run to completion can start another mode or send one final game command instead of stopping. Put the handoff after all arguments for the current mode:
/mode loot bronze|alanti after_mode:wagon romulus
/mode wagon romulus after_do:look in wagon
/mode idle after_ps:stand&&climb wall;;look
The first after_mode:, after_do:, or after_ps: token begins the handoff payload, so it and every later token belong to the handoff. after_mode: treats the first value as the next mode and passes the remaining tokens to that mode. after_do: joins the payload into one game command, disables automation, then sends it. after_ps: joins the payload into one PraetorScript expression and runs it after disabling automation.
Because the next mode receives the remaining tokens, mode handoffs can nest:
/mode loot hand after_mode:wagon romulus after_mode:idle
Not every mode supports completion handoffs. The hint line and Switch mode screen show [after_<mode|do|ps>:<mode|command|praetorscript>] when one does. The older after:<mode> spelling remains available for compatibility, but it can pass only a mode name, not arguments for the target mode.
Five modes to learn from¶
The shared library has a few dozen modes. These five cover the patterns the rest are built from, and each links to its source on GitHub so you can read the real thing.
idle¶
idle.lua is the simplest useful mode. It sends a status check, then waits until the game reports full fatigue and hands off to whatever you chained after it. Every 7 to 11 minutes it sends another status check so the game doesn't drop you for idling.
/mode idle
/mode idle after_mode:macro
What it shows you: a single reaction that matches one phrase from the game (Fatigue: 100%), a timer set with set_interval, a notification with notify, and the lib_after library that implements completion handoffs. Lua notifications appear only when Enable script notifications is on under Esc → Notifications & logs → Notifications.
wagon¶
wagon.lua sells the contents of a wagon (or another container) to a vendor. It takes an item from the container, offers it to the vendor, and repeats until the container has nothing left that matches.
/mode wagon romulus # alias from lib_wagon: the item list Romulus buys
/mode wagon bronze|boss jovinus # sell bronze and boss items to Jovinus
/mode wagon tin telaria sack # sell tin from a sack, not the wagon
What it shows you: reading arguments in on_start and storing them with state.set, three reactions that form a loop (You take leads to an offer, You offer leads to the next take, You don't see ends the run), and an alias table in lib_wagon.lua so a vendor's whole shopping list is one word.
macro¶
macro.lua is the main combat mode. It rotates through six attack macros against your current target, stands you up when knocked down, rewields a dropped weapon, advances on targets that are out of reach, approaches new arrivals, and finishes off targets that fall unconscious. It needs the in-game macros described in the next section.
/mode macro
/mode macro nokill # rotate attacks but never send the kill command
What it shows you: a mode that leans on two libraries, lib_strings.lua for the game phrases it reacts to and lib_combat.lua for the rotation, approach, kill, and stall-watchdog logic that every combat mode shares. It also declares metrics with metrics.track so the Metrics tab counts kills, crits, and actions.
loot¶
loot.lua walks through every corpse in the room, taking the items you list. Items are separated by a pipe and can't contain spaces, so multi-word items go in the alias table in lib_loot.lua.
/mode loot bronze|alanti|retalq
/mode loot metals # alias from lib_loot: retalq|boison|alanti|sooty|iron
/mode loot hand drop:rawhide # loot the "hand" list, but drop any rawhide taken
/mode loot bandit start:3 # start at the third corpse
/mode loot metals from:pile # use numbered piles instead of corpses
/mode loot hand stow:pack stow_start:3 # begin with the third pack and rotate as packs fill
Every option is a key:value token and can appear in any position alongside the item list. start: chooses the first numbered source, from: replaces “corpse” in the get command, stow: names a one-word stowage container, stow_start: chooses the first instance of that container, and drop: accepts a pipe-delimited list to discard after taking it.
What it shows you: named arguments picked out of the argument list, source and stowage counters kept in state, reactions whose match can be a list of phrases, and an action function using the matched text itself to decide what to do.
empty_containers¶
empty_containers.lua takes every container of one type out of a source, empties it into a destination, and drops the empty. With no arguments it empties sacks from the wagon into the wagon.
/mode empty_containers
/mode empty_containers pouch wagon wagon
/mode empty_containers sack wagon chest
What it shows you: default values for arguments (args[1] or 'sack'), and a four-step loop of reactions (You take, then You empty, then You drop, then back to the next take) that ends when the source runs out. It is the shortest complete example of the take-act-repeat shape most utility modes use.
What the combat macros need¶
The combat modes don't fight for you directly. They send short commands like at1 and k1, and the game turns those into your real attacks through its own @macro system. Each character needs these macros defined once, before any combat mode will do anything useful.
| Macro | Used by | Should send |
|---|---|---|
| at1 to at6 | all combat modes | your attack rotation, one move per slot (chain_macro also uses at7) |
| app1 | all combat modes | approach first target: app 1 <target> or your weapon's approach move |
| adv1 | all combat modes | advance on first target: advance 1 <target> |
| k1 | all combat modes | kill first target: kill 1 <target> (fslash 1 <target> for falx) |
| r | all combat modes | rewield: wield <weapon> |
| doStance | all combat modes | your weapon's stance move |
| st1 | falx_macro | stun: bash 1 <target> head |
| dr | falx_macro | drag: ankle <target> |
| ev | falx_macro | eviscerate: evisc <target> |
| nm | chain_macro | no-mind attack |
A worked example for a one-handed sword. Type each of these once per character. The game prompts you for the command string after each one:
@macro at1 -> slash <target>
@macro at2 -> thrust <target>
@macro at3 -> chop <target>
@macro at4 -> slash <target> high
@macro at5 -> thrust <target> low
@macro at6 -> chop <target> head
@macro app1 -> app 1 <target>
@macro adv1 -> advance 1 <target>
@macro k1 -> kill 1 <target>
@macro r -> wield sword
@macro doStance -> stance <target>
Set your target first with the game's own target command. The combat modes act against your current target:
target rat|snake
For the game side of macros and targeting, see Macros and Macros and Targeting.
Troubleshooting¶
| Symptom | Likely cause | Fix |
|---|---|---|
| mode not in the mode list | source disabled, local folder not added, or scripts not reloaded | check the source under Automation → Script Manager, then use the Reload scripts quick action |
| "unknown mode" | typo, or the file is a lib_*.lua helper (it never appears in the list and there's no reason to start one) |
check the list with /list (names are matched regardless of case) |
| combat mode starts but nothing attacks | @macro entries missing on this character |
see the macro table above, and watch for the game answering "I don't understand" to at1 |
| an expected action does not happen | a Lua callback hit the 2-second limit or raised an error | check the app log; Praetor aborts that callback but leaves the mode running |
| error when reloading | a required lib_*.lua file is missing, or the managed checkout failed validation |
check Script Manager and the app log; managed updates roll back automatically |
| commands keep going after you stop it | the queue is still draining | /mode disable, then Alt+X |
| changes to a script do nothing | it wasn't reloaded | use the Reload scripts quick action. This also clears cached libraries |
The app log is at:
~/.local/state/praetor/tec.log (macOS and Linux)
C:\Users\<you>\.local\state\praetor\tec.log (Windows)
If you need to ask for help, paste the last few lines mentioning your mode into #unofficial-clients along with the exact /mode command you ran.
Modify an existing script¶
Copy the mode file from the shared folder into your own scripts folder under a new name. A mode's name is its filename, so a copy of macro.lua saved as mymacro.lua runs as its own mode without touching the shared original:
/mode mymacro
Use the Reload scripts quick action after saving any change. Reloading clears cached libraries and immediately refreshes changed, added, and removed mode names, descriptions, and input hints.
Change the attack rotation. In macro.lua, the rotation is a plain list near the top of the file:
local default_actions = {'at1', 'at2', 'at3', 'at4', 'at5', 'at6'}
Drop it to three slots, or reorder it to lead with your hardest hit:
local default_actions = {'at3', 'at1', 'at2'}
React to a new phrase. lib_strings.lua is a shared helper that several combat modes load for the lines they react to. Its must_stand list currently reads:
S.must_stand = {
'Several trainers drag you back to the start.', 'You must be standing',
"You do not meet that stance's requirements",
}
Add a phrase the game sends that isn't covered yet, say, a stance-break message:
S.must_stand = {
'Several trainers drag you back to the start.', 'You must be standing',
"You do not meet that stance's requirements", 'You are knocked off balance',
}
Editing a lib_ file in the shared folder affects every mode that loads it. Copy the whole set (the mode plus the libraries it needs) into your own folder first if you want the change to stay isolated.
Write a simple mode¶
A mode is a Lua file that returns a table. Here's a complete one, greet.lua, that waves back whenever someone waves at you:
local M = {}
M.desc = 'Say hello whenever someone waves at you'
M.chains = false
M.hidden = false
function M.on_start(args)
log('greet mode started')
end
function M.on_stop()
log('greet mode stopped')
end
M.reactions = {
{
match = 'waves at you',
action = function(text)
send('wave')
end,
},
}
return M
Reading it top to bottom:
- M.usage is the mode's argument signature without the mode name. Omit it when the mode takes no arguments.
- M.desc is the one-line description the mode list and the hint line show next to the mode's name.
- M.chains should be true only when the mode implements completion handoffs. Praetor then adds the handoff suffix to its hint.
- M.hidden hides the mode from input hints when true. It can still be run by name and still appears in the Switch Mode window.
- on_start runs when the mode is activated, and gets the words you typed after the mode name as a list of arguments.
- on_stop runs when you switch away.
- reactions is a list of match and action pairs. A match is a case-sensitive substring, or a pattern where
*matches any run of characters and?matches one character. Put^at the start or$at the end to anchor that edge of the line; use both for a whole-line match. A list of strings matches if any of them does. When a line matches, the action runs with that line as its argument. - send queues a command for the game.
- return M at the end hands the finished mode to Praetor.
A reaction can also take two optional fields. condition is a function returning true or false that gates whether the action fires, useful for checking your health or your own state before acting. delay is a number of milliseconds to wait before the action runs. Neither is needed above.
Save the file in your scripts folder, choose Reload scripts, then:
/mode greet
A second example: count how many times you've waved, using a timer and per-mode state. Replace on_start with:
function M.on_start(args)
state.set('waves', 0)
set_interval(function()
log('waved ' .. state.get('waves') .. ' times so far')
end, 60000)
end
and add one line to the reaction's action, before the send:
state.set('waves', state.get('waves') + 1)
State is scoped to the current mode and normally clears when you switch modes. Timers started with set_interval or set_timeout are canceled automatically when the mode stops, so there's nothing to clean up in on_stop.
Use state.persist(key) only for accumulated long-term records such as observations, discovered map data, or lifetime statistics. Persistent data follows the active character profile and appears under Automation → Long-term script data. state.unpersist(key) removes a legacy persistent key during a migration.
Player-visible preferences and resumable workflow inputs belong in the active character's Variables instead:
local weapon = variables.get('weapon') or 'gladius'
variables.set('weapon', weapon)
send('wield ' .. weapon)
variables.get(name) returns a string or nil. variables.set(name, value) validates and saves the string before Lua continues. These are the same values shown in the Variables view and expanded by ${name} in PraetorScript.
Run PraetorScript from a mode¶
The normal send(command) function queues one literal game command; it does not interpret PraetorScript syntax. When a mode deliberately needs variables, ;;, &&, or $() controls, submit the complete expression through praetor_script(expression) instead:
function M.on_start(args)
praetor_script([[$(repeat "search chest" count ${tries:3});;$(notify "Search" "Finished")]])
end
This uses the same parser, executor, Stop control, and Automation Bar status as PraetorScript entered by hand. It also follows the same validation, timing, cancellation, disconnect, and shutdown behavior. See the PraetorScript guide for the complete language.
Rules that bite¶
- Only one mode runs at a time. Starting another stops the current one.
- Each piece of Lua (a reaction, a timer callback, on_start, on_stop) may run for at most 2 seconds. If it doesn't finish, Praetor aborts it and logs an error, then keeps going.
- send queues a command rather than sending it instantly. Commands use a 1-second delay by default, or your own delay passed as a second argument in milliseconds, and are sent at least 500ms apart.
- praetor_script is the explicit opt-in to PraetorScript processing. A normal send never expands variables or treats separators as controls.
- A command identical to one already waiting in the queue is dropped rather than queued twice.
- The queue holds 20 commands and drops anything past that, except high-priority commands (configured in the menu), which push their way in instead of being dropped.
- Matching is plain text, not a regular expression, and a reaction's Lua only runs when its match actually matches a line.
- Matching is case-sensitive.
- The first reaction that matches a line wins. Later reactions in the list are not checked.
- Reload scripts clears cached libraries, so an edit to a lib_ file only takes effect after a reload.
Learn more¶
- Lua API reference: every function, state, metrics, and timer Praetor exposes to scripts
- praetor-scripts: the whole shared library, with a README that lists every mode
- Lua 5.1 reference manual
- Ask in #unofficial-clients if you get stuck
See also¶
- Praetor: install and first login
- Praetor Guide: using the client
- TEC Discord: #unofficial-clients