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.
{ "id": "truce", "name": "Truce", "version": "1.0.0", "api_version": 1, "author": "you", "description": "No superweapons in the first three minutes."}{ "truce.over": "TRUCE OVER: SUPERWEAPONS ARMED", "truce.refused": "TRUCE: NO SUPERWEAPONS YET"}How events work
Section titled “How events work”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.
Build it
Section titled “Build it”-
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) -
Refuse early strikes.
weapon_fireis a cancel event: if any handler returnsfalse, 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 thenmod.log("refused", e.weapon, "from", e.by)return falseendend)mod.logwrites to the game’s log with your mod’s id in front. -
Announce the end.
mod.after(seconds, fn)runsfnonce, 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 thenmod.after(TRUCE, function()mod.game.toast(mod.text("truce.over"))end)endmod.text("truce.over")looks the key up instrings/, in the player’s language. -
Make strikes felt. After the truce, every hit shakes the screen.
weapon_landedfires 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 thenmod.fx.shake(if e.weapon == "ion" then 8 else 4)endend)
See it
Section titled “See it”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 botThree minutes in, the banner TRUCE OVER: SUPERWEAPONS ARMED shows for everyone, and strikes land again.
Limits
Section titled “Limits”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.