Your first superweapon
Solar Flare is the example mod that ships with the game, in examples/mods/solar_flare/. It adds a superweapon called Solar Flare. You will read it file by file, then change it.

Directorysolar_flare/
- mod.json
Directorydata/
- superweapons.json the new weapon
- ships.json a cheaper Destroyer
Directorystrings/
- en.json the text
Directorysprites/
- flare.png a 12x12 icon
- main.luau the logic
The weapon is data
Section titled “The weapon is data”A new superweapon does not need new art or a new console. It borrows them from a base weapon, and you change the numbers.
{ "add": { "solarflare": { "base": "sunlance", "name": "@flare.name", "short": "@flare.short", "color": [255, 170, 60], "price": 600, "cooldown": 240, "knock": 0.6, "kills": 2, "scorch": 12, "silo_damage": 0.8, "rebuild": 0.7, "milestone": { "stat": "bestTier", "at": 6, "text": "@flare.milestone" } } }}addmakes a new record. Its id,solarflare, is how code refers to it."base": "sunlance"takes the Sun Lance’s console, art and strike rules. You get its aiming puzzle for free.price,cooldown,kills,scorchand the rest are fields of the superweapons kind. A new weapon needsbase,name,short,color,priceandcooldown; the rest are optional.milestonegives every player one free charge the first time their best missile tier reaches 6.
Text that starts with @ is a key into your strings file:
{ "flare.name": "Solar Flare", "flare.milestone": "FIRST SOLAR FLARE", "flare.short": "FLARE", "flare.landed": "FLARE %d LANDED", "flare.count": "FLARES"}Keeping text in strings/ means a translator can add strings/de.json without touching your data. %d is filled in by mod.text, below.
Start the game with the mod. The weapon is in the WEAPONS sheet, and the Sun Lance console opens with your weapon’s name in the title:

The rules hook
Section titled “The rules hook”Data covers most of a weapon. For the rest, main.luau can edit the strike plan: the list of what the weapon is about to hit, after the data has trimmed it.
-- 1. RULES. The strike plan is the list of what the weapon will hit. The data-- file already trimmed it (knock, kills, scorch); this hook has the last-- word. It only ever runs in the server VM (the client registers it too,-- harmlessly). A level 1 flare may destroy at most one missile.mod.weapons.on_plan("solarflare", function(plan, ctx) if ctx.level == 1 then for i = #plan.destroy, 2, -1 do plan.destroy[i] = nil end endend)plan.destroy holds the missiles the strike destroys. A level 1 flare keeps only the first. The weapons API lists every list in the plan and what ctx holds.
Events
Section titled “Events”weapon_landed fires when any superweapon lands, in both VMs. The server keeps the score; the client makes it felt.
-- 2. EVENTS. "weapon_landed" fires in both VMs for every superweapon.local flares = 0 -- this VM's count of flares that landed since the game started
mod.on("weapon_landed", function(e) if e.weapon ~= "solarflare" then return end flares += 1 if mod.is_server then -- the server keeps a lifetime total in the save file local total = (mod.save.get("total") or 0) + 1 mod.save.set("total", total) mod.game.toast(mod.text("flare.landed", total)) else -- the client shows it: a white flash and a shake (both respect the player's -- "reduce motion" and shake settings) mod.fx.flash(0.5, 0.25) mod.fx.shake(5) endend)mod.saveonly exists in the server VM. The total survives restarts (Save data goes deeper).mod.game.toastfrom the server shows a banner to every player.mod.fx.flashandmod.fx.shakerespect the player’s motion settings, so you do not need to check them.
The counter
Section titled “The counter”The last block draws a widget in the HUD’s style. It stays hidden until the first flare has landed:
-- 3. UI (client only; on the server these calls do nothing). A small widget-- in the HUD style, top right, under the menu button.mod.ui.widget({ id = "counter", anchor = "top_right", w = 84, h = 18, draw = function(g) g.sprite("flare", 3, 3) g.text(mod.text("flare.count") .. " " .. flares, 19, 5, mod.ui.colors.gold) end, -- only once the first one has landed visible = function() return flares > 0 end,})
g.sprite("flare", ...) draws sprites/flare.png. The frame comes from the game.Change it
Section titled “Change it”-
Copy
examples/mods/solar_flareinto your mods folder and rename the copy’sidinmod.json, for example tomy_flare. Two mods with the same id do not both run. -
Make the flare cheaper and quicker to recharge. In
data/superweapons.json, set"price": 200and"cooldown": 60. The field table gives each field’s range:cooldownis 0 to 86400 seconds. -
Restart the game. If the mod fails, the MODS page shows the first error; Troubleshooting has every message.
Next: react to events, including stopping a strike before it happens.