运行环境与可用库

一个软件包会运行在多个隔离的 Lua 环境里。搞清楚「这段代码在哪里跑」，能避免一大半的「函数未定义」「对象不存在」问题。

三个环境

环境	何时创建	加载的文件	能访问游戏对象？
任务环境	任务启动时，每个任务一份	根目录 `index.lua`	否
界面环境	打开任务面板时，每个任务一份	`ui/` 下的表单	否
游戏环境	游戏客户端自身	`inject/` 脚本	是

任务 / 界面环境要访问 Player、Pet、Talk 等对象，只能经 DoLuaString 送到游戏环境执行，详见游戏原生接口。各环境可用的全局函数见 VM 全局函数。

任务与界面环境是标准的 Lua 5.1（gopher-lua）状态，带完整基础库，常用标准库都可用：

base：assert、pairs、ipairs、type、tostring、tonumber、pcall、print、error 等；
string、table、math；
os：os.time()、os.date()、os.clock() 都可用，用来做定时 / 计时很方便；
其它：io、debug、coroutine、package。

提示

判断「该不该做某件事」时可以用 os.time() 记时间戳。例如喊话器按秒间隔轮询：

if os.time() - lastSendAt >= intervalSec then
  return 2
end

备注

虽然 io 库存在，但任务通常不需要、也不建议直接读写文件；需要持久化数据请用 GetRoleSettings / SetRoleSettings（见 VM 全局函数）。

任务之间互相隔离：每个任务一份 Lua 状态，全局变量不共享。想跨任务传数据，只能用 SetRoleSettings，或通过任务之间的依赖关系。
index.lua 只加载一次：任务是「加载一次、循环调用 Check / Main」，所以文件顶层的 local 变量会一直存活，适合放缓存与运行状态；但任务停止 / 重启后会重置。
界面环境也是独立的：ui/ 里的代码与 index.lua 不共享变量；改完 Lua 记得在面板点「重载」让界面环境重新加载。
Delay 会响应停止：Delay(ms) 期间若任务被停止，会立即中断并结束任务，不会继续往下执行。

require 的搜索路径包含软件包自身目录与 apps/ 根目录：

local main = require("ui.main")                -- 本包内
local hmPlayer = require("黑猫@基础库.player")  -- 其它软件包（需先声明依赖）

每个软件包目录下的 .luarc.json 会把仓库根目录的 lua_types/ 加入语言服务器的库路径，由 lua_types/global.lua 为编辑器提供 VM 全局函数的签名。

提示

新增 VM 全局函数后，请同步更新 lua_types/global.lua，否则编辑器会误报 Undefined global 'xxx'。详见目录结构。