持久化数据

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

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

提示

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

文件格式

持久化数据会自动以 TOML 格式存储在 Packages/ 目录下的 .data/ 文件夹中以你的包命名的文件中，例如 Packages/.data/my-package.toml（服务器端和客户端均是如此）。

只有当你调用 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 将为：
-- awesome_table = { my_id = 123, my_data_02 = "data" }

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

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

-- Packages/.data/my-package.toml 将为：
-- awesome_table = { my_id = 123, my_data_02 = "another data" }

然后检索数据，传递你想要的键：

local my_table = Package.GetPersistentData("awesome_table")

Console.Log(my_table.my_id)

-- 将打印：
-- 123

若要删除某个值，请将其设置为 nil：

Package.SetPersistentData("awesome_table", nil)

何时保存？

写入磁盘速度较慢，因此 SetPersistentData 仅修改内存中的数据并将其标记为待保存。待处理的修改会在较短时间后以及包卸载时自动写入磁盘。

如果你确实需要立即写入数据（例如在执行有风险的操作之前），请调用 Package.FlushPersistentData()。避免频繁调用它，因为每次调用都会写入整个文件。

提示

持久化数据非常适合小数据量，例如设置或小型排行榜。要存储大量数据或非常频繁变动的数据（如每个玩家的物品栏），建议优先使用 Database。