跳到主要内容

目录结构

一个软件包是 apps/ 下的一个目录。下面是一个任务类型软件包的典型结构：

apps/黑猫@我的任务/
├── .hm.json            # 【必需】软件包清单
├── index.lua           # 【任务必需】任务入口（CheckTime / Check / Main）
├── ui/                 # 界面目录（可选）
│   ├── index.lua       # 【界面必需】注册表单，定义 Init()
│   ├── main.lua        # 主表单模块
│   └── form_xxx.lua    # 其它子表单模块（可选）
├── inject/             # 注入脚本（可选，通常只在函数库中使用）
│   └── xxx.lua
├── global.lua          # 自定义模块，可被 require
└── player.lua          # 自定义模块，可被 require

一个函数库类型软件包的结构更简单，通常没有 index.lua 与 ui/：

apps/黑猫@基础库/
├── .hm.json
├── global.lua          # require("黑猫@基础库.global")
├── player.lua          # require("黑猫@基础库.player")
├── package.lua
└── inject/             # 注入到游戏客户端的原生脚本
    ├── player.lua
    └── package.lua

各文件 / 目录的职责​

.hm.json —— 清单（必需）​

描述软件包的元信息：名称、作者、类型、版本、依赖等。详见 清单 .hm.json。

index.lua —— 任务入口​

任务类型软件包的运行入口。它需要定义：

  • CheckTime：数字，检查间隔（毫秒）。
  • Check()：返回数字，决定是否执行 Main。
  • Main()：真正执行的逻辑。

详见 运行机制。

备注

运行任务时只会加载根目录的 index.lua，其余 .lua 文件需要通过 require 主动引入。

ui/ —— 界面目录​

存放表单界面。存在 ui/index.lua 时，助手会以「新方式」加载界面：先 require 表单模块， 再调用全局函数 Init()。详见 界面（表单）。

inject/ —— 注入脚本​

inject/ 下的 .lua 文件不在本软件包的运行环境中执行，而是被注入到游戏客户端的 Lua 环境中执行。它主要用于函数库向任务暴露游戏原生操作。

例如 黑猫@基础库/inject/player.lua 定义了一个函数：

apps/黑猫@基础库/inject/player.lua
function hml_getPlayerHpPercent()
  local hp = Player:GetData("HP")
  local maxHp = Player:GetData("MAXHP")
  return hp * 100 / maxHp
end

任务再通过 DoLuaString 调用它：

local percent = DoLuaStringAndGetInteger("return hml_getPlayerHpPercent()")
注意

任务的 inject/ 目录不会在任务自己运行时被注入。只有被依赖的函数库的 inject/ 目录才会被注入。因此任务自身需要原生能力时，应把它放进被依赖的函数库，或直接依赖基础库。

其它 .lua 文件 —— 可复用模块​

根目录及子目录下的任意 .lua 文件都可以通过 require 引入。require 的搜索路径包含：

  • 软件包自身目录（如 require("ui.main") → ui/main.lua）。
  • apps/ 根目录，用全名引用其它软件包（如 require("黑猫@基础库.global") → apps/黑猫@基础库/global.lua）。
-- 引用自身目录下的模块
local main = require("ui.main")
-- 引用其它软件包
local hmPlayer = require("黑猫@基础库.player")

开发环境小贴士：类型提示​

在 apps/ 目录下开发时，现代编辑器（如 VS Code + Lua Language Server）可以借助 .luarc.json 与类型存根获得函数签名与自动补全。

  • 每个软件包目录下都有一个 .luarc.json，它把仓库根目录下的 lua_types/ 加入语言服务器的库搜索路径：

    apps/黑猫@我的任务/.luarc.json
    {
      "workspace": {
        "library": [
          "${workspaceFolder}/..",
          "${workspaceFolder}/../../lua_types"
        ],
        "ignoreDir": ["inject"]
      }
    }

  • lua_types/global.lua 声明了所有 VM 注入全局函数的签名（以 ---@meta 开头）。 它只是给编辑器看的类型存根，不参与运行。

提示

如果你新增了 VM 全局函数，记得同步更新仓库根目录的 lua_types/global.lua， 这样所有软件包都能获得补全。

下一步：软件包清单 .hm.json。