原创 开源 工具 MittelRandomEvents —— 一个可高度自定义的随机事件系统 | 支持Folia 1.0.0

[MD] # MittelRandomEvents ## 让服务器的每一分钟，都值得期待。 做服务器久了，有个尴尬的事： 内容都做完了。地图搭了，玩法定了，奖励也配了。玩家进来逛一圈，走了。 不是内容不好。是太“死”了。什么都是写死的，玩家摸清规律就不来了。 MRE 就是冲着这个来的。 它不帮你建地图，不帮你定玩法。它只做一件事：**让服务器在你没看着的时候，自己运转、自己变化、自己制造意外。** 事件线跑起来，权重随机一抽，条件门控一过——玩家永远不知道下一秒会发生什么。 ## 它跟“定时抽奖”是两码事 市面上的随机事件插件，基本就两种：定时发消息，或者随机给奖励。用两次就腻了，因为玩家知道它会干嘛。 MRE 的核心是两个东西： **事件（Event）**——“发生了什么”。一个事件由一连串动作组成，可以带条件、带权重、带时长。 **事件线（Event Line）**——“什么时候发生”。按固定间隔跑，或者用 Cron 表达式精确定时，然后从挂载的事件里加权抽一个出来。 天灾、福报、地牢入侵、商队路过、随机 Boss、世界异变……你想得到的玩法，基本都能塞进去。 说白了，你的服务器有了自己的“命运系统”。 ## 时间你定 - **固定间隔**：每 30 秒、每 5 分钟，随你设 - **Cron 表达式**：凌晨 3 点、每周五晚 8 点半、每天正午——精确到分钟 - **手动触发**：想测试就测试，想搞活动就搞活动，一键执行 ## 随机但合理 - 每个事件在事件线里有**独立权重**，权重越高越常出现 - 支持**空事件槽**——“什么也没发生”也能放进概率池，抽奖感拉满 - 抽取前先过**条件过滤**：不满足条件的事件不参与抽取 随机不等于乱来。 ## 动作编排 | 类别 | 能做什么 | |---|---| | 目标选择 | 选玩家 / 选世界（可按权限、按世界过滤，随机洗牌、限制数量） | | 效果施加 | 治疗 / 伤害 / 清空背包 / 播放音效 / 改变天气 | | 消息广播 | 私聊玩家 / 全服广播 | | 命令执行 | 控制台命令 / 玩家命令，支持 `%参数%` 插值 | | 流程控制 | 停止后续动作 / 跳过下一个动作 | 动作按顺序执行，前一个的结果会传给后一个。所以你可以编排这样的链路： > 选中全服 VIP 玩家 → 每人执行一段命令 → 播放音效 → 广播公告 ## 条件系统 内置 11 种检测条件：在线人数、玩家数、世界数、服务器 TPS、服务端版本、插件启停、玩家权限、玩家名 / 世界名匹配…… 再加上 `all_of` / `any_of` / `not` 三个逻辑门，简单条件能组合成任意复杂的规则。 比如：“TPS 高于 15 **且** 在线人数超过 30 **且** 不是凌晨时段”才触发。 服务器状态不对？那就不触发。 ## 有始有终 事件可以设置**持续时长**：触发时执行“开始动作”，持续时间内保持状态，时间一到自动执行“结束动作”收尾。 限时活动、阶段事件、Boss 降临——事件有完整的生命周期，不是一瞬即逝。 **如果你需要在某事件内对一些东西进行数值操作，且不是永久的，记得在”结束动作“中恢复原来的数值！** ### 全 GUI 配置 所有东西都能在游戏里点出来： 主界面一键进入，分页列表管理事件和事件线。创建、改名、换图标、启用停用、删除。事件里可视化编排动作和条件，事件线里可视化设置权重、间隔、Cron、时长。随时开始、停止、立即执行。 不会写 YAML？没关系。整条链路都可以点出来。 [/MD]


