【后端接口】setplayvar：玩家变量的三级范围与落库标记

实战应用：用在哪里

setplayvar 是玩家自定义变量的读写接口：师门贡献、活跃天数、挑战次数这类业务状态全部存这里。接口的参数表把变量的三要素定死了：范围（HUMAN/GUILD）、名字、是否落库，第三个 isSave 参数是内存变量与持久变量的分界线。

接口签名与读写

---给玩家自定义变量赋值 varType:HUMAN/GUILD varName:变量名 isSave:1落库
function setplayvar(actor, varType, varName, varValue, isSave) end
function getplayvar(actor, varType, varName) end

-- 师门贡献：持久化变量
setplayvar(actor, "HUMAN", "师门贡献", 120, 1)
local point = getplayvar(actor, "HUMAN", "师门贡献")

-- 临时标记：当日已领奖，不落库
setplayvar(actor, "HUMAN", "今日已领", 1, 0)

varType 选 HUMAN 就是玩家维度，选 GUILD 挂到行会维度。isSave 置 1 的变量写入数据库随档保存，置 0 的只活在本进程内存，重启即清。划分的原则：玩家花了钱或投了时间的数值必须落库，跨天重置类的临时标记不落库，落库是有成本的，滥用落库会让存档膨胀。

变量的初始化

-- 引擎侧初始化变量声明（启动时执行）
function oninit()
    iniplayvar(nil, "HUMAN", 100, "师门贡献")
    iniplayvar(nil, "HUMAN", 100, "活跃天数")
end

变量要先声明后使用，iniplayvar 在启动钩子里声明变量的容量与类型，未声明的变量读写行为不可预期。读接口对不存在的变量返回空值，业务层拿到后要做类型转换与默认值兜底，tonumber(getplayvar(...)) or 0 是标准写法。

验证与监控

落库变量的写入频次监控，单个变量每分钟写入超过 10 次说明调用方在高频循环里刷写，需要合并写。

踩坑记录

变量名的中文命名在早期版本有序列化兼容问题，改为拼音与下划线后稳定，变量命名的规范是英文加下划线。isSave 忘传的场景让一个赛季的排位分在重启后蒸发，从此落库标记进了代码评审的必查项，凡是积分、货币、进度的变量缺 isSave=1 直接打回。

上线要点

setplayvar 的写入是即时的但落库是批量的，极端宕机场景末尾几秒的落库变量可能丢失，货币与交易类强一致数值不走这套接口而走专门的资产接口。变量的读取在热路径上要做局部缓存，循环里反复 getplayvar 是常见的性能反模式。GUILD 范围的变量读写权建议只开放给行会管理类脚本，避免个人脚本污染行会数据。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。