DataStore 数据存储 1.4.0+

DataStore 模块提供基于类属性的自动数据存储能力，是当前推荐的数据存储方案。

推荐用法

服务端使用 ServerAutoStoreCls，客户端使用 ClientAutoStoreCls。定义数据类后，直接读写类属性即可触发懒加载与延迟保存。

服务端存储

服务端数据通过网易 ExtraData 存储在当前存档中。

# -*- coding: utf-8 -*-
from .QuModLibs.Modules.DataStore.Server import ServerAutoStoreCls

class ServerData(ServerAutoStoreCls):
    __VERSION__ = 1
    __AUTO_SAVE_INTERVAL__ = 8.0
    __SAVED_MOD_KEY_NAME__ = "server_data"

    count = 0
    playerNames = []

def addCount():
    ServerData.count += 1
    ServerData.playerNames.append("Steve")
    # 修改可变容器内部内容时，建议显式标记需要保存。
    ServerData.mSignNeedUpdate()

客户端存储

客户端数据通过 ConfigClient 存储。默认是当前存档数据；如果需要跨存档共享，可以设置 __GLOBAL_MODE__ = True。

# -*- coding: utf-8 -*-
from .QuModLibs.Modules.DataStore.Client import ClientAutoStoreCls

class ClientData(ClientAutoStoreCls):
    __VERSION__ = 1
    __GLOBAL_MODE__ = False
    __SAVED_MOD_KEY_NAME__ = "client_data"

    uiScale = 1.0
    lastTab = "main"

def updateTab(tabName):
    ClientData.lastTab = tabName

配置项

• __VERSION__：数据版本，默认 1。存档中的版本与当前版本不一致时，会丢弃旧数据。
• __AUTO_SAVE_INTERVAL__：延迟自动保存间隔，默认 8.0 秒。
• __SAVED_FULL_NAME__：完整存储 Key。设置后会直接使用该值。
• __SAVED_MOD_KEY_NAME__：按当前 Mod 名自动隔离的存储 Key，实际格式为 ModDirName.xxx。
• __GLOBAL_MODE__：仅客户端可用。False 表示当前存档数据，True 表示客户端全局数据。

保存机制

DataStore 使用元类拦截类属性读写：

• 首次读取或写入数据属性时，会调用 mLoadUserData() 懒加载存档数据。
• 类属性被赋予新值时，会调用 mSignNeedUpdate() 标记需要保存。
• 标记后会注册延迟保存定时器，并在环境销毁时补一次保存。
• 普通数字、字符串、布尔值和 None 会直接保存；其他对象会用 pickle 打包。

可变容器注意

DataStore 能自动捕获 Data.value = newValue 这类赋值，但无法自动感知 list.append()、dict["key"] = value 这种容器内部原地修改。修改可变容器后，请调用 mSignNeedUpdate() 或重新赋值一次。