- 版权类型
- 转载
- 插件中文名
- 里程碑 | 作者：Omega Plugins
- 插件英文名
- Omega Plugins
- 支持的核心 [服务端]
- Spigot
- 语言支持
- 中文(简体)
- 适配Minecraft版本 [Java]
- 1.21
[MD]
## 简介
作者： Omega Plugins
资源分类： Java 版多人游戏 · 服务端插件
# 里程碑
> **作者：** Omega Plugins
> **资源分类：** Java 版多人游戏 · 服务端插件
里程碑是一款基于 YAML 配置的服务端插件，支持自定义进度链、奖励命令、游玩时间统计和农作物收获统计，并提供完整的图形化界面。
## 核心功能
### 无限可配置的里程碑链
每种里程碑类型对应 `milestones/` 目录中的一个 YAML 文件。添加文件后，执行 /ms 即可加载。
插件附带两个经过完善的示例：
- **Farming（农耕）**：共 112 个等级，包含以下称号链：
Farmer → Harvester → Cultivator → Harvest Lord → Agronomist → Crop Sovereign → Land Baron → Crop Emperor → Harvest Titan → Agrarian Overlord → Cosmic Cultivator → Harvest Deity → Stellar Sovereign → Void Harvester → Harvest God → Legend of the Harvest
- **Playtime（游玩时间）**：共 75 个等级。前 18 小时按小时递进，之后每 12 小时递进一次，直到 35 天。
### 链式解锁
通过 `requires:` 设置前置条件，只有领取前一个里程碑后，后续等级才会解锁。
领取某个等级后，聊天栏会提示下一个里程碑已经解锁。
### 奖励支持任意控制台命令
奖励本质上是由控制台执行的命令，因此可以兼容任意插件。示例配置使用了以下命令：
- `eco give`
- `tokens give`
- `credits`
- `ocrates give`
- `ac give`
你可以替换为服务器上其他插件提供的命令。通过配置 `reward-display:`，界面中的奖励说明会与实际发放内容保持一致。
### 两种进度统计类型
- `PLAYTIME`：基于秒数的实时在线时间统计。
- `CROPS_HARVESTED`：按作物分别统计收获数量。
- 删除 `material:` 后，可将五种作物合并统计。
- 设置 `material: WHEAT` 等材料后，则会创建仅统计指定作物的独立进度链。
## 自定义锄头兼容层
这是本插件的核心特色之一。所有统计方式都可以在 config.yml 中进行配置，支持以下四种收获计数路径：
1. **普通且未取消的 `BlockBreakEvent`**
仅统计已经完全成熟的作物。
2. **被取消的方块破坏事件**
适用于由自定义锄头自行处理掉落物和重新种植的情况。
可通过 `count-cancelled-crop-breaks` 计数，并可选启用单 tick 验证：`cancelled-break-verify`。
3. **原版右键收获事件**
支持原版 `PlayerHarvestBlockEvent`。
4. **数据包锄头回退检测**
某些锄头完全不会触发事件，此时插件会监听作物掉落物进行识别。
相关配置为 `count-crop-drops`，并支持严格的作物表面检查：`require-crop-surface`，默认关闭。
此外还提供以下兼容与安全机制：
- **信任模式：** `trust-crop-break-events`，默认开启。适用于在事件触发前就已经完成重新种植的锄头。
- **去重窗口：** `dedupe-window-ms: 50`。某些锄头会针对同一株作物触发重复事件，该设置可以避免进度被重复增加。
- **调试日志：** /ms 会记录所有检测到的作物事件，包括已计数和被跳过的事件，并说明跳过原因，方便快速排查自定义锄头插件的兼容性。
- **种子永久禁止计数：** 种子材料始终位于拒绝列表中，即使配置文件中指定了种子材料，也不会被计入收获进度。
## GUI 系统
### 主菜单
- 使用分类按钮展示各类别内容。
- Lore 中显示每个类别的进度和可领取状态：`{progress}` / `{ready}`。
- 有待领取奖励时，可选择自动发光。
- 通过 `category-slots:` 自定义分类按钮位置。
- 支持自动分页。
### 分类页面
- 使用 54 格菜单。
- 里程碑状态分别以不同颜色显示：
- **LOCKED（已锁定）**：红色
- **IN PROGRESS（进行中）**：黄色
- **UNLOCKED（已解锁）**：绿色
- **CLAIMED（已领取）**：橙色
- 每个里程碑都支持完整自定义：
- 材料
- 名称
- 标签
- 进度条颜色
- Lore
### Lore 占位符
支持 15 个以上的 Lore 占位符：
`{level}`、`{name}`、`{type}`、`{status}`、`{description}`、`{current}`、`{target}`、`{unit}`、`{percent}`、`{bar}`、`{rewards}`、`{requires}`、`{player}`、`{page}`、`{pages}`、`{category}`
多行占位符在内容为空时会自动隐藏，不会留下多余空行。
### 查看者统计头像
- 使用查看者自己的皮肤。
- 显示已完成数量与总数量。
- 显示当前进度条。
- 显示可领取奖励数量。
- 有待领取奖励时自动发光。
### 菜单装饰
- 支持双色填充边框。
- 通过 `filler-accent:` 分别设置顶部、底部、侧边和角落。
- 提供返回按钮和翻页按钮。
- 菜单不会出现空白区域。
## 命令、权限与占位符
| 命令 | 权限 | 默认权限 | 功能 |
|---|---|---|---|
| /milestones | /ms | `milestones.use`（默认：`true`） | 打开菜单 |
| /ms | `milestones.admin` | 默认：`op` | 实时重载所有配置 |
| /ms | `milestones.admin` | 默认：`op` | 强制保存所有缓存中的进度 |
| /ms | `milestones.admin` | 默认：`op` | 切换作物事件控制台日志 |
### PlaceholderAPI
全部 7 个 PlaceholderAPI 占位符都支持离线玩家。插件会从磁盘延迟加载离线玩家数据。
```text
%milestones_progress_<id>%
%milestones_progress_raw_<id>%
%milestones_target_<id>%
%milestones_status_<id>%
%milestones_claimed_<category>%
%milestones_total_<category>%
%milestones_counter_<counter>%
```
## 性能与工程细节
### 性能优化
监听器在执行实际逻辑前，只需进行一次预计算集合查询。超过 99% 的方块破坏事件会立即结束，只有真正的收获事件才会进入里程碑处理引擎。
游玩时间统计采用轻量级 tick 机制，不会为每个里程碑单独保存进度。所有进度始终根据一个共享计数器实时计算。
### 数据安全
- 后台自动保存，默认间隔为 300 秒。
- 玩家退出时自动保存。
- 服务端关闭时执行同步保存。
- 支持 /ms 保存。
- 配置版本管理会将过期配置备份为 `.old` 文件，并重新生成兼容配置。
- 更新插件不会清除服务器已有的自定义设置。
### 配置细节
- 提供总开关 `enabled:`，可立即暂停计数、GUI 和奖励发放。
- `log-rewards` 可记录每次奖励发放的控制台审计信息。
- 全部界面支持十六进制颜色，例如 `&#FFAA00`。
- 不使用硬编码文本，界面内容均可配置。
### 可扩展性
插件提供公开、线程安全的只读 API：`MilestonesAPI`，方便其他插件读取里程碑数据。
里程碑类型系统也提供了扩展文档。若要添加“破坏方块数量”“击杀生物数量”等新类型，只需添加一个枚举常量和一条事件数据输入逻辑即可。
## 常见问题
### 能兼容我的经济、代币或箱子插件吗？
可以。奖励只是由控制台执行的命令，你可以使用经济、代币、钥匙箱或其他插件提供的命令。
### 能兼容自定义锄头吗？
可以。插件提供四种收获计数路径、事件去重机制，以及 /ms 调试功能，可用于确认自定义锄头的实际触发方式。
### 可以创建自己的分类吗？
可以。`milestones/` 目录中的每个 YAML 文件都可以作为一个独立分类。
### 重启后会丢失进度吗？
不会。插件提供多层持久化机制，包括后台自动保存、退出保存和服务端关闭时的同步保存。
### AFK 状态下会计算游玩时间吗？
游玩时间统计的是玩家真实在线时间。如果服务器使用了 AFK 插件，请将其 AFK 状态接入里程碑追踪器的 tick 逻辑。
### Spigot 分类应该选择什么？
推荐选择 **Miscellaneous（杂项）**。如果页面重点介绍奖励发放，可以选择 **Economy（经济）**；如果重点介绍统计功能，也可以选择 **Utility（实用工具）**。
## 下载与交流
- **Discord：** [https://discord.gg/KQcCjsGxQP](https://discord.gg/KQcCjsGxQP)
目前暂未提供图片和 GIF 预览。
[/MD]
## 简介
作者： Omega Plugins
资源分类： Java 版多人游戏 · 服务端插件
# 里程碑
> **作者：** Omega Plugins
> **资源分类：** Java 版多人游戏 · 服务端插件
里程碑是一款基于 YAML 配置的服务端插件，支持自定义进度链、奖励命令、游玩时间统计和农作物收获统计，并提供完整的图形化界面。
## 核心功能
### 无限可配置的里程碑链
每种里程碑类型对应 `milestones/` 目录中的一个 YAML 文件。添加文件后，执行 /ms 即可加载。
插件附带两个经过完善的示例：
- **Farming（农耕）**：共 112 个等级，包含以下称号链：
Farmer → Harvester → Cultivator → Harvest Lord → Agronomist → Crop Sovereign → Land Baron → Crop Emperor → Harvest Titan → Agrarian Overlord → Cosmic Cultivator → Harvest Deity → Stellar Sovereign → Void Harvester → Harvest God → Legend of the Harvest
- **Playtime（游玩时间）**：共 75 个等级。前 18 小时按小时递进，之后每 12 小时递进一次，直到 35 天。
### 链式解锁
通过 `requires:` 设置前置条件，只有领取前一个里程碑后，后续等级才会解锁。
领取某个等级后，聊天栏会提示下一个里程碑已经解锁。
### 奖励支持任意控制台命令
奖励本质上是由控制台执行的命令，因此可以兼容任意插件。示例配置使用了以下命令：
- `eco give`
- `tokens give`
- `credits`
- `ocrates give`
- `ac give`
你可以替换为服务器上其他插件提供的命令。通过配置 `reward-display:`，界面中的奖励说明会与实际发放内容保持一致。
### 两种进度统计类型
- `PLAYTIME`：基于秒数的实时在线时间统计。
- `CROPS_HARVESTED`：按作物分别统计收获数量。
- 删除 `material:` 后，可将五种作物合并统计。
- 设置 `material: WHEAT` 等材料后，则会创建仅统计指定作物的独立进度链。
## 自定义锄头兼容层
这是本插件的核心特色之一。所有统计方式都可以在 config.yml 中进行配置，支持以下四种收获计数路径：
1. **普通且未取消的 `BlockBreakEvent`**
仅统计已经完全成熟的作物。
2. **被取消的方块破坏事件**
适用于由自定义锄头自行处理掉落物和重新种植的情况。
可通过 `count-cancelled-crop-breaks` 计数，并可选启用单 tick 验证：`cancelled-break-verify`。
3. **原版右键收获事件**
支持原版 `PlayerHarvestBlockEvent`。
4. **数据包锄头回退检测**
某些锄头完全不会触发事件，此时插件会监听作物掉落物进行识别。
相关配置为 `count-crop-drops`，并支持严格的作物表面检查：`require-crop-surface`，默认关闭。
此外还提供以下兼容与安全机制：
- **信任模式：** `trust-crop-break-events`，默认开启。适用于在事件触发前就已经完成重新种植的锄头。
- **去重窗口：** `dedupe-window-ms: 50`。某些锄头会针对同一株作物触发重复事件，该设置可以避免进度被重复增加。
- **调试日志：** /ms 会记录所有检测到的作物事件，包括已计数和被跳过的事件，并说明跳过原因，方便快速排查自定义锄头插件的兼容性。
- **种子永久禁止计数：** 种子材料始终位于拒绝列表中，即使配置文件中指定了种子材料，也不会被计入收获进度。
## GUI 系统
### 主菜单
- 使用分类按钮展示各类别内容。
- Lore 中显示每个类别的进度和可领取状态：`{progress}` / `{ready}`。
- 有待领取奖励时，可选择自动发光。
- 通过 `category-slots:` 自定义分类按钮位置。
- 支持自动分页。
### 分类页面
- 使用 54 格菜单。
- 里程碑状态分别以不同颜色显示：
- **LOCKED（已锁定）**：红色
- **IN PROGRESS（进行中）**：黄色
- **UNLOCKED（已解锁）**：绿色
- **CLAIMED（已领取）**：橙色
- 每个里程碑都支持完整自定义：
- 材料
- 名称
- 标签
- 进度条颜色
- Lore
### Lore 占位符
支持 15 个以上的 Lore 占位符：
`{level}`、`{name}`、`{type}`、`{status}`、`{description}`、`{current}`、`{target}`、`{unit}`、`{percent}`、`{bar}`、`{rewards}`、`{requires}`、`{player}`、`{page}`、`{pages}`、`{category}`
多行占位符在内容为空时会自动隐藏，不会留下多余空行。
### 查看者统计头像
- 使用查看者自己的皮肤。
- 显示已完成数量与总数量。
- 显示当前进度条。
- 显示可领取奖励数量。
- 有待领取奖励时自动发光。
### 菜单装饰
- 支持双色填充边框。
- 通过 `filler-accent:` 分别设置顶部、底部、侧边和角落。
- 提供返回按钮和翻页按钮。
- 菜单不会出现空白区域。
## 命令、权限与占位符
| 命令 | 权限 | 默认权限 | 功能 |
|---|---|---|---|
| /milestones | /ms | `milestones.use`（默认：`true`） | 打开菜单 |
| /ms | `milestones.admin` | 默认：`op` | 实时重载所有配置 |
| /ms | `milestones.admin` | 默认：`op` | 强制保存所有缓存中的进度 |
| /ms | `milestones.admin` | 默认：`op` | 切换作物事件控制台日志 |
### PlaceholderAPI
全部 7 个 PlaceholderAPI 占位符都支持离线玩家。插件会从磁盘延迟加载离线玩家数据。
```text
%milestones_progress_<id>%
%milestones_progress_raw_<id>%
%milestones_target_<id>%
%milestones_status_<id>%
%milestones_claimed_<category>%
%milestones_total_<category>%
%milestones_counter_<counter>%
```
## 性能与工程细节
### 性能优化
监听器在执行实际逻辑前，只需进行一次预计算集合查询。超过 99% 的方块破坏事件会立即结束，只有真正的收获事件才会进入里程碑处理引擎。
游玩时间统计采用轻量级 tick 机制，不会为每个里程碑单独保存进度。所有进度始终根据一个共享计数器实时计算。
### 数据安全
- 后台自动保存，默认间隔为 300 秒。
- 玩家退出时自动保存。
- 服务端关闭时执行同步保存。
- 支持 /ms 保存。
- 配置版本管理会将过期配置备份为 `.old` 文件，并重新生成兼容配置。
- 更新插件不会清除服务器已有的自定义设置。
### 配置细节
- 提供总开关 `enabled:`，可立即暂停计数、GUI 和奖励发放。
- `log-rewards` 可记录每次奖励发放的控制台审计信息。
- 全部界面支持十六进制颜色，例如 `&#FFAA00`。
- 不使用硬编码文本，界面内容均可配置。
### 可扩展性
插件提供公开、线程安全的只读 API：`MilestonesAPI`，方便其他插件读取里程碑数据。
里程碑类型系统也提供了扩展文档。若要添加“破坏方块数量”“击杀生物数量”等新类型，只需添加一个枚举常量和一条事件数据输入逻辑即可。
## 常见问题
### 能兼容我的经济、代币或箱子插件吗？
可以。奖励只是由控制台执行的命令，你可以使用经济、代币、钥匙箱或其他插件提供的命令。
### 能兼容自定义锄头吗？
可以。插件提供四种收获计数路径、事件去重机制，以及 /ms 调试功能，可用于确认自定义锄头的实际触发方式。
### 可以创建自己的分类吗？
可以。`milestones/` 目录中的每个 YAML 文件都可以作为一个独立分类。
### 重启后会丢失进度吗？
不会。插件提供多层持久化机制，包括后台自动保存、退出保存和服务端关闭时的同步保存。
### AFK 状态下会计算游玩时间吗？
游玩时间统计的是玩家真实在线时间。如果服务器使用了 AFK 插件，请将其 AFK 状态接入里程碑追踪器的 tick 逻辑。
### Spigot 分类应该选择什么？
推荐选择 **Miscellaneous（杂项）**。如果页面重点介绍奖励发放，可以选择 **Economy（经济）**；如果重点介绍统计功能，也可以选择 **Utility（实用工具）**。
## 下载与交流
- **Discord：** [https://discord.gg/KQcCjsGxQP](https://discord.gg/KQcCjsGxQP)
目前暂未提供图片和 GIF 预览。
[/MD]