Persistent Data

How to store and retrieve persistent data from disk using the built-in system.

In nanos world it is possible to store and retrieve data from disk with simple functions.

tip

It is possible to store Persistent Data in both Client and Server!

File Format

The persistent data is automatically stored in the TOML format, in a file named after your Package inside the .data/ folder of the Packages/ directory, e.g. Packages/.data/my-package.toml (both server and client side).

This file is only created if you call Package.SetPersistentData().

Storing and Retrieving data

All PersistentData files are loaded automatically when the Package loads and stored in memory. You can easily access the whole file with Package.GetPersistentData().

For storing data you will need to pass a key value, which will store any lua value in that key.

Examples

local my_table = {
    my_id = 123,
    my_data_02 = "data"
}

Package.SetPersistentData("awesome_table", my_table)

-- Packages/.data/my-package.toml will be:
-- awesome_table = { my_id = 123, my_data_02 = "data" }

You can also set an individual value in the table with the dot notation:

Package.SetPersistentData("awesome_table.my_data_02", "another data")

-- Packages/.data/my-package.toml will be:
-- awesome_table = { my_id = 123, my_data_02 = "another data" }

Then retrieving the data, passing the key you want:

local my_table = Package.GetPersistentData("awesome_table")

Console.Log(my_table.my_id)

-- Will print:
-- 123

To delete a value, set it to nil:

Package.SetPersistentData("awesome_table", nil)

When is it Saved?

Writing to disk is slow, so SetPersistentData only changes the data in memory and marks it to be saved. The pending changes are written to disk automatically after a short time, and when the Package unloads.

If you really need the data to be written immediately (e.g. before a risky operation), call Package.FlushPersistentData(). Avoid calling it often, as each call writes the whole file.

tip

Persistent Data is great for small amounts of data, such as settings or a small leaderboard. To store a lot of data or data which changes very often (like the inventory of every player), prefer using a Database.