开发文档

提示

开发接口可在售后群下载，如果你是开发者，欢迎联系作者 15568820 进行交流咨询

API

IMailAPI.kt

package me.yeezhi.yeemail.api

import me.yeezhi.yeemail.api.entity.mail.MailAttachment
import me.yeezhi.yeemail.api.entity.mail.MailDraft
import me.yeezhi.yeemail.api.entity.mail.MailEntry
import me.yeezhi.yeemail.api.entity.mail.MailItemRule
import me.yeezhi.yeemail.api.entity.mail.MailSender
import me.yeezhi.yeemail.api.entity.mail.MailTarget
import org.bukkit.entity.Player
import org.bukkit.inventory.ItemStack

/** 邮箱接口 */
interface IMailAPI {
    /**
     * 构建邮件草稿
     *
     * @param target 收件目标
     * @param sender 发件人
     * @param title 邮件标题
     * @param content 邮件正文
     * @param templateId 模板 ID
     * @param attachment 附件
     * @param expireAt 过期时间戳，`0` 表示不过期
     * @return 草稿对象
     */
    fun buildMail(
        target: MailTarget,
        sender: MailSender,
        title: String = "",
        content: String = "",
        templateId: String = "",
        attachment: MailAttachment = MailAttachment(),
        expireAt: Long = 0L
    ): MailDraft {
        return MailDraft(
            sender = sender,
            target = target,
            title = title,
            content = content,
            templateId = templateId,
            expireAt = expireAt,
            currencies = attachment.currencies,
            items = attachment.items
        )
    }

    /**
     * 构建邮件草稿
     *
     * @param name 收件玩家名
     * @param sender 发件人
     * @param title 邮件标题
     * @param content 邮件正文
     * @param templateId 模板 ID
     * @param attachment 附件
     * @param expireAt 过期时间戳，`0` 表示不过期
     * @return 草稿对象
     */
    fun buildMail(
        name: String,
        sender: MailSender,
        title: String = "",
        content: String = "",
        templateId: String = "",
        attachment: MailAttachment = MailAttachment(),
        expireAt: Long = 0L
    ): MailDraft {
        return buildMail(
            target = MailTarget.Player(name),
            sender = sender,
            title = title,
            content = content,
            templateId = templateId,
            attachment = attachment,
            expireAt = expireAt
        )
    }

    /**
     * 发送草稿
     *
     * @param draft 草稿对象
     * @return 发送成功的邮件 ID 列表
     */
    fun send(draft: MailDraft): List<String>

    /**
     * 按模板发送邮件
     *
     * @param target 收件目标
     * @param templateId 模板 ID
     * @return 发送成功的邮件 ID 列表
     */
    fun sendTemplate(
        target: MailTarget,
        templateId: String
    ): List<String>

    /**
     * 按模板发送邮件
     *
     * @param player 在线玩家
     * @param templateId 模板 ID
     * @return 发送成功的邮件 ID 列表
     */
    fun sendTemplate(
        player: Player,
        templateId: String
    ): List<String>

    /**
     * 获取收件箱快照
     *
     * @param player 在线玩家
     * @return 收件箱邮件列表
     */
    fun mailbox(player: Player): List<MailEntry>

    /**
     * 获取已发送快照
     *
     * @param player 在线玩家
     * @return 已发送邮件列表
     */
    fun sentbox(player: Player): List<MailEntry>

    /**
     * 标记邮件为已读
     *
     * @param player 在线玩家
     * @param mailId 邮件 ID
     * @return 是否标记成功
     */
    fun read(player: Player, mailId: String): Boolean

    /**
     * 领取单封邮件
     *
     * @param player 在线玩家
     * @param mailId 邮件 ID
     * @return 是否领取成功
     */
    fun claim(player: Player, mailId: String): Boolean

    /**
     * 快捷领取可领取邮件
     *
     * @param player 在线玩家
     * @return 成功领取数量
     */
    fun quickClaim(player: Player): Int

    /**
     * 删除单封邮件
     *
     * @param player 在线玩家
     * @param mailId 邮件 ID
     * @return 是否删除成功
     */
    fun delete(player: Player, mailId: String): Boolean

    /**
     * 快捷删除可删除邮件
     *
     * @param player 在线玩家
     * @return 成功删除数量
     */
    fun quickDelete(player: Player): Int

    /**
     * 执行过期清理
     *
     * @param now 当前毫秒时间戳
     * @return 本轮处理数量
     */
    fun cleanupExpired(now: Long = System.currentTimeMillis()): Int

    /**
     * 注册附件物品校验规则
     *
     * @param rule 规则实现
     */
    fun registerItemRule(rule: MailItemRule)

