玩家模型、移动与右键交互

本页介绍 PLAYER 宠物、皮肤、显示距离、移动速度、跟随、传送、头顶信息和潜行右键详情页。

修改文件后执行：

text

/gtpet reload

已经召唤的 PLAYER 宠物需要先收回，再重新召唤。

创建 PLAYER 宠物

在 templates.yml 添加：

yaml

pets:
  player_companion:
    display-name: '&d契约伙伴'
    entity: PLAYER
    appearance:
      skin: OWNER
    generation: 1
    quality: COMMON
    qualities:
      - id: COMMON
        weight: 70.0
      - id: RARE
        weight: 25.0
      - id: LEGENDARY
        weight: 5.0
    max-level: 80
    default-stance: DEFENSIVE
    allowed-stances:
      - PASSIVE
      - DEFENSIVE
      - AGGRESSIVE
      - HOLD
      - WORK
    attributes:
      attack: 6.5
      defense: 3.5
      max-health: 24.0
      max-mana: 120.0
      max-energy: 110.0
      max-rage: 100.0
      critical-chance: 0.06
      dodge-chance: 0.04
      move-speed: 0.33
      gather-speed: 1.0
    traits:
      - loyal
      - guardian
    skills:
      - id: claw
        level: 1
    genes:
      - id: attack
        alleles: A/a
      - id: vitality
        alleles: V/v
    equipment-slots:
      - weapon
      - helmet
      - armor
      - leggings
      - boots
      - charm
    evolutions:
      - guardian_ii
    work-jobs:
      - patrol
    resources:
      health: 24.0
      mana: 120.0
      energy: 110.0
      rage: 100.0

皮肤来源

yaml

appearance:
  skin: OWNER

OWNER 使用召唤者皮肤。固定皮肤可以填写玩家名：

yaml

appearance:
  skin: Notch

使用 INTERNAL 时，固定玩家名只会复制召唤时在线玩家的皮肤。该玩家不在线时不会联网查询皮肤，客户端可能显示默认皮肤。需要固定皮肤时，先让皮肤来源玩家在线，再重新召唤宠物进行检查。

保存后执行：

text

/gtpet reload
gtpet give Steve player_companion 1

完整显示配置

display.yml：

yaml

schema: 1

player:
  carrier: INTERNAL
  logic-entity: HUSK
  view-distance: 64.0
  movement-sync-ticks: 1
  tab-list-ticks: 20
  resync-ticks: 40

nameplate:
  enabled: true
  refresh-ticks: 5
  height: 0.65
  line-spacing: 0.28
  lines:
    - '&f{pet_name} &8[&r{quality_color}{quality}&8] &7Lv.{level}'
    - '&7主人: &f{owner_name}'
    - '&c生命: &f{health}/{max_health} &8(&f{health_percent}%&8)'
  templates:
    player_companion:
      lines:
        - '&d{pet_name} &8[&r{quality_color}{quality}&8] &7Lv.{level}'
        - '&7契约者: &f{owner_name}'
        - '&c生命: &f{health}/{max_health}'
        - '&b法力: &f{mana}/{max_mana}'

玩家模型字段

字段	建议值	说明
`carrier`	`INTERNAL`	使用 GTPet 自带 PLAYER 外观
`logic-entity`	`HUSK`	负责寻路、碰撞、受击和右键交互
`view-distance`	`64.0`	玩家超过该距离后不再显示 PLAYER 外观
`movement-sync-ticks`	`1`	每多少 tick 更新一次位置和朝向，`1` 最平滑
`tab-list-ticks`	`20`	皮肤加载等待时间
`resync-ticks`	`40`	定期重新校正外观，必须大于 `tab-list-ticks`

carrier 可用值：

值	用法
`INTERNAL`	默认选择，不需要 NPC 插件
`CITIZENS`	已安装 Citizens 并完成测试时使用
`ADYESHACH`	当前不可用，不要选择

不要填写 AUTO。logic-entity 不要填写 PLAYER。推荐保持 HUSK，它的尺寸接近玩家并且可以自动寻路。

调整模型移动流畅度

yaml

player:
  movement-sync-ticks: 1

1：每 tick 更新，移动和步行动画最平滑。
2-3：减少更新次数，适合 PLAYER 宠物数量较多的服务器。
更高数值：移动会明显迟钝或出现跳动。

修改后执行 /gtpet reload，收回并重新召唤 PLAYER 宠物。

调整跟随速度

全局移动参数位于 coefficients.yml：

yaml

coefficients:
  ai.owner.follow-distance:
    base: 3.5
  ai.owner.navigation-speed:
    base: 0.87
    formula: "{base} + {pet.role.move-speed}"
  ai.owner.follow-speed:
    base: 0.0
    formula: "{base} + {pet.role.move-speed}"
    min: 0.0
  ai.owner.fallback-acceleration:
    base: 0.35
  ai.owner.fallback-jump-velocity:
    base: 0.42
  ai.owner.fallback-max-jump-height:
    base: 1.25
  ai.owner.teleport-distance:
    base: 32.0

