Gates

A gate runs while the game waits, before the thing happens, and can refuse it or change it.

gates = {
  auction_list = { fail = "closed", run = function(m, ev)
    if ev.price > m:setting("max_price") then return false, "That price is too high." end
  end },
  damage = { fail = "open", run = function(m, ev)
    return { amount = math.floor(ev.amount / 2) }
  end },
},

What a Gate Returns

A damage gate's answer is clamped between 0 and lua.damage_max_factor times the original hit.

A gate allows, refuses or changes the fields marked changeable, and nothing else. It cannot change who sees an auction listing, so a cross-race auction is not something a module can build.

When a Gate Cannot Answer

Every gate declares fail, and the load refuses one without it.

That covers an error, running over budget, the module being busy, and the module being switched off after repeated errors. A module an operator switched off with %mod disable is skipped.

Fail closed when the gate protects the economy, such as an auction ceiling. Fail open when it only adds something, such as a chat filter.

Inside a Gate

A gate has a tight budget (lua.gate_budget_ms, and lua.damage_budget_ms for damage, which runs on every hit in the game). budget_ms on the gate asks for less.

• Read the event and your module's own Lua tables. Do not loop over players.
• A gate decides, and an on handler acts. Any verb that changes the world raises an error, and so does rf.monsters. rf.notice and the other queries work.
• m:send and bag writes are applied just after the gate returns.
• A bag read returns only what this module has already read or written, and may be empty. bag:keys() is unavailable.
• Custom tables raise an error.

Keep what a gate needs in a top-level Lua table, filled by on_start, commands and handlers. examples/auction_max_price.lua and examples/pvp_penalty.lua both work that way.

At most lua.max_gates modules may gate one point. They run in module-name order, and the first refusal ends the chain.

The Damage Gate

ev.attacker is the attacking player. When the hit comes from something a player owns or commands, ev.source says what (animus, tower, trap, siege, unit, nuclear, potion or drain) and ev.attacker is its owner or master. ev.source is nil for a player's own swing, skill or force.

Gate Reference

auction_list

An item is about to be listed; return false, "reason" to refuse it.

Suggested fail: closed.

chat

A chat line is about to be sent; return false to drop it or {text=s} to rewrite it.

Suggested fail: open.

damage

A hit is about to land; return false to cancel or {amount=n} to change it.

Suggested fail: open.

loot

A player is about to pick an item up; return false to refuse it.

Suggested fail: open.