Insality/defold-saver/saver.saver
Persistent save helpers for Defold: typed tables, versioned slots, and atomic writes.
- GitHub: Insality/defold-saver — pinned to
10- This repo publishes no stable release. Pick a tag from Insality/defold-saver tags and add its Source code (zip) URL — for the pinned tag,
https://github.com/Insality/defold-saver/archive/refs/tags/10.zip— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as saver from "saver.saver"
- This repo publishes no stable release. Pick a tag from Insality/defold-saver tags and add its Source code (zip) URL — for the pinned tag,
Functions
set_logger(logger_instance?:saver_logger| LuaTable | undefined)init(config?:saver_config| undefined)save_game_state(save_name?: string | undefined): booleanload_game_state(save_name?: string | undefined): booleandelete_game_state(save_name?: string | undefined): booleanget_game_state():saver_game_stateset_game_state(data: LuaTable): booleanbind_save_state(table_key_id: string, table_reference: LuaTable): LuaTablesave_file_by_path(data: LuaTable, path: string, format?: string | undefined): booleansave_binary_by_path(data: string, path: string): booleanload_file_by_path(path: string, format?: string | undefined): LuaTable | undefinedload_binary_by_path(path: string): string | undefineddelete_file_by_path(path: string): booleanis_file_exists_by_path(path: string): booleansave_file_by_name(data: LuaTable, filename: string, format?: string | undefined): booleansave_binary_by_name(data: string, filename: string): booleanload_file_by_name(filename: string, format?: string | undefined): LuaTable | undefinedload_binary_by_name(filename: string): string | undefineddelete_file_by_name(filename: string): booleanis_file_exists_by_name(filename: string): booleanget_save_path(filename?: string | undefined): stringget_save_version(): numberset_autosave_timer(timer: number)get_autosave_timer(): numberget_current_game_project_folder(): string | undefinedset_migrations(migrations_table: ((game_state:saver_game_state, logger:saver_logger) => undefined)[])apply_migrations()get_value<T>(key_id: string, default_value?: T | undefined): Tset_value(key_id: string, value: unknown)is_value_exists(key_id: string): boolean
set_logger(logger_instance?: saver_logger | LuaTable | undefined)
File format enum (mirrors saver_internal.FORMAT) Customize the logging mechanism used by Defold Saver. You can use Defold Log library or provide a custom logger. local log = require("log.log") local saver = require("saver.saver")
saver.set_logger(log.get_logger("saver"))
Parameters
logger_instance?:saver_logger | LuaTable | undefined— A logger object that follows the specified logging interface, including methods for trace, debug, info, warn, error. Pass nil to remove the default logger.
init(config?: saver_config | undefined)
Initialize the Saver module. Should be called at the start of your game to set up the module. Call it after saver.set_migrations if you are using migrations. This function loads the game state from a file and starts the autosave timer. If the game state file does not exist, a new game state is created. saver.init()
Parameters
config?:saver_config | undefined— Configuration table.
save_game_state(save_name?: string | undefined): boolean
Save the current game state to a file. If no file name is provided, the default file name specified in the game.project file is used. -- Save the game with default name saver.save_game_state()
-- Save the game with custom name saver.save_game_state("custom_save")
Parameters
save_name?:string | undefined— The name of the file to save the game state to. Default is the file name specified in the game.project file under the saver.save_file key.
Returns
boolean— true if the game state was saved successfully, false otherwise.
load_game_state(save_name?: string | undefined): boolean
Load the game state from a file. If no file name is provided, the default file name specified in the game.project file is used. local is_loaded = saver.load_game_state() -- Load the game state with default name local is_loaded = saver.load_game_state("custom_save") -- Load the game state with custom name
Parameters
save_name?:string | undefined— The name of the file to load the game state from. Default is the file name specified in the game.project file.
Returns
boolean— true if the game state was loaded successfully, false if the new game state is created
delete_game_state(save_name?: string | undefined): boolean
Delete the game state file. Doesn't affect the current game state. If autosave is enabled, it will be rescheduled, so probably you want to immediately restart the game. -- Delete the game state with default name saver.delete_game_state()
-- Delete the game state with custom name saver.delete_game_state("custom_save")
Parameters
save_name?:string | undefined— The name of the file to delete the game state from. Default is the file name specified in the game.project file.
Returns
boolean— true if the game state was deleted successfully, false otherwise.
get_game_state(): saver_game_state
Returns the current game state. local game_state = saver.get_game_state() pprint(game_state)
Returns
saver_game_state— The current game state.
set_game_state(data: LuaTable): boolean
Sets the current game state to the specified state. local game_state = saver.get_game_state() game_state.game.level = 5 saver.set_game_state(game_state)
Parameters
data:LuaTable— The state to set the game state to.
Returns
boolean— true if the game state was set successfully, false otherwise.
bind_save_state(table_key_id: string, table_reference: LuaTable): LuaTable
Binds a table reference as a part of the game state. When the game state is saved, all table references will be saved. This is a main function to use to save your game state. You can bind multiple tables to different parts of the game state. After binding, the table_reference will be updated with the saved data if it exists. local game_state = { level = 1, money = 100 }
saver.bind_save_state("game", game_state)
-- If we have previously saved game state, the game_state will be changed to the saved data print(game_state.level) -- 5 (if it was saved before)
Parameters
table_key_id:string— The table key to set the value for.table_reference:LuaTable— The table reference to bind to the game state.
Returns
LuaTable— The table_reference
save_file_by_path(data: LuaTable, path: string, format?: string | undefined): boolean
Saves the specified data to a file at the specified path. The data format is chosen by file path extension. local data = { score = 100, level = 1 }
-- Get project path works on build from the Defold Editor only local project_path = saver.get_current_game_project_folder() -- Use path to the resources folder local file_path = project_path .. "/resources/data.json" saver.save_file_by_path(data, file_path)
Parameters
data:LuaTable— The lua table to save to the file.path:string— The absolute path to save the file to. Contains the file name and extension. Extension can be empty, .json or .luaformat?:string | undefined— Optional format override (json, lua, serialized, binary). If not specified, format will be detected from paths extension or data type.
Returns
boolean— true if the file was saved successfully, false otherwise.
save_binary_by_path(data: string, path: string): boolean
Saves the specified data to a file at the specified path. The data format is binary.
Parameters
data:string— The binary data to save to the file.path:string— The absolute path to save the file to. Contains the file name and extension.
Returns
boolean— true if the file was saved successfully, false otherwise.
load_file_by_path(path: string, format?: string | undefined): LuaTable | undefined
Loads the data from a file at the specified path.
-- Get project path works on build from the Defold Editor only
local project_path = saver.get_current_game_project_folder()
-- Use path to the resources folder
local file_path = project_path .. "/resources/data.json"
local data = saver.load_file_by_path(file_path)
pprint(data)
NOTE: For binary data like images, use saver.load_binary_by_path instead.
Parameters
path:string— The absolute path to load the file from. Contains the file name and extension.format?:string | undefined— Optional format override (json, lua, serialized). If not specified, format will be detected from paths extension.
Returns
LuaTable | undefined— The data loaded from the file. If the file does not exist, returns nil.
load_binary_by_path(path: string): string | undefined
Loads the binary data from a file at the specified path.
Parameters
path:string— The absolute path to the file to load. Contains the file name and extension.
Returns
string | undefined— The binary data loaded from the file. If the file does not exist, returns nil.
delete_file_by_path(path: string): boolean
Deletes the file at the specified path.
Parameters
path:string— The absolute path to the file to delete. Contains the file name and extension.
Returns
boolean— true if the file was deleted successfully, false otherwise.
is_file_exists_by_path(path: string): boolean
Checks if the file exists at the specified path. local is_project_file_exists = saver.is_file_exists_by_path(absolute_path_to_file)
Parameters
path:string— The absolute path to the file to check. Contains the file name and extension.
Returns
boolean— true if the file exists, false otherwise.
save_file_by_name(data: LuaTable, filename: string, format?: string | undefined): boolean
Saves the specified data to a file with the specified name. The file is saved in the game save folder. local data = { score = 100, level = 1 }
-- Save the data to the game save folder saver.save_file_by_name(data, "data.json")
Parameters
data:LuaTable— The lua table to save to the file.filename:string— The name of the file to save the data to.format?:string | undefined— Optional format override (json, lua, serialized, binary)
Returns
boolean— true if the file was saved successfully, false otherwise.
save_binary_by_name(data: string, filename: string): boolean
Saves the specified data to a file with the specified name. The data format is binary.
Parameters
data:string— The binary data to save to the file.filename:string— The name of the file to save the data to.
Returns
boolean— true if the file was saved successfully, false otherwise.
load_file_by_name(filename: string, format?: string | undefined): LuaTable | undefined
Loads the data from a file with the specified name. The file is loaded from the game save folder. local data = saver.load_file_by_name("data.json") pprint(data) NOTE: For binary data like images, use saver.load_binary_by_name instead.
Parameters
filename:string— The name of the file to load the data from.format?:string | undefined— Optional format override (json, lua, serialized, binary)
Returns
LuaTable | undefined— The data loaded from the file. If the file does not exist, returns nil.
load_binary_by_name(filename: string): string | undefined
Loads the binary data from a file with the specified name. The file is loaded from the game save folder.
Parameters
filename:string— The name of the file to load the binary data from.
Returns
string | undefined— The binary data loaded from the file. If the file does not exist, returns nil.
delete_file_by_name(filename: string): boolean
Deletes the file with the specified name. The file is deleted from the game save folder. saver.delete_file_by_name("data.json")
Parameters
filename:string— The name of the file to delete.
Returns
boolean— true if the file was deleted successfully, false otherwise.
is_file_exists_by_name(filename: string): boolean
Checks if the file exists with the specified name. The file is checked in the game save folder. local is_header_downloaded = saver.is_file_exists_by_name("header.png")
Parameters
filename:string— The name of the file to check.
Returns
boolean— true if the file exists, false otherwise.
get_save_path(filename?: string | undefined): string
Returns the absolute path to the game save folder. If a file name is provided, the path to the file in the game save folder is returned. local folder_path = saver.get_save_path() print(folder_path) -- "/Users/user/Library/Application Support/Defold Saver/"
local file_path = saver.get_save_path("data.json") print(file_path) -- "/Users/user/Library/Application Support/Defold Saver/data.json"
Parameters
filename?:string | undefined— The name of the file to get the path for. If nil, returns the folder path.
Returns
string— The absolute path to the game save folder, or the path to the file in the game save folder if a file name is provided.
get_save_version(): number
Returns the current save version of the game state. The save version is used to check if the game state is older than the current version. The save version increments when the game state is saved. local save_version = saver.get_save_version() print(save_version)
Returns
number— The current save version of the game state.
set_autosave_timer(timer: number)
Sets the autosave timer to the specified number of seconds. The autosave timer is used to automatically save the game state at regular intervals. Use 0 to disable autosave. saver.set_autosave_timer(5) -- Autosave every 5 seconds saver.set_autosave_timer(0) -- Disable autosave
Parameters
timer:number— The number of seconds between autosaves. Use 0 to disable autosave.
get_autosave_timer(): number
Returns the current autosave timer.
Returns
number— The current autosave timer.
get_current_game_project_folder(): string | undefined
Returns the absolute path to the current game project folder. It is useful when you need to save or load files from the game project folder at development. Returns nil if the game project folder is not found. Used only at desktop platforms and if game started from the Defold Editor. local project_folder = saver.get_current_game_project_folder() print(project_folder) -- "/Users/user/projects/my_game"
Returns
string | undefined— The absolute path to the current game project folder. Nil if the game.project folder is not found.
set_migrations(migrations_table: ((game_state: saver_game_state, logger: saver_logger) => undefined)[])
Sets the list of migrations to apply after loading the game state manually with saver.apply_migrations() function. Migrations are used to update the game state in case of changes to the game state structure. Migrations are applied in order. Each migration should be a function that takes the game state as a parameter and returns the updated game state. local migrations = { -- Migration 1 function(game_state, logger) -- Assume we have new level_data field in the game state and we need to move level and score to it game_state.game.level_data = { level = game_state.game.level, score = game_state.game.score } game_state.game.level = nil game_state.game.score = nil return game_state }, -- Migration 2 function(game_state, logger) -- Just an example, multiply the score by 1000. For example we changed our score system game_state.game.level_data.score = game_state.game.level_data.score * 1000 return game_state } }
saver.set_migrations(migrations) saver.init() saver.bind_save_state("game", game_state) saver.apply_migrations()
Parameters
migrations_table:((game_state: saver_game_state, logger: saver_logger) => undefined)[]— Array of migration functions
apply_migrations()
Applies the migrations set by saver.set_migrations function. It should be called after loading the game state manually with saver.init() function. A save from a newer game version keeps its migration version: back on the newer game, its migrations do not run twice. saver.apply_migrations()
get_value<T>(key_id: string, default_value?: T | undefined): T
Gets the value from the saver storage. If the value does not exist, it will return the default value.
Parameters
key_id:string— The storage field namedefault_value?:T | undefined— The default value
Returns
T— The value from the saver storage
set_value(key_id: string, value: unknown)
Sets the value in the saver storage.
Parameters
key_id:string— The storage field namevalue:unknown— value
is_value_exists(key_id: string): boolean
Checks if the value exists in the saver storage.
Parameters
key_id:string— The storage field name
Returns
boolean— true if the value exists, false otherwise
Types
saver_state
saver_state.storage: LuaTable<string, unknown>
Table with key-value data
saver_state.version: number
Current save version
saver_state.last_game_version: string
Last game version
saver_state.migration_version: number
Current migration version
saver_game_state
saver_game_state.saver: saver_state
Saver state
saver_game_state.storage: saver_storage_state
Storage state
saver_config
saver_config.save_folder: string | undefined
Save folder name. Default is project name without special characters
saver_config.save_name: string | undefined
Save file name, use ".json" or ".lua" extension to use these formats. Default is "game"
saver_config.saver_key: string | undefined
Saver key, where saver internal data will be stored. Default is "saver"
saver_config.storage_key: string | undefined
Storage key, where storage internal data will be stored. Deprecated. Default is "storage"
saver_config.autosave_timer: number | undefined
Autosave timer in seconds. Default is 3 seconds
saver_config.lua_require_as_string: boolean | undefined
If true, the require() function will load Lua files as strings instead of Lua tables. Default is false
saver_logger
saver_logger.trace: (logger: saver_logger, message: string, data: unknown | undefined) => void
saver_logger.debug: (logger: saver_logger, message: string, data: unknown | undefined) => void
saver_logger.info: (logger: saver_logger, message: string, data: unknown | undefined) => void
saver_logger.warn: (logger: saver_logger, message: string, data: unknown | undefined) => void
saver_logger.error: (logger: saver_logger, message: string, data: unknown | undefined) => void
saver_storage_state
saver_storage_state.storage: LuaTable<string, saver_storage_value>
The storage data