全局加速

先调整：

yaml

ai.owner.navigation-speed:
  base: 1.10

数值越大，支持寻路的宠物追赶越快。建议每次增加 0.1-0.2，重载后实际走动测试。

单独调整一个模板

在 templates.yml 修改：

yaml

pets:
  player_companion:
    attributes:
      move-speed: 0.45

这样只提高 player_companion 的移动速度。

检查最终速度

text

gtpet coefficient ai.owner.navigation-speed pet.role.move-speed=0.45

命令返回的数值就是本次输入下的最终结果。

跟随、跳跃和传送

玩家与宠物距离不超过 follow-distance 时，宠物保持当前位置。
超过 follow-distance 后，宠物开始寻路跟随。
遇到小台阶时，宠物可以按 fallback-jump-velocity 起跳。
高度差超过 fallback-max-jump-height 时，不会连续向上跳。
主人飞行时，宠物留在地面；距离达到 teleport-distance 后返回主人附近。
teleport-distance 不能小于 follow-distance。

传送太频繁：调大 ai.owner.teleport-distance.base。

宠物卡住太久才返回：调小 ai.owner.teleport-distance.base。

配置头顶信息

yaml

nameplate:
  enabled: true
  refresh-ticks: 5
  height: 0.65
  line-spacing: 0.28
  lines:
    - '&f{pet_name} &8[&r{quality_color}{quality}&8] &7Lv.{level}'
    - '&7主人: &f{owner_name}'
    - '&c生命: &f{health}/{max_health}'

常用变量：

变量	内容
`{pet_name}`	宠物名称
`{owner_name}`	主人名称
`{quality}`	品质名称
`{quality_color}`	品质颜色
`{level}`	等级
`{health}` / `{max_health}`	当前/最大生命
`{health_percent}`	生命百分比
`{mana}` / `{max_mana}`	当前/最大法力
`{energy}` / `{max_energy}`	当前/最大能量
`{rage}` / `{max_rage}`	当前/最大怒气
`{state}`	宠物状态
`{stance}`	宠物姿态

文字遮住模型时调大 height。多行文字重叠时调大 line-spacing。

潜行右键打开详情

操作方式：

召唤宠物。
主人按住 Shift。
使用主手右键自己的宠物。

预期结果：打开这只宠物的详情页。普通右键不会打开页面。

如果没有打开：

先执行 /gtpet，确认原版背包 GUI 可以打开。
确认右键的是当前玩家自己的已召唤宠物。
确认使用的是主手。
检查其他插件是否拦截实体右键事件。

如果客户端断开，保存客户端提示和同一时间的 logs/latest.log。

完整客户端验收

使用真实 Minecraft 客户端进入测试服。
发放并召唤 player_companion。
近距离观察皮肤和模型。
走出 view-distance，再走回范围，确认模型消失后重新出现。
让宠物连续跟随至少 20 格，确认没有间歇跳动，步行动画正常。
飞到高处，确认宠物不会连续向上升空；距离足够远后才返回。
给宠物更换主手、头盔、胸甲、护腿和鞋子，确认外观刷新。
让宠物攻击一次，确认挥手动画和攻击位置一致。
潜行主手右键宠物，确认不会断开连接，并打开正确的详情页。
收回宠物，确认模型和头顶信息全部消失。

排错

移动很慢

先检查 ai.owner.navigation-speed.base，再检查模板 attributes.move-speed。修改后重载并重新召唤。

移动没有动画或位置跳动

检查 display.yml：

yaml

movement-sync-ticks: 1

同时确认控制台没有 INTERNAL player presentation failed。

宠物跟着飞起来

检查：

yaml

ai.owner.fallback-max-jump-height:
  base: 1.25

不要把该值设置成很大的数字。距离过远时应由 teleport-distance 负责返回。

只看到普通生物，没有 PLAYER 外观

确认 carrier: INTERNAL，收回并重新召唤。仍不正确时查看控制台中的 INTERNAL player presentation failed，并记录服务端核心、客户端版本和协议兼容插件版本。

玩家模型、移动与右键交互 ​

创建 PLAYER 宠物 ​

皮肤来源 ​

完整显示配置 ​

玩家模型字段 ​

调整模型移动流畅度 ​

调整跟随速度 ​

全局加速 ​

单独调整一个模板 ​

检查最终速度 ​

跟随、跳跃和传送 ​

配置头顶信息 ​

潜行右键打开详情 ​

完整客户端验收 ​

排错 ​

移动很慢 ​

移动没有动画或位置跳动 ​

宠物跟着飞起来 ​

只看到普通生物，没有 PLAYER 外观 ​

玩家模型、移动与右键交互

创建 PLAYER 宠物

皮肤来源

完整显示配置

玩家模型字段

调整模型移动流畅度

调整跟随速度

全局加速

单独调整一个模板

检查最终速度

跟随、跳跃和传送

配置头顶信息

潜行右键打开详情

完整客户端验收

排错

移动很慢

移动没有动画或位置跳动

宠物跟着飞起来

只看到普通生物，没有 PLAYER 外观