模板、存储与召唤

本页介绍如何创建宠物模板、配置品质、选择存储、限制数量，并完成发放、召唤、改名和收回。

配置目录

plugins/GTCore/modules/GTPet/

主要文件：

• templates.yml：宠物模板。
• config.yml：存储、数量限制、下线收回和改名。
• attributes.yml：属性成长与品质加成。

完整模板示例

下面的模板可以直接放入 templates.yml 的 pets 下：

schema: 3

pets:
  fire_wolf:
    display-name: '&c烈焰狼'
    entity: WOLF
    generation: 1
    quality: COMMON
    qualities:
      - id: COMMON
        weight: 60.0
      - id: UNCOMMON
        weight: 25.0
      - id: RARE
        weight: 10.0
      - id: EPIC
        weight: 4.0
      - id: LEGENDARY
        weight: 1.0
    max-level: 60
    default-stance: DEFENSIVE
    allowed-stances:
      - PASSIVE
      - DEFENSIVE
      - AGGRESSIVE
      - HOLD
      - WORK
    attributes:
      attack: 8.0
      defense: 3.0
      max-health: 28.0
      max-mana: 80.0
      max-energy: 100.0
      max-rage: 100.0
      critical-chance: 0.06
      dodge-chance: 0.02
      move-speed: 0.34
      gather-speed: 1.0
    traits:
      - loyal
      - hunter
    skills:
      - id: claw
        level: 1
      - id: guardian_heal
        level: 1
    genes:
      - id: attack
        alleles: A/a
      - id: vitality
        alleles: V/v
      - id: scavenger
        alleles: S/s
    equipment-slots:
      - weapon
      - helmet
      - armor
      - leggings
      - boots
      - collar
      - charm
    evolutions:
      - guardian_ii
      - guardian_iii
    work-jobs:
      - patrol
      - offline_hunter
    resources:
      health: 28.0
      mana: 80.0
      energy: 100.0
      rage: 100.0

保存后执行：

/gtpet reload
/gtpet templates

列表中应出现 fire_wolf 和“烈焰狼”。

模板字段说明

字段	说明
display-name	GUI、命令和头顶信息显示的模板名称
entity	实体类型，例如 WOLF、HORSE、IRON_GOLEM、PLAYER
generation	初始世代
quality	没有配置品质池时使用的固定品质
qualities	创建宠物时使用的品质权重池
max-level	最高等级
default-stance	创建后的默认姿态
allowed-stances	玩家可以切换的姿态
attributes	模板基础属性
traits	初始特质
skills	初始技能和等级
genes	初始基因与等位基因
equipment-slots	允许显示和使用的装备槽 ID
evolutions	允许使用的进化路线 ID
work-jobs	允许选择的工作 ID
resources	创建时的生命、法力、能量和怒气

配置品质权重

qualities:
  - id: COMMON
    weight: 70.0
  - id: RARE
    weight: 25.0
  - id: LEGENDARY
    weight: 5.0

权重按比例计算，不要求合计必须为 100。上例中普通、稀有、传说的比例为 70:25:5。

测试方法：

gtpet give Steve fire_wolf 10

玩家执行 /gtpet pets，可以查看每只实例抽到的品质。品质对应的属性倍率在 attributes.yml 的 qualities 中配置。

配置基础属性

模板中的 attributes 是每只宠物的起点：

attributes:
  attack: 8.0
  defense: 3.0
  max-health: 28.0
  max-mana: 80.0
  max-energy: 100.0
  max-rage: 100.0
  critical-chance: 0.06
  dodge-chance: 0.02
  move-speed: 0.34
  gather-speed: 1.0

critical-chance: 0.06 表示 6%。move-speed 会参与宠物跟随速度计算。每级成长、属性点、品质、基因、特质和装备加成在 attributes.yml 中继续配置。

选择存储

存储配置位于 config.yml。

本地存储

单服先使用：

storage:
  backend: LOCAL
  namespace: pets

