Skip to content

Save data

You will build War Diary: it counts every island wipe you see, remembers the biggest payout, and greets you with the total next time you play.

strings/en.json
{
"diary.back": "WAR DIARY: %d WIPES SO FAR",
"diary.wipe": "WIPE %d. BIGGEST PAYOUT %d"
}

mod.save.set(key, value) stores plain data (numbers, text, booleans, tables of those) in the current save slot, under your mod’s id. Nothing else can read it or overwrite it.

Saving belongs to the server VM, the one that runs the rules and writes the save file. In the client VM the calls work but only keep the value in memory until the game closes. So this mod runs on the server only:

main.luau
-- mod.save lives in the server VM. The client keeps nothing between sessions.
if not mod.is_server then
return
end
  1. Load what was saved. save_loaded fires at start, once the slot’s mod data is back. mod.save.get returns nil the first time.

    main.luau
    local diary = { wipes = 0, best = 0 }
    -- save_loaded fires at start, once your saved values are back.
    mod.on("save_loaded", function()
    local saved = mod.save.get("diary")
    if saved then
    diary = saved -- get returns a copy: yours to change
    end
    end)

    get gives you a copy of a table. Change it as much as you like; nothing is stored until you call set.

  2. Count, and store. Every wipe updates the table and stores the whole thing again.

    main.luau
    mod.on("island_wiped", function(e)
    diary.wipes += 1
    diary.best = math.max(diary.best, math.floor(e.cash))
    mod.save.set("diary", diary) -- written within 30 s and when the game closes
    mod.game.toast(mod.text("diary.wipe", diary.wipes, diary.best))
    end)

    The game writes the save within 30 seconds of a change, and when it closes. You do not need to call anything else.

  3. Say hello. ready fires once every mod has loaded. A five second delay lets the HUD come up first.

    main.luau
    -- ready fires after every mod has loaded. Give the world a few seconds.
    mod.on("ready", function()
    mod.after(5, function()
    if diary.wipes > 0 then
    mod.game.toast(mod.text("diary.back", diary.wipes))
    end
    end)
    end)

Each save slot has a mods.json next to the game’s own files:

slot1/mods.json
{
"api": 1,
"mods": [{ "id": "war_diary", "version": "1.0.0" }],
"data": { "war_diary": { "diary": { "wipes": 3, "best": 4200 } } }
}
  • mods is the set of mods that were active when it was written.
  • data holds what each mod stored. If you remove a mod, its data stays in the file and comes back when you install it again.
  • Loading a save made with other mods logs the difference and plays on. Nothing is refused.
Key text, 40 characters at most
Value plain data, 6 levels deep, 2000 entries
Co-op a co-op session keeps no mod data; save_loaded does not fire

Saves and co-op has the rest. Next: ship it as a .nkp.