持久化数据

如何使用内置系统从磁盘存储和检索持久数据。

在 nanos world 中，可以使用简单的函数从磁盘存储和检索数据。

提示

持久化数据可以同时存储在客户端和服务器！

文件格式

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).

只有当你调用 Package.SetPersistentData() 时才会创建此文件。

存储与检索数据

所有 PersistentData 文件在包加载时自动加载并存储在内存中。你可以使用 Package.GetPersistentData() 轻松访问整个文件。

要存储数据，你需要传递一个 key 值，该值会将 any lua 值存储在该键中。

示例

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" }

你还可以使用点号表示法在表格中设置单个值：

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.

提示

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.