📥 安装配置

全新安装

1. 下载 Paper 1.21.4+ 服务端
2. 将 AdventureMail-5.2.0.jar 放入 plugins/
3. 启动服务器，自动生成配置
4. 按需修改 config.yml 和 messages.yml
5. /amail reload 重载

文件结构

plugins/AdventureMail/
├── config.yml              # 主配置
├── messages.yml            # 消息文本
├── mails/<UUID>.yml       # 玩家邮件数据（YAML模式）
├── sent/<玩家名>.yml       # 发件箱记录
├── templates/              # 邮件模板
└── scheduled.yml           # 定时邮件队列

群组服配置

1. 在所有子服安装 AdventureMail-5.2.0.jar
2. 修改每个子服的 config.yml（详见跨服配置）
3. 重启所有子服

⌨️ 命令权限

玩家命令

管理员命令

命令行发送示例

# 发送给指定玩家
/amail send player Steve 系统通知 欢迎来到服务器!

# 发送给全服（指定邮件类型）
/amail send all _ 服务器公告 --type system_notice 今晚维护

# 发送给有权限的玩家
/amail send permission vip.access VIP专属 --type event_ranking VIP通知

# 发送给所有在线玩家
/amail send online _ 在线奖励 --type system_reward 感谢在线

目标类型：player / all / online / permission

权限节点

PAPI 占位符

消息内置变量

📝 更新记录

v5.2.2

• CONFIG softdepend 更新 — plugin.yml 新增 AdventureManage 为可选依赖，提升跨插件兼容性

v5.2.1

• FIX 跨服邮件投递Bug：resolveRecipients 从 Redis 线程移至主线程
• 每个收件人独立 Mail 对象避免 ID 冲突
• NEW 数据库管理指令：/amail dbstatus / dbreset / dbclean

v5.2.0

• NEW 书本模式 (view-mode: book)
• NEW 未读邮件闪烁：每秒交替类型图标↔红色染料
• FIX 双行标题重复显示
• IMPROVED 跨服性能：移除15秒DB轮询改用事件驱动
• FIX Redis cross_send 回调 + 新增玩家UUID注册表

v5.1.0

• 跨服邮件：Redis cross_send 广播实现真正跨服投递
• 多步目标选择向导（多选服务器+多选玩家类型GUI）
• MailManager.sendMail 支持多目标类型合并收件人

v5.0.0

• Redis跨服同步全面重写（server-id过滤、JSON结构化、指数退避重连）
• 所有玩家消息100%可自定义（messages.yml 50+条目）

v4.0.0

• 邮箱分类筛选（红=系统/黄=活动/绿=社交/蓝=安全）
• 邮件显示格式重做 + Web编辑器同步更新

v3.x

• v3.2.0 — Web邮件编辑器
• v3.1.0 — 领取截止时间 + 草稿保护 + 性能优化
• v3.0.0 — 邮件类型系统(10种) + MySQL + StorageProvider

v2.0.0

• 回收站、模板、发件箱、一键领取/全部已读、定时邮件、过期清理

📨 邮件类型系统

四大分类

10种邮件类型

特殊属性

• 违规处罚 (security_punish)：不可删除，登录时强制显示
• 玩家私信 (social_private)：支持回复功能
• 每种类型有独立的通知音效

查看模式

书本模式：标题金色加粗，正文自动分页，[关闭]/[领取] 可点击按钮。

mail-types:
  system_notice:
    view-mode: book
  system_reward:
    view-mode: gui

未读邮件闪烁

每秒交替切换：邮件类型图标 ↔ 红色染料（附魔光效）。全局一个定时任务，性能友好。

📎 附件系统

指令执行模式

变量：{player} = 玩家名，{uuid} = UUID

🖥️ GUI 界面

玩家邮箱 /amail

54格箱子界面，4行×7列显示邮件列表：

操作方式

• 左键 → 标记已读
• 右键 → 打开邮件预览
• Shift+右键 → 删除（移到回收站）

底栏按钮

邮件编辑GUI（管理员）

其他GUI

📋 模板 / 定时 / 回收站

模板系统

• 保存模板 — 当前草稿存为模板
• 加载模板 — 从模板恢复到编辑界面
• 删除模板 — 移除不需要的模板
• 保存在 plugins/AdventureMail/templates/

模板保存所有属性：标题、内容、附件、邮件类型等。

定时邮件

数据保存在 scheduled.yml，重启后自动恢复。

回收站

• 删除的邮件移入回收站，可恢复或永久删除
• 支持一键清空
• 默认保留 7天，到期自动清理

mail:
  trash-retain-days: 7

🗄️ 数据库

YAML 模式（默认）

• 单服本地文件存储，保存在 mails/
• 无需额外配置，适合单服

MySQL 模式（跨服同步）

