安装与授权

购买与下载

1. 打开 资源中心，注册并登录，购买 CloudPet 云宠物（45R，一次购买、永久包更）。
2. 在资源中心打开 CloudPet 云宠物，下载最新的 CloudPet-1.0.1-简体授权版.jar。
3. 授权码在 会员中心 的「我的授权」。

运行环境

项目	要求
服务端	Paper / Purpur 1.20 – 26.x，同一个 jar
Java	17 或更新（1.20.5 起的服务端本身需要 Java 21）
前置插件	无（数据库连接池已内置；SQLite / MySQL 驱动由 Paper 提供）
数据库	默认 SQLite，不用设置；多个子服共用宠物时改用 MySQL / MariaDB，见 数据库
可选：MythicMobs	MythicMobs 怪物当宠物身体、宠物技能、野生宠物驯服，见 MythicMobs
可选：云模型 CloudModel / ModelEngine	宠物换成模型，见 模型与 MythicMobs 身体
可选：云界面 CloudUI	宠物图鉴与皮肤改用云界面画面，见 云界面画面
可选：Vault + 经济插件	用金币买宠物、买皮肤、进化花费。没有时这些功能显示「不能购买」
可选：PlaceholderAPI	变量，自动注册
可选：WorldGuard	区域旗标：不能带宠物 / 不能骑 / 不能骑飞行坐骑，见 宠物保护
不支持	Spigot（需要 Paper 系服务端）

安装

1. 把 CloudPet-1.0.1-简体授权版.jar 放进 plugins/，启动服务器。
2. 首次启动会生成 plugins/CloudPet/（config.yml、messages.yml、foods.yml、categories.yml、pets/示例/ 七只示例宠物）与 token.yml，照下面的 授权 填好授权码后重启。控制台会显示：

[CloudPet] 授权验证通过（机器码 XXXX）
[CloudPet] 云宠物授权已生效，宠物功能已开启
[CloudPet] 云宠物 v1.0.1 已启用
已加载 7 种宠物、5 种食物，数据库 SQLite data.db（简体授权版，子服 server:25565）
✔ 已侦测到 云界面 CloudUI 1.1.1：宠物图鉴、宠物详细、皮肤使用云界面画面
✔ 已侦测到 云模型 CloudModel 1.6.3：宠物可以使用云模型的模型（pets/ 的 model.id）
共侦测到 2 个本系列插件

3. 照 快速上手 召唤第一只宠物，然后输入 /cp 打开宠物菜单。

设置写错了会告诉你

宠物文件、foods.yml、config.yml 写错的地方，开服和 /cp admin reload 时会在后台逐条说明：哪个文件、哪个键、写了什么、可以填什么，然后先用默认值继续运行。宠物文件提到的 MythicMobs 怪物、技能和模型不存在时也会提示。

授权

1. 首次启动会生成 plugins/CloudPet/token.yml，此时插件处于「未授权模式」：服务器照常开启、宠物设置与玩家数据全部保留，可以先写宠物文件，但召唤与菜单都暂停（提示「云宠物尚未授权」）。
2. 登录 会员中心，在「我的授权」复制 CloudPet 的授权码，填进 token.yml 的 key:，重启服务器。
3. 首次验证会自动绑定本机（后台会显示本机机器码）；换服务器时请先在会员中心自助解绑。

plugins/CloudPet/token.yml

key: 'XXXX-XXXX-XXXX-XXXX'

• 授权在后台验证，不会拖慢开服；连不上授权服务器时每 60 秒自动重试，连上后立即生效，不需要重启。
• 断网时可使用最近一次验证结果离线运行 72 小时。
• 多个子服都装的话，每个子服的 token.yml 都要填好授权码。

升级

关服，替换 jar，开服。宠物文件、设置文件与玩家数据都会保留；新版本新增的设置项与消息会使用默认值（messages.yml 里没有的键自动用插件内置的文字）。

从 MCPets 迁移

已经在用 MCPets 的服务器，可以用一条指令把宠物设置和玩家数据导入云宠物：

/cp admin import mcpets [config|data|all] [overwrite]

