EZStorage

Easily store/fetch data using key-value storage.

• EZStorage
  • A low-level key-value storage using the file system.
  • Store/Fetch anything that would work with var2str.
  • Replication logic can prevent corrupted files.
• EZCache
  • An efficient in-memory cache that only loads files once.
  • Includes events for receiving updates when values change.

Settings

Settings can be found under application/storage in the project settings.

Directory

The directory used to save the data. It should be at least in user:// and by default is user://data.

If you need to further customize the directory use EZStorage.set_directory_suffix(unique_id). This is useful to support multiple users.

Debug Filenames

When enabled file names will use html encoding making it easier to debug the files created. This feature can be disabled to use filenames that would be used in release mode.

Provider

The system used for saving data.

Directory

Saves data using folders. This is a reliable and quick method but creates many files on your system. It may not be ideal in some situations like with cloud saves.

Directory V2

Similar to Directory but uses less resources and is faster.

Files

Saves data using a file for each section. Updating a key rewrites the file. Lightweight and good performance when key+values are small per section.

File

Saves data using a fixed number of files, currently 2, but it's slower and wastes memory compared to Directory.

Comparison

Comparison of different providers. Take note of the Status.

• Stable is recommended to use.
• Deprecated is not recommeneded to use.
• Experimental lacks features or possible bugs.

API

EZStorage API

A low-level key-value storage using the file system.

# Setup a custom directory, do this before storing/fetching data
EZStorage.set_directory_suffix(steam_id)

# Store a value.
EZStorage.store("my_section", "my_key", "my_value")


# Fetch a value, return null if key does not exist.
EZStorage.fetch("my_section", "my_key")

# Fetch a value, return "my_default" if key does not exist
EZStorage.fetch("my_section", "my_key", "my_default")


# Delete "my_section/my_key".
EZStorage.purge_section_key("my_section", "my_key")

# Delete all data in "my_section" execpt keys listed.
EZStorage.purge_section("my_section", ["skip", "these", "keys"])

# Delete all data except sections listed.
EZStorage.purge(["skip", "these", "sections"])

EZCache API

An efficient in-memory cache that only loads from storage once.

# Create a cache.
var my_section = EZCache.get_section("my_section")


# Store a key in the cache.
my_section.store("my_key", "my_value")


# Fetch a value, return null if key does not exist.
var my_value = my_section.fetch("my_key")

# Fetch a value, return "my_default" if key does not exist.
var my_value = my_section.fetch("my_key", "my_default")

# Fetch a value, return "my_default" if key does not exist. Will set "my_default" in the cache for future fetching.
var my_value = my_section.fetch("my_key", "my_default", true)]

# Delete a key from the section.
my_section.purge_key("delete_this_key")

# Delete all keys in my_section except those listed.
my_section.purge(["skipped_key"])

# Delete all sections in cache except those listed.
EZCache.purge(["skipped_section"])

# Yield until a key is changed on the cache
var key = yield(my_section, "changed")
print("The following key changed in my_section: ", key)

# Connect method and listen to key change events
function _key_changed(key: String) -> void:
  print("The following key changed in my_section: ", key)
my_section.connect("changed, self, "_key_changed")

Example

Pokaban uses signals from EZCache to update the level select screen by adjusting the stars displayed after beating stages.