完善并添加README.md

README.md

@@ -0,0 +1,508 @@
+# 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、召唤宠物、喂养、退出保存的冒烟测试。