Pack and save format
This is the specification: what the game reads from a mod. It is stable and public. For how to write a mod, start with the tutorials.
Where mods live
Section titled “Where mods live”On every start the game scans, in order:
mods/next to the game executablemods/in the user data folder:~/Library/Application Support/NukeIslands/(macOS),%APPDATA%\NukeIslands\(Windows),~/.local/share/NukeIslands/(Linux)- on iPhone and iPad,
Documents/Mods(in the Files app: On My iPhone > Nuke Islands > Mods). The game creates it, with aREADME.txt, on first launch. - the folder in
FORGE_MODS_DIR
Every subfolder and every *.nkp file is a candidate. A pack that fails its checksums, or a folder without a readable mod.json, is listed as broken with the reason and never runs. If two scan folders hold a folder or pack of the same name, the later folder’s copy replaces the earlier one. --nomods or FORGE_NOMODS=1 skips the scan.
A candidate’s key is dir:<name> for a folder and nkp:<name> for a pack (file name without .nkp). Keys are for the host; mods are known by their manifest id.
Files in a mod
Section titled “Files in a mod”Directorymy_mod/
- mod.json manifest, required
- main.luau entry script (or main.luauc;
entrynames another) - util.luau modules for require
Directorydata/
- ships.json one file per data kind
Directorystrings/
- en.json text for one language
Directorysprites/
- icon.png PNG, up to 64x64
Directoryaudio/
- boom.ogg .ogg or .wav
Directorygame/ base-file overrides, only with “overrides”: true
- …
- notes.txt anything else: readable with mod.read, 1 MB each
<name> in sprites and audio is letters, digits and _. If a name exists as both .luau and .luauc, the bytecode one wins.
The pack (.nkp)
Section titled “The pack (.nkp)”NKPK is the game’s own container, also used for the base game and for saves. Little-endian; every section and the file itself are checksummed with CRC-32.
Header
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | magic NKPK |
| 4 | u16 | format version, 1 |
| 6 | u16 | header length, 64 (readers skip what they do not know) |
| 8 | u32 | flags, 0 |
| 12 | u32 | section count |
| 16 | u64 | table offset |
| 24 | u64 | table length |
| 32 | u64 | build id: the game build that wrote it, 0 for a mod or tool |
| 40 | u32 | CRC-32 of the table |
| 44 | u32 | CRC-32 of the data area, from header length to table offset |
| 48 | 12 | reserved, 0 |
| 60 | u32 | CRC-32 of header bytes 0 to 59 |
Table entry, one per section:
| Size | Field |
|---|---|
| u16 + n | name: UTF-8 path, / separated, no leading /, no .. |
| u8 | kind |
| u8 | codec: 0 stored, 1 zstd |
| u8 | layer: 0 none. A later transform takes a new id; old readers refuse that section by name |
| u8 | flags |
| u64 | offset |
| u64 | stored length |
| u64 | raw length |
| u32 | CRC-32 of the raw bytes |
| u32 | CRC-32 of the stored bytes |
| u16 + n | extra bytes, for future fields; skipped |
Mod packs use the section kinds manifest (mod.json), luau, bytecode, data (JSON), image, audio and blob, and carry build id 0.
forge pack build <dir> <out.nkp> [--bytecode] [--build-id N]forge pack unpack <pack> <dir>forge pack dump <pack>forge pack verify <pack>--bytecode compiles each .luau to bytecode and stores it under the same .luau name, without the source. Luau does not verify bytecode, so a bytecode mod is trusted code. The mod layer takes binary code only from .luauc files and bytecode sections; a source file that starts with binary code is refused.
mod.json
Section titled “mod.json”Every field, its type and its rule: mod.json reference. A manifest that is not valid JSON, misses a required field or breaks a rule makes the mod broken. Unknown fields are ignored with a note.
Versions
Section titled “Versions”api_version is the integer API level. This game is at level 1 and accepts mods for levels 1 to 1.
- above the game’s level: refused
- below the oldest supported level: refused
- below the game’s level but still supported: loads, with a warning
Adding a function, event, kind or field does not raise the level. Removing one or changing its meaning does, and the game keeps accepting the previous level for as long as it can.
Data files
Section titled “Data files”data/<kind>.json is an object with up to four keys, applied in this order:
Any other key is an error. Inside a patch, {"$remove": true} deletes that field. Kinds, fields, types and ranges: Data kinds. Not every kind allows every key; each kind’s page shows which.
A text value of the form @key (pattern ^@[%w_.-]+$, at most 41 characters) is looked up in the strings, in the fields name, short, blurb, text and milestone.text only. The result is cut to the field’s length.
strings/<lang>.json is { "key": "text" }. <lang> is a language code such as en or pt-br.
Overrides
Section titled “Overrides”With "overrides": true, a file in the mod with the same path as a base game file replaces it, for example game/nukeislands/credits_data.luau. Any existing path can be replaced, engine files included; the last mod in load order wins. A replaced Luau file runs with full access: no sandbox, no API checks.
Replacement happens when the mod layer boots. By then the server has already loaded a few of its own modules (save, settings, weapons, upgrades, plots, crew, base), so files those load cannot be replaced. Overrides are the most likely thing to break on a game update, and the MODS page marks such mods.
Load order
Section titled “Load order”The full algorithm. The friendly version is Load order and conflicts.
- Same id found twice: the higher version is kept, the other is
shadowed. Equal versions keep the first found, by key, sodir:beforenkp:. - A mod whose
api_versionis refused, or that the player turned off, is out. - A mod whose
requiresentry is missing, too old, off or out ismissing_dep. Repeat until nothing changes. - For each
conflictspair, the one later in the tie-break order (step 5) is switched off:conflict. A mod’s own id inrequires,conflictsorload_afteris dropped, with a note. requiresandload_afterare edges: a loads before b. Between mods without an edge: the player’s order, thenpriority(lower first), thenid.- Mods left on a cycle are
cycle. - Each mod runs: data files sorted by name, strings files sorted by name, then the entry script. One that raises while loading is
failed; its data writes are undone and the mods that required it becomemissing_dep.
The player’s settings
Section titled “The player’s settings”mods.json in the save root, written by the MODS page and read at start:
{ "disabled": { "my_first_mod": true }, "order": ["solar_flare", "my_first_mod"] }Mods are on unless listed in disabled.
Each save slot has slotN/mods.json:
{ "api": 1, "mods": [ { "id": "solar_flare", "version": "1.0.0" } ], "data": { "solar_flare": { "total": 3 } } }meta.json.mod.save. Data of a mod that is not running is written back unchanged.Only single-player slots have this file. On load, the game compares the active mods with mods and logs one line per difference (added, missing, version changed). It warns and plays on. The container’s checksums detect damage, after which the game restores the newest good backup; they never refuse a modded game.
Multiplayer
Section titled “Multiplayer”The client sends its active set with the join request: mods = [ { id, version, hash } ]. hash is a CRC-32: of the pack’s data for a .nkp, of all file names and contents for a folder, so a folder and a pack of the same mod do not match. At most 64 mods are compared.
The host compares the set with its own. Ids, versions and hashes must all match, or the host refuses with a message listing the differences. A client with no mods joins a host with none. A side: "server" or "client" mod counts in both sets. Old game builds send no mods and are treated as having none.
With no mods installed, or with --nomods, startup does one directory scan and stops: no mod code, no events, no UI, no per-frame work. With mods, a game event nobody listens to costs a table lookup, and the server’s event stream is skipped when no mod listens to a gameplay event. Per-frame work exists only if a mod listens to frame or has timers or UI.