VM 全局函数

助手在运行你的 Lua 代码时，会预先注入一批全局函数。它们不需要 require，直接调用即可。

三个运行环境

理解这些函数从哪里来，有助于避免「函数未定义」的问题：

环境	说明	典型文件
任务环境	每个任务独立一份，运行 `index.lua`	`index.lua`
界面环境	每个任务独立一份，运行 `ui/` 下的表单	`ui/*.lua`
游戏环境	游戏客户端自身的 Lua，可访问 `Player`、`Pet` 等原生对象	`inject/*.lua`

任务/界面环境无法直接访问游戏对象，需要通过 DoLuaString 系列函数把代码送进游戏环境执行。

可用性总览

函数	任务环境	界面环境	说明
`GoPrint(...)`	✅	✅	打印日志（同时输出到服务器日志与前端日志面板）
`DoLuaString(code)`	✅	✅	在游戏环境执行代码，无返回值
`DoLuaStringAndGetTable(code)`	✅	✅	执行并返回 table
`DoLuaStringAndGetBool(code)`	✅	✅	执行并返回 boolean
`DoLuaStringAndGetString(code)`	✅	✅	执行并返回 string
`DoLuaStringAndGetNumber(code)`	✅	✅	执行并返回 number
`DoLuaStringAndGetInteger(code)`	✅	✅	执行并返回 integer
`GetRoleSettings(name)`	✅	✅	读取按角色持久化的配置
`SetRoleSettings(name, value)`	✅	✅	写入按角色持久化的配置
`GetRoleSettingsVersion(name)`	✅	✅	读取配置版本号
`Delay(ms)`	✅	❌	暂停指定毫秒
`Exit()`	✅	❌	停止当前任务
`PushCommand(target, command, args)`	❌	✅	向前端推送命令
`AddTask(name)`	❌	✅	启动一个任务
`RemoveTask(name)`	❌	✅	停止一个任务
`RegisterForm(name, module)`	❌	✅	注册一个表单（见界面）
`CurrentSettings`	✅（变量）	❌	当前任务配置（启动时快照）

日志

GoPrint("hello", 123)
GoPrint("开始执行任务")

GoPrint 支持任意多个参数，会拼成一行：既写入服务器日志，也会推送到前端日志面板（在前端会带上时间、客户端与级别）。

在游戏环境执行代码

这是任务与游戏交互的核心。你无法在任务里直接使用 Player、Pet 等对象，而是把一段 Lua 代码字符串交给游戏环境执行。

-- 无返回值：直接执行
DoLuaString("AutoRunToTarget(100, 200)")

-- 有返回值：代码里必须有 return
local name = DoLuaStringAndGetString("return Player:GetName()")
local hp = DoLuaStringAndGetInteger("return Player:GetData('HP')")
local pos = DoLuaStringAndGetTable("return hml_getCurrentPosition()")
local ok = DoLuaStringAndGetBool("return hml_hasPetFight()")

返回值会按 JSON 转换回 Lua：

GetTable 返回一个 table；
GetBool / GetString / GetNumber / GetInteger 返回对应类型；
GetInteger 适合取整型（如 ID、血量）。

注意

使用 xxxAndGetYyy 时，代码字符串里必须包含 return，否则拿不到结果。

inject/ 脚本里定义的函数（如 hml_getCurrentPosition）就是通过这种方式调用的。常见能力已经封装在黑猫@基础库中，优先使用它们。

配置存储（按角色）

GetRoleSettings / SetRoleSettings 按「角色 + 名称」读写持久化配置，常用于缓存和跨任务共享数据：

-- 读取名为 "yuanbao_shop_items" 的配置
local data = GetRoleSettings("yuanbao_shop_items")

-- 写入配置
SetRoleSettings("my_cache", { items = { "a", "b" } })

-- 版本号：每次写入都会自增，可用于判断缓存是否需要刷新
local version = GetRoleSettingsVersion("my_cache")

任务自身的界面配置（CurrentSettings）也使用同一套存储，其名称就是任务的全名。

任务控制

以下函数在任务环境中可用：

-- 暂停 500 毫秒；等待期间若任务被停止会立即结束
Delay(500)

-- 主动停止当前任务
Exit()

在界面环境中，可以启动/停止其它任务：

-- 启动全名为 "黑猫@挂机打怪" 的任务
AddTask("黑猫@挂机打怪")

-- 停止它
RemoveTask("黑猫@挂机打怪")

向前端推送命令

PushCommand 在界面环境中使用，用于让前端执行动作（打开子表单、往列表添加项等）：

-- 通用命令：target 传 nil 或省略
PushCommand(nil, "openForm", { formName = "selectUseItem", title = "选择物品" })

-- 列表命令：target 为列表组件的 field
PushCommand("useItems", "addItems", { { label = "金创药" } })

命令的完整列表见事件与命令。

三个运行环境​

可用性总览​

日志​

在游戏环境执行代码​

配置存储（按角色）​

任务控制​

向前端推送命令​