[MD] ## 其他插件兼容性 - **PlaceholderAPI + MiniPlaceholders 双支持** - ***还有更多插件将在未来被支持*** ## 变量 将 `EVENT_ID` 替换为事件 ID，将 `LINE_ID` 替换为事件线 ID；使用 ID，而非显示名称。 ### PlaceholderAPI | 变量 | 中文说明 | |---|---| | `%mittelrandomevents_event_count%` | 已注册的事件总数，包含已禁用事件；没有事件时返回 `0`。 | | `%mittelrandomevents_line_count%` | 已注册的事件线总数；没有事件线时返回 `0`。 | | `%mittelrandomevents_event_enabled_EVENT_ID%` | 事件是否启用，返回 `true` 或 `false`；ID 缺失或不存在时返回 `false`。 | | `%mittelrandomevents_event_display_name_EVENT_ID%` | 事件的显示名称，包含格式信息；ID 缺失或不存在时返回空文本。 | | `%mittelrandomevents_line_running_LINE_ID%` | 事件线是否有尚未取消的 Cron 调度任务，返回 `true` 或 `false`；ID 缺失、不存在或未调度时返回 `false`。 | | `%mittelrandomevents_next_event_remaining_LINE_ID%` | 距离事件线下一次 Cron 执行的剩余秒数，向上取整；ID 缺失、不存在或未调度时返回 `0`。 | | `%mittelrandomevents_next_event_remaining_formatted_LINE_ID%` | 下一次 Cron 执行的倒计时，使用 MittelLib 的倒计时格式；ID 缺失或不存在时返回 `0`，事件线存在但未调度时返回格式化的零秒。 | | `%mittelrandomevents_current_event_LINE_ID%` | 事件线当前持有的事件 ID；ID 缺失、不存在或没有当前事件时返回空文本。 | | `%mittelrandomevents_current_event_display_name_LINE_ID%` | 事件线当前事件的显示名称，包含格式信息；ID 缺失、不存在或没有当前事件时返回空文本。 | 示例：`%mittelrandomevents_event_enabled_merchant%`。 注意：MittelLib 1.4.8 会按下划线拆分 PlaceholderAPI 参数，而 MRE 仅使用第一个参数作为 ID。请使用不含下划线的 ID（可以使用连字符 `-`），或使用 MiniPlaceholders。 ### MiniPlaceholders | 变量 | 中文说明 | |---|---| | `<mittelrandomevents_event_count>` | 已注册的事件总数，包含已禁用事件；没有事件时返回 `0`。 | | `<mittelrandomevents_line_count>` | 已注册的事件线总数；没有事件线时返回 `0`。 | | `<mittelrandomevents_event_enabled:EVENT_ID>` | 事件是否启用，返回 `true` 或 `false`；ID 缺失或不存在时返回 `false`。 | | `<mittelrandomevents_event_display_name:EVENT_ID>` | 事件的格式化显示名称；ID 缺失或不存在时返回空文本。 | | `<mittelrandomevents_line_running:LINE_ID>` | 事件线是否有尚未取消的 Cron 调度任务，返回 `true` 或 `false`；ID 缺失、不存在或未调度时返回 `false`。 | | `<mittelrandomevents_next_event_remaining:LINE_ID>` | 距离事件线下一次 Cron 执行的剩余秒数，向上取整；ID 缺失、不存在或未调度时返回 `0`。 | | `<mittelrandomevents_next_event_remaining_formatted:LINE_ID>` | 下一次 Cron 执行的倒计时，使用 MittelLib 的倒计时格式；ID 缺失或不存在时返回 `0`，事件线存在但未调度时返回格式化的零秒。 | | `<mittelrandomevents_current_event:LINE_ID>` | 事件线当前持有的事件 ID；ID 缺失、不存在或没有当前事件时返回空文本。 | | `<mittelrandomevents_current_event_display_name:LINE_ID>` | 事件线当前事件的格式化显示名称；ID 缺失、不存在或没有当前事件时返回空文本。 | 示例：`<mittelrandomevents_event_enabled:merchant>`。 ### 使用说明 - 示例：`%mittelrandomevents_event_enabled_merchant%` 或 `<mittelrandomevents_event_enabled:merchant>`。 - MittelLib 1.4.8 会按下划线拆分 PlaceholderAPI 参数，而 MRE 仅使用第一个参数作为 ID。因此，PlaceholderAPI 应使用不含下划线的 ID（可以使用连字符 `-`）；含下划线的 ID 可使用 MiniPlaceholders。 - `line_running` 表示调度任务是否运行，不表示当前是否有事件正在进行。 - `next_event_remaining` 系列表示距离下一次 Cron 执行的时间，不是当前事件的剩余持续时间；下一次执行也不一定触发新事件。 - 无持续时间的事件会在动作执行完毕后立即清除，因此执行结束后通常无法通过 `current_event` 系列读取。 ### 控制台命令变量 以下变量用于 `execute_console_command` 动作的 `command` 参数，采用 `%变量名%` 写法，无需安装 PlaceholderAPI 或 MiniPlaceholders。 | 变量 | 中文说明 | 可用条件 | |---|---|---| | `%player%` | 当前选中玩家的名称。 | 设置 `runForEachPlayer: true`，逐个玩家执行时可用。 | | `%playerUuid%` | 当前选中玩家的 UUID。 | 设置 `runForEachPlayer: true`，逐个玩家执行时可用。 | | `%playerWorld%` | 当前选中玩家所在世界的名称。 | 设置 `runForEachPlayer: true`，逐个玩家执行时可用。 | | `%playerX%` | 当前选中玩家的 X 坐标，包含小数部分。 | 设置 `runForEachPlayer: true`，逐个玩家执行时可用。 | | `%playerY%` | 当前选中玩家的 Y 坐标，包含小数部分。 | 设置 `runForEachPlayer: true`，逐个玩家执行时可用。 | | `%playerZ%` | 当前选中玩家的 Z 坐标，包含小数部分。 | 设置 `runForEachPlayer: true`，逐个玩家执行时可用。 | | `%parameterName%` | 动作参数或事件上下文中对应参数的文本值；将 `parameterName` 替换为实际参数名，区分大小写。 | 对应键存在于 `action.parameters()` 或 `context.parameters()` 中。 | ### 参数替换规则 - 同名参数的覆盖顺序：事件上下文参数 → 动作参数 → 注入的逐玩家变量。 - 未定义的局部变量会在此替换步骤中保留原样。 - 例如，设置 `rewardAmount: 3` 和 `runForEachPlayer: true` 后，可使用命令 `give %player% minecraft:diamond %rewardAmount%`。 - `%player%` 还可由 MittelLib 在存在玩家上下文时解析，包括 `message_players` 和 `execute_player_command`；表中其余局部变量由 MRE 的控制台命令插值逻辑处理。 ## 给开发者的三行代码 MRE 提供稳定的集成 API。其他插件可以注册自己的动作类型、事件和事件线： ``` MittelRandomEventsAPI.registerActionType(myAction); // 注册自定义动作 MittelRandomEventsAPI.registerEvent(myEvent); // 注册自定义事件 MittelRandomEventsAPI.registerLine(myLine); // 注册并立即调度事件线 ``` 自定义上下文、自定义动作、深度联动。 ## 它能用来做什么？ 基本上，只要你想让服务器“发生点什么”，它都能用： - 生存服日常事件 - RPG 世界随机事件 - 小游戏服务器活动 - 节日主题活动 - 副本和挑战机制 - 玩家在线奖励 - 服务器公告联动 - 跨插件自动化流程 - 管理员测试与临时活动 你可以让服务器热闹一点，也可以让随机事件克制、稀有、神秘一点。真正重要的不是“随机”本身，而是让每一次随机发生，都符合你的服务器节奏。 ### 相关信息 GitHub：<https://github.com/LinsMinecraftStudio/MittelRandomEvents> QQ 交流群：1107921027 Discord：<https://discord.gg/9YP2UaPZhE> [/MD]