跳到主要内容

编写第一个软件包

这一节我们从一个最小的任务开始：它每隔一秒打印一次计数，数到 5 次后自动退出。 跟着做完，你就掌握了软件包的基本骨架。

1. 创建目录​

在助手的 apps/ 目录下新建一个文件夹，名字就是软件包的全名，例如 黑猫@你好世界：

apps/黑猫@你好世界/

2. 编写清单 .hm.json​

apps/黑猫@你好世界/.hm.json
{
  "名称": "你好世界",
  "作者": "黑猫",
  "类型": "任务",
  "版本": "v1.0",
  "简介": "我的第一个软件包",
  "仓库地址": "",
  "依赖软件包": {}
}

类型 设为 "任务"，它才会出现在任务列表里。

3. 编写任务入口 index.lua​

apps/黑猫@你好世界/index.lua
-- 每隔 1000 毫秒检查一次
CheckTime = 1000

-- 计数器
local count = 0

-- 返回非 0 表示可以执行 Main
function Check()
  return 1
end

function Main()
  count = count + 1
  GoPrint("你好，世界！第 " .. count .. " 次")

  if count >= 5 then
    GoPrint("数到 5 了，任务结束")
    Exit()
  end
end

要点说明：

  • GoPrint(...) 是助手的日志函数，会打印到调试日志里。
  • Check() 返回 1，表示每次检查都执行 Main()。
  • Exit() 主动结束任务，避免一直运行。

4. 运行与调试​

  1. 重新打开任务面板，任务列表中应出现「你好世界」。
  2. 选中它并点击「启动」。
  3. 打开调试日志，即可看到每秒输出一行、共 5 行后停止。

如果没看到任务：

  • 确认 .hm.json 是合法 JSON（可用任意 JSON 校验工具）。
  • 确认 名称 非空、类型 是 "任务"、隐藏 不为 true。
  • 确认目录位于 apps/ 下。

5. 让它更有意义：使用基础库​

真实任务几乎都会依赖 黑猫@基础库。先声明依赖：

apps/黑猫@你好世界/.hm.json
{
  "名称": "你好世界",
  "作者": "黑猫",
  "类型": "任务",
  "版本": "v1.0",
  "简介": "我的第一个软件包",
  "仓库地址": "",
  "依赖软件包": {
    "黑猫@基础库": "v1.0"
  }
}

然后在 index.lua 中引用它的模块：

local hmPlayer = require("黑猫@基础库.player")

function Main()
  local name = hmPlayer.getName()
  local pos = hmPlayer.getCurrentPosition()
  GoPrint("角色：" .. name .. "，坐标：(" .. pos.x .. ", " .. pos.y .. ")")
  Delay(2000)
end
提示

require("黑猫@基础库.player") 中的 黑猫@基础库 是依赖的全名，.player 对应 apps/黑猫@基础库/player.lua。

6. 下一步：加上界面​

到目前为止任务没有任何配置界面。要让它可配置，只需增加一个 ui/ 目录， 用声明式的表单描述界面即可。参见 界面（表单）。

备注

如果在编辑器中 require 没有补全、GoPrint 等函数提示未定义，请确认软件包目录下存在 .luarc.json 且指向仓库根目录的 lua_types/，参见目录结构。

下一步：VM 全局函数。