黑猫@基础库

黑猫@基础库 是一个函数库类型软件包，封装了角色、背包、珍兽、技能、生活技能、元宝商店等常用操作，是绝大多数任务的基础依赖。

引入方式

在清单中声明依赖：

apps/黑猫@你的任务/.hm.json
{
  "依赖软件包": {
    "黑猫@基础库": "v1.0"
  }
}

在任务或界面脚本中 require 对应模块：

local hm         = require("黑猫@基础库.global")
local hmPlayer   = require("黑猫@基础库.player")
local hmPackage  = require("黑猫@基础库.package")

提示

基础库内部通过 DoLuaString 调用注入到游戏环境的原生函数，因此它必须在运行时可用（即已声明依赖并在安装时一并安装）。

global —— 通用

local hm = require("黑猫@基础库.global")

函数	返回值	说明
`hm.pushDebugMessage(message)`	—	向游戏内推送调试消息
`hm.getItemBindStatus(bagPos)`	boolean	获取装备的绑定状态
`hm.autoRunToTarget(x, y)`	—	自动寻路到指定坐标
`hm.getMountID()`	number	获取当前坐骑 ID
`hm.isWindowShow(name)`	boolean	判断窗口是否显示
`hm.getWindowComponentText(window, component)`	string	获取窗口组件文本

player —— 角色

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

hmPlayer.state 提供人物状态常量：

字段	值	含义
`stop`	0	停止
`move`	2	移动
`storage`	5	蓄气
`meditation`	6	打坐
`attack`	7	攻击

函数	返回值	说明
`hmPlayer.getName()`	string	获取角色昵称
`hmPlayer.getHpPercent()`	number	当前血量百分比
`hmPlayer.getMpPercent()`	number	当前气量百分比
`hmPlayer.getRemainPoint()`	number	剩余潜能点
`hmPlayer.getPlayerState()`	number	当前状态（见上表）
`hmPlayer.waitStateDisappear(state)`	—	等待人物状态消失
`hmPlayer.getCurrentPosition()`	table	当前位置 `{ x, y, sceneId, sceneName }`
`hmPlayer.onMount()`	—	上坐骑
`hmPlayer.unMount()`	—	下坐骑
`hmPlayer.isLeader()`	number	是否队长（1=是，0=否）
`hmPlayer.getIntData(name)`	number	读取角色整型数据，如 `Player:GetData` 的字段
`hmPlayer.sendAskManualAttr(str, spr, con, int, dex)`	—	提交手动加点
`hmPlayer.sendAgreeTeamFollow()`	—	同意进入组队跟随
`hmPlayer.askTeamFollow()`	—	邀请队友进入组队跟随

local pos = hmPlayer.getCurrentPosition()
GoPrint("当前地图：" .. pos.sceneName .. " (" .. pos.x .. ", " .. pos.y .. ")")

env —— 环境对象

local hmEnv = require("黑猫@基础库.env")

hmEnv.itemType 是环境对象类型常量：

字段	值
`self`	1
`player`	2
`pet`	3
`npc`	4
`monster`	5
`resource`	6
`platform`	7
`itemBox`	8

函数	返回值	说明
`hmEnv.getEnvItems()`	table	获取环境物品列表
`hmEnv.getEnvItemsFilter(type)`	table	按类型过滤环境物品
`hmEnv.selectItem(id)`	—	选择环境对象

skill —— 技能

local hmSkill = require("黑猫@基础库.skill")

函数	返回值	说明
`hmSkill.updateSkillItems()`	—	刷新技能缓存
`hmSkill.getSkills()`	table	获取技能列表
`hmSkill.useSkill(name, itemId)`	—	对目标使用技能
`hmSkill.useSkillToSelf(name)`	—	对自己使用技能
`hmSkill.getMemPaiDefultSkillName()`	string	获取门派默认技能名
`hmSkill.getId(name)`	number	根据技能名获取技能 ID

package —— 背包

local hmPackage = require("黑猫@基础库.package")

背包类型 type：1=道具栏，2=材料栏，3=任务道具；不传表示全部。

BagItem（背包物品）：

字段	类型	说明
`index`	number	背包索引
`id`	number	物品 ID
`name`	string	物品名称
`count`	number	数量
`desc`	string	描述

函数	返回值	说明
`hmPackage.getList(type?)`	BagItem[]	获取背包物品列表
`hmPackage.getUniqueNamesFromArray(data)`	string[]	去重后的物品名称列表
`hmPackage.getCountFromArray(data, name)`	number	指定物品总数量（精确匹配）
`hmPackage.getCountFromArrayWithPattern(data, pattern)`	number	指定物品总数量（正则）
`hmPackage.getIndexesFromArray(data, name)`	number[]	匹配物品的索引数组
`hmPackage.getIndexFromArray(data, name)`	number	第一个匹配的索引，未找到返回 `-1`
`hmPackage.getPatternIndexFromArray(data, pattern)`	number	正则匹配的第一个索引，未找到返回 `-1`
`hmPackage.isItemExistsFromArray(data, name)`	boolean	数组中是否存在该物品
`hmPackage.isItemExists(name, type?)`	boolean	背包中是否存在该物品
`hmPackage.isEquip(pos)`	boolean	背包位置上是否是装备
`hmPackage.isGemForName(name)`	boolean	物品名称是否是宝石
`hmPackage.isEquipUnAdjuest(bagPos)`	boolean	装备是否未鉴定
`hmPackage.getEquipStarLevel(bagPos)`	number	装备星级
`hmPackage.getEquipProperties(bagPos)`	table	装备属性（属性名 → 属性值）
`hmPackage.getGemLevel(name)`	number\|nil	从名称解析宝石等级，如「猫眼石(5级)」
`hmPackage.getItemLevel(name)`	number\|nil	从名称解析物品等级
`hmPackage.getItemLevelForName(name)`	number\|nil	同上
`hmPackage.useItem(bagPos)`	—	使用物品
`hmPackage.destoryItem(bagPos)`	—	丢弃物品（注意原函数名拼写为 `destory`）

