Ship it as a .nkp
A folder is fine while you work. To share a mod, pack it into one .nkp file. The game reads it exactly like the folder, and checks every byte before it runs anything.
-
Build the pack. From a source checkout, with the step 2 version of your first mod:
Terminal window ./target/release/forge pack build mods/my_first_mod my_first_mod.nkp[pack] my_first_mod.nkp: 3 sections, 0 KB raw -> 0 KBEach file becomes a section. Text is compressed with zstd when that makes it smaller.
-
Check it.
Terminal window ./target/release/forge pack verify my_first_mod.nkp{"format":1,"build":0,"sections":[{"name":"data/ships.json","kind":"data","codec":"stored","raw":82,"stored":82,"ok":true},{"name":"main.luau","kind":"luau","codec":"zstd","raw":177,"stored":135,"ok":true},{"name":"mod.json","kind":"manifest","codec":"zstd","raw":180,"stored":133,"ok":true}],"ok":true}"ok":trueon the last line means every checksum matched. A damaged file fails here, and in the game:{"ok":false,"error":"my_first_mod.nkp: header checksum mismatch"} -
Install it. Put
my_first_mod.nkpin a mods folder and restart. Remove the folder version first: with the same id and version in both forms, only the folder runs. -
Share it. One file. Say which game version you tested with, and the
api_versionin yourmod.jsontells the game the rest.
Other commands
Section titled “Other commands”| Command | Does |
|---|---|
forge pack dump <pack> |
like verify, and prints each JSON file |
forge pack unpack <pack> <dir> |
writes the files back out |
forge pack build <dir> <out> --bytecode |
ships compiled Luau instead of source |
About –bytecode
Section titled “About –bytecode”--bytecode compiles each .luau file and leaves the source out. That has a cost for your players: Luau does not check compiled bytecode, so a crafted file can escape the sandbox. A player should only install a bytecode mod from someone they trust. Ship source unless you have a reason not to.
Players in a co-op game must have the same mods, at the same versions, in the same form. A folder and a pack of the same mod count as different, because the game fingerprints them differently. Tell your players to use the .nkp.
The byte layout of the file is in Pack and save format.