邮箱重置版 LyMailReload

LyMailReload 是一款 Minecraft 服务器邮箱插件。插件通过邮箱 GUI 管理玩家邮件，支持模板邮件、条件检查、附件物品、领取指令、定时自动发送、邮件过期删除、CDK 兑换、本地 YAML 存储和 MySQL 存储。

邮件模板位于插件目录的 template/ 文件夹。发送模板邮件时，插件会检查模板条件；条件满足后，邮件会写入玩家邮箱。玩家打开邮箱后可以查看邮件标题、内容和附件，并在空余背包槽位足够时领取奖励。

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认 LyMySQLCore 已成功连接数据库。否则玩家数据、CDK 数据以及相关 MySQL 读写功能不会生效。

插件信息

项目	内容
插件名	LyMailReload
插件版本	1.0.4
作者	Liyuan
主命令	/lmail
Bukkit API 声明	api-version: 1.13
项目编译 API	Paper API 1.16.5-R0.1-SNAPSHOT
Java 目标版本	Java 8
数据存储	本地 YAML 或 MySQL
软依赖声明	PlaceholderAPI、ProtoclLib、LyMySQLCore、Vault、PlayerPoints、LyShopReload

项目文件同时包含 LyMailReload-Core.jar 和 LyMailReload-Bungee 模块。Bungee 模块注册了 lmr:channel 通道，并在玩家登录时向各个代理服务器发送登录信息；是否使用该模块取决于服务器部署方式。

支持环境

• 插件描述文件声明 Bukkit API 1.13。
• 项目使用 Paper API 1.16.5-R0.1-SNAPSHOT 编译。
• 项目 Java 编译目标为 Java 8。
• 配置中的物品材质同时兼容英文材质名和部分旧版数字 ID 格式，例如 160:9。
• 实际运行时还需要满足服务器核心、依赖插件和所使用物品插件的兼容性要求。

功能

功能	说明
模板邮件	从 template/ 文件夹读取 YAML 模板，按模板 ID 发放邮件。
邮件内容	支持图标、标题、多行内容、附件物品和领取后执行的指令。
收件条件	支持权限、反权限和 PlaceholderAPI 表达式条件。
唯一邮件	使用 only-mail: true 时，玩家只会被记录为收到该模板一次；重复发送会被拦截。
自动发送	按定时任务扫描在线玩家，并发送处于有效时间范围且满足条件的模板邮件。
尝试发送	可以按秒重复尝试发送，直到发送成功或达到指定次数。
邮件过期	邮件可以按领取后的持续时间或固定结束日期计算到期时间，过期后自动删除。
邮箱 GUI	使用 54 格界面展示邮件，每页最多显示 27 封邮件，并提供翻页和领取按钮。
空间检查	领取前检查玩家背包空余槽位，不足时不会删除邮件。
CDK 兑换	支持固定 CDK 和按格式生成的随机 CDK。每个 CDK 组的玩家兑换记录独立保存。
兑换奖励	CDK 可以发送一个或多个模板邮件、发送消息并执行指令。
本地存储	使用玩家 UUID 对应的 YAML 文件保存邮件和兑换记录。
MySQL 存储	使用 LyMySQLCore 事件加载和保存玩家数据，并保存随机 CDK 使用状态。
PlaceholderAPI	提供邮箱数量、当前选中邮件和模板收件记录变量，也可用于邮件条件。

指令

插件没有在 plugin.yml 中声明独立权限节点。代码中使用 OP 判断的管理指令需要发送者为 OP；open 和 cdk 为玩家指令。

指令	使用者	说明
/lmail open	玩家	打开自己的邮箱。
/lmail cdk <cdk>	玩家	兑换 CDK。兑换受到 cdk-redeem-cd 冷却时间限制。
/lmail reload	OP	重载 config.yml、邮件模板和 cdk.yml，同时重启自动任务。
/lmail send <玩家> <模板id>	OP	向在线玩家发送指定模板邮件。模板不存在时不会发送。
/lmail send {online} <模板id>	OP	向所有在线玩家尝试发送指定模板邮件。
/lmail try-send <玩家> <模板id> <次数>	OP	每秒尝试向在线玩家发送邮件，成功或达到次数后停止。
/lmail try-send {online} <模板id> <次数>	OP	对所有在线玩家执行尝试发送。
/lmail createcdk <cdk组id> <数量>	OP	为非固定 CDK 组生成随机 CDK，数量范围为 1 至 10000。

