AuPet/README.md

# AuPet 灵宠系统

AuPet 是一个面向 Minecraft Paper 1.21 系列服务端的灵宠插件。

插件围绕“宠物物品 + 玩家携带数据 + 宠物召唤实体 + GUI 管理”构建，适合用于服务器宠物养成、宠物技能展示、宠物出战和宠物经验成长玩法。

核心功能：

- 玩家通过 GUI 查看当前携带的灵宠、等级、经验、血量和资质
- 支持将手持宠物物品携带到玩家数据中
- 支持从玩家数据中取出宠物物品
- 支持召唤和召回宠物实体
- 支持 BetterModel 模型展示
- 支持 MythicMobs 技能触发
- 支持宠物喂养、经验增加和进化阶段控制
- 支持宠物改名
- 支持 MySQL 持久化玩家宠物数据
- 提供宠物召唤事件，方便其他插件监听

简单理解：

```yml
AuPet = 灵宠物品管理 + 宠物数据持久化 + 宠物 GUI + 宠物召唤 + 技能触发
玩家 = 携带、召唤、喂养、改名和培养宠物
管理员 = 配置宠物类型、模型、技能、等级经验和 GUI 展示
```

------

# 运行环境

## 服务端版本

```yml
Minecraft: 1.21.x
推荐服务端: Paper
Java: 21
```

当前构建配置使用：

```yml
Paper API: 1.21.8-R0.1-SNAPSHOT
plugin.yml api-version: 1.21
```

## 前置依赖

插件代码依赖以下组件：

```yml
DemonAPI
CraftDataManager
NBTAPI
MythicMobs
BetterModel
```

服务器启动前应确认这些插件或依赖已正确安装，并且版本与构建配置兼容。

------

# 安装方式

## 第一步：构建插件

在项目根目录执行：

```bash
mvn -q -DskipTests package
```

构建成功后会生成：

```yml
target/AuPet-1.0-SNAPSHOT.jar
```

## 第二步：放入服务器

将插件 jar 放入服务器插件目录：

```yml
plugins/AuPet.jar
```

同时放入前置依赖插件。

## 第三步：启动服务器

首次启动后会生成插件配置目录。

控制台应能看到宠物系统参数、等级经验配置和宠物类型加载日志。

------

# 目录结构

## 插件默认资源

```yml
config.yml
lang.yml
plugin.yml
```

## 插件数据目录

宠物类型配置读取自：

```yml
plugins/AuPet/PetData/
```

玩家携带宠物数据保存到 MySQL 表：

```yml
aupets_data
```

表字段：

```yml
PLAYERNAME: 玩家名
PETSTACK: 序列化后的宠物 ItemStack
```

------

# 玩家命令

## 打开主界面

```yml
/apet
/apet open
```

玩家未携带宠物时会打开携带界面；已携带宠物时会打开宠物主界面。

## 携带或取出宠物

```yml
/apet carry
```

当玩家未携带宠物时：

- 需要手持带有 `petKey` NBT 的宠物物品
- 执行后会将手持宠物写入玩家数据
- 手持栏会被清空

当玩家已携带宠物时：

- 会收回已召唤宠物
- 刷新宠物物品数据
- 将宠物物品返还给玩家

如果玩家背包已满，剩余物品会掉落在玩家当前位置。

## 召唤或召回宠物

```yml
/apet call
```

当宠物未出战时会召唤宠物；当宠物已出战时会召回宠物。

召唤时会：

- 生成狼实体作为宠物基础实体
- 应用宠物血量、攻击、移动速度属性
- 加载 BetterModel 模型
- 触发配置的出生技能
- 触发 `PetCallEvent`

------

# 管理员命令

管理员命令需要：

```yml
admin.use
```

## 查看帮助

```yml
/apet
```

## 重载配置

```yml
/apet reload
```

重载内容：

- 语言文件
- 默认配置
- 等级经验配置
- 宠物模板
- GUI 物品配置
- 品质显示配置
- 宠物类型配置

## 给予宠物

```yml
/apet give 宠物Key 玩家名
```

示例：

```yml
/apet give cat Steve
```

插件会读取 `PetData` 中对应宠物配置，生成默认宠物物品并发放给目标玩家。

## 增加宠物经验

```yml
/apet addexp 经验 玩家名
```

给玩家当前携带的宠物增加经验。

## 增加手持宠物经验

```yml
/apet addexp 经验 玩家名 true
```

给目标玩家手持的宠物物品增加经验。

------

# 宠物配置

宠物配置文件位于：

```yml
plugins/AuPet/PetData/宠物Key.yml
```

示例：