local list = hmPackage.getList(1)
if hmPackage.isItemExists("金创药") then
  local pos = hmPackage.getIndexFromArray(list, "金创药")
  hmPackage.useItem(pos)
end

player_package —— 背包物品属性

local hmPlayerPackage = require("黑猫@基础库.player_package")

函数	返回值	说明
`hmPlayerPackage.isGem(bagPos)`	number	是否是宝石（1=是，0=否）
`hmPlayerPackage.getItemSubTableIndex(v1, v2)`	number	物品子表索引（如 `0` 返回 `1` 表示装备）
`hmPlayerPackage.getItemGrade(bagPos)`	number	物品品级

pet —— 珍兽

local hmPet = require("黑猫@基础库.pet")

PetItem（珍兽信息）：

字段	类型	说明
`index`	number	索引（从 0 开始）
`id`	string	珍兽 ID（`idHight` + `idLow`）
`idHight` / `idLow`	string	ID 高位 / 低位
`name`	string	名称
`level`	number	等级
`hp` / `maxHp`	number	当前 / 最大血量
`happy`	number	快乐值
`potential`	number	潜能点数
`fighting`	boolean	是否出战

函数	返回值	说明
`hmPet.getList()`	PetItem[]	获取珍兽列表
`hmPet.getPos(petId)`	number\|nil	根据珍兽 ID 获取列表位置（从 0 开始）
`hmPet.getPetForId(petId)`	PetItem\|nil	根据 ID 获取珍兽信息
`hmPet.getFightingPet()`	PetItem\|nil	获取当前出战的珍兽
`hmPet.hasPetFight()`	boolean	是否有珍兽出战
`hmPet.getIsFighting(index)`	number	是否出战（1=出战，0=未出战）
`hmPet.getPotential(index)`	number	潜能点数
`hmPet.addAttribute(index, str, spr, con, int, dex)`	—	潜能加点
`hmPet.goFight(index)`	—	珍兽出战
`hmPet.feed(index)`	—	喂养
`hmPet.dome(index)`	—	驯养
`hmPet.setFightPetAsMainTarget()`	—	将出战珍兽设为目标

life_ability —— 生活技能（装备/宝石）

local hmLifeAbility = require("黑猫@基础库.life_ability")

函数	返回值	说明
`hmLifeAbility.getEquipLevel(pos)`	number	装备等级
`hmLifeAbility.getEquipHoleCount(pos)`	number	已打孔数量
`hmLifeAbility.getEquipGem(equipPos, gemPos)`	string	装备宝石图标
`hmLifeAbility.getEquipPoint(pos)`	number	装备类型
`hmLifeAbility.getGemLevel(pos, kind)`	number	宝石等级
`hmLifeAbility.getEquipGemLevel(equipPos, index)`	number	装备宝石等级
`hmLifeAbility.getEquipCurStrengthLevel(pos)`	number	强化等级
`hmLifeAbility.doEnchase(equipPos, gemPos, fPos)`	—	普通镶嵌
`hmLifeAbility.doEnchaseFour(equipPos, gemPos, fPos)`	—	极限镶嵌
`hmLifeAbility.splitGemUpdate(equipPos)`	—	装备宝石更新
`hmLifeAbility.doSeparateGem(equipPos, index, itemPos)`	—	宝石摘除

yuanbao_shop —— 元宝商店

local hmYuanBaoShop = require("黑猫@基础库.yuanbao_shop")

函数	返回值	说明
`hmYuanBaoShop.pay(name, count)`	boolean	购买商品（名称精确匹配）
`hmYuanBaoShop.payWithPattern(pattern, count)`	boolean	购买商品（名称正则匹配）
`hmYuanBaoShop.getItemInfo(pattern)`	table\|nil	查询商品位置信息 `{ name, x, y, z }`
`hmYuanBaoShop.open(hPos, vPos)`	—	打开商店分类
`hmYuanBaoShop.close()`	—	关闭商店
`hmYuanBaoShop.updatePage(index)`	—	切换到指定页码
`hmYuanBaoShop.clickGood(pos)`	—	点击当前页指定位置（1–18）的商品

备注

商品的坐标信息来自按角色持久化的配置 yuanbao_shop_items，通常由「扫描元宝商城」任务写入。

guild / team / action —— 其它

local hmGuild = require("黑猫@基础库.guild")
local hmTeam  = require("黑猫@基础库.team")
local hmAction = require("黑猫@基础库.action")

函数	返回值	说明
`hmGuild.getMembers()`	table	获取帮会成员列表
`hmTeam.getTeamItemCount()`	number	队伍物品数量
`hmTeam.getTeamItems()`	table	获取队伍物品列表
`hmAction.use(id)`	—	使用指定动作（如 `1001`）

想扩展基础库？你可以把自己的原生逻辑放进 inject/ 目录，供任务通过 DoLuaString 调用，详见目录结构。

提示

聊天 / 喊话等尚未封装的游戏原生接口，见游戏原生接口。

下一步：游戏原生接口。

引入方式​

global —— 通用​

player —— 角色​

env —— 环境对象​

skill —— 技能​

package —— 背包​

player_package —— 背包物品属性​

pet —— 珍兽​

life_ability —— 生活技能（装备/宝石）​

yuanbao_shop —— 元宝商店​

guild / team / action —— 其它​