Skip to content

React to events

You will build Truce: nobody can fire a superweapon in the first three minutes of a match, and everyone gets a banner when the truce ends. Along the way: mod.on, a cancel event, a timer and the two VMs.

The whole mod is mod.json, strings/en.json and main.luau.

mod.json
{
"id": "truce",
"name": "Truce",
"version": "1.0.0",
"api_version": 1,
"author": "you",
"description": "No superweapons in the first three minutes."
}
strings/en.json
{
"truce.over": "TRUCE OVER: SUPERWEAPONS ARMED",
"truce.refused": "TRUCE: NO SUPERWEAPONS YET"
}

mod.on(name, handler) calls handler every time the game reports name. The handler gets one table with the details, the payload: for island_wiped, { from, to, cash }.

Each event fires in the server VM, the client VM, or both. The events table lists all of them, with where they fire and what the payload holds.

  1. Note when the match starts. mod.time() is the game clock in seconds. It stops when the game is paused, so a truce does not run out while the player is in a menu.

    main.luau
    -- mod.time() is the game clock. Note when the match starts.
    local started = mod.time()
    mod.on("match_start", function()
    started = mod.time()
    end)
  2. Refuse early strikes. weapon_fire is a cancel event: if any handler returns false, the strike does not happen. It fires on the server, where the rules run, for players and bots alike.

    main.luau
    -- weapon_fire is a cancel event: return false and the strike never happens.
    -- It only fires in the server VM, where the rules run.
    mod.on("weapon_fire", function(e)
    if mod.time() - started < TRUCE then
    mod.log("refused", e.weapon, "from", e.by)
    return false
    end
    end)

    mod.log writes to the game’s log with your mod’s id in front.

  3. Announce the end. mod.after(seconds, fn) runs fn once, later. A toast from the server reaches every player, so only the server sets the timer. In the client VM this block is skipped.

    main.luau
    -- One banner for everyone when the truce ends. A toast from the server goes
    -- to every player, so only the server sends it.
    if mod.is_server then
    mod.after(TRUCE, function()
    mod.game.toast(mod.text("truce.over"))
    end)
    end

    mod.text("truce.over") looks the key up in strings/, in the player’s language.

  4. Make strikes felt. After the truce, every hit shakes the screen. weapon_landed fires in both VMs, but shaking a screen only means something on the client.

    main.luau
    -- The client VM sees the same strikes land. Make them felt.
    mod.on("weapon_landed", function(e)
    if mod.is_client then
    mod.fx.shake(if e.weapon == "ion" then 8 else 4)
    end
    end)

Start a match with bots that fire early (the game’s --swbots test flag makes them fire every superweapon at you in turn). The log shows each refusal:

[mods] server: 1 of 1 active (truce 1.0.0)
[mod:truce] refused ion from bot
[mod:truce] refused droppod from bot

Three minutes in, the banner TRUCE OVER: SUPERWEAPONS ARMED shows for everyone, and strikes land again.

Handlers run inside the game’s frame, so the game keeps them short:

  • A handler that raises an error 5 times is switched off.
  • A handler that takes more than 4 ms, 3 times, is switched off.

The log says when it happens. The sandbox has the full list. Timers (mod.after, mod.every) have no time limit, but they run in the frame too: keep them quick.

Next: add a HUD widget.