    /**
     * 检测物品是否允许邮寄
     *
     * @param itemStack 物品对象
     * @return 是否允许发送
     */
    fun canSend(itemStack: ItemStack): Boolean

    /**
     * 检测文本是否命中违禁词
     *
     * @param text 原始文本
     * @return 是否命中违禁词
     */
    fun containsProfanity(text: String): Boolean

    /**
     * 屏蔽文本中的违禁词
     *
     * @param text 原始文本
     * @return 屏蔽后的文本
     */
    fun maskProfanity(text: String): String
}

ICdkAPI.kt

package me.yeezhi.yeemail.api

import me.yeezhi.yeemail.api.config.CdkConfig
import me.yeezhi.yeemail.api.entity.cdk.CdkCreateResult
import org.bukkit.entity.Player

/** CDK 接口 */
interface ICdkAPI {

    /**
     * 兑换 CDK
     *
     * @param player 在线玩家
     * @param code 兑换码
     * @return 成功时返回邮件 ID，失败返回 `null`
     */
    fun redeem(player: Player, code: String): String?

    /**
     * 基于一次性预设批量创建兑换码
     *
     * @param presetId 预设 ID（`public=false` 的配置节点）
     * @param amount 生成数量
     * @param expireAt 兑换码过期时间（绝对时间戳，0 表示不过期）
     * @return 创建结果
     */
    fun create(presetId: String, amount: Int, expireAt: Long = 0L): CdkCreateResult

    /**
     * 删除兑换码
     *
     * @param code 兑换码
     * @return `true` 表示删除成功
     */
    fun remove(code: String): Boolean

    /**
     * 获取预设配置
     *
     * @return 预设映射
     */
    fun presets(): Map<String, CdkConfig>
}

ICurrencyRegistry.kt

package me.yeezhi.yeemail.api

/** 货币注册中心接口 */
interface ICurrencyRegistry {

    /**
     * 注册货币实现
     *
     * @param currency 货币实现
     */
    fun register(currency: Currency)

    /**
     * 按 key 获取货币实现
     *
     * @param id 货币 key
     * @return 货币实现
     */
    fun getCurrency(id: String): Currency

    /**
     * 获取全部已注册货币
     *
     * @return 货币实现集合
     */
    fun getAll(): Collection<Currency>

    /**
     * 执行货币重载
     */
    fun load()

    /**
     * 获取货币显示名
     *
     * @param id 货币 key
     * @return 货币显示名
     */
    fun getCurrencyName(id: String): String
}

Currency.kt

package me.yeezhi.yeemail.api

import org.bukkit.entity.Player

/**
 * 通用货币接口
 */
interface Currency {

    /**
     * 货币唯一 ID
     *
     * 例如：`vault`、`points`、`craftx`
     */
    val id: String

    /**
     * 对应依赖插件名，插件未加载时不进行接口注册
     */
    val plugin: String

    /**
     * 初始化货币接口
     *
     * @return `true` 表示初始化成功并可注册；`false` 表示注册失败
     */
    fun setup(): Boolean

    /**
     * 查询玩家余额
     *
     * @param player 玩家对象
     * @param currencyId 货币子类型 ID（可空，用于多货币系统）
     * @return 当前余额
     */
    fun getBalance(player: Player, currencyId: String? = null): Double

    /**
     * 判断玩家余额是否充足
     *
     * @param player 玩家对象
     * @param currencyId 货币子类型 ID（可空）
     * @param amount 要校验的金额
     * @return `true` 表示余额足够，`false` 表示余额不足
     */
    fun hasBalance(player: Player, currencyId: String? = null, amount: Long): Boolean {
        return getBalance(player, currencyId) >= amount
    }

    /**
     * 增加余额
     *
     * @param player 玩家对象
     * @param currencyId 货币子类型 ID（可空）
     * @param amount 增加金额
     */
    fun deposit(player: Player, currencyId: String? = null, amount: Long)

    /**
     * 扣减余额
     *
     * @param player 玩家对象
     * @param currencyId 货币子类型 ID（可空）
     * @param amount 扣减金额
     */
    fun withdraw(player: Player, currencyId: String? = null, amount: Long)
}

MailDraftBuilder.kt

package me.yeezhi.yeemail.api

import me.yeezhi.yeemail.api.entity.mail.*
import org.bukkit.inventory.ItemStack

/**
 * 邮件草稿构建器
 *
 * 以链式调用组装 [MailDraft]，最终由 `MailAPI.send(draft)` 发送
 */