```yml
PetName: "§a森林灵宠"
MaxLevel: 30
ModelId: forest_pet
CustomIconModelId: 10001
AccessChannels:
  - "活动获取"
  - "商城购买"
SummonSkill: "pet_spawn_effect"
DeathSkill: "default"
Skills:
  bite:
    mmSkill: "pet_bite"
    needLevel: 1
    trigger: "onAttack"
    coolDown: 5000
    item:
      name: "&a撕咬"
      lore:
        - "&7触发条件: 攻击时"
        - "&7冷却: 5秒"
```

字段说明：

```yml
PetName: 宠物显示名
MaxLevel: 宠物最大等级
ModelId: BetterModel 模型 ID
CustomIconModelId: 宠物物品 CustomModelData
AccessChannels: 获取渠道展示
SummonSkill: 召唤时触发的 MythicMobs 技能，default 表示不触发
DeathSkill: 死亡技能预留字段
Skills: 宠物技能列表
```

------

# 技能触发器

当前代码支持：

```yml
onAttack: 玩家攻击实体时触发
onDamaged: 玩家受到伤害时触发
onSpawn: 宠物召唤后触发 SummonSkill
```

技能由 MythicMobs 执行。

技能冷却使用玩家 UUID 和技能名作为冷却键。

------

# 等级经验配置

默认配置节点：

```yml
NeedExpSettings:
  1: 10000
  2: 10000
  3: 10000
  30: -1
```

说明：

```yml
正数: 当前等级升到下一级所需经验
-1: 终止等级，不再继续升级
```

宠物还会受到进化阶段限制：

```yml
进化 1: 最高 20 级
进化 2: 最高 40 级
进化 3: 最高 60 级
进化 4: 最高 70 级
进化 5: 最高 75 级
```

------

# GUI 功能

## 主界面

主界面展示：

- 宠物物品
- 宠物技能
- 宠物资质
- 召唤或召回按钮
- 喂养入口
- 改名入口

## 携带界面

用于携带或取出宠物。

玩家可以通过点击背包中的宠物物品，将其写入当前携带数据。

## 喂养界面

支持放入带有以下 NBT 的道具：

```yml
petAppleExp: 增加经验
petAppleUp: 进化阶段要求等级
```

关闭界面时，如果喂养槽仍有物品，会自动返还玩家。

背包满时，剩余物会掉落到玩家当前位置。

------

# 数据保存机制

玩家数据以序列化 ItemStack 形式保存到 MySQL。

主要保存时机：

- 携带宠物
- 取出宠物
- 喂养加经验
- 宠物改名
- 玩家退出
- 插件关闭

注意：

```yml
当前数据库读写仍是同步模型。
在线人数较多或数据库延迟较高时，建议后续改造为异步加载和保存队列。
```

------

# API 与事件

## 宠物经验 API

其他代码可以调用：

```java
PetExpAPI.addExp(player, 1000);
```

也可以对手持宠物物品增加经验：

```java
PetNbt petNbt = PetExpAPI.addExp(playerName, itemStack, 1000);
```

## 宠物召唤事件

宠物召唤成功后会触发：

```java
PetCallEvent
```

可读取：

```java
event.getOwner();
event.getCutomName();
event.getEntityUuid();
```

------

# 构建验证

本地验证命令：

```bash
mvn -q test
mvn -q -DskipTests package
```

当前验证结果：

```yml
mvn test: 通过
mvn package: 通过
```

------

# 常见问题

## 插件启动时报缺少类

检查前置依赖是否安装：

```yml
DemonAPI
CraftDataManager
NBTAPI
MythicMobs
BetterModel
```

同时检查这些依赖的版本是否与构建配置兼容。

## 执行 /apet give 找不到宠物

检查：

```yml
plugins/AuPet/PetData/宠物Key.yml 是否存在
文件名是否与命令中的宠物Key一致
配置是否能被 YAML 正常读取
```

## 召唤宠物失败

检查：

```yml
BetterModel 中是否存在对应 ModelId
宠物血量是否大于 0
MythicMobs 技能名是否正确
```

## 宠物无法升级

检查：

```yml
NeedExpSettings 当前等级是否为 -1
宠物是否已达到 MaxLevel
宠物是否已达到当前进化阶段上限
```

## GUI 按钮显示异常

检查：

```yml
config.yml 中 GuiItemData 是否完整
lang.yml 中语言键是否完整
```

------

# 维护建议

- 发布前同步检查 `plugin.yml` 版本号。
- 修改宠物配置后执行 `/apet reload`。
- 新增宠物前先在测试服验证 BetterModel 模型和 MythicMobs 技能。
- 不建议在高峰期进行大量玩家数据迁移。
- 后续优先补充数据库异步队列和 MockBukkit 测试。
- 每次更新后至少完成一次登录、携带宠物、打开 GUI、召唤宠物、喂养、退出保存的冒烟测试。