尖括号内容为需要替换的参数，不需要原样输入。

配置文件

插件会使用以下配置文件：

文件	用途
config.yml	时间格式、MySQL、本地保存、自动任务、CDK 冷却、GUI 和消息。
cdk.yml	CDK 组、固定或随机 CDK、兑换邮件、兑换消息和兑换指令。
template/*.yml	邮件模板。插件会递归读取 template/ 目录下的 YAML 文件。

完整配置说明：

• 配置说明：按 config.yml、数据库、GUI、消息和自动任务整理配置键。
• 模板邮件：说明 template/*.yml 中的模板字段、条件、附件、时效和领取指令。
• CDK 配置：说明 cdk.yml 中的固定 CDK、随机 CDK和兑换奖励。

重载时插件会重新保存示例模板文件 template/示例模板邮件.yml，该文件仅用于展示字段结构，不应直接作为正式邮件模板使用。

邮箱界面

邮箱界面由 config.yml 的 gui 配置段控制：

• 邮件列表使用前 27 个槽位，每页最多展示 27 封邮件。
• 第 27 槽位为上一页按钮，第 35 槽位为下一页按钮。
• 第 36 至 52 槽位用于预览当前邮件的附件，最多显示 17 个附件条目。
• 第 53 槽位为当前邮件的领取按钮。
• 邮件图标使用模板中的 icon 字段。
• 邮件 Lore 使用模板中的 message，并追加 gui.mail-lore。
• gui.mail-lore 中的 {time} 会替换为邮件到期时间。
• 点击领取时，插件先检查空余背包槽位，再发放附件、执行领取指令并删除邮件。

附件物品来源

模板的 items 字段使用逗号分隔格式：

items:
  - '来源标识,物品ID,数量,是否给予'

代码中支持以下来源标识：

来源标识	处理方式
ni	调用对应物品管理器获取物品。
si	调用 SX 物品管理器获取物品。
mm	调用 MythicMobs 物品管理器获取物品。
mm5	调用 MythicBukkit 物品管理器获取物品。
oa	调用对应物品工厂获取物品。
af	调用 AzureFlow 物品工厂获取物品。
sx	调用 SXAttribute API 获取物品。

是否给予 为 true 时，领取邮件会把物品加入玩家背包；为 false 时只用于界面预览，不会实际发放。

数据与运行机制

邮件发送

1. 根据模板 ID 查找模板。
2. 检查 only-mail 和玩家收件记录。
3. 依次检查模板中的权限、反权限和 PlaceholderAPI 条件。
4. 创建独立邮件实例并生成邮件 UUID。
5. 按到期时间排序后加入玩家邮箱。
6. 更新模板收件记录并发送 message.mail-receive 消息。

自动任务

• auto-send-time 控制自动发送扫描间隔，单位为秒。
• 自动发送任务扫描在线玩家和已加载的邮件模板。
• 只有处于 timed-send-start-time 至 timed-send-end-time 范围内的模板才会进入自动发送检查。
• auto-delete-time 控制过期邮件扫描间隔，单位为秒。
• 过期扫描任务会检查在线玩家的邮件。
• 玩家切换世界后也会执行一次过期邮件检查。

邮件有效期

• 只配置 expiration-time 时，邮件从发放时间开始按秒计算到期时间。
• 同时配置完整的 timed-send-start-time 和 timed-send-end-time 时，如果发放时间处于该日期范围内，邮件到期时间使用 timed-send-end-time。
• 邮件到期后会从玩家邮箱中删除，并发送 message.mail-expire 消息。
• 邮件按到期时间排序，较早到期的邮件排在前面。

CDK 兑换

• fixed-cdk: true 时，CDK 内容直接使用 CDK 组 ID。
• fixed-cdk: false 时，插件根据 format 生成随机 CDK。
• 固定 CDK 不需要使用 /lmail createcdk。
• 随机 CDK 可以使用 /lmail createcdk 生成，生成数量范围为 1 至 10000。
• 每个玩家每个 CDK 组只能兑换一次。
• 随机 CDK 每个兑换码只能被使用一次。
• 随机 CDK 使用本地存储时保存在插件目录的 cdkdata/ 文件夹。
• 随机 CDK 使用 MySQL 存储时保存在插件名追加 _cdk 的数据表中。
• CDK 兑换会发送配置中的邮件和消息，并执行配置中的指令。
• 如果 CDK 邮件自身的条件不满足，邮件不会加入玩家邮箱；但 CDK 的兑换状态仍会被记录，无法再次兑换。

数据保存

本地 YAML 模式下，玩家数据保存于：

plugins/LyMailReload/data/<玩家UUID>.yml

本地模式会在玩家进入时读取数据，在退出或被踢出时异步保存数据。保存时使用临时文件、备份文件和 UTF-8 无 BOM 写入方式，主文件损坏时会尝试从 .bak 文件恢复。

MySQL 模式下，玩家数据保存到插件名对应的数据表，随机 CDK 保存到插件名追加 _cdk 的数据表。启用 MySQL 后，服务器会在插件初始化和重载时连接数据库并初始化数据表。

PlaceholderAPI 变量

安装并启用 PlaceholderAPI 后，插件注册变量前缀 lmail：

变量	返回值
%lmail_amount%	当前玩家邮箱中的邮件数量。玩家数据未加载时返回 0。
%lmail_now_mail%	当前选中的邮件索引；没有选中邮件时返回 -1。
%lmail_has_<模板id>%	玩家是否曾收到指定模板 ID 的邮件，收到返回 1，否则返回 0。

模板条件中的 papi:{...} 也使用 PlaceholderAPI 解析变量。需要使用字符串比较时，应将字符串放在引号中。

完整变量说明见 插件变量。

API

插件提供 LyMailAPI 接口，包含以下方法：

方法	说明
sendMail(Player player, String templateId)	检查模板和条件后，向玩家发送一次模板邮件。
deleteExpiredMail(Player player)	删除玩家当前已到期的邮件。
trySendMail(Player player, String templateId, int count)	立即尝试发送；失败时每秒继续尝试，直到成功或达到次数。

API 发送邮件同样会检查模板是否存在、唯一邮件记录和模板条件。

常见问题

启用 MySQL 后数据没有保存

确认以下条件：

• 已安装 LyMySQLCore。
• LyMySQLCore 已成功连接数据库。
• config.yml 中的 mysql.enable 已设置为 true。
• 数据库地址、端口、数据库名、用户名和密码正确。
• 修改数据库开关后已重启服务器；配置注释明确要求数据库开关需要重启服务器。

邮件发送后玩家没有收到

检查以下内容：

• 模板文件位于 template/ 目录，并且扩展名为 .yml。
• 模板中的 id 与指令中的模板 ID 完全一致。
• 玩家满足 condition 中的所有条件。
• only-mail 没有阻止重复发送。
• 玩家数据已经加载完成。
• 如果使用自动发送，当前时间处于模板的定时发送范围内。

CDK 显示无效

确认 CDK 是否属于 cdk.yml 中已加载的 CDK 组。随机 CDK 还需要确认生成操作已经完成，并且当前使用的存储模式与生成 CDK 时一致。

CDK 兑换成功但没有邮件

CDK 兑换时会调用模板邮件发送逻辑。如果配置的邮件模板条件不满足，邮件不会加入邮箱；CDK 本身仍可能被标记为已兑换，因此应先检查邮件模板条件。

领取按钮提示空余槽位不足

模板中的 need-slot 表示领取前要求的空余背包槽位数量。清理背包后再次点击领取；空间不足时邮件不会被删除。

重载后示例邮件被覆盖

template/示例模板邮件.yml 是插件随附的示例文件，插件重载时会重新保存它。正式邮件应复制该文件后使用其他文件名，并修改模板 ID、标题、内容和奖励。

页面索引

页面	内容
配置说明	config.yml 的全局设置、MySQL、自动任务、GUI 和消息。
模板邮件	模板字段、条件、附件、邮件有效期和领取指令。
CDK 配置	固定 CDK、随机 CDK、CDK 组和兑换奖励。
插件变量	PlaceholderAPI 变量及返回值。
常见问题	数据库、模板、CDK、领取和重载问题排查。
更新日志	更新日志页面。