Skip to content
UltiKitsPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

215 Commits

Folders and files

Repository files navigation

UltiMail

UltiTools-API

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

📦 安装

  1. 确保服务器已安装 UltiTools-API 6.3.0+(本模块声明 api-version: 630,更早的框架会拒绝加载它)
  2. 将 UltiMail-1.1.0.jar 放入 plugins/UltiTools/plugins/ 目录
  3. 重启服务器(/ul reload 只重载配置,不会加载新的模块 JAR)

或通过 UPM 安装:

/upm install UltiMail

⚙️ 配置文件

主配置 (config/mail.yml)

# 是否在玩家登录时通知未读邮件
notify-on-join: true

# 登录通知延迟(秒,0-60)
notify-delay: 3

# 新邮件通知消息模板
messages:
  mail-received: "&e[邮件] &f你收到了来自 &a{SENDER} &f的新邮件!"

Optional mail expiry

Expiry is off by default. In plugins/UltiTools/pluginConfig/UltiMail/config/mail.yml, set the new setting below, then run /ul reload UltiMail:

expiry:
  retention-days: 0 # 0 = disabled; choose 1-365 to enable

With retention-days: 30, a background pass every 1200 server ticks (about one minute at normal speed, first pass one minute after load) permanently removes mail that was sent at least 30 full 24-hour days ago only if it is read and has no unclaimed items or unexecuted commands. The shared row is removed from both inbox and sentbox, even if one side has not deleted it. Unread mail and mail with pending items or commands are retained indefinitely; expiry never returns, grants or executes attachments. Already recorded command attempts count as executed, even when a command was rejected. Mail stays visible until the pass removes it. This is an asynchronous full-table scan, not a bounded batch; very large tables still require storage capacity planning. With JSON storage, deletions follow the framework's normal cache-flush durability contract.

Back up mail storage before opting in: enabling applies to existing mail as well as new mail, using its original sending time. Setting 0 and reloading stops future passes from deleting mail; it does not recover rows already removed, and a pass already running finishes with its previous setting. The old mail-expire-days key is still ignored (and warned about). An old mail-expire-days: 30 never enables the new feature and is not migrated or overwritten. A failed scan or deletion is logged and retried on the next pass; a failed deletion does not stop other eligible mail being removed. A mailbox GUI opened before a purge can still show the removed mail's text until reopened; it cannot claim pending value from expiry because such mail is never eligible for deletion.

邮件过期默认关闭。主动设置新键 expiry.retention-days 为 1-365 并执行 /ul reload UltiMail 后, 后台每 1200 tick 检查一次,只永久删除自发送起达到天数、已读且没有待领取物品或待执行命令的邮件, 收件箱和发件箱共用的记录会一起删除。未读邮件和仍有待领取附件或待执行命令的邮件始终保留。 旧的 mail-expire-days: 30 仍无效,不会自动启用或迁移。启用前请备份;改回 0 只停止后续清理, 不能恢复已删邮件,正在运行的一轮仍按原设置完成。这里的天数从发送时间计算,每天为 24 小时。

⚠️ Known limitations / 已知限制

Shared database: sender deletion through another plugin can be undone by a stale mail copy. If two servers share one database, a receiver's open inbox GUI holds the mail as it was when the GUI opened. If a third-party plugin on the other server then calls MailService#deleteMail(MailData, UUID) or MailService#recordDeletion(MailData, UUID) with the sender's UUID, a later read, attachment claim or attached-command action in that already-open inbox can write the old deleted_by_sender = false back to storage. The mail can reappear in the sender's sentbox. A receiver-side deletion through the API using an older MailData can likewise leave a receiver-only soft-deleted row instead of removing a mail both sides have deleted. The inbox GUI itself has no delete action; /mail delete, /mail delall and /mail delread load the receiver's inbox again before deleting.

