Running Modules

Switching One Module

command	does
`%mod list`	what is loaded, with each module's commands
`%mod status`	every module's state and counters
`%mod status <module>`	one module: its settings, errors and gate counters
`%mod reload`	load or reload every module file
`%mod disable <module>`	switch one module off, remembered across restarts
`%mod enable <module>`	switch it back on, which also re-arms it after repeated errors
`%mod set <module> <setting> <value>`	change one setting

A Lua error in a hook is logged with the file and line, counted in %mod status, and answered to the caller of a command. Ten errors inside a minute switch the module off until %mod enable, and its gates then answer with their fail policy. A module can switch itself off with m:disable("reason").

Catching an Expected Error

When an error is expected and harmless, such as a full bag or a player who logged out, catch it:

local ok, err = pcall(rf.give_item, id, "irtal01", 1)
if not ok then rf.notice(id, "Your bag is full.") end

A call that runs over its time or instruction budget is stopped, and pcall cannot catch that.

Limits

limit	default	setting
one event, timer, command or inbound message	100 ms and 1,000,000 instructions	`lua.event_budget_ms`
a gate	20 ms and 200,000 instructions	`lua.gate_budget_ms`
a damage gate	20 ms and 20,000 instructions	`lua.damage_budget_ms`
`on_start`, `on_stop`	2 s
text built in one call	64 MiB
events waiting per module	1024	`lua.event_queue`
modules gating one point	4	`lua.max_gates`
pending timers per module	64
`m:log` lines	20 a second; more are dropped and counted

A handler with a lot to do should do a batch and schedule the rest with m:after: Examples shows how.

What a Module Cannot Do

A module cannot read or write the game's own tables, send raw bytes, send anything to an official client, open files, or see another module's data.

Modules are code you run on your own server. Only Lua's base, string, table and math libraries exist; io, os, debug, package, coroutine, load and require do not. The standard and rf tables are read-only. print writes to the server log.

Troubleshooting

Nothing happens. Is lua.enabled on? Does %mod list show the module? Is the file directly in scripts/modules, not in examples/, and without a leading _?
%mod reload reports a problem. It names the file, the module and the key. An unknown key or event comes with the closest valid name.
A module stopped working. %mod status <module> shows its state, its counters and its last error. Fix the cause, %mod reload, then %mod enable <module>.
Lines from m:log are missing. More than 20 lines a second are dropped and counted.

The `%mod` Commands

command	lowest staff level
`%mod reload`	3
`%mod enable`	3
`%mod disable`	3
`%mod set`	3
`%mod status`	1
`%mod list`	1
`%mod`	1

Server Settings

These are on the GameCP's Settings page, under Lua Modules.

setting	default	what
`lua.enabled`	`true`	Lua modules. The kill switch for every operator Lua module. ON by default: the server runs whatever modules are in the folder below, and an empty folder costs nothing. Turning it off stops every event, gate, command and timer within seconds, without a restart.
`lua.dir`	`modules`	Module folder. Where the module files are, relative to the server's scripts folder unless absolute. Default: "modules". A file whose name starts with _ is not loaded, and neither is the examples folder. Read at server start.
`lua.player_prefix`	`.`	Player command prefix. What a player types before a module's player command in chat. Default: "." (so .bosses). One to three punctuation characters, never %. Read at server start.
`lua.strict`	`false`	Strict module checking. Off by default: an unknown key in a module is a warning with a suggestion. On refuses the module instead. Read at server start.
`lua.event_queue`	`1024`	Event queue per module. How many events may wait for one module before new ones are dropped and counted. Default: 1024. Range 16 to 65536. Read at server start.
`lua.max_gates`	`4`	Modules per gate. How many modules may gate one gate point. Default: 4. Range 1 to 16. Read at server start.
`lua.event_budget_ms`	`100`	Handler budget (ms). How long one event handler, timer, command or inbound message may run. Default: 100. Range 1 to 2000. Read at server start.
`lua.gate_budget_ms`	`20`	Gate budget (ms). How long one auction, chat or loot gate may run before its declared fail policy answers. Default: 20. Range 1 to 500. Read at server start.
`lua.damage_budget_ms`	`20`	Damage gate budget (ms). How long one damage gate may run. It is on every hit, so keep it small. Default: 20. Range 1 to 100. Read at server start.
`lua.damage_max_factor`	`10`	Damage gate ceiling. The most a damage gate may multiply a hit by; a larger answer is clamped. Default: 10. Range 1 to 1000. Read at server start.
`lua.breaker_errors`	`10`	Errors before a module is switched off. How many errors inside the window below switch a module off until %mod enable. Default: 10. Range 1 to 1000. Read at server start.
`lua.breaker_window_s`	`60`	Error window (seconds). The window the error count above is taken over. Default: 60. Range 1 to 3600. Read at server start.