参数	导入什么
config	宠物、等级表、皮肤、信号、坐骑、背包格数、进化、升级宣告、收回技能、食物、分类、改名黑名单与部分 config.yml 设置
data	玩家数据：每位玩家每只宠物的名字、等级、经验、血量与背包
all	两个都导入（不写时默认 all）
overwrite	覆盖已经存在的同名宠物文件、食物与分类；玩家数据则是「已经有这种宠物也再建一只」

换插件步骤

1. 关服。
2. 移除 MCPets 的 jar，保留 plugins/MCPets/ 文件夹（云宠物从这里读取，不会修改里面任何文件）。
3. 放入 CloudPet-1.0.1-简体授权版.jar，开服，填好 授权码 后再重启一次。
4. 在后台或游戏里执行 /cp admin import mcpets all，完成后会显示导入结果，例如：

已导入 MCPets 设定：12 只宠物、6 种食物、3 个分类（0 个已存在略过，加 overwrite 覆盖）。原本的设定已备份到 backups/
已导入 MCPets 玩家资料（PlayerData）：820 位玩家、1904 只宠物、311 个背包（0 个背包读不出来，后台有说明）

导入设置前，云宠物会先把自己现在的 config.yml、foods.yml、categories.yml 与 pets/ 文件夹备份到 plugins/CloudPet/backups/before-mcpets-<时间>/。设置导入完成后自动重载；玩家数据在后台线程导入，导入时在线的玩家会自动重新读取宠物。

宠物与设置怎么转换

MCPets 的内容	云宠物
Pets/ 里的每个宠物文件	pets/MCPets导入/<宠物编号>.yml（编号不变）
图示的名称、说明、材质、CustomModelData	name、description、icon
Permission	permission 原样保留；mcpets.use 改成 cloudpet.use。玩家原本在权限插件里有的宠物权限照样有效
MythicMob	entity.mythicmobs（MythicMobs 怪物当身体）
回来的距离、传送距离	movement.follow-distance、movement.teleport-distance
是否可骑、坐骑类型、坐骑权限、自动骑乘、下坐骑收回	mount.enabled、mount.type（含 fly 的是飞行）、mount.controller、mount.permission、mount.auto、mount.despawn-on-dismount
等级表（按经验门槛排序）	levels.max、levels.names、levels.exp，以及每级一个值的 stats.health、stats.regen、stats.defense、stats.damage
背包大小与每级扩充	backpack（每级一个值，单位是列）
升级宣告（文字 / 类型 / 技能）	levels.messages（title: / actionbar:）与 levelup 技能
等级里的进化	evolutions（auto: true、keep-level: false）
昏倒冷却	respawn-cooldown
收回技能	despawn 技能 + despawn-delay: 20
皮肤	skins（名称、图示、MythicMobs 怪物、权限）
信号（Signals）	signals
petfoods.yml	foods.yml：回血、经验、驯服、进化、解锁宠物、伤害 / 抗性加成、冷却、限定宠物、信号
Categories/	categories.yml，宠物自动放进对应分类
blacklist.yml	config.yml 的 rename.blacklist
config.yml 的名字长度、禁用世界、复活血量	rename.max-length、pets.disabled-worlds、respawn.health

玩家数据从哪里读

• MCPets 的 config.yml 设了 MySQL（而且没有关闭 MySQL）时，照它的连接设置读取 mcpets_player_data 表（含它的表前缀）；连不上时改读 PlayerData/ 文件夹。
• 否则读取 PlayerData/<UUID>.yml。

导入的宠物会记成「权限宠物」：玩家要有那只宠物的 permission 才能召唤，而且不能打包成宠物蛋或放生（和原本靠权限取得宠物的规则一样）。不加 overwrite 时，玩家已经有的宠物种类会略过，可以放心重复执行。

MythicMobs 技能不用改

没有安装 MCPets 时，云宠物会用同样的名称注册 MCPets 的 MythicMobs 机制、目标、条件与变量（例如 PetDamage、@PetOwner、petLevel、<pet.level>），PlaceholderAPI 的 %mcpets_pet_*% 与 WorldGuard 的 mcpets-* 旗标也照样能用，所以宠物的技能文件、计分板与区域设置都不用改。完整列表见 MythicMobs 与 变量。

导入后请检查

导入完成后用 /cp admin list <玩家> 抽查玩家的宠物，打开 pets/MCPets导入/ 看一下转换出来的宠物文件。后台有「设置问题」提示时，照提示修改后 /cp admin reload。