MySQL

storage:
  backend: MYSQL
  namespace: pets
  mysql:
    url: ''
    host: 127.0.0.1
    port: 3306
    database: gtpet
    username: root
    password: '修改为数据库密码'
    table: gtpet_storage
    maximum-pool-size: 8
    minimum-idle: 1
    connection-timeout-ms: 5000
    idle-timeout-ms: 600000
    max-lifetime-ms: 1800000

如果填写 url，连接会优先使用 URL；不填写时使用 host、port 和 database。

Redis

storage:
  backend: REDIS
  namespace: pets
  redis:
    uri: ''
    host: 127.0.0.1
    port: 6379
    username: ''
    password: '修改为Redis密码'
    database: 0

AUTO

storage:
  backend: AUTO
  namespace: pets

AUTO 使用服务器当前提供的默认存储。需要明确控制数据位置时，直接填写 LOCAL、MYSQL 或 REDIS。

存储配置修改后重启服务器，再执行：

gtpet status

确认 ready=true，并检查显示的存储类型。

限制拥有和召唤数量

limits:
  max-owned-per-player: 32
  max-summoned-per-player: 1

• max-owned-per-player：一名玩家最多保存多少只宠物。
• max-summoned-per-player：一名玩家最多同时召唤多少只宠物。

召唤上限不能大于拥有上限。

发放宠物

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

示例：

gtpet give Steve fire_wolf 2

玩家会获得两只独立宠物。执行：

/gtpet pets

记录两只宠物的短 ID，后续命令优先使用短 ID。

召唤、姿态和收回

/gtpet summon <宠物短ID>
/gtpet stance <宠物短ID> DEFENSIVE
/gtpet recall <宠物短ID>

如果同模板只有一只宠物，也可以用模板 ID：

/gtpet summon fire_wolf

同模板有多只时，插件会要求使用短 ID。

修改名称

玩家可以在详情页点击改名图标，也可以执行：

/gtpet rename <宠物短ID> 烈焰

规则位于 config.yml：

pets:
  rename:
    max-length: 24
    allow-color-codes: false
    reset-keywords:
      - reset
      - default
      - 重置
      - 默认

恢复模板名称：

/gtpet rename <宠物短ID> 重置

主人下线自动收回

pets:
  recall-on-owner-quit: true

设为 false 后，主人下线不会触发自动收回。修改后执行 /gtpet reload。

完整验收流程

1. 添加 fire_wolf 模板。
2. 执行 /gtpet reload，确认成功。
3. 执行 gtpet give Steve fire_wolf 2。
4. 玩家执行 /gtpet pets，确认出现两个不同短 ID。
5. 分别召唤两只宠物，确认召唤数量受到 max-summoned-per-player 限制。
6. 修改一只宠物名称，确认另一只名称不变。
7. 收回宠物并重启测试服。
8. 玩家再次执行 /gtpet pets，确认两只宠物仍可读取。

排错

gtpet reload 失败

查看提示中的 YAML 路径。重点检查：

• 实体类型是否存在。
• resources.health 是否大于 0。
• default-stance 是否包含在 allowed-stances 中。
• 技能 ID 是否存在于 skills.yml。
• 装备槽 ID 是否存在于 equipment.yml。
• 进化 ID 是否存在于 breeding.yml。
• 工作 ID 是否存在于 jobs.yml。

ready=false

检查存储连接、账号密码、数据库地址和端口。MySQL/Redis 不可用时，指定的后端不会自动改成本地存储。

宠物无法召唤

执行 /gtpet pets，检查宠物状态。再检查：

• 是否达到同时召唤上限。
• 宠物是否倒地、工作中或已退役。
• 玩家是否使用了正确的短 ID。
• 模板实体是否能在当前服务端创建。

重启后宠物显示为已收回

玩家重新执行 /gtpet summon <宠物短ID>。服务器重启后不会保留旧世界中的宠物实体。