class MailDraftBuilder(private val target: MailTarget) {
    private var sender: MailSender = MailSender(MailSender.Type.System, "系统")
    private var title: String = ""
    private var content: String = ""
    private var templateId: String = ""
    private var expireAt: Long = 0L
    private val currencies = ArrayList<MailCurrency>()
    private val items = ArrayList<MailItem>()

    /**
     * 设置系统发送者显示名
     *
     * @param value 显示名
     * @return 当前构建器
     */
    fun sender(value: String) = apply { sender = MailSender(MailSender.Type.System, value) }

    /**
     * 设置发送者对象
     *
     * @param value 发送者
     * @return 当前构建器
     */
    fun sender(value: MailSender) = apply { sender = value }

    /**
     * 设置邮件标题
     *
     * @param value 标题
     * @return 当前构建器
     */
    fun title(value: String) = apply { title = value }

    /**
     * 设置邮件正文
     *
     * @param value 正文
     * @return 当前构建器
     */
    fun content(value: String) = apply { content = value }

    /**
     * 设置模板 ID
     *
     * @param value 模板 ID
     * @return 当前构建器
     */
    fun templateId(value: String) = apply { templateId = value }

    /**
     * 设置绝对过期时间
     *
     * @param value 过期时间戳，`0` 表示不过期
     * @return 当前构建器
     */
    fun expireAt(value: Long) = apply { expireAt = value }

    /**
     * 添加货币附件
     *
     * @param key 货币键名
     * @param amount 货币数量
     * @return 当前构建器
     */
    fun addCurrency(key: String, amount: Long) = apply {
        currencies += MailCurrency(key, amount)
    }

    /**
     * 添加物品附件
     * 内部会强制把 `item.amount` 归一化为 `1`，实际数量仅使用 `amount` 字段
     *
     * @param item 物品对象
     * @param amount 数量（最小为 1）
     * @return 当前构建器
     */
    fun addItem(item: ItemStack, amount: Int) = apply {
        val singleItem = item.clone().apply { this.amount = 1 }
        items += MailItem(singleItem, amount)
    }

    /**
     * 添加单件物品附件
     *
     * @param item 物品对象
     * @return 当前构建器
     */
    fun addItem(item: ItemStack) = addItem(item, 1)

    /**
     * 构建不可变草稿对象
     *
     * @return 草稿对象
     */
    fun build(): MailDraft {
        return MailDraft(
            sender = sender,
            target = target,
            title = title,
            content = content,
            templateId = templateId,
            expireAt = expireAt,
            currencies = currencies.toList(),
            items = items.toList()
        )
    }
}

Event

提示

由于 YeePlugins 在 onEnable 阶段执行云端加载，若需注册监听，请在插件加载完成后通过循环检测再进行注册

CdkRedeemEvent.kt

package me.yeezhi.yeemail.api.event

import me.yeezhi.yeemail.api.config.CdkConfig
import org.bukkit.entity.Player
import org.bukkit.event.Cancellable
import org.bukkit.event.Event
import org.bukkit.event.HandlerList

/**
 * CDK 兑换事件
 *
 * @property player 兑换玩家
 * @property code 兑换码
 * @property config 命中的配置，可能为空
 */
class CdkRedeemEvent(
    val player: Player,
    val code: String,
    val config: CdkConfig?
) : Event(true), Cancellable {

    private var cancelled = false

    override fun isCancelled(): Boolean {
        return cancelled
    }

    override fun setCancelled(cancel: Boolean) {
        cancelled = cancel
    }

    override fun getHandlers(): HandlerList {
        return handlerList
    }

    companion object {
        @JvmStatic
        val handlerList = HandlerList()
    }
}

MailClaimEvent.kt

package me.yeezhi.yeemail.api.event

import me.yeezhi.yeemail.api.entity.mail.MailEntry
import org.bukkit.entity.Player
import org.bukkit.event.Cancellable
import org.bukkit.event.Event
import org.bukkit.event.HandlerList
import taboolib.common.platform.function.isPrimaryThread

/**
 * 邮件领取事件
 *
 * @property player 领取玩家
 * @property mail 被领取的邮件
 */
class MailClaimEvent(
    val player: Player,
    val mail: MailEntry
) : Event(!isPrimaryThread), Cancellable {

    private var cancelled = false

    override fun isCancelled(): Boolean {
        return cancelled
    }

    override fun setCancelled(cancel: Boolean) {
        cancelled = cancel
    }

    override fun getHandlers(): HandlerList {
        return handlerList
    }

    companion object {
        @JvmStatic
        val handlerList = HandlerList()
    }
}

MailDeliverEvent.kt

package me.yeezhi.yeemail.api.event

