8.1 KiB
AuPet 灵宠系统
AuPet 是一个面向 Minecraft Paper 1.21 系列服务端的灵宠插件。
插件围绕“宠物物品 + 玩家携带数据 + 宠物召唤实体 + GUI 管理”构建，适合用于服务器宠物养成、宠物技能展示、宠物出战和宠物经验成长玩法。
核心功能：
- 玩家通过 GUI 查看当前携带的灵宠、等级、经验、血量和资质
- 支持将手持宠物物品携带到玩家数据中
- 支持从玩家数据中取出宠物物品
- 支持召唤和召回宠物实体
- 支持 BetterModel 模型展示
- 支持 MythicMobs 技能触发
- 支持宠物喂养、经验增加和进化阶段控制
- 支持宠物改名
- 支持 MySQL 持久化玩家宠物数据
- 提供宠物召唤事件，方便其他插件监听
简单理解：
AuPet = 灵宠物品管理 + 宠物数据持久化 + 宠物 GUI + 宠物召唤 + 技能触发
玩家 = 携带、召唤、喂养、改名和培养宠物
管理员 = 配置宠物类型、模型、技能、等级经验和 GUI 展示
运行环境
服务端版本
Minecraft: 1.21.x
推荐服务端: Paper
Java: 21
当前构建配置使用：
Paper API: 1.21.8-R0.1-SNAPSHOT
plugin.yml api-version: 1.21
前置依赖
插件代码依赖以下组件：
DemonAPI
CraftDataManager
NBTAPI
MythicMobs
BetterModel
服务器启动前应确认这些插件或依赖已正确安装，并且版本与构建配置兼容。
安装方式
第一步：构建插件
在项目根目录执行：
mvn -q -DskipTests package
构建成功后会生成：
target/AuPet-1.0-SNAPSHOT.jar
第二步：放入服务器
将插件 jar 放入服务器插件目录：
plugins/AuPet.jar
同时放入前置依赖插件。
第三步：启动服务器
首次启动后会生成插件配置目录。
控制台应能看到宠物系统参数、等级经验配置和宠物类型加载日志。
目录结构
插件默认资源
config.yml
lang.yml
plugin.yml
插件数据目录
宠物类型配置读取自：
plugins/AuPet/PetData/
玩家携带宠物数据保存到 MySQL 表：
aupets_data
表字段：
PLAYERNAME: 玩家名
PETSTACK: 序列化后的宠物 ItemStack
玩家命令
打开主界面
/apet
/apet open
玩家未携带宠物时会打开携带界面；已携带宠物时会打开宠物主界面。
携带或取出宠物
/apet carry
当玩家未携带宠物时：
- 需要手持带有
petKeyNBT 的宠物物品 - 执行后会将手持宠物写入玩家数据
- 手持栏会被清空
当玩家已携带宠物时：
- 会收回已召唤宠物
- 刷新宠物物品数据
- 将宠物物品返还给玩家
如果玩家背包已满，剩余物品会掉落在玩家当前位置。
召唤或召回宠物
/apet call
当宠物未出战时会召唤宠物；当宠物已出战时会召回宠物。
召唤时会：
- 生成狼实体作为宠物基础实体
- 应用宠物血量、攻击、移动速度属性
- 加载 BetterModel 模型
- 触发配置的出生技能
- 触发
PetCallEvent
管理员命令
管理员命令需要：
admin.use
查看帮助
/apet
重载配置
/apet reload
重载内容：
- 语言文件
- 默认配置
- 等级经验配置
- 宠物模板
- GUI 物品配置
- 品质显示配置
- 宠物类型配置
给予宠物
/apet give 宠物Key 玩家名
示例：
/apet give cat Steve
插件会读取 PetData 中对应宠物配置，生成默认宠物物品并发放给目标玩家。
增加宠物经验
/apet addexp 经验 玩家名
给玩家当前携带的宠物增加经验。
增加手持宠物经验
/apet addexp 经验 玩家名 true
给目标玩家手持的宠物物品增加经验。
宠物配置
宠物配置文件位于：
plugins/AuPet/PetData/宠物Key.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秒"
字段说明：
PetName: 宠物显示名
MaxLevel: 宠物最大等级
ModelId: BetterModel 模型 ID
CustomIconModelId: 宠物物品 CustomModelData
AccessChannels: 获取渠道展示
SummonSkill: 召唤时触发的 MythicMobs 技能，default 表示不触发
DeathSkill: 死亡技能预留字段
Skills: 宠物技能列表
技能触发器
当前代码支持：
onAttack: 玩家攻击实体时触发
onDamaged: 玩家受到伤害时触发
onSpawn: 宠物召唤后触发 SummonSkill
技能由 MythicMobs 执行。
技能冷却使用玩家 UUID 和技能名作为冷却键。
等级经验配置
默认配置节点：
NeedExpSettings:
1: 10000
2: 10000
3: 10000
30: -1
说明：
正数: 当前等级升到下一级所需经验
-1: 终止等级，不再继续升级
宠物还会受到进化阶段限制：
进化 1: 最高 20 级
进化 2: 最高 40 级
进化 3: 最高 60 级
进化 4: 最高 70 级
进化 5: 最高 75 级
GUI 功能
主界面
主界面展示：
- 宠物物品
- 宠物技能
- 宠物资质
- 召唤或召回按钮
- 喂养入口
- 改名入口
携带界面
用于携带或取出宠物。
玩家可以通过点击背包中的宠物物品，将其写入当前携带数据。
喂养界面
支持放入带有以下 NBT 的道具：
petAppleExp: 增加经验
petAppleUp: 进化阶段要求等级
关闭界面时，如果喂养槽仍有物品，会自动返还玩家。
背包满时，剩余物会掉落到玩家当前位置。
数据保存机制
玩家数据以序列化 ItemStack 形式保存到 MySQL。
主要保存时机：
- 携带宠物
- 取出宠物
- 喂养加经验
- 宠物改名
- 玩家退出
- 插件关闭
注意：
当前数据库读写仍是同步模型。
在线人数较多或数据库延迟较高时，建议后续改造为异步加载和保存队列。
API 与事件
宠物经验 API
其他代码可以调用：
PetExpAPI.addExp(player, 1000);
也可以对手持宠物物品增加经验：
PetNbt petNbt = PetExpAPI.addExp(playerName, itemStack, 1000);
宠物召唤事件
宠物召唤成功后会触发：
PetCallEvent
可读取：
event.getOwner();
event.getCutomName();
event.getEntityUuid();
构建验证
本地验证命令：
mvn -q test
mvn -q -DskipTests package
当前验证结果：
mvn test: 通过
mvn package: 通过
常见问题
插件启动时报缺少类
检查前置依赖是否安装：
DemonAPI
CraftDataManager
NBTAPI
MythicMobs
BetterModel
同时检查这些依赖的版本是否与构建配置兼容。
执行 /apet give 找不到宠物
检查：
plugins/AuPet/PetData/宠物Key.yml 是否存在
文件名是否与命令中的宠物Key一致
配置是否能被 YAML 正常读取
召唤宠物失败
检查：
BetterModel 中是否存在对应 ModelId
宠物血量是否大于 0
MythicMobs 技能名是否正确
宠物无法升级
检查：
NeedExpSettings 当前等级是否为 -1
宠物是否已达到 MaxLevel
宠物是否已达到当前进化阶段上限
GUI 按钮显示异常
检查：
config.yml 中 GuiItemData 是否完整
lang.yml 中语言键是否完整
维护建议
- 发布前同步检查
plugin.yml版本号。 - 修改宠物配置后执行
/apet reload。 - 新增宠物前先在测试服验证 BetterModel 模型和 MythicMobs 技能。
- 不建议在高峰期进行大量玩家数据迁移。
- 后续优先补充数据库异步队列和 MockBukkit 测试。
- 每次更新后至少完成一次登录、携带宠物、打开 GUI、召唤宠物、喂养、退出保存的冒烟测试。