Skip to content

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.

A match: the Sun Lance console opens with SOLAR FLARE in its title, then the flare lands on an island and a FLARES 1 counter appears top right.
Solar Flare in a match. Captured headless from the game.
  • 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

A new superweapon does not need new art or a new console. It borrows them from a base weapon, and you change the numbers.

data/superweapons.json
{
"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" }
}
}
}
  • add makes 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, scorch and the rest are fields of the superweapons kind. A new weapon needs base, name, short, color, price and cooldown; the rest are optional.
  • milestone gives 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:

strings/en.json
{
"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 Sun Lance console, titled SOLAR FLARE AIM EVERY MIRROR, open over the map.
Same console as the Sun Lance, your weapon's name on top.

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.

main.luau
-- 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
end
end)

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.

weapon_landed fires when any superweapon lands, in both VMs. The server keeps the score; the client makes it felt.

main.luau
-- 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)
end
end)
  • mod.save only exists in the server VM. The total survives restarts (Save data goes deeper).
  • mod.game.toast from the server shows a banner to every player.
  • mod.fx.flash and mod.fx.shake respect the player’s motion settings, so you do not need to check them.

The last block draws a widget in the HUD’s style. It stays hidden until the first flare has landed:

main.luau
-- 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,
})
The FLARES 1 widget: a small navy panel with the flare sprite and gold text.
g.sprite("flare", ...) draws sprites/flare.png. The frame comes from the game.
  1. Copy examples/mods/solar_flare into your mods folder and rename the copy’s id in mod.json, for example to my_flare. Two mods with the same id do not both run.

  2. Make the flare cheaper and quicker to recharge. In data/superweapons.json, set "price": 200 and "cooldown": 60. The field table gives each field’s range: cooldown is 0 to 86400 seconds.

  3. 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.