import me.yeezhi.yeemail.api.entity.mail.MailEntry
import org.bukkit.event.Event
import org.bukkit.event.HandlerList
import taboolib.common.platform.function.isPrimaryThread

/**
 * 邮件投递事件
 *
 * @property name 收件玩家名
 * @property mail 投递后的邮件对象
 */
class MailDeliverEvent(
    val name: String,
    val mail: MailEntry
) : Event(!isPrimaryThread) {

    override fun getHandlers(): HandlerList {
        return handlerList
    }

    companion object {
        @JvmStatic
        val handlerList = HandlerList()
    }
}

MailNotifyEvent.kt

package me.yeezhi.yeemail.api.event

import me.yeezhi.yeemail.api.entity.mail.MailEntry
import org.bukkit.entity.Player
import org.bukkit.event.Event
import org.bukkit.event.HandlerList
import taboolib.common.platform.function.isPrimaryThread

/**
 * 本服邮件通知事件
 *
 * @property player 收件玩家
 * @property mail 通知邮件
 */
class MailNotifyEvent(val player: Player, val mail: MailEntry) : Event(!isPrimaryThread) {

    override fun getHandlers(): HandlerList {
        return handlerList
    }

    companion object {
        @JvmStatic
        val handlerList = HandlerList()
    }
}

MailChannelEvent.kt

package me.yeezhi.yeemail.api.event

import org.bukkit.event.Event
import org.bukkit.event.HandlerList
import taboolib.common.platform.function.isPrimaryThread

/**
 * Redis 频道消息事件
 *
 * @property channel 频道名
 * @property message 原始消息
 */
sealed class MailChannelEvent(val channel: String, val message: String) : Event(!isPrimaryThread) {

    override fun getHandlers(): HandlerList {
        return handlerList
    }

    companion object {
        @JvmStatic
        val handlerList = HandlerList()
    }

    class Publish(channel: String, message: String) : MailChannelEvent(channel, message)
    class Subscribe(channel: String, message: String) : MailChannelEvent(channel, message)
}

发件示例

草稿邮件示例.java

package me.yeezhi.demo;

import me.yeezhi.yeemail.YeeMail;
import me.yeezhi.yeemail.api.IMailAPI;
import me.yeezhi.yeemail.api.MailDraftBuilder;
import me.yeezhi.yeemail.api.entity.mail.MailDraft;
import me.yeezhi.yeemail.api.entity.mail.MailTarget;
import org.bukkit.inventory.ItemStack;

import java.util.List;

/**
 * 其它插件调用 YeeMail 发送草稿邮件示例
 */
public final class MailSendDemo {

    /**
     * 给指定玩家发送一封系统邮件
     *
     * @param targetName 收件玩家名
     * @param rewardItem 附件物品
     * @return 邮件 ID 列表
     */
    public static List<String> sendDraftToPlayer(String targetName, ItemStack rewardItem) {
        IMailAPI mailApi = YeeMail.INSTANCE.getMailAPI();

        // 使用草稿构建器组装邮件
        MailDraft draft = new MailDraftBuilder(new MailTarget.Player(targetName))
                .sender("系统")
                .title("在线补偿")
                .content("请查收附件")
                .addItem(rewardItem, 1)
                .addCurrency("money", 1000L)
                .build();

        // 发送草稿并返回邮件 ID
        return mailApi.send(draft);
    }
}

模板邮件示例.java

package me.yeezhi.demo;

import me.yeezhi.yeemail.YeeMail;
import me.yeezhi.yeemail.api.IMailAPI;
import me.yeezhi.yeemail.api.entity.mail.MailTarget;
import org.bukkit.entity.Player;

import java.util.List;

/**
 * 其它插件调用 YeeMail 按模板发送邮件示例
 */
public final class MailTemplateSendDemo {

    /**
     * 按模板给指定玩家名发件
     *
     * @param targetName 收件玩家名
     * @param templateId 模板 ID
     * @return 邮件 ID 列表
     */
    public static List<String> sendTemplateToName(String targetName, String templateId) {
        IMailAPI mailApi = YeeMail.INSTANCE.getMailAPI();
        return mailApi.sendTemplate(new MailTarget.Player(targetName), templateId);
    }

    /**
     * 按模板给在线玩家发件
     *
     * @param player 在线玩家
     * @param templateId 模板 ID
     * @return 邮件 ID 列表
     */
    public static List<String> sendTemplateToPlayer(Player player, String templateId) {
        IMailAPI mailApi = YeeMail.INSTANCE.getMailAPI();
        return mailApi.sendTemplate(player, templateId);
    }
}