Calendar Events - 日历事件插件

CalendarEvents 是一款基于真实时间调度的插件，它允许你配置在特定时间点触发自定义事件，并执行相应的操作，例如发送消息、执行命令或与其他插件联动。无论是简单的定时问候，还是复杂的周期性任务，都可以轻松实现。

💡主要特性

• 灵活的时间配置：支持按日、周、月、年或具体日期时间触发事件。
• 多种执行动作：可执行命令、发送全服公告、标题、动作栏消息。
• 权限控制：可为广播、标题、动作栏等动作设置接收权限。
• 组合事件：通过组合多个基础事件，创建更复杂的触发条件（如“每月第一个周日”）。
• API 支持：提供完整的 API，供其他插件动态注册和监听事件。
• PlaceholderAPI 集成：可通过占位符显示距离下次事件触发的时间。
• 时区与语言适配：支持调整服务器时间偏移以适应玩家时区，并自定义日期/月份的语言显示。

🎮配置说明

配置文件 config.yml 结构清晰，以下为关键部分概述。

事件定义 (events)

每个事件需要一个唯一的标签作为标识。在 timing 下配置触发时机。

• occasion: 触发日期。支持具体日期（如 "01"、"24.12.2022"）、星期（如 "monday"）、关键词（如 "every day"）或逗号分隔的列表。
• time: 触发时间（24小时制）。支持具体时间（如 "12:00"）、逗号分隔列表，或使用 x 作为通配符（如 "xx:00" 表示每小时整点）。

监听器动作 (listener)

在对应事件标签下，可配置触发时执行的动作。可使用以下占位符：

• %time%: 事件触发时间（hh:mm）。
• %day%: 星期名称（取决于设置的语言）。
• %month%: 月份名称（取决于设置的语言）。
• %player%: 玩家名（用于需要玩家的上下文中）。
• %allOnline%: 为每个在线玩家单独执行命令时替换为玩家名。
• %allOffline%: 为每个离线玩家单独执行命令时替换为玩家名。
• %allPlayers%: 为所有（在线和离线）玩家单独执行命令时替换为玩家名。

可用动作类型：

• commands: 执行命令列表。
• commandsWithPerm: 为拥有特定权限的玩家执行命令列表。
• broadcast: 发送全服广播。
• broadcastWithPerm: 向拥有特定权限的玩家发送广播。
• actionbar: 发送动作栏消息（可选权限）。
• title: 发送标题消息（可选权限，可设置显示时长）。

通用设置 (settings)

• addHoursToServerTime: 调整服务器时间的小时偏移量，用于适配玩家所在时区。
• language: 设置语言（使用 IETF 语言标签），影响 %day% 和 %month% 的输出。

🔧命令与权限

插件本身不提供玩家命令，所有操作均通过配置文件或 API 在事件触发时自动执行。

动作中涉及的权限节点示例：

• example.perm: 在示例配置中，用于控制谁可以接收带权限的广播、标题或动作栏。

✨占位符 (PlaceholderAPI)

安装 PlaceholderAPI 后，可使用以下占位符获取距离指定事件下一次触发的时间：

• %calendarevents_until:事件标签%：返回 d h min s 格式。
• %calendarevents_until-s:事件标签%：返回秒数。
• %calendarevents_until-min:事件标签%：返回分钟数。
• %calendarevents_until-min-plus-one:事件标签%：返回分钟数加一（用于修正显示）。
• %calendarevents_until-h:事件标签%：返回小时数。
• %calendarevents_until-d:事件标签%：返回天数。

⭐API 开发者指南

如果你开发自己的插件并希望集成 CalendarEvents，可以使用其 API。

获取 API 实例

me.nikl.calendarevents.CalendarEvents calendarEvents = (me.nikl.calendarevents.CalendarEvents) Bukkit.getPluginManager().getPlugin("CalendarEvents");
CalendarEventsApi api = calendarEvents.getApi();

主要 API 方法

• boolean addEvent(String label, String occasions, String timings): 动态添加一个事件。
• void removeEvent(String label): 移除指定标签的事件。
• boolean isRegisteredEvent(String label): 检查事件是否已注册。
• int secondsToNextCall(String label): 计算距离事件下次触发的秒数。

监听事件

在你的插件中监听 CalendarEvent：

@EventHandler
public void onCalendarEvent(CalendarEvent event) {
    if (!event.getLabels().contains("你的_事件_标签")) {
        return;
    }
    // 事件触发，执行你的逻辑
}

Maven 依赖

<repositories>
    <repository>
        <id>nikl-repo</id>
        <url>https://repo.nikl.me/artifactory/public</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>me.nikl</groupId>
        <artifactId>calendarevents</artifactId>
        <version>2.1.0</version> <!-- 请使用最新版本 -->
    </dependency>
</dependencies>

❓注意事项与提示

• 版本兼容性：对于 Minecraft 1.14 以下版本，请使用 CalendarEvents v1 (1.9.0)。
• 时间精度：事件在指定分钟的第一秒触发。
• 通配符 x：在时间配置中，x 可代表任何有效数字（例如 "xx:15" 表示每小时的 15 分）。
• 组合事件：组合事件（events）仅在它所列出的所有基础事件在同一时间触发时才会触发。
• 问题反馈：如有问题、建议或疑问，请在 GitHub 上提交 Issue，这比直接留下评论更有效。

---

相关链接

• SpigotMC 资源页面
• GitHub 源码与 Issue 反馈
• API 使用示例项目
• Discord 支持聊天 (请替换为实际链接)