GT Wiki

外观

GUI、装备属性与 PAPI ​

配置目录：

text
plugins/GTCore/modules/GTPet/

分文件管理 GUI ​

原版背包界面位于 plugins/GTCore/modules/GTPet/gui/：

text
gui/
|- main.yml       # 宠物列表
|- detail.yml     # 宠物详情
|- growth.yml     # 成长属性
|- breeding.yml   # 繁育配对
|- evolution.yml  # 进化路线
|- equipment.yml  # 装备管理
|- skills.yml     # 技能管理
`- jobs.yml       # 工作管理

每个文件都包含一个 menus 页面。修改某一页时不需要在一个大文件中查找其他 GUI。保存后执行：

text
gtpet reload

重载成功后重新打开 /gtpet。如果行数、每行字符数、图标字符或点击操作无效，重载会失败并继续使用旧界面，控制台会指出文件和菜单路径。

配置详情页与子页面 ​

玩家执行 /gtpet 后先看到 main.yml 宠物列表。点击某只宠物进入 detail.yml，详情页默认提供五个入口：

  • OPEN_GROWTH：进入成长页，属性条目左键投入 1 点，Shift+左键投入 10 点。
  • OPEN_BREEDING：进入繁育页，选择同模板的另一只实例；再从该页进入进化路线。
  • OPEN_SKILLS：进入技能页。
  • OPEN_EQUIPMENT：进入装备页。
  • OPEN_JOBS：进入工作页。

每个入口都可在 gui/detail.yml 调整位置、材质、名称和 Lore。

修改一个页面 ​

下面是装备页的核心结构：

yaml
schema: 1

menus:
  equipment:
    title: '&8装备管理 &7- &f{pet_name}'
    rows: 4
    locked: true
    layout:
      - '####I####'
      - '#EEEEEEE#'
      - '#########'
      - '<##B#X##>'
    icons:
      'E':
        function: EQUIPMENT_ENTRY
        material: CHEST
        name: '&b槽位: {equipment_id}'
        lore:
          - '&7已穿戴: {equipment_equipped}'
          - '&e拿起背包装备后左键穿戴，右键卸下'
        clicks:
          LEFT: EQUIP
          RIGHT: UNEQUIP

rows 只能是 1 到 6。layout 必须恰好有相同行数，每行恰好 9 个字符。页面至少要定义一个 function: EQUIPMENT_ENTRY 图标作为装备槽样式模板；坐标由 equipment.yml 决定，不需要预先铺满 E。

locked: true 只锁定上方宠物 GUI。玩家自己的背包仍可正常左键、右键拿取和放回物品。为了防止物品进入上方装饰格，打开宠物 GUI 时会拦截从玩家背包 Shift 转移、双击收集上方图标，以及拖拽物品进入上方区域。

把自定义装备槽映射到槽位栏 ​

装备槽在 equipment.yml 中声明自己的页码、行和列：

yaml
schema: 2

slots:
  weapon:
    gui:
      page: 1
      row: 2
      column: 2
    slot-type: HAND
    type-policy: ALLOW_ONLY
    visual-target: HAND
    allow:
      - lore: '[宠物武器]'
      - nbt:
          gtpet_slot: weapon

  charm:
    gui:
      page: 1
      row: 2
      column: 8
    slot-type: ACCESSORY
    type-policy: ALLOW_ONLY
    visual-target: NONE
    allow:
      - lore: '[宠物饰品]'

这里的行列从 1 开始。示例把 weapon 放在装备页第二行第二列，把 charm 放在第二行第八列。坐标可以直接覆盖 gui/equipment.yml 中的空格、装饰格或原动态格。GUI 文件只需保留一个 function: EQUIPMENT_ENTRY 图标定义作为所有装备槽的显示样式；实际位置完全以 equipment.yml 为准。

例如做人形装备排版时，先把 gui/equipment.yml 的 rows 和 layout 扩展到 6 行，再配置：

yaml
slots:
  helmet:
    gui:
      page: 1
      row: 2
      column: 5
    slot-type: HEAD
    type-policy: ALLOW_ONLY
    visual-target: HELMET
    allow:
      - lore: '[宠物帽子]'
      - nbt:
          gtpet_slot: helmet

  chest:
    gui:
      page: 1
      row: 3
      column: 5
    slot-type: CHEST
    type-policy: ALLOW_ONLY
    visual-target: CHESTPLATE
    allow:
      - lore: '[宠物胸甲]'

  legs:
    gui:
      page: 1
      row: 4
      column: 5
    slot-type: LEGS
    type-policy: ALLOW_ONLY
    visual-target: LEGGINGS
    allow:
      - lore: '[宠物护腿]'

  boots:
    gui:
      page: 1
      row: 5
      column: 5
    slot-type: FEET
    type-policy: ALLOW_ONLY
    visual-target: BOOTS
    allow:
      - lore: '[宠物鞋子]'

  weapon:
    gui:
      page: 1
      row: 3
      column: 3
    slot-type: HAND
    type-policy: ALLOW_ONLY
    visual-target: HAND
    allow:
      - lore: '[宠物武器]'

把新增槽位 ID 加入目标宠物模板的 equipment-slots 后才会显示。坐标超出 GUI 行数或同页坐标重复时，重载会拒绝并指出槽位 ID。

限制只能穿宠物装备 ​

材质包、自定义模型和第三方物品常把武器或帽子的底层材质做成 PAPER，因此只按材质判断会误判。推荐每个槽位使用 type-policy: ALLOW_ONLY，再按宠物装备自己的 Lore、NBT/PDC 或物品库 ID 放行：

yaml
slots:
  helmet:
    slot-type: HEAD
    type-policy: ALLOW_ONLY
    allow:
      # Lore 会去除颜色，并忽略大小写检查“是否包含”。
      - lore: '[宠物帽子]'
      # NBT/PDC 按键值匹配，适合物品生成插件写入稳定标记。
      - nbt:
          gtpet_slot: helmet
      - pdc:
          'gtpet:slot': helmet
      # 也可以精确写统一物品 ID。
      - item: 'mm:pet_dragon_helmet'
    deny:
      - lore: '[禁止宠物使用]'

同一个 allow 列表中的规则按“任意一个命中”处理；deny 永远先于 allow。因此普通玩家头盔、普通 PAPER 或其他宠物部位装备都不能放入这个帽子槽，只有带 [宠物帽子]、对应 NBT/PDC，或命中指定物品 ID 的物品才能穿戴。

可用策略：

type-policy行为
ALLOW_ONLY只允许命中 allow 的宠物专用装备，推荐默认使用
VANILLA_ONLY只按原版头盔、胸甲、护腿、鞋子、武器或工具材质判断
VANILLA_OR_ALLOW原版部位匹配或命中 allow 任一即可
UNRESTRICTED除 deny 外不限制，通常只适合完全自定义的临时槽位

自定义槽位超过一页时增加 page：

yaml
  second_charm:
    gui:
      page: 2
      row: 2
      column: 2

页面切换后仍使用同一套装备页布局，因此每一页的坐标都要落在动态装备栏中。

使用鼠标光标穿戴装备 ​

玩家需要先在下方背包中用鼠标拿起目标物品，再左键点击上方宠物装备槽。GTPet 每次只从光标扣除 1 件物品，并检查该槽位的解锁、允许/拒绝、Lore、NBT/PDC 和物品 ID 规则。

如果槽位已有装备，旧装备会返回玩家背包。背包没有空间时不会替换。右键槽位会把当前装备卸回背包，同样会在背包已满时拒绝操作。

验证时可以把一组数量大于 1 的宠物装备拿到光标上，左键槽位一次。成功后光标数量应只减少 1；换下的旧装备应出现在背包中。再用普通物品点击同一槽位，界面应显示可编辑的中文拒绝原因，宠物装备与光标物品都保持不变。

选择宠物属性与基础普攻引擎 ​

在 systems.yml 中明确选择一套最终结算器：

yaml
combat:
  damage-calculator: ATTRIBUTE_PLUS
  • ATTRIBUTE_PLUS：GTPet 负责目标、攻击间隔和能量，AttributePlus/AP 负责命中、暴击、防御、吸血与最终伤害。
  • CRANE_ATTRIBUTE：GTPet 负责目标、攻击间隔和能量，CraneAttribute/CA 负责最终伤害。
  • GTPET：不安装属性插件时使用 GTPet 内置公式。

这里没有 AUTO。选择 AP 或 CA 后，对应属性插件必须已安装并能正常使用；不可用时本次基础攻击会被拒绝，不会自动改成 GTPet 公式。combat.attribute.trigger-damage 在属性插件模式下保持默认 1 即可。

SX-Attribute 可以提供装备属性读取，但不能填写到 damage-calculator。可选值只有 ATTRIBUTE_PLUS、CRANE_ATTRIBUTE 和 GTPET。

配置 AP、CA 与 SX 属性名 ​

在 attributes.yml 中为每个属性填写服务器实际使用的精确中文名：

yaml
schema: 3

attributes:
  attack:
    role: ATTACK
    provider-sources:
      ATTRIBUTE_PLUS: '物理伤害'
      CRANE_ATTRIBUTE: '物理攻击力'
    equipment:
      names:
        - '攻击'
        - '物理攻击'
        - '物理伤害'
        - '物理攻击力'
      aggregation: SUM
      scale: 1.0
      include-in-total: true

  attack-marker:
    role: CUSTOM
    provider-sources:
      ATTRIBUTE_PLUS: '宠物攻击标记'
      CRANE_ATTRIBUTE: '宠物攻击标记'
    equipment:
      names:
        - '宠物攻击标记'

provider-sources 填写本服 AP 或 CA 实际使用的属性名。equipment.names 填写装备上会出现的精确属性名。名称中即使含有“攻击”，只要 role 是 CUSTOM，就不会作为 GTPet 内置攻击属性使用。

aggregation 可用 SUM、MAX、MIN、AVERAGE。百分比插件如果返回 5 表示 5%，使用 scale: 0.01 转为 0.05。

没有安装属性插件时，宠物仍可穿戴符合规则的装备。若 damage-calculator 选择了未安装的属性插件，基础攻击不会执行。安装或切换属性插件后执行 /gtpet reload，重新召唤宠物，再用下方 PAPI 变量和实际战斗确认属性。

验证时先记录测试怪物当前生命值，让宠物只攻击一次，再比较扣血值。修改 AP/CA 的攻击、暴击或防御配置后，结果应跟随所选属性插件变化。AP 与 CA 同时安装时，只在 damage-calculator 中选择一个。

PAPI 选择宠物 ​

全局变量不需要选择宠物：

变量结果
%gtpet_count%玩家拥有的宠物总数
%gtpet_summoned_count%已召唤数量
%gtpet_working_count%工作中数量
%gtpet_reward_count%全部待领奖励数量
%gtpet_average_level%平均等级

选择一只宠物时推荐使用双下划线：

text
%gtpet_first__level%
%gtpet_summoned__health_percent%
%gtpet_宠物短ID__state%
%gtpet_starter_wolf__equipment_count%

双下划线左侧可用 first、summoned、stored、downed、working、retired、宠物 UUID/短 ID 或模板 ID。模板或自定义 ID 含下划线时必须使用双下划线写法。

常用宠物字段 ​

将下表中的 <宠物> 替换为 first、短 ID 或模板 ID：

变量说明
%gtpet_<宠物>__display_name%模板的显示名称
%gtpet_<宠物>__state% / %gtpet_<宠物>__stance%生命周期与姿态
%gtpet_<宠物>__health% / max_health / health_percent生命值
%gtpet_<宠物>__mana_percent%法力百分比，返回 0.00 到 100.00
%gtpet_<宠物>__potential_points%可用潜能点
%gtpet_<宠物>__traits%特性列表
%gtpet_<宠物>__skills%已学技能与等级
%gtpet_<宠物>__work_job%当前工作 ID
%gtpet_<宠物>__lifespan_seconds%剩余寿命秒数；无限为 -1

动态 ID 变量示例：

text
%gtpet_first__skill_claw_level%
%gtpet_first__cooldown_claw_seconds%
%gtpet_first__channel_combat_level%
%gtpet_first__channel_combat_experience%
%gtpet_first__gene_power%
%gtpet_first__mutation_swift%
%gtpet_first__attribute_points_strength%
%gtpet_first__equipment_weapon_item%

装备属性变量：

text
%gtpet_first__equipment_attribute_attack%
%gtpet_first__equipment_attribute_attack_min%
%gtpet_first__equipment_attribute_attack_max%
%gtpet_first__equipment_slot_weapon_attribute_attack%
%gtpet_first__equipment_provider_attribute_plus%
%gtpet_first__equipment_provider_crane_attribute%

provider 变量返回 true 或 false。属性名称和装备槽 ID 使用 equipment.yml 中配置的 ID。

命令帮助 ​

/gtpet help 会列出玩家可用命令；管理员根据权限额外看到 give、reload 和诊断命令。

管理员发放宠物：

text
gtpet give <在线玩家> <模板> [数量]

验证与排错 ​

  1. 修改一个 GUI 标题、子页面入口、装备坐标或属性别名。
  2. 执行 gtpet reload，确认返回成功。
  3. 重新打开 /gtpet，从详情页依次进入成长、繁育、进化、技能、装备和工作页。
  4. 使用 PlaceholderAPI 的解析命令或记分板插件显示目标变量。
  5. 在玩家背包中普通左键拿起装备，确认下方背包可以操作。
  6. 左键上方宠物槽位，确认光标数量减少 1。
  7. 右键槽位卸下装备，确认物品返回背包。
  8. 使用 Shift 点击下方物品，确认物品不会被塞进上方宠物 GUI。
  9. 穿戴带 AP/CA/SX 属性的物品，比较穿戴前后的属性 PAPI 值。

如果 GUI 重载失败，先检查 rows、layout 长度、图标字符和装备槽坐标。如果属性始终为 0，检查属性插件是否启用、names 是否与物品实际属性名一致，以及百分比是否需要 scale: 0.01。如果 PAPI 返回空字符串，检查玩家是否拥有匹配选择器的宠物，以及技能、频道、槽位或属性 ID 是否拼写正确。

如果在 Purpur、Paper 或 Folia 1.21.11 上执行 /gtpet 时出现下面的错误：

text
IncompatibleClassChangeError: Found interface org.bukkit.inventory.InventoryView, but class was expected

这不是 GUI YAML、权限或存档问题。请升级到 GTPet 1.7.34 或更高版本，完整关闭服务器后替换 GTCore 模块目录中的旧 JAR，再重新启动。无需删除 plugins/GTCore/modules/GTPet/ 下的配置和宠物数据。启动完成后由真实玩家依次打开 /gtpet、详情页和装备页，并测试下方背包拿取、上方槽位穿戴、拖动与关闭界面；四项都不再报错才算替换完成。1.7.33 及更早版本无法通过修改配置规避这个异常。