UltiMail's own commands delete only the receiver's copy, and the sentbox GUI is read-only: this particular sender-deletion conflict needs a third-party integration. On shared storage, do not let such an integration delete the sender's copy while the receiver can still act on an older copy of that mail. Coordinate the operations across servers: stop recipient actions and discard held mail copies, perform the sender deletion, then reload the mail before allowing recipient actions again (close and reopen an inbox GUI). Re-reading once without coordinating the writers does not prevent another intervening write. This is a documented integration limitation, not a cross-server concurrency guarantee (#47).

共享数据库:其他插件执行的发件人删除可能被旧邮件副本撤销。 两台服务器共用数据库时,收件人已打开的收件箱 GUI 会保留打开时的邮件副本。此后,若另一台服务器上的第三方插件以发件人 UUID 调用 MailService#deleteMail(MailData, UUID) 或 MailService#recordDeletion(MailData, UUID),收件人在原 GUI 中阅读、领取附件或触发附带命令时,可能将旧的 deleted_by_sender = false 写回,令邮件重新出现在发件箱中。 以旧 MailData 调用收件人删除 API,也可能只留下收件人已删除的记录,而不是彻底删除双方都已删除的邮件。 收件箱 GUI 本身没有删除操作;/mail delete、/mail delall 和 /mail delread 都会先重新读取收件箱。

模块自带命令只删除收件人一侧,发件箱 GUI 只读,因此这种发件人删除冲突需要第三方集成才会触发。共用数据库时, 集成方不要在收件人仍能操作旧副本期间删除发件人一侧。应跨服协调操作:先暂停收件人操作并丢弃持有的邮件副本, 完成发件人删除,再重新读取邮件后恢复操作(收件箱 GUI 需关闭后重新打开)。不协调写入方、仅重新读取一次,不能防止 读取与写入之间再次发生冲突。这是集成限制的说明,不是跨服并发安全保证(#47)。

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)。

A mail text whose last word is items or attach. The mail content of /mail sendall and the subject of /sendmail may hold several words. A final word items (for /mail sendall) or attach (for /sendmail) is read as the attachment switch, not as text: /mail sendall Server restart items broadcasts "Server restart" with attachments, and /sendmail Alex Meeting attach sends the subject "Meeting" with an attachment. A content or subject that should itself end with that word cannot be sent as written; reword it (for example ... items list). The flag word on its own, or no text at all, sends nothing and shows the command's usage.

以 items 或 attach 结尾的邮件文字。 /mail sendall 的内容和 /sendmail 的标题可以包含多个词。最后一个词若是 items(/mail sendall)或 attach(/sendmail),会被当作附件开关而不是文字:/mail sendall Server restart items 群发内容为“Server restart”的带附件邮件,/sendmail Alex Meeting attach 发送标题为“Meeting”的带附件邮件。若内容或标题 本身就要以这个词结尾,无法按原样发送,请换一种写法(例如 ... items list)。只写这个词、或什么文字都不写时,不会发送, 并显示该命令的用法。

🖼️ GUI 预览

收件箱 GUI

  • 未读邮件显示为 绿色羊毛 ✉️
  • 已读邮件显示为 灰色羊毛 📭
  • 有附件的邮件在 Lore 中显示物品数量
  • 点击邮件可阅读并领取附件

发件箱 GUI

  • 所有已发送邮件按时间排序
  • 显示接收者、标题和发送时间

附件选择 GUI(管理员)

  • 管理员发送邮件时可打开多物品选择界面
  • 45 格物品槽位
  • 确认/取消按钮

🔌 API 使用

UltiMail 提供了完整的 API 供其他插件调用。

获取 MailService

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);

MailData 实体

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 的区别

功能 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/
    └── lang/
        ├── zh.yml                 # 中文
        └── en.yml                 # 英文

🛠️ 开发依赖

<dependency>
    <groupId>com.ultikits</groupId>
    <artifactId>UltiTools-API</artifactId>
    <version>6.3.0</version>
    <scope>provided</scope>
</dependency>

Compatibility verification / 兼容性核查

The dependency above is a build input; plugin.yml's api-version: 630 is the framework level checked at module load. Matching those declarations is not, by itself, a complete binary-compatibility proof. UltiTools-API 6.3.0 is available on Maven Central, so the example uses the released dependency, not a snapshot.

