Data Persistence & Saving

Your mod needs to remember things — player progress, settings, high scores. BeamNG offers several persistence mechanisms depending on what you're saving and when. Pick the right one to avoid data loss.

:::tip[Quick Decision]

• User preferences → settings/mymod/config.json
• Career progress → Career save hooks (onSaveCurrentSaveSlot)
• In-memory state → setExtensionUnloadMode("manual") in your mod script :::

JSON Files

The simplest way to save and load structured data:

local M = {}

local savePath = "settings/mymod/data.json"

local function saveData(data)
  jsonWriteFile(savePath, data)
end

local function loadData()
  return jsonReadFile(savePath) or {}
end

M.saveData = saveData
M.loadData = loadData

return M

jsonWriteFile() creates parent directories automatically. Files are saved relative to the user directory.

Common save locations

• settings/mymod/ - mod configuration and user preferences
• settings/mymod/saves/ - save files or progress data

Persisting Data Across Level Changes

By default, extensions are unloaded and reloaded on level changes. To keep your data in memory:

Register your extension in your mod script so it persists:

-- scripts/mymod/modScript.lua
setExtensionUnloadMode("mymod_data", "manual")
loadManualUnloadExtensions()

Then your extension just manages its data:

local M = {}
local state = {}

local function onExtensionLoaded()
  state = jsonReadFile("settings/mymod/state.json") or {}
end

local function saveState()
  jsonWriteFile("settings/mymod/state.json", state)
end

M.onExtensionLoaded = onExtensionLoaded
M.saveState = saveState

return M

Local variables survive as long as the extension stays loaded.

Game Settings

For simple key-value settings that integrate with the game's settings system:

-- Read a setting
local value = settings.getValue("mymod_difficulty")

-- Write a setting
settings.setValue("mymod_difficulty", "hard")

Settings persist automatically through the game's built-in settings file.

Career Savedata

If your mod integrates with career mode, use the career savedata system:

local M = {}

local function onCareerSave(saveData)
  saveData.mymod = {
    progress = 50,
    unlockedItems = {"item_a", "item_b"}
  }
end

local function onCareerLoad(saveData)
  local data = saveData.mymod or {}
  -- restore state from data
end

M.onCareerSave = onCareerSave
M.onCareerLoad = onCareerLoad

return M

The onCareerSave and onCareerLoad hooks are called by the career system. Data is stored as part of the career save file.

Tips

• Always provide defaults when loading: jsonReadFile(path) or {}
• Save on meaningful events (mission complete, setting changed), not every frame
• Register with setExtensionUnloadMode in your mod script if you need data to survive level changes
• Keep save files small - avoid dumping large tables every frame

See Also

• Mod Scripts - Registering extensions for persistence
• Common Patterns - Save/load and settings patterns
• Error Handling - JSON safety patterns