• HikariCP 高性能连接池
• 自动建表（amail_mails + amail_sent）
• 支持 BungeeCord / Velocity 多子服共享
• 单条记录级精确更新

storage:
  type: mysql
  mysql:
    host: localhost
    port: 3306
    database: adventuremail
    username: root
    password: "your_password"
    table-prefix: "amail_"
    pool-size: 10

🌐 跨服配置

storage:
  type: mysql
  mysql:
    host: 数据库地址          # 所有子服相同
    database: adventuremail
    username: your_user
    password: your_password
  redis:
    enabled: true             # 跨服必须启用!
    host: redis地址            # 所有子服相同
    port: 6379

cross-server:
  enabled: true
  server-id: "lobby"          # 每个子服不同!
  server-name: "主城服"
  servers:                    # 所有子服必须一致!
    - id: "lobby"
      name: "&a主城服"
      icon: GRASS_BLOCK
    - id: "survival"
      name: "&2生存服"
      icon: DIAMOND_PICKAXE

通信架构

• 子服A发送 → MySQL写入 → Redis广播 cross_send
• 子服B收到 → 事件驱动刷新缓存 → 在线玩家收到通知
• 支持500人在线（移除高频DB轮询）

⚙️ 配置参考

存储设置

storage:
  type: yaml                    # yaml 或 mysql
  mysql:
    host: localhost
    port: 3306
    database: adventuremail
    username: root
    password: ""
    table-prefix: "amail_"
    pool-size: 10

邮件设置

mail:
  max-mails-per-player: 50
  expire-days: 30
  trash-retain-days: 7
  default-sender-display: "来自Feiiy管理组"
  claim-deadline-days: 7

GUI / 通知

gui:
  title: "&6&l冒险邮件"
  mails-per-page: 28

notification:
  login-reminder: true
  sound-enabled: true

邮件类型配置

mail_types:
  system_reward:
    enabled: true
    display_name: "&a系统奖励"
    icon: CHEST
    allow_attachments: true
    default_expiry_days: 7
    priority: HIGH
    sound: ENTITY_PLAYER_LEVELUP
  security_punish:
    enabled: true
    display_name: "&4违规处罚"
    icon: BARRIER
    allow_attachments: false
    expiry: permanent
    priority: HIGH
    sound: ENTITY_WITHER_SPAWN
    settings:
      cannot_delete: true
      force_read: true

消息配置 (messages.yml)

prefix: "&a&l[冒险邮件] &f"

player:
  mail-received: "&a您收到了一封新邮件！"
  login-unread: "&e您有 &f%count% &e封未读邮件"
  login-unclaimed: "&a您有 &f%count% &a封附件待领取"
  mark-all-read: "&a已将 &e%count% &a封标记为已读"
  claim-all: "&a已领取 &e%count% &a封附件"

admin:
  mail-sent: "&a邮件发送成功！"
  template-saved: "&a模板已保存: &e%name%"

input:
  enter-title: "&f请输入邮件标题 &7(cancel 取消):"
  enter-content: "&f请输入邮件内容 &7(done 完成, cancel 取消):"

messages.yml 支持 50+ 条目完全自定义。

🧩 项目结构 / 数据库表 / 构建

项目结构

AdventureMail/
├── pom.xml
└── src/main/
    ├── java/com/adventuremail/
    │   ├── AdventureMail.java          # 主类
    │   ├── ConfigManager.java          # 配置管理
    │   ├── MailManager.java            # 邮件核心
    │   ├── MailCommandExecutor.java    # 命令处理
    │   ├── model/
    │   │   ├── Mail.java / MailDraft.java
    │   │   ├── MailType.java (10种)
    │   │   ├── MailCategory.java (4分类)
    │   │   ├── MailCommand.java / TargetType.java
    │   ├── storage/
    │   │   ├── StorageProvider.java     # 存储抽象
    │   │   ├── YamlStorage.java
    │   │   ├── DatabaseManager.java    # HikariCP
    │   │   └── DatabaseStorage.java    # MySQL
    │   ├── gui/  (18个GUI类)
    │   └── listener/
    │       └── PlayerJoinListener.java
    └── resources/
        ├── plugin.yml / config.yml / messages.yml
web-editor/
└── index.html                          # Web邮件编辑器

数据库表结构

amail_mails

索引：idx_recipient, idx_recipient_trashed, idx_expire, idx_send_time

amail_sent

构建方式

cd AdventureMail
mvn clean package
# 产物: target/AdventureMail-5.2.0.jar

HikariCP 通过 maven-shade-plugin 重定位到 com.adventuremail.libs.hikari。

Web 邮件编辑器

独立浏览器端工具，直接打开 web-editor/index.html。支持可视化编辑、附件管理、内置模板、Minecraft风格预览、输出YAML/命令。