Skip to Content
defold-typescript libraries
Insalitydefold-saver

Insality/defold-saver/saver.saver

Persistent save helpers for Defold: typed tables, versioned slots, and atomic writes.

  • GitHub: Insality/defold-saver — pinned to 10
    1. 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 — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as saver from "saver.saver"

Functions

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 .lua
  • format?: 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 name
  • default_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 name
  • value: 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

saver_storage_value

saver_storage_value.s_value: string | undefined

saver_storage_value.i_value: number | undefined

saver_storage_value.b_value: boolean | undefined

On this page

Functionsset_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): booleanTypessaver_statesaver_state.storage: LuaTable<string, unknown>saver_state.version: numbersaver_state.last_game_version: stringsaver_state.migration_version: numbersaver_game_statesaver_game_state.saver: saver_statesaver_game_state.storage: saver_storage_statesaver_configsaver_config.save_folder: string | undefinedsaver_config.save_name: string | undefinedsaver_config.saver_key: string | undefinedsaver_config.storage_key: string | undefinedsaver_config.autosave_timer: number | undefinedsaver_config.lua_require_as_string: boolean | undefinedsaver_loggersaver_logger.trace: (logger: saver_logger, message: string, data: unknown | undefined) => voidsaver_logger.debug: (logger: saver_logger, message: string, data: unknown | undefined) => voidsaver_logger.info: (logger: saver_logger, message: string, data: unknown | undefined) => voidsaver_logger.warn: (logger: saver_logger, message: string, data: unknown | undefined) => voidsaver_logger.error: (logger: saver_logger, message: string, data: unknown | undefined) => voidsaver_storage_statesaver_storage_state.storage: LuaTable<string, saver_storage_value>saver_storage_valuesaver_storage_value.s_value: string | undefinedsaver_storage_value.i_value: number | undefinedsaver_storage_value.b_value: boolean | undefined