Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Worker

local w = Worker("worker.lua")

在独立线程里运行 worker.lua(路径相对于模组目录)。worker 有自己独立的 Lua 状态,和游戏线程并行执行,所以耗时的计算、解析、文件处理不会卡游戏。

worker 和主脚本之间只能通过消息交换数据。游戏对象(UObject)不能进入 worker:引擎只允许游戏线程访问它们,在别的线程里碰会随机崩溃。

游戏线程一侧

方法说明
w:post(msg)发消息给 worker。返回前已完整复制,之后修改 msg 不影响 worker
w:onMessage(fn)设置接收 worker 消息的回调 fn(msg),在游戏线程执行,可以放心操作游戏对象。返回 w
w:alive()worker 线程是否还在运行
w:close()停止 worker。模组被禁用或重新加载时会自动关闭,不必手动调用

回调大约每 50 ms 投递一次,每个 worker 每次最多 256 条。

worker 一侧(worker.lua 里的全局)

名称说明
onMessage(fn)注册 fn(msg),收到主脚本的每条消息时调用。注册后线程会一直等待消息,直到被关闭;不注册则脚本跑完线程就结束
post(msg)发消息给游戏线程(触发 w:onMessage 的回调)
Sleep(ms)等待,关闭 worker 时会提前醒来;被要求停止时返回 false
IsStopping()worker 是否正在被关闭。长循环里可以检查它
print(...)写进 kmod 日志,带 [worker <模组id>] 前缀
json.encode(v) / json.decode(s)与 kmod.json 相同
fs.read(path)读取 kmod 目录内的文件,失败返回 nil
fs.write(path, data)写文件,只能写在 kmod/data/ 内,返回是否成功
fs.exists(path) / fs.list(dir)判断存在、列目录({name=, dir=} 列表),只限 kmod 目录内
paths.rootkmod 根目录
标准库string、table、math、utf8、coroutine,以及只含 time/clock/date 的 os

worker 里没有:io、require、dofile、loadfile、os.execute、Hook 一类的游戏 API、FindFirstOf 等。

能发送什么

nil、boolean、number、string,以及由它们组成的 table(键只能是字符串、数字、布尔值)。函数、userdata、游戏对象不能发送,post 会抛错。嵌套最多 32 层,所以包含自己的表也会被拒绝。

队列最多 20000 条,满了 post 抛错,这是为了避免一方发得太快把内存撑满。

错误与停止

  • worker 里的脚本出错,错误写进日志并计入模组的错误数(和钩子出错一样,累计 10 次自动停用模组)。出错后线程结束。
  • 一个死循环的 worker 也能被关闭:Lua 每执行几千条指令会检查停止标记。关闭最多等 2 秒,之后线程被放弃,不会拖住游戏。
  • 每个游戏同时最多 16 个 worker。

示例

main.lua:

local w = Worker("worker.lua")
w:onMessage(function(m)
  Log.info("素数个数:" .. m.count)
end)
w:post({ cmd = "primes", n = 3000000 })     -- 不会卡游戏

worker.lua:

onMessage(function(m)
  if m.cmd == "primes" then
    local count, sieve = 0, {}
    for i = 2, m.n do
      if not sieve[i] then
        count = count + 1
        for j = i * 2, m.n, i do sieve[j] = true end
      end
    end
    post({ count = count })
  end
end)

什么时候用

适合:解析大 JSON、扫描目录、批量计算、需要等待的任务。不适合:需要读写游戏对象的事。那类操作在 onMessage 回调里(游戏线程)做,例如 worker 算好要改的卡牌列表,回调里再逐个应用。