A modern game needs:

• reliable save/load systems
• world state persistence
• player progression
• inventory & quests
• NPCs and simulation state
• safe serialization & versioning
• replay systems
• modding and content pipelines

Lua is ideal for all of this:

• tables serialize well
• code is data, data is code
• tables are readable and versionable
• hot reload simplifies pipelines
• modding = just load more Lua files

This chapter builds a complete system that scales from small to AAA-style persistence.

1. Save System Architecture

A full save includes:

• player info
• inventory
• equipment
• quests & story flags
• world state
• NPC states
• active triggers/events
• current level
• settings
• version metadata

Typical structure:

save/
save1.lua
save2.lua
autosave.lua

2. Save File Format Options

1. Pure Lua Table (Recommended)

return {
    player = {x=100, y=200, hp=80},
    world = {level="forest", time=120},
    inventory = {...}
}

Benefits

• human-readable
• fast
• versionable
• load via dofile()

2. JSON

• Good for modding
• Cross-platform and cross-language

3. Binary format

• Small, fast
• Harder to debug

4. Hybrid binary+Lua

• Use binary for world chunks
• Use Lua for metadata

We will use Lua tables for most cases.

3. Serialization (Turning State → Table)

Define a unified structure:

local SaveSystem = {}

function SaveSystem:serialize()
  return {
    version = 3,
    timestamp = os.time(),

    player = player:serialize(),
    inventory = inventory:serialize(),
    equipment = equipment:serialize(),
    quests = quest_manager:serialize(),
    world = world:serialize(),
    npcs = npc_manager:serialize(),
    flags = quest_manager.flags,
  }
end

Each subsystem must define its own serializer.

4. Subsystem: Player Serialization

function player:serialize()
  return {
    x = self.x,
    y = self.y,
    hp = self.hp,
    xp = self.xp,
    stats = clone(self.stats),
    level = self.level
  }
end

5. Inventory Serialization (Chapter 11 Integration)

function inventory:serialize()
  local data = {}
  for i=1, self.size do
    local s = self.slots[i]
    if s then
      data[i] = {id=s.id, count=s.count}
    end
  end
  return data
end

6. Quest Serialization (Chapter 12 Integration)

function quest_manager:serialize()
  return {
    active = self.active,
    completed = self.completed,
  }
end

7. World & Level Serialization (Chapters 9 & 13 Integration)

function world:serialize()
  return {
    level = self.current_level,
    time_of_day = self.time,
    weather = self.weather_state,
  }
end

NPC Serialization

function npc_manager:serialize()
  local data = {}
  for id, npc in pairs(self.npcs) do
    data[id] = {
      x = npc.x,
      y = npc.y,
      state = npc.state,
      schedule_idx = npc.schedule_index
    }
  end
  return data
end

8. Saving to Disk

Using pure Lua:

local function save_to_file(path, tbl)
  local file = io.open(path, "w")
  file:write("return " .. serialize(tbl))
  file:close()
end

9. Loading a Save

function SaveSystem:load(path)
  local data = dofile(path)

  player:load(data.player)
  inventory:load(data.inventory)
  equipment:load(data.equipment)
  quest_manager:load(data.quests)
  world:load(data.world)
  npc_manager:load(data.npcs)
end

10. Versioning & Migration

Future versions must migrate older saves.

if data.version == 1 then
  data.player.hp = data.player.hp or 100
  data.version = 2
end

if data.version == 2 then
  data.quests.completed = data.quests.completed or {}
  data.version = 3
end

This avoids breaking old saves.

11. Auto-Save & Quick-Save

function SaveSystem:auto_save()
  self:save("save/autosave.lua")
end

Trigger autosaves:

• every level transition
• every N minutes
• boss defeated
• quest completed

12. Replay System (Recording Inputs)

Replays store input history, not world states.

For deterministic games:

Just record commands (lockstep):

replay[#replay+1] = {frame=f, cmd=command}

Playback:

for each frame:
  apply_commands(replay[f])
  simulate_world()

For non-deterministic games:

Store:

• initial state
• per-frame inputs
• periodic snapshots (for checkpoints)

13. Content Pipelines (Loading Game Data)

Your game likely has:

content/
  items/
  enchants/
  maps/
  quests/
  npcs/
  dialogues/
  abilities/

Lua makes this trivial:

function load_folder(path)
  for _, file in ipairs(list_files(path)) do
    local id = file:sub(1,-5)
    Content[id] = require(path.."."..id)
  end
end

load_folder("content/items")
load_folder("content/quests")
load_folder("content/npcs")

This is how:

• Skyrim Creation Kit
• GTA V mods
• Factorio mods
• Hades content

work internally.

14. Modding Support (User Lua Packages)

Mod Folder Layout

mods/
  my_mod/
    items.lua
    quests.lua
    monsters.lua
    override/abilities/
    new_npc.lua

Add Mods to Pipeline

for _, mod in ipairs(list_dirs("mods")) do
  load_folder("mods/"..mod)
end

Hot Reload Mods

function reload_content()
  package.loaded["items"] = nil
  Items = require("items")
end

Game updates instantly.

15. Cloud Saves / Cross-Platform

Serialize to JSON → upload to:

• Steam Cloud
• iCloud
• Google Drive
• custom backend

Lua → JSON is trivial:

local json = require("json")
local text = json.encode(tbl)

16. Putting It All Together — Full Save System

function SaveSystem:save(path)
  local data = self:serialize()
  save_to_file(path, data)
end

function SaveSystem:load(path)
  local data = dofile(path)

  player:load(data.player)
  inventory:load(data.inventory)
  quest_manager:load(data.quests)
  world:load(data.world)
  npc_manager:load(data.npcs)
end

This covers everything from tiny indie games to large RPGs.

17. Summary of Chapter 17

You now understand:

• Save file formats
• Serialization patterns
• Player/world/quest/inventory/NPC persistence
• Save versioning & migrations
• Autosave systems
• Replay recording/playback
• Content pipelines
• Modding systems
• Hot reload pipelines
• Using Lua as a scalable data format

Your Lua engine now has industrial-grade persistence.