{"id":14960994,"url":"https://github.com/gilzoide/unity-key-value-store","last_synced_at":"2025-10-24T20:30:44.309Z","repository":{"id":185129327,"uuid":"666936261","full_name":"gilzoide/unity-key-value-store","owner":"gilzoide","description":"Key-Value Store save system interface and implementations for Unity","archived":false,"fork":false,"pushed_at":"2025-01-17T02:06:04.000Z","size":19616,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-31T03:54:06.586Z","etag":null,"topics":["key-value","key-value-store","save-system","unity","unity3d","upm-package"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gilzoide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":["gilzoide"],"patreon":null,"open_collective":null,"ko_fi":"gilzoide","tidelift":null,"community_bridge":null,"liberapay":"gilzoide","issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2023-07-16T04:56:13.000Z","updated_at":"2025-01-20T11:54:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"605b7e29-3734-4d4a-bb56-3c9c9c8a4c5e","html_url":"https://github.com/gilzoide/unity-key-value-store","commit_stats":{"total_commits":43,"total_committers":1,"mean_commits":43.0,"dds":0.0,"last_synced_commit":"ea39d04fee34aff619f194255c6533c5bb33a342"},"previous_names":["gilzoide/unity-key-value-store"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Funity-key-value-store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Funity-key-value-store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Funity-key-value-store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gilzoide%2Funity-key-value-store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gilzoide","download_url":"https://codeload.github.com/gilzoide/unity-key-value-store/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238030288,"owners_count":19404859,"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":["key-value","key-value-store","save-system","unity","unity3d","upm-package"],"created_at":"2024-09-24T13:23:36.743Z","updated_at":"2025-10-24T20:30:44.297Z","avatar_url":"https://github.com/gilzoide.png","language":"C#","funding_links":["https://github.com/sponsors/gilzoide","https://ko-fi.com/gilzoide","https://liberapay.com/gilzoide"],"categories":[],"sub_categories":[],"readme":"# Key-Value Store for Unity\n[![openupm](https://img.shields.io/npm/v/com.gilzoide.key-value-store?label=openupm\u0026registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.gilzoide.key-value-store/)\n\nSimple to use Key-Value Store interface and implementations for Unity, suitable for save systems.\n\nKey-Value Stores provide a simple and effective way of persisting arbitrary data mapped to string keys.\nPossible implementations of Key-Value Stores include, but are not limited to:\n[C# Dictionary](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.dictionary-2),\n[PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html),\n[LiteDB](https://github.com/mbdavid/LiteDB) / [UltraLiteDB](https://github.com/rejemy/UltraLiteDB),\n[FASTER KV](https://github.com/microsoft/FASTER),\n[LMDB](https://www.symas.com/lmdb),\n[SQLite](https://www.sqlite.org/),\n[iCloud KVS](https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore),\n[macOS/iOS Keychain](https://developer.apple.com/documentation/security/keychain_services/keychain_items),\n[Android Keystore](https://developer.android.com/training/articles/keystore)\n...\n\n\n## Features\n- Simple to use `IKeyValueStore` interface with methods for setting, getting and deleting key-value pairs\n- Custom serialization of complex objects (class/struct types).\n  You can set the default serializer for all objects, as well as one serializer per object type.\n  Choose between serializing to text or binary format by implementing either `ITextSerializer\u003c\u003e` or `IBinarySerializer\u003c\u003e` interfaces.\n- Wrapper for automatically saving data from Key-Value Stores\n\n\n## Implementations\nKey-Value Stores:\n- [DictionaryKeyValueStore](Runtime/DictionaryKeyValueStore.cs): stores data in a `Dictionary\u003cstring, object\u003e`.\n  May be persisted in disk if [Json.NET](https://www.newtonsoft.com/json) is installed in the project, for example via the [Newtonsoft Json Unity Package](https://docs.unity3d.com/Packages/com.unity.nuget.newtonsoft-json@latest).\n  Supports compression using [GZip](https://learn.microsoft.com/en-us/dotnet/api/system.io.compression.gzipstream?view=netstandard-2.1) and encryption/decryption using [SymmetricAlgorithm](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.symmetricalgorithm).\n- [PlayerPrefsKeyValueStore](Runtime/PlayerPrefsKeyValueStore.cs): stores data using Unity's [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) class\n- [EditorPrefsKeyValueStore](Editor/EditorPrefsKeyValueStore.cs): stores data using Unity's [EditorPrefs](https://docs.unity3d.com/ScriptReference/EditorPrefs.html) class (editor only)\n- (external) [SqliteKeyValueStore](https://github.com/gilzoide/unity-key-value-store-sqlite): stores data using the [SQLite](https://sqlite.org) database engine.\n- (external) [GenericPasswordKeychainItemKeyValueStore](https://github.com/gilzoide/unity-key-value-store-apple-keychain): stores data into a Generic Password Keychain Item in Apple platforms (macOS, iOS, tvOS, visionOS).\n- (external) [ICloudKeyValueStore](https://github.com/gilzoide/unity-key-value-store-icloud-kvs): stores data using iCloud Key-Value Store in Apple platforms (macOS, iOS, tvOS, visionOS).\n\nObject serializers:\n- [JsonUtilityTextSerializer](Runtime/ObjectSerializers/JsonUtilityTextSerializer.cs): the default serializer, uses Unity's [JsonUtility](https://docs.unity3d.com/ScriptReference/JsonUtility.html)\n- [NewtonsoftJsonTextSerializer](Runtime/ObjectSerializers/NewtonsoftJsonTextSerializer.cs): uses [Json.NET](https://www.newtonsoft.com/json), if it is installed in your project\n- [XmlTextSerializer](Runtime/ObjectSerializers/XmlTextSerializer.cs): uses C#'s [XmlSerializer](https://learn.microsoft.com/en-us/dotnet/api/system.xml.serialization.xmlserializer?view=netstandard-2.1)\n- [StructBinarySerializer](Runtime/ObjectSerializers/StructBinarySerializer.cs): serializes any unmanaged struct to binary using Unity's [UnsafeUtility](https://docs.unity3d.com/ScriptReference/Unity.Collections.LowLevel.Unsafe.UnsafeUtility.html).\n  Does not support classes.\n- [UnityMathTextSerializer](Runtime/ObjectSerializers/UnityMathTextSerializer.cs): serializes Unity math structs, like `Vector2` and `Matrix4x4`, to text as a list of numbers separated by commas.\n\n\n## How to install\nEither:\n- Use the [openupm registry](https://openupm.com/) and install this package using the [openupm-cli](https://github.com/openupm/openupm-cli):\n  ```\n  openupm add com.gilzoide.key-value-store\n  ```\n- Install using the [Unity Package Manager](https://docs.unity3d.com/Manual/upm-ui-giturl.html) with the following URL:\n  ```\n  https://github.com/gilzoide/unity-key-value-store.git#1.0.0\n  ```\n- Clone this repository or download a snapshot of it directly inside your project's `Assets` or `Packages` folder.\n\n\n## Basic usage\n```cs\nusing Gilzoide.KeyValueStore;\nusing UnityEngine;\n\n// 1. Instantiate one of the IKeyValueStore implementations\nIKeyValueStore kvs = new DictionaryKeyValueStore\n{\n    FilePath = Application.persistentDataPath + \"/MySaveFile.json\",\n};\n\n\n// 2. (optional) If Key-Value Store supports saving, load previous data\nif (kvs is ISavableKeyValueStore savableKvs)\n{\n    savableKvs.Load();\n}\n\n\n// 3. Set/Get/Delete values\nkvs.SetBool(\"finishedTutorial\", true);\nkvs.SetString(\"username\", \"gilzoide\");\n\nDebug.Log(\"Checking if values exist: \" + kvs.HasKey(\"username\"));\nDebug.Log(\"Getting values: \" + kvs.GetInt(\"username\"));\nDebug.Log(\"Getting values with fallback: \" + kvs.GetString(\"username\", \"default username\"));\n// Like C# Dictionary, this idiom returns a bool if the key is found\nif (kvs.TryGetString(\"someKey\", out string foundValue))\n{\n    Debug.Log(\"'someKey' exists: \" + foundValue);\n}\n\nkvs.DeleteKey(\"someKey\");\n\n\n// 4. (optional) If the Key-Value Store supports saving, save the data\nif (kvs is ISavableKeyValueStore savableKvs)\n{\n    savableKvs.Save();\n}\n```\n\n\n## Automatic saving\n```cs\nusing Gilzoide.KeyValueStore;\nusing UnityEngine;\n\n// 1. Instantiate one of the ISavableKeyValueStore implementations\nISavableKeyValueStore wrappedKvs = new DictionaryKeyValueStore\n{\n    FilePath = Application.persistentDataPath + \"/MySaveFile.json\",\n};\n\n\n// 2. Wrap the store into an AutoSaveKeyValueStoreWrapper and use it instead\nIKeyValueStore kvs = new AutoSaveKeyValueStoreWrapper(wrappedKvs);\n\n\n// 3. Whenever you set or delete values, `wrappedKvs.Save()` is automatically\n// called in the next frame. Notice that we skip a frame to avoid making lots\n// of I/O if you change lots of data in a single frame.\nkvs.SetBool(\"will this be saved automatically next frame?\", true);\n```\n\n\n## Class/struct serialization\n```cs\nusing System.Collections.Generic;\nusing Gilzoide.KeyValueStore;\nusing Gilzoide.KeyValueStore.ObjectSerializers;\nusing UnityEngine;\n\nIKeyValueStore kvs = new DictionaryKeyValueStore();\n\n// 1. Set/Get objects\nkvs.SetObject(\"aVector\", new Vector3(1, 2, 3));\nif (kvs.TryGetObject(\"lastPosition\", out Vector3 lastPosition))\n{\n    Debug.Log(\"Last position was: \" + lastPosition);\n}\n\n\n// 2. (optional) Use custom serializers\nvar newtonsoftJsonSerializer = new NewtonsoftJsonSerializer();\nkvs.SetObject(\"jsonList\", new List\u003cint\u003e { 1, 3, 5, 9 }, newtonsoftJsonSerializer);\nList\u003cint\u003e anotherJsonList = kvs.GetObject\u003cList\u003cint\u003e\u003e(\"someKey\", newtonsoftJsonSerializer);\n\n\n// 3. (optional) Add serializers to the default serializer map\n// This makes them be used even when not passed explicitly\nObjectSerializerMap.DefaultSerializerMap.SetObjectSerializer\u003cList\u003cint\u003e\u003e(newtonsoftJsonSerializer);\n\nkvs.SetObject(\"jsonList\", new List\u003cint\u003e { 1, 3, 5, 9 });\nList\u003cint\u003e yetAnotherJsonList = kvs.GetObject\u003cList\u003cint\u003e\u003e(\"someKey\");\n\n\n// 4. (optional) Use your own ObjectSerializerMap\nvar unityMathTextSerializer = new UnityMathTextSerializer();\nvar serializerMap = new ObjectSerializerMap\n{\n    DefaultSerializer = newtonsoftJsonSerializer,\n    TypeToSerializerMap = new Dictionary\u003cType, IObjectSerializer\u003e\n    {\n        [typeof(Vector2)] = unityMathTextSerializer,\n        [typeof(Vector3)] = unityMathTextSerializer,\n        [typeof(Vector4)] = unityMathTextSerializer,\n    },\n};\n\nkvs.SetObject(\"uses UnityMathTextSerializer\", new Vector2(10, 5), serializerMap);\nkvs.SetObject(\"uses NewtonsoftJsonSerializer\", new int[] { 1, 2, 3 }, serializerMap);\n\n// (tip) to avoid the annoyance of adding all math types manually, call this:\nunityMathTextSerializer.RegisterInSerializerMap(serializerMap);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgilzoide%2Funity-key-value-store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgilzoide%2Funity-key-value-store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgilzoide%2Funity-key-value-store/lists"}