Writing a Module

The File

The server loads every *.lua file directly in scripts/modules, in name order. It skips a file whose name starts with _ and every subfolder. A file declares one or more modules; name it after the module it declares.

module "boss_alert" {
  api = 1,                    -- required: the module api this file is written for
  title = "Boss alert",       -- shown by %mod list
  version = 1,                -- your own number, shown by %mod list and %mod status
  enabled = true,             -- false loads it switched off until %mod enable

  settings = { ... },         -- values an operator changes with %mod set
  commands = { ... },         -- staff commands, typed after %
  player_commands = { ... },  -- player commands, typed after . in chat
  on = { ... },               -- notifications: event name = function(m, ev)
  gates = { ... },            -- decisions the game waits for
  every = { ... },            -- repeating timers
  daily = { ... },            -- once a day at a fixed time
  tables = { ... },           -- custom database tables
  messages = { ... },         -- new wire messages, for GoMMO Client
  on_start = function(m) end, -- after the module loads or is enabled
  on_stop = function(m) end,  -- before it stops, reloads or is disabled
}

A module name is 2 to 32 lower-case letters, digits and _, starting with a letter, and is unique on the server. It is the module's namespace for its settings, stored data, tables and log lines.

Only the parts you fill in do anything. The parts have their own pages: settings and commands, on, gates, tables and messages.

What a Hook Receives

Every hook receives m, the module's own handle, first. m carries the module's settings, storage, timers and messages, and the rf table carries the game. Both are listed on Verbs.

Top-Level Variables

Top-level local variables are the module's memory. Every hook in the file shares them, gates included, so a gate can read a table that a handler fills. A reload or restart starts them afresh, so keep anything that must last in storage, or save it in on_stop, as examples/cash_regen.lua does.

Reloading

%mod reload re-reads the whole folder and checks every file first.

• A file that fails keeps its previous version running. The problems are in the reply and the server log, with the file, the key and a suggestion: unknown key "comands"; did you mean "commands"?.
• A file that loads starts afresh. Its settings and stored data survive, because they are in the database. Its Lua variables and pending timers do not.
• An unknown key is a warning. With lua.strict on, it refuses the module.

The server's first placement of monsters happens before modules start, so a module does not see those spawns as events. Use on_start and rf.monsters to learn what is already standing:

on_start = function(m)
  for _, boss in ipairs(rf.monsters(m:setting("bosses"))) do
    alive[boss.code] = boss
  end
end,

Timers

every = { { seconds = 300, run = function(m) end } },  -- at least one second apart
daily = { { at = "05:00", run = function(m) end } },   -- 24-hour clock, server time zone

m:after(seconds, function(m) ... end) runs a function once, from 0.1 seconds to 7 days later, and returns an id for m:cancel(id). A module may hold 64 pending timers. Timers run on the server clock and are not saved: they start again from a reload or a restart.

An interval that a setting controls is easiest as a one-minute every that counts minutes, as examples/global_notice.lua does.

m:now() is the server time in Unix seconds. m:clock() and rf.clock() are the local time as a table. The os library is not available.