Skip to content

Your first mod

You will make the Destroyer cost $1,500 instead of $4,000. No code: one folder, two small files. Five minutes.

  1. Find your mods folder. The game reads mods from all of these:

    Where Path
    Next to the game mods/ beside the executable
    macOS ~/Library/Application Support/NukeIslands/mods
    Windows %APPDATA%\NukeIslands\mods
    Linux ~/.local/share/NukeIslands/mods
    iPhone / iPad Files app: On My iPhone > Nuke Islands > Mods
    Any folder the path in FORGE_MODS_DIR

    Create the folder if it is not there. On iPhone and iPad the game makes Mods on first launch; drop .nkp files into it from the Files app (AirDrop, iCloud Drive or a cable all work) and restart the game.

  2. Make a folder for your mod inside it, called my_first_mod, with this file:

    mod.json
    {
    "id": "my_first_mod",
    "name": "My First Mod",
    "version": "1.0.0",
    "api_version": 1,
    "author": "you",
    "description": "A cheaper Destroyer."
    }

    id is how the game tells mods apart: lower case, digits and _. api_version is the mod API you wrote for; this game is at 1. The mod.json reference has every field.

  3. Add the change. Make a data folder and put ships.json in it:

    data/ships.json
    { "patch": { "destroyer": { "cost": 1500 } } }

    The file name is the kind of data you change. patch changes fields of a record that exists: here the cost of destroyer. Every other field keeps its value.

    • Directorymods/
      • Directorymy_first_mod/
        • mod.json
        • Directorydata/
          • ships.json

Mods load once, when the game starts. Quit the game completely and start it again.

From a source checkout, point the game at your folder:

Terminal window
FORGE_MODS_DIR=$PWD/mods ./target/release/forge game/nukeislands

The log (the terminal the game runs in) shows one line per VM:

[mods] server: 1 of 1 active (my_first_mod 1.0.0)
[mods] client: 1 of 1 active (my_first_mod 1.0.0)

The title menu now has a MODS entry. It only appears when a mod is installed.

The MODS page: one row, MY FIRST MOD 1.0.0 BY YOU, with a green ON toggle.
The MODS page with your mod. The toggle turns it off for the next start.

Start a match, build a Dock and open SHIPS. The Destroyer’s price is the one you set:

The SHIPS sheet. Destroyer, HP 180, bay 2, price $1.50K.
Patrol Boat, Carrier and Submarine keep their prices. Only the field you patched changed.

Change the cost to text:

data/ships.json
{ "patch": { "destroyer": { "cost": "cheap" } } }

Restart. The game starts normally, without your mod. The MODS page says why:

The MODS page row for MY FIRST MOD in red: FAILED, data/ships.json: ships.destroyer.cost: expe...
A failed mod never blocks the game. The row shows the start of the reason.

The log has the whole message, with the file, the kind, the record and the field:

data/ships.json: ships.destroyer.cost: expected a number

Every field has a type and a range, listed in the ships reference. A value outside them is an error, not clamped. When a mod fails, look up its message in Troubleshooting.

Put the number back before you go on.

Data files cover most changes. When you need logic, add main.luau. It runs once at start with a mod global. This version changes three fields in the JSON file and prints the result from Luau:

data/ships.json
{
"patch": {
"destroyer": { "cost": 1500, "speed": 45, "damage": 40 }
}
}
main.luau
-- Runs once at start, in the server VM and again in the client VM.
local d = mod.data.get("ships", "destroyer")
mod.log("destroyer now costs", d.cost, "and sails at", d.speed)

The log shows the line twice, once for each VM:

[mod:my_first_mod] destroyer now costs 1500 and sails at 45
[mods] server: 1 of 1 active (my_first_mod 1.0.0)
[mod:my_first_mod] destroyer now costs 1500 and sails at 45
[mods] client: 1 of 1 active (my_first_mod 1.0.0)

Why twice: the game runs the rules in one Luau VM and the screen in another, and your script runs in both. Two VMs explains it. Next, a mod with logic in it: your first superweapon.