Lua 脚本与更新
当前脚本运行时为 modules/script 的 ScriptRuntime,使用原生 Lua C API。vcpkg manifest 锁定 Lua 5.5.1;运行时与预编译工具保持版本兼容。
执行摘要
已有模块预备、提交、回滚、故障归因、沙盒、契约表装载及异步交接原语。fleetctl module 已接通跨 World 灰度发布、观察与故障回滚;临时 Scene 脚本状态随生命周期装配和清理。完整业务后端及进程重启后的版本恢复仍需验收。
1. 职责
Lua 承担动态玩法;C++ 持有网络、Scene、AOI、属性及持久化。启动时注入具名服务接口,不让脚本任意反查应用容器。任何模拟变更都在所属逻辑线程执行。
2. 宿主
一个 ScriptRuntime 由其所属执行者顺序使用,prepare/commit 等控制操作也必须符合串行约束。不能把同一 Lua 状态交给多个 World 线程并发执行。
WorldApp 当前装配一个脚本状态并接入默认 Scene。多 Instance 的私有脚本状态和任务隔离属于完整副本接线要求,不能把共享全局表称为已隔离。
3. 模块更新
3.1 模块身份
模块携带名称、版本与依赖。准备和提交前校验依赖、绑定和资源约束;拒绝缺失或不兼容内容。
3.2 prepare / commit / rollback
prepare_module 产生预备结果,commit_module 在所属 tick 边界切换,rollback_module 恢复可用旧版本。通过 module_faults_since 等原语观察灰度故障。跨 World 编排由 fleetctl module 与 World 控制面提供,drill_module_update.sh 验证双 World 灰度发布与故障回滚;不据此推导所有生产故障路径已覆盖。
代码更新保留 wire;C++ 更新使用进程替换。活跃副本连续运行、状态兼容与超时排空需要单独验证。
3.3 状态和版本
明确旧协程、模块私有状态及回滚期间的业务写入策略。持久版本记录等原语需要宿主装配和恢复验证,不能只依赖内存中的当前版本号。
3.4 契约表
load_contract 消费生成 contract.lua,包含路由和权限元数据。装载表不是对所有客户端自动完成协议更新。契约变化仍按SDK 兼容规则发布。
3.5 字节码
已有 Lua 预编译与缓存原语。字节码和 manifest 必须匹配 Lua 版本、平台及源版本,错配显式失败;不能把来自不同构建环境的字节码直接当成可用补丁。
4. 服务注入
C++ 注册有限的具名接口,校验参数、对象生存期、会话及权威代次。不得向脚本开放任意网络地址、任意持久写入或跨线程 Scene 指针。
5. 属性钩子
在明确的模拟阶段运行属性钩子,使用写白名单和预算。钩子不能递归触发无界重算,也不能绕过属性可见性、ChangeSink 或结算去重边界。
WorldApp 已有脚本与 Scene 接线原型;完整玩法的属性写入、同步下行和长期资料保存仍需连同真实业务验证。
6. 沙盒和故障
运行时提供指令/内存预算与故障/熔断原语。配置和测试应覆盖死循环、分配超限、异常、预算恢复与回滚。错误归因和日志不能代替恢复结果确认。
6.1 故障事件
通过固定运行时观察接口输出故障与模块状态,不在脚本故障路径同步调用外部 HTTP。是否真正满足模拟时延预算需要应用负载验证。
7. 调试与观测
调试 eval 通过受控入口交接到 tick 边界;只读查询与写操作分级。协程、模块版本、内存和耗时有各自观察面,不以开放任意脚本执行替代运维权限。
暂停整个逻辑线程会影响所有承载副本,不能把断点式暂停作为在线可用性保证。外部性能采样与运行时统计分开使用。
8. 异步任务
8.1 后端边界
register_async_service 是宿主扩展点,不代表已经接入 Redis、SQL 或完整跨服业务。执行器必须尽快返回,将阻塞工作放到合适线程或外部服务。
8.2 交接
complete_async / fail_async 从后台投递,drain_async 在所属边界处理完成、超时和协程恢复;即使同线程完成也不绕过交接点。
8.3 校验和取消
通过 set_async_validator 重新确认对象、会话与权威;cancel_pending 协作取消。Instance 销毁或玩家迁移后,旧请求完成不能恢复出可继续写入的旧对象。
9. 验收
分别验证本地模块切换、灰度失败与回滚、异步完成/取消、私有状态隔离和跨 World 发布。代码热替换、协议升级、TCP 连续和活动副本连续是不同验收项。当前任务仅维护在根目录 todo.md。
