UltiMail 是基于 UltiTools-API 框架开发的游戏内邮件系统插件模块，支持玩家之间发送邮件、附带物品，以及管理员群发功能。
- 📬 完整的邮件系统 - 发送、接收、阅读、删除邮件
- 📦 物品附件支持 - 可以将物品作为附件发送给其他玩家
- 🖥️ 图形化界面 - 分页式收件箱/发件箱 GUI
- 📢 群发邮件 - 管理员可向全服玩家群发邮件（支持多物品附件）
- 🔔 登录通知 - 玩家上线时提示未读邮件数量（可点击打开收件箱）
- 🗑️ 批量删除 - 一键删除所有邮件或已读邮件
- ⚙️ 命令执行 API - 支持邮件携带命令（领取时自动执行）
- 🌐 多语言支持 - 内置中英文语言包
| 命令 | 权限 | 描述 |
|---|---|---|
/mail inbox |
ultimail.use |
查看收件箱列表 |
/mail read |
ultimail.use |
打开收件箱 GUI |
/mail read <编号> |
ultimail.use |
阅读指定邮件 |
/mail sent |
ultimail.use |
查看发件箱列表 |
/mail sentgui |
ultimail.use |
打开发件箱 GUI |
/mail claim <编号> |
ultimail.use |
领取邮件附件 |
/mail delete <编号> |
ultimail.use |
删除指定邮件 |
/mail delall |
ultimail.use |
删除所有邮件 |
/mail delread |
ultimail.use |
删除所有已读邮件 |
/sendmail <玩家> <标题> |
ultimail.send |
发送邮件（进入内容输入模式） |
/sendmail <玩家> <标题> attach |
ultimail.send |
发送带附件的邮件 |
| 命令 | 权限 | 描述 |
|---|---|---|
/mail sendall <内容> |
ultimail.admin.sendall |
向全服玩家群发邮件 |
/mail sendall <内容> items |
ultimail.admin.sendall |
群发带附件邮件（打开选择 GUI） |
| 权限 | 描述 | 默认 |
|---|---|---|
ultimail.use |
使用邮件系统 | 玩家 |
ultimail.send |
发送邮件 | 玩家 |
ultimail.admin.sendall |
群发邮件 | OP |
ultimail.admin.multiattach |
发送邮件时使用多物品附件 GUI | OP |
- 确保服务器已安装 UltiTools-API 6.2.1+
- 将
UltiMail-1.1.0.jar放入plugins/UltiTools/plugins/目录 - 重启服务器或使用
/ul reload重载插件
或通过 UPM 安装:
/upm install UltiMail
# 是否在玩家登录时通知未读邮件
notify_on_join: true
# 登录通知延迟（秒）
notify_delay: 3
# 新邮件通知消息模板
new_mail_message: "&e[邮件] &f你有 &a{COUNT} &f封未读邮件！"messages: {} adds two extra WARNINGs (non-zh servers). UltiMail ships a default for
messages.mail-received in config/mail.yml. If you deliberately write the whole messages section as an
explicit empty value (messages: {}, messages: ~ or messages: null), the file is never changed: UltiMail runs
on its default text, and on a server whose language is not zh the log shows three WARNINGs instead of one.
The first is the framework's own ("the section messages is written as an explicit empty value, which the
framework does not change"). The other two come from UltiMail's own start-up save, which the framework declines:
"the module's changes to 'messages.mail-received' were not written ..." when the server starts, and
"... holds module UltiMail changes that were never saved; they are not written and are dropped ..." when the
server stops. On a zh server the default text already equals the server-language text, so UltiMail has nothing
to save and only the framework's single WARNING appears. Nothing is lost and nothing is overwritten. To have the
defaults put back, leave the line ending after the colon (messages: and nothing else; ~ and null count as
an explicit empty value), or write the keys you want under it (mail-received: ...); to stay quiet, do not
write an empty value for a section that has defaults. This is documented rather than worked around in code
because it only occurs when an operator writes an explicit empty value on purpose (#48).
messages: {} 会多出两条 WARNING（仅限 language 不是 zh 的服务器）。 UltiMail 在 config/mail.yml 中为
messages.mail-received 提供默认值。若你特意把整个 messages 段写成显式空值（messages: {}、messages: ~ 或
messages: null），文件不会被改动：UltiMail 使用默认文本。服务器 language 不是 zh 时，日志中会出现三条
WARNING 而不是一条。第一条来自框架（"该段被写成显式空值，框架不会更改它"）；另外两条来自 UltiMail 自己的启动保存被框架
拒绝："模块对 'messages.mail-received' 的更改未写入"（服务器启动时），以及服务器停止时的"有从未保存的
更改，将被丢弃"。language 为 zh 时，默认文本本身就是服务器语言的文本，UltiMail 无需保存，只会出现框架的一条
WARNING。不会丢失任何内容，也不会覆盖你的配置。想让默认值被补回，请让该行在冒号后结束（messages: 后不写任何内容；
~ 和 null 同样算显式空值），或在其下写出你想要的键（mail-received: ...）；想避免这些警告，请不要为带有默认值的段
写空值。这只在运维人员有意写下显式空值时出现，因此只在文档中说明，不在代码中绕过（#48）。
- 未读邮件显示为 绿色羊毛 ✉️
- 已读邮件显示为 灰色羊毛 📭
- 有附件的邮件在 Lore 中显示物品数量
- 点击邮件可阅读并领取附件
- 所有已发送邮件按时间排序
- 显示接收者、标题和发送时间
- 管理员发送邮件时可打开多物品选择界面
- 45 格物品槽位
- 确认/取消按钮
UltiMail 提供了完整的 API 供其他插件调用。
import com.ultikits.plugins.mail.service.MailService;
import com.ultikits.ultitools.UltiTools;
// 通过容器获取
MailService mailService = UltiTools.getInstance()
.getContext()
.getBean(MailService.class);// 发送纯文本邮件
boolean success = mailService.sendMail(
senderPlayer, // 发送者
"targetPlayer", // 接收者名称
"邮件标题", // 标题
"邮件内容", // 内容
null // 无附件
);
// 发送带物品附件的邮件
ItemStack[] items = new ItemStack[] { itemStack1, itemStack2 };
mailService.sendMail(sender, "target", "标题", "内容", items);
// 发送带命令的邮件（领取时自动执行）
List<String> commands = Arrays.asList(
"give {player} diamond 1",
"eco give {player} 100"
);
mailService.sendMail(sender, "target", "标题", "内容", items, commands);// 向所有玩家群发（异步执行）
mailService.sendToAll(
senderPlayer,
"系统公告",
"服务器将于今晚维护",
null, // 附件
null // 命令
);// 获取未读邮件数
int count = mailService.getUnreadCount(playerUUID);
// 获取收件箱
List<MailData> inbox = mailService.getInbox(playerUUID);
// 获取发件箱
List<MailData> sentbox = mailService.getSentMails(playerUUID);邮件支持携带命令，在玩家领取附件时自动执行：
// 命令中的 {player} 会被替换为领取者名称
List<String> commands = Arrays.asList(
"give {player} diamond 1", // 控制台执行
"eco give {player} 100"
);
// 通过 API 发送
mailService.sendMail(sender, receiver, subject, content, items, commands);
// 手动执行命令（如果需要）
mailService.executeMailCommands(mail, player);public class MailData extends BaseDataEntity<String> {
private UUID sender; // 发送者 UUID
private UUID receiver; // 接收者 UUID
private String senderName; // 发送者名称
private String receiverName;// 接收者名称
private String subject; // 标题
private String content; // 内容
private String items; // Base64 编码的物品数组
private String commands; // JSON 格式的命令列表
private boolean read; // 是否已读
private boolean claimed; // 附件是否已领取
private boolean commandsExecuted; // 命令是否已执行
private Date createTime; // 创建时间
// 辅助方法
boolean hasItems(); // 是否有附件
boolean hasCommands(); // 是否有命令
}| 功能 | UltiTools 5.x | UltiMail 6.x |
|---|---|---|
| 命令系统 | 手动注册 | 注解驱动 |
| 数据存储 | 文件/MySQL 混合 | DataOperator ORM |
| GUI | InventoryManager | BasePaginationPage |
| 群发邮件 | ❌ | ✅ |
| 批量删除 | ❌ | ✅ |
| 命令执行 | ❌ | ✅ API |
| 可点击通知 | ❌ | ✅ Adventure API |
| 多物品附件 | ❌ | ✅ 管理员 |
UltiMail/
├── src/main/java/com/ultikits/plugins/mail/
│ ├── UltiMail.java # 主类
│ ├── commands/
│ │ ├── MailCommand.java # /mail 命令
│ │ └── SendMailCommand.java # /sendmail 命令
│ ├── config/
│ │ └── MailConfig.java # 配置实体
│ ├── entity/
│ │ └── MailData.java # 邮件数据实体
│ ├── gui/
│ │ ├── MailboxGUI.java # 收件箱 GUI
│ │ ├── SentboxGUI.java # 发件箱 GUI
│ │ └── AttachmentSelectorPage.java # 附件选择 GUI
│ ├── listener/
│ │ ├── MailNotifyListener.java # 登录通知
│ │ └── AttachmentGUIListener.java # GUI 监听
│ └── service/
│ └── MailService.java # 邮件服务
└── src/main/resources/
├── config.yml # 默认配置
└── lang/
├── zh.yml # 中文
└── en.yml # 英文
<dependency>
<groupId>com.ultikits</groupId>
<artifactId>UltiTools-API</artifactId>
<version>6.2.1</version>
<scope>provided</scope>
</dependency>- ✅ 新增收件箱/发件箱 GUI
- ✅ 新增群发邮件功能
- ✅ 新增批量删除命令 (delall, delread)
- ✅ 新增可点击通知消息
- ✅ 新增命令执行 API
- ✅ 管理员支持多物品附件
- ✅ 完善 i18n 国际化
- 🎉 初始版本
- 基础邮件收发功能
- 物品附件支持
- 登录通知
UltiMail 支持多语言，语言文件位于 lang/ 目录：
lang/zh.yml- 简体中文lang/en.yml- English
本项目基于 MIT License 开源。
欢迎提交 Issue 和 Pull Request！
- GitHub Issues: https://github.com/UltiKits/UltiTools-Reborn/issues
- 文档: https://doc.ultikits.com