The historical check recorded in #50 compared only Methodref and InterfaceMethodref entries, with its 6.3.0 result taken against a local 6.3.0-SNAPSHOT build. It showed that DataOperator.updateCounted was absent from 6.2.1 and 6.2.5; it did not check class or field references, or establish that every reference resolves against the released 6.3.0 JAR. #51 records that limitation.

上面的依赖是构建输入;模块加载时检查的框架级别来自 plugin.yml 的 api-version: 630,两者一致并不等于 完整的二进制兼容性证明。6.3.0 正式版已在 Maven Central 上可用。旧检查只比较方法引用,6.3.0 一栏使用的是本地 SNAPSHOT;它证明旧框架缺少 DataOperator.updateCounted,但未核查类和字段引用,也未证明正式版能解析所有引用。

2.1.0 reference audit. The 2.1.0 JAR was checked with the framework's LinkageAudit (shipped in UltiTools-API 6.4.0), which resolves every class, field and method reference the module makes into the Paper/Bukkit/Adventure and UltiTools namespaces, by JVM descriptor and including interface methods and inherited members. Against the released UltiTools-API 6.3.0 JAR with the Paper 1.21.11 API, nothing is unresolved; all 19 UltiTools classes the module references exist in 6.3.0. Against UltiTools-API 6.4.0 with the Paper 1.21.11 API and with the Paper 1.19.2 API, nothing is unresolved either. Reflection and behaviour behind unchanged signatures are outside such an audit.

2.1.0 引用核查。 2.1.0 的 JAR 用框架自带的 LinkageAudit(UltiTools-API 6.4.0 起提供)核查过:它按 JVM 描述符 解析模块对 Paper/Bukkit/Adventure 与 UltiTools 的每个类、字段和方法引用(含接口方法和继承成员)。对照正式版 UltiTools-API 6.3.0 JAR 与 Paper 1.21.11 API,没有未解析的引用,模块引用的 19 个 UltiTools 类在 6.3.0 中都存在; 对照 UltiTools-API 6.4.0 与 Paper 1.21.11 API、Paper 1.19.2 API,同样没有未解析的引用。反射以及签名不变的行为变化 不在这类核查范围内。

📝 更新日志

Changes not yet in a release, and every release from 2.0.0 on, are listed in CHANGELOG.md. 尚未发布的更改及 2.0.0 起的各版本见 CHANGELOG.md。

v1.1.0

本仓库首个也是唯一一个发布版本(2026-02-18)。仓库从初始提交起即为 1.1.0,从未发布过 1.0.0;下面 v1.1.0 与 v1.0.0 两节列表在初始提交中即已存在,合起来就是 1.1.0 包含的内容,并不对应两次发布。这个版本号是在模块版本号规范 (UltiKits/UltiTools-Dev-Doc#7、#12)落地之前定的,规范从下一版起适用(#7)。

The first and only release of this repository (2026-02-18). The repository has been at 1.1.0 since its initial commit and no 1.0.0 was ever published; the v1.1.0 and v1.0.0 lists below were already in that initial commit and together describe what 1.1.0 contains, not two releases. The number predates the module version rules (UltiKits/UltiTools-Dev-Doc#7, #12), which apply from the next release on (#7).

  • ✅ 新增收件箱/发件箱 GUI
  • ✅ 新增群发邮件功能
  • ✅ 新增批量删除命令 (delall, delread)
  • ✅ 新增可点击通知消息
  • ✅ 新增命令执行 API
  • ✅ 管理员支持多物品附件
  • ✅ 完善 i18n 国际化

v1.0.0(未发布 / never published)

  • 🎉 初始版本
  • 基础邮件收发功能
  • 物品附件支持
  • 登录通知

🌍 多语言支持

UltiMail 支持多语言,语言文件位于 lang/ 目录:

  • lang/zh.yml - 简体中文
  • lang/en.yml - English

📄 开源协议

本项目基于 MIT License 开源。

🤝 贡献

欢迎提交 Issue 和 Pull Request!

📞 支持

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages