Skip to content

Lua API Changelog

Jump to bottom
Nicholas van de Walle edited this page Jun 21, 2026 · 1 revision

Lua API Changelog

Every change to the cl.* Lua macro API, newest first. This page is maintained alongside the Lua API Cheatsheet and Lua Macro Guide whenever the API changes (see the lua-docs-sync skill in the source repo).

Section headings match the TrowlLord release the change ships in; Unreleased collects changes already in the code but not yet tagged. ⚠️ Breaking marks a change that can stop an existing macro from working — see Lua API Migration for how to update.

Categories per release: Added (new functions/values), Changed (different signature/behavior), Deprecated, Removed, Fixed.

Unreleased

Added

  • cl.play_sound(id [, volume [, bypass]]) — play a CL_Sounds effect by id. volume is a "70%" string or a number (≤1 = fraction, else percent); bypass = true plays at exactly volume, ignoring your volume slider and the master/background mute (a reliable alert).
  • cl.on_text([filter,] fn) — run fn(text, frame, category) for each new incoming text-log line. filter is an optional Lua pattern string or { pattern=, category= }; every matching handler fires (unlike cl.bind_text).
  • cl.select(name) / cl.select_item(name) — select a player / inventory item by full or partial name (no argument clears). The setters for cl.selected_player() / cl.selected_item().
  • cl.equip_num(n) / cl.use_num(n) — equip, or smart hand-aware "use", the item bound to inventory number slot n (0–9), exactly like Alt+n.
  • cl.num_item(n) — read inventory number slot n (0–9) as { name = , equipped = , right_hand = }, or nil if the slot is empty.
  • cl.bubble_fade([on]) — turn speech/thought-bubble fade-out on/off, or toggle with no argument.

No breaking changes.

0.0.12 and earlier

The initial Lua 5.4 macro API:

  • Output: cl.send, cl.message, cl.move.
  • State reads: cl.my_name, cl.my_simple_name, cl.selected_player, cl.selected_item, cl.my_item, cl.frame, cl.textlog, cl.textlog_latest, cl.simple_name.
  • Registration / events: cl.bind_key, cl.bind_click, cl.bind_double_click, cl.bind_text, cl.on_login, cl.on_logout, cl.register.
  • Timing: cl.pause.

Clone this wiki locally