{"id":15722520,"url":"https://github.com/whiteboxdev/library-defold-persist","last_synced_at":"2025-05-05T21:45:26.194Z","repository":{"id":219158171,"uuid":"748320403","full_name":"whiteboxdev/library-defold-persist","owner":"whiteboxdev","description":"Defold Persist provides a simple interface for saving and loading data in a Defold game engine project.","archived":false,"fork":false,"pushed_at":"2024-05-24T16:14:05.000Z","size":96,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-02T23:08:40.822Z","etag":null,"topics":["defold","defold-library"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whiteboxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-25T18:24:11.000Z","updated_at":"2025-04-19T08:41:50.000Z","dependencies_parsed_at":"2024-05-16T06:14:00.493Z","dependency_job_id":"e4f26e5f-99c6-4df9-9921-6efc1cf99cbc","html_url":"https://github.com/whiteboxdev/library-defold-persist","commit_stats":null,"previous_names":["klaytonkowalski/library-defold-persist","whiteboxdev/library-defold-persist"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-persist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-persist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-persist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-persist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whiteboxdev","download_url":"https://codeload.github.com/whiteboxdev/library-defold-persist/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252582316,"owners_count":21771643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-library"],"created_at":"2024-10-03T22:08:17.241Z","updated_at":"2025-05-05T21:45:26.175Z","avatar_url":"https://github.com/whiteboxdev.png","language":"Lua","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"# Defold Persist\r\n\r\nDefold Persist provides a simple interface for saving and loading data in a Defold game engine project.\r\n\r\nPlease click the ☆ button on GitHub if this repository is useful or interesting. Thank you!\r\n\r\n![thumbnail.png](https://github.com/whiteboxdev/library-defold-persist/blob/main/assets/images/thumbnail.png?raw=true)\r\n\r\n## Installation\r\n\r\nAdd the latest version to your project's dependencies:  \r\nhttps://github.com/whiteboxdev/library-defold-persist/archive/main.zip\r\n\r\n## Tutorial\r\n\r\nImport Persist into script files that need to save or load data:\r\n\r\n```\r\nlocal persist = require \"persist.persist\"\r\n```\r\n\r\nA file must exist before it can be accessed, otherwise an error message will be printed to standard output. Let's create a *settings* file:\r\n\r\n```\r\nlocal default_settings_data =\r\n{\r\n    master_volume = 100,\r\n    music_volume = 100,\r\n    sound_volume = 100\r\n}\r\npersist.create(\"settings\", default_settings_data)\r\n```\r\n\r\nIf the file already exists, then `persist.create()` will simply be ignored. This function should be called as part of a project's startup routine for each file to ensure that it exists.\r\n\r\nIf the file has the \".json\" extension, then its data will be saved as JSON instead of Defold's built-in format. Be cautious to only save data types that are supported by Defold's `json` API. For example, the hashed string `hash(\"test\")` cannot be encoded or decoded properly, so it should instead be saved as just `\"test\"` then manually hashed.\r\n\r\nEach OS has its own conventions and preferences for where applications should create custom files. See the following table for details:\r\n\r\n| OS | Path | More |\r\n| -- | ---- | ---- |\r\n| Windows | *C:\\\\Users\\\\\\\u003cuser\u003e\\\\AppData\\\\Roaming\\\\\\\u003cproject_title\u003e\\\\\\\u003cfile_name\u003e* | |\r\n| MacOS | *~/Library/Application Support/\\\u003cproject_title\u003e/\\\u003cfile_name\u003e* | |\r\n| Linux | *\\\u003cconfig\u003e/\\\u003cproject_title\u003e/\\\u003cfile_name\u003e* | The *config* variable adopts the contents of the *XDG_CONFIG_HOME* environment variable, otherwise it defaults to *~/.config*. |\r\n| (Other Platforms) | (Please submit a pull request!) | |\r\n\r\nLet's change the music volume from 100 to 75, and change the sound volume from 100 to 25:\r\n\r\n```\r\npersist.write(\"settings\", \"music_volume\", 75)\r\npersist.write(\"settings\", \"sound_volume\", 25)\r\n```\r\n\r\nPersist differentiates between **saved data** and **written data**. Written data has not yet been transferred to non-volatile memory. It only exists as a table within the running process. This allows us to abort file changes before they overwrite previously saved data.\r\n\r\nLet's revert back to whatever the sound volume was before we changed it, then save our changes:\r\n\r\n```\r\npersist.flush(\"settings\", \"sound_volume\")\r\npersist.save(\"settings\")\r\n```\r\n\r\nNext let's load the data from the *settings* file so that we know how loudly to play our wonderful background music:\r\n\r\n```\r\nlocal settings_data = persist.load(\"settings\")\r\nlocal master_volume = settings_data.master_volume\r\nlocal music_volume = settings_data.music_volume\r\nsound.play(msg.url(nil, nil, \"background_music\"), { gain = master_volume * music_volume })\r\n```\r\n\r\nWhen loading data, written data is prioritized over saved data. This means that `persist.load()` will always return the latest version of a file, even if it has not yet been saved.\r\n\r\n## API\r\n\r\n### persist.create(file_name, data [, overwrite])\r\n\r\nCreates a file with the specified data. If the file already exists, then its data can be overwritten.\r\n\r\n### persist.write(file_name, key, value)\r\n\r\nWrites data to a file.\r\n\r\n### persist.flush(file_name [, key])\r\n\r\nFlushes unsaved data from a file. If a key is specified, then only that field is flushed.\r\n\r\n### persist.save(file_name)\r\n\r\nSaves data that was written to a file.\r\n\r\n### persist.load(file_name)\r\n\r\nLoads data from a file, including written data.\r\n\r\n### persist.exists(file_name)\r\n\r\nChecks if a file exists.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-persist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-persist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-persist/lists"}