Skip to content

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.

On every start the game scans, in order:

  1. mods/ next to the game executable
  2. mods/ in the user data folder: ~/Library/Application Support/NukeIslands/ (macOS), %APPDATA%\NukeIslands\ (Windows), ~/.local/share/NukeIslands/ (Linux)
  3. on iPhone and iPad, Documents/Mods (in the Files app: On My iPhone > Nuke Islands > Mods). The game creates it, with a README.txt, on first launch.
  4. 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.

  • Directorymy_mod/
    • mod.json manifest, required
    • main.luau entry script (or main.luauc; entry names 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.

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.

Header64 bytes
Datasection payloads, back to back
Tableone entry per section

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.

Terminal window
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.

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.

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/<kind>.json is an object with up to four keys, applied in this order:

addnew records: id to record
>
replacewhole records: id to record
>
patchsome fields: id to fields
>
removea list of ids

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.

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.

The full algorithm. The friendly version is Load order and conflicts.

  1. Same id found twice: the higher version is kept, the other is shadowed. Equal versions keep the first found, by key, so dir: before nkp:.
  2. A mod whose api_version is refused, or that the player turned off, is out.
  3. A mod whose requires entry is missing, too old, off or out is missing_dep. Repeat until nothing changes.
  4. For each conflicts pair, the one later in the tie-break order (step 5) is switched off: conflict. A mod’s own id in requires, conflicts or load_after is dropped, with a note.
  5. requires and load_after are edges: a loads before b. Between mods without an edge: the player’s order, then priority (lower first), then id.
  6. Mods left on a cycle are cycle.
  7. 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 become missing_dep.

mods.json in the save root, written by the MODS page and read at start:

mods.json
{ "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:

slot1/mods.json
{ "api": 1, "mods": [ { "id": "solar_flare", "version": "1.0.0" } ], "data": { "solar_flare": { "total": 3 } } }
modsthe active set when it was written. Also kept in the slot’s meta.json.
datawhat each mod stored with 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.

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.