[MD]
# MythicQuests | 神话任务
## 特色功能
1. 限时任务（设定每个任务需要在多少时间内完成，否则视为任务失败）
2. 自定义PAPI 目标 （可用于其他插件的任务目标是否达成）
例如：玩家属性必要达到多少或者是等级达到目标才算完成该任务
3. 任务奖励可配置多选一（随机奖励）
4. 组队类型任务（需要MMOCore）
该任务需要几人共同完成，同样的队伍其他人也可以帮助完成该任务
5. 副本通关类型任务（指定要通关或者进入的副本才算任务完成目标，需要MythicDungeons）
可配合多阶段任务进行配置，任务阶段1 进入指定副本，任务阶段2 完成指定副本
6. 支持锻造、分解、鉴定、升级、镶嵌、合并、幻化、出售等作为任务目标（需要MMOItems与Coretools）
7. 配套的声望与任务点数
8. 赛季榜单（提供了完成任务时间的排名，可用于赛季设定）
9. 奖励支持 随机数量 （比如： 奖励牛排 1 - 10 的随机数，如果是命令则支持 支持 {random:1-10} 占位符）
10. 声望称号系统
11. 护送任务类型
12. 团本任务类型
---
## 功能总览
| 任务类型 | 支持的操作 | 集成的插件 |
|---|---|---|
| 方块 `BLOCK` | 放置 / 破坏 / 使用 / 互动 | 原生 + 自定义区域 |
| 物品 `ITEM` | 合成 / 熔炼 / 附魔 / 酿造 / 消耗 | 原生 |
| 物品 `ITEM` | 强化 / 鉴定 / 分解 / 重铸 / 宝石 / 合并 / 词缀 / 重随机 / 出售 / 幻化 | MMOItems、CoreTools |
| NPC `NPC` | 交付物品 / 与 NPC 交谈 | Citizens、MythicMobs、Typewriter |
| 击杀 `KILL` | 击杀生物（vanilla 或 MythicMob） | MythicMobs、MMOCore（组队共享） |
| 地点 `LOCATION` | 指定世界 / 命名区域 / 坐标+范围 / 进入副本 / **通关副本** | MythicDungeons、自定义区域 |
| 钓鱼 `FISH` | 钓起鱼（可指定鱼类/世界/区域） | 原生 |
| 剪羊毛 `SHEAR` | 剪羊毛（可指定实体/世界/区域） | 原生 |
| 耕地 `TILL` | 锄头耕地（可指定源方块/世界/区域） | 原生 |
| 种植 `PLANT` | 种植作物（可指定种子/世界/区域） | 原生 |
| 繁殖 `BREED` | 繁殖动物（可指定动物/世界/区域） | 原生 |
| 护送 `ESCORT` | 右键 NPC 开始护送，NPC 跟随到目标点完成 | Citizens / MythicMobs |
| 击杀掉落采集 `LOOT` | 拾取"来自击杀掉落"且匹配指定战利品（vanilla / MMOItems）的物品；可选来源怪约束（`mob` / `mythic_mob`） | 原生 + MythicMobs + MMOItems |
| 队伍共享总额 `party_shared` | 阶段目标按"队伍所有成员计数之和"判定，达标时全队一起结算（各领一份奖励） | MMOCore（组队） |
配套系统：
1. **任务点数**、**声望**（任务完成奖励，跨任务累积）
2. **声望称号**（按声望值动态显示称号，PAPI 调用）
3. **最佳完成用时排行榜**（用时最少第一）
4. 任务完成**全服公告**（可选）、**任务进度计分板**（可选）
5. **多类型奖励**（MMOItems/MythicMobs 物品 + MMOCore 经验/点数，可叠加，含随机多选一权重）、**队伍共享总额**（`party_shared`，全队合计达标一起结算）
6. **WorldGuard 区域**支持（region 可引用 WorldGuard 命名区域）
7. **任务前置/任务链**（前置任务 + 等级/点数/声望门槛解锁）
8. **周期刷新任务**（每日/每周重做）
9. **可完成次数**（默认完成 1 次后不可再接，可配置上限）
10. **失败惩罚**（限时超时扣除货币/声望/点数/职业经验/背包物品，可选）
11. **每日悬赏轮换**（每天从悬赏池随机抽取，`/mq daily` 查看）
12. **目标指引**（`guide` 目标点 + PAPI 方向/距离占位符）
13. **扩展完成条件**（物品栏/概率/时间段/星期/世界/区域/天气）、**多语言**（内置中/英，`language` 一键切换，提示无硬编码）。
---
## 安装
1. 将 `MythicQuests-1.0.0.jar` 放入服务器 `plugins/` 目录。
2. **完整重启服务器**（请勿使用 `/reload`，插件/数据初始化与软依赖挂接需要完整重启）。插件首次启动会生成 `config.yml` 与 `quests/` 示例任务。
3. 按需编辑 `quests/*.yml` 定义任务，编辑后执行 `/mq admin reload` 生效。
> **升级注意事项**：插件默认 `auto_generate_examples: true`（config.yml），每次启动自动补齐 `quests/` 中缺失的示例（已存在/你改过的文件保留不覆盖）。若你把该开关设为 `false`，则只在首次启动生成示例，之后删除/改名示例不会被回补，由你完全管理。
**运行要求**：Java 21+，Paper（或兼容 Bukkit/Spigot）。建议按需安装以下插件以启用对应集成：MythicMobs、MMOItems、MMOCore、MythicDungeons、Citizens、CoreTools、Typewriter、PlaceholderAPI、WorldGuard（区域）。
---
## 快速上手（从零到一）
**第一步：建一个最简单的任务**
在 `plugins/MythicQuests/quests/` 新建 `first.yml`：
```yaml
id: first_task
name: "第一次任务"
description: "击杀 5 只僵尸"
stages:
stage1:
type: KILL
entity: ZOMBIE
amount: 5
reward:
commands:
- "give %player% diamond 1"
message: "&a你完成了第一次任务！"
```
**第二步：让玩家能用命令**
插件默认玩家**无任何权限**，需要手动给玩家（或在权限组插件里）分配：
```
/mq admin 给权限在权限管理插件里配置
```
或在游戏内（OP/管理员）用 LuckPerms 等授予：
```
lp user <玩家> permission set mythicquests.use
```
**第三步：玩家接取 → 推进 → 结算**
```
/mq list 玩家查看可接取任务
/mq take first_task 接取任务（显示目标）
/mq progress 查看进度
击杀 5 只僵尸 自动推进
/mq complete first_task 手动结算（目标已达成时）
/mq done 查看已完成记录
/mq stats 查看任务点数/声望
```
**第四步（可选）**：开启计分板实时显示右侧进度：
`config.yml` 里 `scoreboard.enabled: true`，玩家用 `/mq sb [auto|on|off]` 切换显示模式。
任务创建/修改后执行 `/mq admin reload` 生效。更完整可复制的案例见下文「任务配置格式」各类型小节与内置 45 个示例任务。
---
## 命令（纯命令交互）
主指令 `/mythicquests`，简化指令 `/mq`。
| 命令 | 说明 | 权限 |
|---|---|---|
| `/mq help` | 查看命令帮助 | mythicquests.use |
| `/mq list` | 查看可接取与进行中的任务 | mythicquests.use |
| `/mq take <id>` | 接取任务 | mythicquests.use |
| `/mq progress [id]` | 查看当前任务进度 | mythicquests.use |
| `/mq complete [玩家] <id>` | 手动结算已达成目标的任务（玩家对自己可省略 `[玩家]`；控制台/代他人需填 `[玩家]`，代他人需 `mythicquests.admin`） | mythicquests.use |
| `/mq quit <id>` | 放弃任务 | mythicquests.use |
| `/mq done` | 查看已完成任务 | mythicquests.use |
| `/mq stats [玩家]` | 查看任务点数与声望 | mythicquests.use |
| `/mq top time <id> [数量]` | 该任务最快完成排行榜（用时最少第一） | mythicquests.use |
| `/mq top points [数量]` | 任务点数排行榜 | mythicquests.use |
| `/mq top reputation [数量]` | 声望排行榜 | mythicquests.use |
| `/mq daily` | 查看今日悬赏（每日从悬赏池随机轮换） | mythicquests.use |
| `/mq scoreboard [auto\|on\|off]` | 查看/设置任务计分板显示模式（自动/开启/关闭），简写 `/mq sb` | mythicquests.use |
| `/mq admin reload` | 重载配置、任务与语言文件 | mythicquests.admin |
| `/mq admin reset <玩家> <id\|*>` | 重置玩家进度 | mythicquests.admin |
| `/mq admin give <玩家> <id>` | 强制玩家接取任务 | mythicquests.admin |
| `/mq admin points <玩家> <add\|set> <数量>` | 给/设置玩家任务点数 | mythicquests.admin |
| `/mq admin rep <玩家> <add\|set> <数量>` | 给/设置玩家声望 | mythicquests.admin |
| `/mq admin time <玩家> <id> <add\|sub\|reset> [秒]` | 延长(add)/减少(sub)/重置为配置值(reset)任务限时 | mythicquests.admin |
| `/mq admin resettop <time\|points\|reputation>` | 重置全服排行榜 | mythicquests.admin |
| `/mq admin resettime <玩家> [任务id]` | 重置玩家最佳用时记录（省略 id=全部） | mythicquests.admin |
| `/mq admin resetplayer <玩家>` | **重置指定玩家全部数据**（任务进度 + 任务点数 + 声望 + 用时） | mythicquests.admin |
| `/mq admin resetall` | **重置全部玩家的全部数据**（任务进度 + 点数 + 声望 + 用时） | mythicquests.admin |
| `/mq admin debug <on\|off>` | 运行时开启/关闭调试日志（排查任务不计数/不触发等；等价于 `config.yml` 的 `debug` 开关） | mythicquests.admin |
别名：`/mq`。指令权限见下节。
## 权限
**默认所有玩家无任何任务权限**，必须授予相应权限才能使用命令：
| 权限 | 作用 | 默认 |
|---|---|---|
| `mythicquests.use` | 使用全部玩家命令（help/list/take/progress/complete/quit/done/stats/top/scoreboard） | **false（无）** |
| `mythicquests.admin` | 管理员命令（reload/reset/give/points/rep/time/resettop/resettime/resetplayer/resetall/debug） | op |
授予示例（LuckPerms）：`/lp group default permission set mythicquests.use true`，或对单个玩家 `/lp user <玩家> permission set mythicquests.use true`。
> **OP 与服务器控制台/后台不受限制**（`isOp` 或非玩家发送者直接放行），仅普通玩家需要 `mythicquests.use`。未授权玩家执行 `/mq` 会提示"无权限"；任务完成后发放点数/声望、计时与 PAPI 占位符不受权限影响（仅命令入口受限）。
> **同时进行任务数量上限**：`config.yml` → `max_active_quests`（默认 1，0=不限）。接取新任务前需先完成或放弃当前任务，达到上限会提示且拒绝接取。
---
## PlaceholderAPI 占位符（%mythicquests_*%）
需安装 PlaceholderAPI。`<id>` 为任务 ID，`<key>` 为子目标（缺省为 `main`）：
| 占位符 | 说明 | 使用案例（示例输出） |
|---|---|---|
| `%mythicquests_progress_<id>[_<key>]%` | 当前/总数，如 `3/10` | `%mythicquests_progress_example_kill_zombies%` → `3/10` |
| `%mythicquests_count_<id>[_<key>]%` | 当前数量 | `%mythicquests_count_example_kill_zombies%` → `3` |
| `%mythicquests_required_<id>[_<key>]%` | 所需数量 | `%mythicquests_required_example_kill_zombies%` → `10` |
| `%mythicquests_remaining_<id>[_<key>]%` | 剩余还需完成数量 | `%mythicquests_remaining_example_kill_zombies%` → `7` |
| `%mythicquests_percent_<id>[_<key>]%` | 完成百分比（整数） | `%mythicquests_percent_example_kill_zombies%` → `30` |
| `%mythicquests_progressbar_<id>%` | 进度条（字符与长度在 `lang.yml` 的 `progressbar` 段配置，默认 `█`/`░`/10 格） | `%mythicquests_progressbar_example_kill_zombies%` → `███░░░░░░░` |
| `%mythicquests_stage_<id>%` | 当前阶段/总阶段，如 `2/3`（进行到第几阶段） | `%mythicquests_stage_example_staged%` → `1/3` |
| `%mythicquests_stage_count_<id>%` | 当前阶段序号（1 起） | `%mythicquests_stage_count_example_staged%` → `1` |
| `%mythicquests_stage_total_<id>%` | 任务总阶段数 | `%mythicquests_stage_total_example_staged%` → `3` |
| `%mythicquests_stage_text_<id>%` | 当前阶段目标描述（含物品/NPC 显示名） | `%mythicquests_stage_text_example_kill_zombies%` → `击杀 10 只僵尸` |
| `%mythicquests_name_<id>%` | 任务名称 | `%mythicquests_name_example_kill_zombies%` → `剿灭僵尸` |
| `%mythicquests_id_<id>%` | 任务 ID | `%mythicquests_id_example_kill_zombies%` → `example_kill_zombies` |
| `%mythicquests_description_<id>%` | 任务描述 | `%mythicquests_description_example_kill_zombies%` → `在世界 world 击杀 10 只僵尸` |
| `%mythicquests_objective_<id>%` | 目标描述 | `%mythicquests_objective_example_kill_zombies%` → `击杀 10 只僵尸` |
| `%mythicquests_state_<id>%` | 状态（NOT_TAKEN/ACTIVE/COMPLETED/FAILED） | `%mythicquests_state_example_kill_zombies%` → `ACTIVE` |
| `%mythicquests_active_<id>%` | 是否进行中（true/false） | `%mythicquests_active_example_kill_zombies%` → `true` |
| `%mythicquests_completed_<id>%` | 已完成次数 | `%mythicquests_completed_example_kill_zombies%` → `2` |
| `%mythicquests_timeleft_<id>%` | 限时剩余秒数（阶段限时优先，任务限时兜底） | `%mythicquests_timeleft_example_timed%` → `180` |
| `%mythicquests_timeleft_fmt_<id>%` | 限时剩余时间（`分秒` 格式） | `%mythicquests_timeleft_fmt_example_timed%` → `3分0秒` |
| `%mythicquests_best_<id>%` | 该任务最佳完成用时（秒） | `%mythicquests_best_example_kill_zombies%` → `45` |
| `%mythicquests_best_fmt_<id>%` | 该任务最佳完成用时（分秒） | `%mythicquests_best_fmt_example_kill_zombies%` → `45秒` |
| `%mythicquests_points%` | 玩家任务点数 | `%mythicquests_points%` → `120` |
| `%mythicquests_reputation%` | 玩家声望 | `%mythicquests_reputation%` → `8` |
| `%mythicquests_title%` | 当前声望对应的称号（config.yml `titles` 段按门槛动态匹配，支持负数声望；无匹配返回空） | `%mythicquests_title%` → `&a新秀` |
| `%mythicquests_top_points_<rank>_name%` | 任务点数榜第 `rank` 名玩家名 | `%mythicquests_top_points_1_name%` → `Steve` |
| `%mythicquests_top_points_<rank>_value%` | 任务点数榜第 `rank` 名的点数 | `%mythicquests_top_points_1_value%` → `500` |
| `%mythicquests_top_reputation_<rank>_name%` | 声望榜第 `rank` 名玩家名 | `%mythicquests_top_reputation_2_name%` → `Alex` |
| `%mythicquests_top_reputation_<rank>_value%` | 声望榜第 `rank` 名的声望 | `%mythicquests_top_reputation_2_value%` → `66` |
| `%mythicquests_top_time_<id>_<rank>_name%` | 指定任务最快完成榜第 `rank` 名玩家名 | `%mythicquests_top_time_example_kill_zombies_1_name%` → `Steve` |
| `%mythicquests_top_time_<id>_<rank>_value%` | 指定任务最快完成榜第 `rank` 名的用时（秒） | `%mythicquests_top_time_example_kill_zombies_1_value%` → `12` |
| `%mythicquests_top_time_<id>_<rank>_fmt%` | 同上，用时格式化为"分秒" | `%mythicquests_top_time_example_kill_zombies_1_fmt%` → `12秒` |
| `%mythicquests_guide_distance_<id>%` | 与当前阶段目标指引点（`guide`）的水平距离（米）；`<id>` 可省略（取玩家第一个进行中任务） | `%mythicquests_guide_distance_example_guide%` → `123` |
| `%mythicquests_guide_direction_<id>%` | 目标指引点方向（北/东北/东/东南/南/西南/西/西北；跨世界显示`跨世界`，到达显示`到达`） | `%mythicquests_guide_direction_example_guide%` → `东` |
> 说明：案例中以 `example_kill_zombies`（击杀僵尸任务）与 `example_staged`（三阶段任务）、`example_timed`（限时任务）为例，示例输出为该占位符在某玩家的真实渲染结果。把 `<id>` 换成你自己的任务 ID 即可在消息、计分板、BetterHud、物品 lore 等任意支持 PAPI 的地方使用。
---
## 语言文件（多语言）
所有玩家可见文本**全部**集中在语言文件（**无硬编码**，任何提示都在语言文件里），支持 `{占位符}` 与颜色码（`&` 单色码 + `&#RRGGBB` RGB，1.16+ 生效），修改后 `/mq admin reload` 生效。
**多语言选择**：在 `config.yml` 设置 `language`（默认 `zh-CN` 中文）：
- 中文：`language: zh-CN`（默认，使用 `lang.yml`）。
- 英文：`language: en-US`（自动加载内置的 `lang_en-US.yml`）。
- 自定义语言：新建 `plugins/MythicQuests/lang_<语言>.yml` 并设 `language: <语言>`，插件自动读取。
- **缺键自动回退**：所选语言文件缺失某个键时，自动回退到默认中文 `lang.yml` 补齐，任何语言都不会空白。
`lang.yml`（中文，默认）与 `lang_en-US.yml`（英文）结构一致。可配置内容按段组织：
| 段 | 可配置内容 |
|---|---|
| `prefix` | 所有命令消息的前缀（默认 `&8[&6任务&8]`） |
| `help.*` | `/mq help` 帮助的每一行 |
| `common.*` | 通用提示（仅玩家、无权限、未知子命令、找不到玩家、用法、未进行任务、全部任务） |
| `scoreboard.*` | 计分板模式提示（当前/无效/已设置/模式文本） |
| `daily.*` | 每日悬赏（标题/条目/空/状态文本） |
| `time.*` | 限时剩余显示（正常/警告/格式） |
| `condition.*` | 完成条件描述（职业/副职业/等级/副本/物品/概率/时间段/星期/世界/区域/天气/未知）与阻塞提示 |
| `list.*` | 任务列表（进行中/可接取/已失败/无任务/各条目） |
| `progress.*` | 进度查看（当前阶段/已完成/未解锁/无任务/标题） |
| `stage.completed` | 阶段完成并推进提示 |
| `quest.failed` | 限时未完成任务失败提示 |
| `take.*` | 接取（不存在/无权限/已进行/冷却/上限/前置/门槛/刷新等待/接取条件未满足/成功/目标） |
| `quit.*` | 放弃任务提示 |
| `complete.*` | 结算（未进行/未达成/成功/点数声望统计） |
| `stats.*` | 我的任务点数与声望 |
| `top.*` | 排行榜（三种类型标题/空/条目/用法/未知/类型名） |
| `admin.*` | 管理员操作（重载/重置/给点/限时/重置榜/调试）的提示与用法 |
| `npc.*` | NPC 交谈/交付提示 |
| `announce` | 任务完成全服公告（`enabled` 开关 + `format` 模板） |
| `progressbar.*` | **PAPI 进度条**（`filled` 已完成字符 + `empty` 未完成字符 + `length` 总格数，`%mythicquests_progressbar_<id>%`） |
| `done.*` | 已完成任务列表 |
| `admin.*` | 全部管理命令反馈（重置/给点/声望/限时/榜单等） |
| `npc.*` | NPC 交付（缺物品/交付成功） |
| `announce.*` | **任务完成全服公告**（`enabled` 开关 + `format` 格式，可用 `{player}`/`{name}`/`{id}`） |
| `progressbar.*` | **PAPI 进度条**（`filled` 已完成字符 + `empty` 未完成字符 + `length` 总格数，`%mythicquests_progressbar_<id>%`） |
> 说明：任务/阶段的自定义奖励消息（`reward.message`）与完成公告（`completeMessage`）是**任务特有内容**，在任务 yml 里配置，会原样显示（支持颜色码，不强制加前缀）；语言文件负责所有系统固定提示与公告模板。
---
## 任务配置格式
每个任务一个 YAML 文件，放在 `quests/` 目录。**可在 `quests/` 下新建子文件夹分类管理任务**（如 `quests/主线/`、`quests/悬赏/`），插件会递归读取所有子目录下的任务文件。**统一采用多阶段 `stages` 格式**（任务按顺序推进，完成当前阶段自动进入下一阶段，全部阶段完成才结算发放奖励）。
插件自带 45 个示例任务（jar 内 `quests/`，首次运行时复制到数据目录），覆盖全部任务类型与可选功能，每个示例文件顶部注释写明了功能与可用选项，可直接参考/复制修改：
| 类型 | 示例文件 | 说明 |
|---|---|---|
| 方块 | `example_block_place / _break / _use / _interact` | 放置 / 破坏 / 使用 / 互动，可限定材质、世界、区域 |
| 物品·原版 | `example_item_craft / _smelt / _enchant / _brew / _consume` | 合成 / 熔炼 / 附魔 / 酿造 / 消耗 |
| 物品·MMO工艺 | `example_item_upgrade / _identify / _deconstruct / _reforge / _gemstone / _merge / _modifiers / _reroll / _sell / _transmog` | 强化 / 鉴定 / 分解 / 重铸 / 宝石 / 合并 / 词缀 / 重随机 / 出售 / 幻化（MMOItems 与 CoreTools 工艺站） |
| NPC | `example_npc_talk / _deliver` | 交谈（可绑 Typewriter）/ 交付物品（支持多个、vanilla 与 MMOItems、自定义显示名） |
| 击杀 | `example_kill_zombies / _multi` | 单目标（原版/ MythicMob）/ 多目标各自计数，可组队共享 |
| 地点 | `example_location / _dungeon_finish / _dungeon_conditions` | 到达坐标/区域 / 通关副本 / 完成条件（职业、等级、组队、副本） |
| PAPI | `example_papi` | 按 PlaceholderAPI 占位符值判定（等于/不等于/大于/小于/大于等于/小于等于，数值与文字自适应） |
| 生活 | `example_fishing / _shear / _till / _plant / _breed / _farming` | 钓鱼 / 剪羊毛 / 耕地 / 种植 / 繁殖（可指定目标与限定） |
| 任务链/刷新 | `example_chain_a / _chain_b` | 前置任务解锁（chain_b 需先完成 chain_a）+ 点数门槛 + 每日刷新（refresh: daily） |
| 每日悬赏/指引/条件 | `example_daily / _guide` | 每日悬赏（daily: true 加入轮换池 + ITEMS 条件）/ 目标指引（guide + PAPI 方向距离 + WORLD/REGION/TIME 等条件） |
| 高级 | `example_staged / _timed / _display / _rewards / _manual / _reward_random` | 多阶段+阶段描述/奖励 / 限时+点数声望 / 自定义显示名 display / 多类型叠加奖励（物品+经验+点数）/ 手动完成模式（manual_complete，/mq complete 确认）/ 随机多选一奖励（reward.random 按权重） |
```yaml
id: 任务唯一ID # 必填，命令用
name: "任务名称"
description: "任务描述"
permission: optional.node # 可选：接取所需权限
cooldown: 60 # 可选：完成后再次接取的冷却（秒），0=无
time-limit: 900 # 可选：任务总限时（秒），接取开始计时，超时未完成则任务失败
manual_complete: false # 可选：true=手动完成，false（默认）=达成目标自动完成
# 手动完成：目标全部达成后不自动结算，需玩家执行 /mq complete <id> 手动确认后才发放任务奖励
# ---- 任务链前置与门槛（均可选） ----
prerequisites: # 可选：需先完成这些任务（全部完成才可接取本任务），实现任务链解锁
- chain_a
- beginner_quest
min-level: 10 # 可选：需要 MMOCore 职业等级 ≥ 10 才能接取（需装 MMOCore；未装时该门槛自动忽略）
min-points: 50 # 可选：需要任务点数 ≥ 50 才能接取
min-reputation: 20 # 可选：需要声望 ≥ 20 才能接取
# ---- 周期刷新（可选） ----
refresh: daily # 可选：none（默认，不刷新）/ daily（每日）/ weekly（每周）
# 完成后过刷新周期方可再次接取（每日=24小时、每周=7天），用于可重复/日常任务
# ---- 可完成次数（可选） ----
max_completions: 3 # 可选：该任务玩家最多可完成次数（默认 1：完成过则无法再接取）。
# 配合 refresh 时每刷新周期重新计数（默认 1 = 每天/每周可做 1 次）；无 refresh 则为永久总次数上限。
# ---- 失败惩罚（可选） ----
# 任务失败（如 time-limit 超时）时扣除指定或随机数量的资源；去掉整个 fail 段则失败不惩罚。
fail:
points: 5 # 扣任务点数（"5" 或随机区间 "3-8"）
reputation: "1-3" # 扣声望（指定或随机）
currency: "10-20" # 扣货币（需 Vault，未装则尝试经济命令）
class_exp: # 扣职业经验（MMOCore，命令扣减负值）
class: KNIGHT
amount: "10-20"
subclass_exp: # 扣副职业经验（MMOCore）
class: ARCHER
amount: 5
items: # 从背包扣除物品（指定或随机数量）
- material: IRON_INGOT
amount: "1-3"
- mmo: { type: GEMS, id: LUCK_GEM }
amount: 1
stages:
stage1:
display: "剿灭骷髅守卫" # 可选：自定义显示名/文本（任意任务类型通用，优先级最高，替代自动生成的目标显示）
description: "剿灭骷髅守卫" # 可选：阶段自定义描述（否则自动生成）
time-limit: 180 # 可选：本阶段限时（秒），进入本阶段计时，超时则任务失败
reward: # 可选：本阶段完成奖励
commands:
- "give %player% cooked_beef 3"
message: "&a阶段一完成！"
type: KILL # 每阶段必须指定类型与对应参数
entity: SKELETON
amount: 5
stage2:
type: ITEM
operation: craft
material: DIAMOND_SWORD
amount: 1
stage3:
type: LOCATION
region: example_city
amount: 1
reward:
commands: # 完成时由控制台执行的命令
- "give %player% diamond 1"
- "!async mmocore giveclassxp %player% KNIGHT 50" # !async 前缀=异步执行
message: "&a完成提示"
points: 100 # 可选：完成获得的任务点数（跨任务累积）
reputation: 5 # 可选：完成获得的声望
```
- **多阶段**：`stages` 段下每个子项是一个阶段，需含自己的 `type` 与对应参数。玩家进度会显示所有阶段；当前阶段完成后自动推进；全部阶段完成才发奖励。多阶段任务可混合不同类型阶段（如先击杀、后合成、再抵达）。示例见 `quests/example_staged.yml`。
- **限时任务**：任务级 `time-limit`（接取计时）或阶段级 `time-limit`（进入本阶段计时），任一超时未完成则该任务失败（状态 FAILED，可在 `/mq list` 看到并重新接取）。
- **阶段描述/奖励**：每个阶段可配 `description`（自定义显示）与 `reward`（阶段完成奖励命令+消息），均为非必填。
- **点数/声望**：`reward` 段可配 `points` 与 `reputation`（均非必填），任务完成时发放并跨任务累积，用 `/mq stats` 查看、`/mq top` 排榜。
- **多类型奖励（可叠加）**：`reward.items` 段可配置**多个额外奖励条目**，除命令外还支持 MMOItems 物品、MythicMobs 物品、MMOCore 职业/副职业经验/属性/技能点/属性点，与 `commands`/`points`/`reputation` 叠加发放（任务级与阶段级 reward 都支持）。格式见下文「多类型奖励」。物品发放**有保障**：发放失败自动重试一次，背包已满时提示"部分物品奖励可能已掉落在地上"（掉落由各插件 API 处理）。
- **最佳用时**：每次完成任务自动记录耗时，仅首次完成或更快时更新，作为该任务用时排行榜依据。
- **完成条件**：阶段可配 `conditions`（非必填）。这不是接取条件，而是"必须满足条件才能完成/推进本阶段"——目标数量达标后若条件不满足则阻塞并提示，满足后才结算推进。支持职业/副职业/职业等级/副本单人/副本组队人数，见下方"完成条件"节。
奖励命令占位符：`%player%`（玩家名）、`%player_uuid%`。
### 多类型奖励（reward.items）
任务级与阶段级的 `reward` 段都可配 `items` 列表，每项是一种额外奖励，**可任意多个叠加**。完整示例见 `quests/example_rewards.yml`：
```yaml
reward:
commands: # 原有：命令奖励（控制台执行，支持 %player% 与 !async 前缀）
- "give %player% diamond 1"
message: "&6&l奖励已发放！"
points: 100 # 原有：任务点数
reputation: 10 # 原有：声望
items: # 新增：额外奖励条目（可多个）
reward_mmo: # MMOItems 物品
kind: MMOITEMS
mmo:
type: SWORD
id: CUTLASS
amount: 1
reward_mythic: # MythicMobs 物品/掉落物
kind: MYTHICMOBS
item: MythicSword # MythicMobs 物品 ID
amount: 1
reward_classxp: # MMOCore：指定职业经验
kind: MMOCORE
sub: CLASS_XP
class: KNIGHT
amount: 500 # 经验值
reward_skill: # MMOCore：技能点
kind: MMOCORE
sub: SKILL_POINTS
amount: 2
```
**`kind` 与参数**：
| kind | 用途 | 参数 |
|---|---|---|
| `MMOITEMS` | 发放一个 MMOItems 物品 | `mmo.type` + `mmo.id` + `amount` |
| `MYTHICMOBS` | 发放一个 MythicMobs 物品/掉落物 | `item`（物品 ID）+ `amount` |
| `MMOCORE` | 给 MMOCore 各类奖励 | `sub` 指定子类型（见下） |
**`MMOCORE` 的 `sub` 子类型**：
| sub | 含义 | 参数 |
|---|---|---|
| `CLASS_XP` | 指定职业经验 | `class`（职业名）+ `amount`（经验值） |
| `SUBCLASS_XP` | 指定副职业经验 | `subclass`（副职业名）+ `amount` |
| `SKILL_POINTS` | 技能点 | `amount`（点数） |
| `ATTRIBUTE_POINTS` | 属性点 | `amount`（点数） |
| `ATTRIBUTE` | 指定属性数值 | `attribute`（属性名）+ `amount`（数值） |
> 实现说明：MMOItems / MythicMobs 物品与 MMOCore 经验/点数优先通过插件 API 发放（反射），若对应 API 未命中会自动回退为执行插件命令；`SUBCLASS_XP` 与 `ATTRIBUTE` 因 API 复杂，主要走命令（命令名 `mmocore ...`）。若某条命令名与你服务器的 MMOCore 版本不一致，建议改用 `commands` 直接写你的命令。
### 随机多选一奖励（reward.random，可选）
配置多个奖励候选项，完成时**按权重"多选一"随机发放其中一个**（权重越大被抽中概率越高）。不配置则保持原行为（固定奖励全部发放），完全可选。完整示例见 `quests/example_reward_random.yml`：
```yaml
reward:
message: "&a任务完成！" # 固定完成提示（可保留）
random: # 随机多选一：以下候选项按权重抽一个发放
- weight: 50 # 相对权重（>=1，越大越容易抽中）→ 50/50+30+20 = 50%
commands:
- "give %player% diamond 1"
message: "&e你抽中了钻石！"
points: 5 # 该项额外加 5 任务点数
reputation: 0 # 该项额外加 0 声望
- weight: 30 # → 30% 概率
commands:
- "give %player% emerald 5"
items: # 该项也可带 MMOItems/MythicMobs/MMOCore 条目（同 reward.items 格式）
item1:
kind: MMOCORE
sub: CLASS_XP
class: KNIGHT
amount: 100
- weight: 20 # → 20% 概率
commands:
- "give %player% paper 1"
message: "&7手气不佳，抽到一张纸条…"
```
**规则**：
- 每个候选项含 `weight` + 内部奖励（`commands` / `items` / `message` / `points` / `reputation`），随该项一起发放；
- 抽中概率 = 该项 `weight` ÷ 所有项 `weight` 之和；
- 与固定 `commands`/`items`/`points`/`reputation` **可叠加**（固定部分照常发放，另抽一份随机）；若只想要随机奖励，则不写固定部分即可；
- 阶段级 `reward` 暂不支持 `random`（如需阶段随机可后续扩展）。
### 奖励数量随机（amount 区间 / 命令 {random}）
奖励数量支持**随机区间**，均取整数（不产生小数）：
- **奖励条目 `amount`**：写 `"min-max"` 即每次在 min~max 间随机取一个整数（可用于 `MMOITEMS`/`MYTHICMOBS` 物品数量、`MMOCORE` 经验/点数）。例如：
```yaml
items:
reward_mmo:
kind: MMOITEMS
mmo:
type: SWORD
id: CUTLASS
amount: "1-3" # 每次随机给 1~3 把
```
- **命令 `commands` 数量**：在命令里用 `{random:min-max}` 占位符，执行时替换为随机整数。例如"牛排 1~10 个"：
```yaml
commands:
- "give %player% beef {random:1-10}"
```
两种方式都可叠加在固定奖励、随机多选一（`reward.random`）候选项里使用；区间倒置（如 `10-1`）会自动交换。
### 完整案例：一个整合全部功能的成就任务
下面这个任务把多阶段、自定义显示名、任务级/阶段级限时、阶段奖励、完成条件、点数声望、交付多物品全部用上，可直接复制参考：
```yaml
id: epic_adventure
name: "史诗冒险"
description: "一场贯穿山谷的史诗冒险"
permission: mythicquests.epic # 可选：接取所需权限
cooldown: 3600 # 可选：完成后再接冷却（秒）
time-limit: 1800 # 可选：任务总限时（秒），接取计时，超时失败
stages:
# 阶段一：击杀（自定义显示名 + 限时 + 阶段奖励）
stage1:
display: "讨伐山谷狼群"
time-limit: 600 # 本阶段限时，进入本阶段计时
type: KILL
mythic_mob: ValleyWolf
amount: 10
reward:
commands:
- "give %player% cooked_beef 5"
message: "&a狼群已剿灭，继续前进！"
# 阶段二：合成（物品任务）
stage2:
type: ITEM
operation: CRAFT
material: DIAMOND_SWORD
amount: 1
# 阶段三：交付（多物品，每个物品独立进度 + 自定义物品显示名）
stage3:
type: NPC
action: DELIVER
mythic_mob: Blacksmith
display: "把战利品交给铁匠"
deliver:
item1:
display: "狼皮" # 自定义物品显示名
material: RABBIT_HIDE
amount: 5
item2:
display: "狼牙"
mmo:
type: MATERIAL
id: WOLF_TOOTH
amount: 3
amount: 1
# 阶段四：抵达 + 完成条件（需组队 2 人才能完成）
stage4:
type: LOCATION
world: world
x: 100
y: 64
z: -200
radius: 5
amount: 1
conditions:
cond1:
type: DUNGEON_PARTY
dungeon: MyDungeon
players: 2
reward:
commands:
- "give %player% netherite_ingot 1"
- "!async mmocore giveclassxp %player% KNIGHT 500"
message: "&6&l你完成了史诗冒险！"
points: 100
reputation: 10
```
### 1) 方块任务 `BLOCK`
```yaml
stages:
stage1:
type: BLOCK
action: PLACE # PLACE 放置 | BREAK 破坏 | USE 使用 | INTERACT 互动
material: STONE # 可选：指定材质（省略=任意方块）
world: world # 可选：限制世界
region: city # 可选：限制在命名区域内（见 config.yml regions）
amount: 50
```
- `USE`：点击门/按钮/箱子/工作台等**可交互**方块（空手开门等可交互也计）
- `INTERACT`：**手持物品**右击任意方块（空手右键不计）
### 2) 物品任务 `ITEM`
```yaml
stages:
stage1:
type: ITEM
operation: CRAFT # 见下方操作列表
material: DIAMOND_SWORD # 方式一：vanilla 材质（省略=任意）
# custom-model-data-float: 1.5 # 可选：浮点型自定义模型数据（1.21.4+ CustomModelData float），物品需匹配该值
# mmo: # 方式二：MMOItems 物品（与 material 二选一）
# type: SWORD
# id: CUTLASS
amount: 1
```
操作列表：`CRAFT` 合成 · `SMELT` 熔炼 · `ENCHANT` 附魔 · `BREW` 酿造 · `CONSUME` 消耗 · `UPGRADE` 强化/升级 · `IDENTIFY` 鉴定 · `DECONSTRUCT` 分解 · `REFORGE` 重铸 · `GEMMING` 宝石镶嵌/拔出 · `MERGE` 物品合并 · `MODIFIERS` 附加词缀 · `REROLL` 重随机属性 · `SELL` 出售物品 · `TRANSMOG` 外观幻化
- 原生操作（合成/熔炼/附魔/酿造/消耗）通过 Bukkit 事件监听。
- **MMO 工艺操作**（强化/鉴定/分解/重铸/宝石/合并/词缀/重随机/出售/幻化）监听 **MMOItems 原生事件** 与 **CoreTools 工艺站通用事件**（`StationConfirmEndEvent/StationConfirmEvent`，按 `getStation()` 站名映射到操作）：装了 MMOItems 或 CoreTools，玩家在对应工艺台/站内完成操作即计数；两者都没装时这些操作的任务无法触发（其余任务不受影响）。双来源对同一操作的时间去重，避免重复计数。
- 配置里可加 `material`/`mmo` 限定被操作物品（省略则任意物品；出售/合并等站不暴露具体物品，限定物品时以 MMOItems 原生事件为准）。
- 每个 MMO 工艺操作都有独立示例：`example_item_upgrade / _identify / _deconstruct / _reforge / _gemstone / _merge / _modifiers / _reroll / _sell / _transmog`。
### 3) NPC 任务 `NPC`
> 说明：配置里 `mythic_mob` 填的是 MythicMob **内部名**；显示（任务描述/计分板）时若 MythicMobs 为该生物配置了显示名（DisplayName），会自动用显示名替换内部名展示。`DELIVER` 支持多个交付物品，每个物品作为独立子目标，计分板分别显示各自进度（如 `牛肉: 0/5`、`宝石: 0/3`）；交付物品名称同样显示**显示名**（原版物品用内置中文常用名、MMOItems 物品用其显示名，未收录/解析失败时回退材质名或 `type:id`）。**自定义显示名**：可在任务里对 NPC 和每个交付物品用 `display` 字段手动设置名称，优先级最高（设置后不再自动解析），适合插件解析不到或想用自定名称的场景。
```yaml
stages:
stage1:
type: NPC
action: DELIVER # TALK 交谈 | DELIVER 交付物品
mythic_mob: Blacksmith
display: "铁匠" # 可选：自定义 NPC 显示名
deliver:
item1:
display: "新鲜牛肉" # 可选：自定义物品显示名
material: BEEF
amount: 5
amount: 1
```
```yaml
stages:
stage1:
type: NPC
action: TALK # TALK 交谈 | DELIVER 交付物品
citizens_id: 5 # Citizens NPC ID（可选，与 mythic_mob 可并存）
mythic_mob: Merchant # MythicMobs 的 MythicMob 名（可选）
amount: 1
# 交谈时绑定 Typewriter 对话进度（可选）
typewriter:
dialogue_id: "merchant_intro" # 右键 NPC 时触发的 Typewriter 对话/entry
fact: "Talk Quest Fact" # 需要达到的 Typewriter fact 名
fact_value: 1 # fact 达到该值即视为交谈完成
# 交付时要求的物品（多个条目需全部满足才可交付）
deliver:
item1: { material: BEEF, amount: 5 }
item2:
mmo: { type: GEMS, id: SAPPHIRE }
amount: 3
```
- **交谈 TALK**：右键目标 NPC。若绑定 `typewriter.fact`，触发对话并每 0.5s 轮询 fact，达到 `fact_value` 后计入；Typewriter 不可查询或未绑定 fact 时回退为"右键即完成"。
- **交付 DELIVER**：右键 NPC 时检查背包物品（支持 vanilla 与 MMOItems），满足则自动扣除并计入。
### 4) 击杀任务 `KILL`
单目标（vanilla 实体或 MythicMob）：
```yaml
stages:
stage1:
type: KILL
entity: ZOMBIE # vanilla 实体类型（可选，与 mythic_mob 二选一）
mythic_mob: ZombieKing # MythicMobs 的 MythicMob 名（可选）
amount: 10
party: true # MMOCore 组队共享：队伍任一成员击杀，全队计入
```
**MythicMob 通配击杀**：`mythic_mob` 支持 `"*"`（任意 MythicMob），并可加 `min_level`（等级下限）与 `tag`（标签）进一步过滤，适合针对"一类精英/BOSS"做任务而无需逐个列名字：
```yaml
stages:
stage1:
type: KILL
mythic_mob: "*" # 任意 MythicMob
min_level: 50 # 只算等级 ≥ 50 的（可选）
tag: "boss" # 只算带 boss 标签的（可选，忽略大小写）
amount: 3
```
> 通配同样可用在 `targets` 多目标里（`target1` 等每个目标都可配 `min_level` / `tag`）。`"*"` 或普通名字 + `min_level`/`tag` 组合都支持：名字精确匹配 **且** 等级达标 **且** 标签命中才算一次击杀。MythicMob 等级/标签需 MythicMobs 提供（反射读取 ActiveMob 等级与标签），解析失败时对应条件视为不满足。
**多目标**：用 `targets` 列表可任意设定多个击杀目标，各自独立计数，全部达标后该阶段完成：```yaml
stages:
stage1:
type: KILL
targets:
target1:
mythic_mob: demo1 # MythicMob 名（与 entity 二选一）
amount: 10
target2:
entity: ZOMBIE # vanilla 实体类型（与 mythic_mob 二选一）
amount: 5
party: true # MMOCore 组队共享（可选）
```
> **组队共享的两种方式**：
> - `party: true`（KILL 目标内）：队伍任一成员击杀，**全队各计各的**进度（每人各自凑满自己的 amount）。
> - `party_shared: true`（任意累计型阶段的通用选项，见下文）：本阶段按**队伍所有成员计数之和**判定完成，全队合计凑满 amount，达标时**全队一起结算**（每人领一份奖励）。适合"团队副本/世界 Boss 级目标"。
### 5) 击杀掉落采集任务 `LOOT`
玩家**拾取一个来自击杀掉落的、匹配指定战利品**的物品才计数。要点：必须是击杀掉落的物品（合成/交易/刷新等不计；战利品被抢或掉虚空也不计），且可选来源怪约束。
```yaml
stages:
stage1:
type: LOOT
material: SKELETON_SKULL # 目标战利品（vanilla 材质）；与 mmo 二选一
# mmo: {type: SWORD, id: 狼牙} # 或用 MMOItems 类型+ID 指定战利品
mob: ZOMBIE # 可选：来源怪约束（实体类型名，忽略大小写）；不配置则任意击杀掉落命中该物品即可
# mythic_mob: BossDragon # 可选：来源 MythicMob 名（比 mob 更精确）
amount: 3
```
- `material` / `mmo{type,id}`：目标战利品，二选一；都不配置则任意击杀掉落物都计。
- `mob` / `mythic_mob`：可选来源怪约束，不配置则不限来源；配置后需来源怪匹配才计数。
- 实现：通过 `EntityDropItemEvent` 记录每个掉落物 → 来源怪，玩家 `InventoryPickupItemEvent` 拾取时核对命中。
### 6) 地点任务 `LOCATION`（含副本通关）
```yaml
stages:
stage1:
type: LOCATION
world: world # 必填：限制世界
x: 100 # 方式一：坐标点
y: 64
z: -200
radius: 5 # 到达半径
region: city # 方式二：到达命名区域
mythic_dungeon: MyDungeon # 方式三：进入指定 MythicDungeons 副本实例
dungeon_finish: MyDungeon # 方式四：通关指定 MythicDungeons 副本（完成后计入）
amount: 1
```
四种位置条件可叠加（全部满足才完成）；仅填 `world` 时表示"到达该世界即完成"。
- `mythic_dungeon`：玩家进入指定副本实例即计数
- `dungeon_finish`：玩家**通关**指定副本时计数（通过 MythicDungeons 完成事件监听，副本名支持精确或包含匹配）
### 6) 钓鱼 `FISH`
```yaml
stages:
stage1:
type: FISH
material: COD # 可选：指定鱼类（COD/SALMON/TROPICAL_FISH/PUFFERFISH...），省略=任意
world: world # 可选
region: lake # 可选
amount: 5
```
### 7) 剪羊毛 `SHEAR`
```yaml
stages:
stage1:
type: SHEAR
entity: SHEEP # 可选：指定实体类型（默认任意可剪羊毛实体）
world: world # 可选
region: farm # 可选
amount: 2
```
### 8) 耕地 `TILL`
```yaml
stages:
stage1:
type: TILL
material: DIRT # 可选：指定被耕的源方块（DIRT/GRASS_BLOCK/COARSE_DIRT/ROOTED_DIRT，省略=任意可耕方块）
world: world # 可选
region: farm # 可选
amount: 3
```
### 9) 种植作物 `PLANT`
```yaml
stages:
stage1:
type: PLANT
material: WHEAT_SEEDS # 可选：指定种子（WHEAT_SEEDS/CARROT/POTATO/BEETROOT_SEEDS...），省略=任意作物
world: world # 可选
region: farm # 可选
amount: 3
```
### 10) 繁殖动物 `BREED`
```yaml
stages:
stage1:
type: BREED
entity: COW # 可选：指定动物类型（COW/SHEEP/PIG/CHICKEN...，省略=任意）
world: world # 可选
region: farm # 可选
amount: 2
```
以上 5 类生活任务均可用于多阶段 `stages`，并可叠加世界/区域限定。示例见 `example_fishing.yml`、`example_farming.yml`。
### 11) 护送 NPC 任务 `ESCORT`
玩家**右键**目标 Citizens NPC（原型）开始护送；插件会从原型**克隆出一个临时护送 NPC**（spawn 到玩家附近），临时 NPC 跟随玩家移动，玩家把它带到阶段目标点（`guide`，必填）即完成本阶段。
```yaml
stages:
stage1:
type: ESCORT
npc_id: 5 # 原型 Citizens NPC ID（右键它触发护送）
radius: 3 # 到达目标点 3 格内即完成（默认 3）
max_distance: 40 # 玩家离护送目标超过 40 格则中止（默认 40）
guide: # 护送目标点（必填）
world: world
x: -100
y: 60
z: 200
```
**行为要点**：
- **临时克隆**：每个玩家护送时各自克隆一个临时 NPC，原型 NPC 保持原位不动。多名玩家可同时护送同一原型，各自副本互不冲突。
- **动态速度**：临时 NPC 的移动速度 = 玩家当前移动速度，并在跟随过程中**持续同步**（玩家加速/疾跑时 NPC 同步提速）。
- **结束销毁**：任务**完成**时临时 NPC 被销毁；**失败**（目标消失 / 玩家死亡 / 玩家下线 / 距离超限）时同样被销毁，右键原型可重新开始。
- 玩家**掉线 / 离开服务器视为护送失败**，临时 NPC 一并清除，不残留、无卡顿。
- `mythic_mob`（与 `npc_id` 二选一）时护送 MythicMob 本体（无法克隆，不销毁，由玩家带路到点）。
- 示例见 `example_escort.yml`。
### 12) PAPI 任务目标 `PAPI`
读取某个 PlaceholderAPI 占位符的值，与设定值比较，**条件成立即完成本阶段**（条件型，不累积计数）。
```yaml
stages:
stage1:
type: PAPI
placeholder: "%mmocore_level%" # 要读取的占位符（任意 PAPI 占位符）
operator: ">=" # 比较运算符（见下）
value: "5" # 比较值（数字或文字）
```
**operator 可用写法**（英文/符号/中文别名均可）：
| 语义 | 写法 |
|---|---|
| 等于 | `=`、`==`、`equals`、`等于` |
| 不等于 | `!=`、`<>`、`notequals`、`不等于` |
| 大于 | `>`、`greater_than`、`大于` |
| 小于 | `<`、`less_than`、`小于` |
| 大于等于 | `>=`、`greater_equal`、`大于等于` |
| 小于等于 | `<=`、`less_equal`、`小于等于` |
**类型自适应**：插件先剥离颜色码并去掉首尾空白，再判断——
- **纯数值**（占位符值与 `value` 都能解析为数字，支持负数/小数/千分位）→ **数值比较**，全部 6 个运算符均有效；
- **文字**（如 `KNIGHT`、`已开启`、`true`/`false`）→ **仅支持 等于/不等于**，忽略大小写；
- 对文字值使用 `>`/`<` 等数值运算符会视为**不满足**（不报错）。
> 注：PAPI 目标每 tick（1 秒）轮询判定，适合职业等级、金币余额、点数、声望等动态数值；需安装 PlaceholderAPI。示例见 `example_papi.yml`。
## 完成条件
阶段级 `conditions`：**不是接取条件**，而是"必须满足特定条件才能完成/推进本阶段"。阶段目标数量全部达标后，若任一条件不满足则**阻塞完成并提示**（含冷却防刷屏），满足后才结算、发奖励、推进。可叠加多个条件（全部满足）。
```yaml
stages:
stage1:
type: LOCATION
dungeon_finish: MyDungeon
amount: 1
conditions:
cond1:
type: DUNGEON_PARTY # 副本组队完成：至少 N 人
dungeon: MyDungeon # 必须在该副本内
players: 2 # 至少 2 人
cond2:
type: CLASS_LEVEL # 职业等级条件
class: KNIGHT
level: 10
```
| 条件类型 | 参数 | 说明 |
|---|---|---|
| `class` | `class: <职业名>` | 玩家 MMOCore 主职业需为该职业 |
| `subclass` | `class: <职业名>` | 玩家副职业需为该职业（无副职业 API 时回退主职业） |
| `class_level` | `class: <职业名>, level: N` | 主职业匹配（可选）且职业等级 ≥ N |
| `dungeon_solo` | `dungeon: <副本名>` | 需单人（队伍人数 ≤1）在该副本内 |
| `dungeon_party` | `dungeon: <副本名>, players: N` | 需至少 N 人组队在该副本内 |
| `items` | 若干物品项（`material` 或 `mmo{type,id}`） | 玩家背包需持有这些物品（全部满足才算通过） |
| `chance` | `chance: 0-100` | 结算时需通过该百分比概率（每次随机判定） |
| `time` | `time: "HH:mm-HH:mm"` | 当前服务器时间需在该时间段内（支持跨天，如 `18:00-06:00`） |
| `day` | `days: [MONDAY, TUESDAY]` | 需在指定星期（英文名 `MONDAY..SUNDAY` 或数字 `1-7`） |
| `world` | `world: <世界名>` | 玩家需位于指定世界 |
| `region` | `region: <区域名>` | 玩家需位于指定区域（插件自定义区域 / WorldGuard 命名区域） |
| `weather` | `weather: CLEAR\|RAIN\|THUNDER` | 玩家所在世界需为指定天气 |
- 副本条件（`dungeon_solo`/`dungeon_party`）配合 `LOCATION` 的 `dungeon_finish`/`mythic_dungeon` 目标使用；人数取 MMOCore 队伍在线成员数（无队伍视为单人）。
- 职业/等级条件需要安装 MMOCore，缺失时该条件自动视为不满足。
- **接取预检**：可预判的条件（`items`/`time`/`day`/`world`/`region`/`weather`）在玩家**接取任务时也会校验**——不满足则提示 `接取条件未满足` 并拒绝接取；`chance` 与副本条件仅在结算时判定。
- 示例见 `quests/example_dungeon_conditions.yml`、`quests/example_guide.yml`。
---
## 每日悬赏（每日轮换）
每天从"悬赏池"（配置了 `daily: true` 的任务）随机抽取 `daily.count`（config.yml，默认 3）个作为**今日悬赏**，玩家用 `/mq daily` 查看。跨天自动重新抽取；结果持久化到 `data/daily.txt`，**跨重启保持当天结果**。
```yaml
# config.yml
daily:
count: 3 # 每天抽 3 个；0 关闭
```
任务加入悬赏池只需加一行：
```yaml
id: daily_bounty
name: "悬赏：猎杀荒原狼"
daily: true # 加入每日悬赏池（可选，默认 false）
stages:
stage1:
type: KILL
entity: WOLF
amount: 5
reward:
points: 5
message: "&a悬赏完成。"
```
> 每日悬赏与任务的 `refresh: daily`（完成后隔天可重做）是两个独立概念：`daily` 决定"是否进今日轮换池"，`refresh` 决定"完成后多久能再次接取"，可叠加使用。示例见 `quests/example_daily.yml`。
---
## 目标指引（guide + PAPI 方向/距离）
给阶段配置目标指引点 `guide`，插件据此计算玩家与目标的**方向与距离**，配合 PAPI 占位符做导航（计分板/聊天/BossBar 均可）：
```yaml
stages:
stage1:
type: BLOCK
action: BREAK
material: IRON_ORE
amount: 10
guide: # 目标指引点（可选）
world: world
x: -120
y: 40
z: 300
```
PAPI 占位符（`<id>` 可省略，省略时取玩家第一个进行中任务）：
| 占位符 | 说明 |
|---|---|
| `%mythicquests_guide_distance_<id>%` | 与目标点的水平距离（米，取整）；跨世界显示 `跨世界` |
| `%mythicquests_guide_direction_<id>%` | 目标方向（北/东北/东/东南/南/西南/西/西北）；到达显示 `到达` |
> 示例见 `quests/example_guide.yml`。未配置 `guide` 的阶段，这两个占位符返回空。
---
## 声望称号（titles）
根据玩家**当前声望值**（可为负）动态返回配置好的称号文本，供 PAPI `%mythicquests_title%` 使用（计分板 / 聊天 / 插件均可调用）。规则：取"门槛 ≤ 当前声望"中门槛最高的一档作为当前称号；低于最低门槛或未配置档位时返回空。
```yaml
# config.yml
titles:
- min: -100
title: "&7阶下囚" # 声望 ≥ -100
- min: 0
title: "&f平民" # 声望 ≥ 0
- min: 10
title: "&a新秀" # 声望 ≥ 10
- min: 50
title: "&2荣誉卫士" # 声望 ≥ 50
- min: 100
title: "&6声望大师" # 声望 ≥ 100
```
- 门槛 `min` 可为负数（声望扣成负也能有称号）；`title` 支持 `&` 颜色码与 **RGB 十六进制**（`&#RRGGBB`，1.16+ 生效），内容完全由你自定义。
- 修改后执行 `/mq admin reload` 生效。
- 结合 `%mythicquests_reputation%`（当前声望值）可做类似 `%mythicquests_title% &7(%mythicquests_reputation%)` 的组合展示。
---
## 任务点数 / 声望 / 用时排行榜
- **点数与声望**：任务 `reward` 段可配 `points`、`reputation`，完成时发放并跨任务累积。查看：`/mq stats`；排行榜：`/mq top points`、`/mq top reputation`。
- **最佳完成用时**：每次完成任务自动记录耗时（接取→完成），仅首次或更快时更新。排行榜：`/mq top time <任务id> [数量]`（用时最少第一）。
- **全服公告**：`config.yml` 的 `announce.enabled` 设为 `true` 时，完成任务向全服广播（`format` 支持 `{player}`、`{name}`）。
---
## 任务进度计分板（可选）
向进行中任务的玩家显示右侧边栏进度。在 `config.yml` 的 `scoreboard` 段配置：
```yaml
scoreboard:
enabled: false # true 启用
default_mode: auto # 玩家默认模式：auto（有任务才显示）/ on（始终显示）/ off（始终不显示）
title: "&6&l任务进度" # 标题
refresh: 20 # 刷新间隔（tick，20 = 1 秒）
empty_text: "&7暂无进行中的任务" # on 模式下无任务时显示；留空则隐藏计分板
limit: 6 # 最多同时显示的任务数，超出折叠为"等 N 个"
lines:
# ---- 每一行模板，玩家可自定义显示内容 ----
# 支持颜色代码（&a 等）与占位符；把某行设为 "" 即可隐藏该行。
task: "&e{task}" # 任务名
goal: " &7{goal}" # 当前阶段目标（显示名/描述）
progress: " &f{count}&7/&f{required}" # 进度
remaining: "" # 剩余数量行（可用 {remaining}，留空隐藏）
percent: "" # 百分比行（可用 {percent}，留空隐藏）
timer: " &c⏱ {timeleft}" # 限时剩余（可用 {timeleft}，留空隐藏）
separator: " " # 任务之间的分隔行
deliver_item: " &7{item}&7: &f{itemgot}&7/&f{itemreq}" # 交付物品行（逐物品渲染）
more: "&8... 等 {more} 个任务" # 折叠提示
```
**可用参数（占位符）一览**——普通任务（方块/物品/击杀/地点/生活等）：
| 占位符 | 含义 |
|---|---|
| `{task}` | 任务名称 |
| `{goal}` | 当前阶段目标（显示名/描述，自动含自定义 `display`/`description`） |
| `{count}` | 当前完成数量 |
| `{required}` | 所需数量 |
| `{remaining}` | 剩余数量（`required - count`） |
| `{percent}` | 完成百分比（整数，如 `50`） |
| `{timeleft}` | 限时剩余（如 `5分30秒`；无时限时该行自动隐藏） |
NPC 交付任务（多物品）额外可用：
| 占位符 | 含义 |
|---|---|
| `{item}` | 交付物品名（支持自定义 `display`） |
| `{itemgot}` | 该物品已交付数量 |
| `{itemreq}` | 该物品所需数量 |
| `{itemremaining}` | 该物品剩余数量 |
其他：`{more}` 用于折叠行的任务数量。启用后玩家完成任务、接取/放弃任务都会自动反映（定时刷新）。改配置后 `/mq admin reload` 生效。该功能不受命令权限限制。
**玩家可自行切换显示模式**（`/mq scoreboard [auto|on|off]`，或简写 `/mq sb`）：
| 模式 | 行为 |
|---|---|
| `auto`（默认） | 有进行中任务时显示，任务全部完成/放弃后自动隐藏 |
| `on` | 无论有无任务都显示（无任务时显示 `empty_text`） |
| `off` | 无论有无任务都不显示 |
不带参数执行 `/mq scoreboard` 查看当前模式。模式按玩家持久化保存。
---
## 插件集成说明
| 插件 | 集成点 | 缺失时行为 |
|---|---|---|
| **MythicMobs** | 击杀 MythicMob、NPC 交谈（识别 MythicMob 实体） | 击杀/交谈任务无法匹配 MythicMob，vanilla 目标仍可用 |
| **MMOItems** | 物品识别（NBT 类型+ID）、强化/鉴定/分解/重铸/宝石工艺事件 | MMO 匹配与工艺操作任务不可用 |
| **MMOCore** | 击杀任务组队共享、职业/副职业/等级完成条件、奖励经验/点数、任务接取等级门槛 | 击杀任务退化为仅击杀者本人计入；条件与点数奖励不可用 |
| **MythicDungeons** | 地点任务：进入副本实例判定 + **副本通关事件** | 副本位置/通关条件不可用 |
| **Citizens** | NPC 交谈/交付（识别 Citizens NPC 与 ID） | Citizens NPC 任务不可用 |
| **CoreTools** | 工艺站通用事件（`StationItemEvent` 带物品 + `StationConfirmEvent/StationConfirmEndEvent` 兜底）：强化/鉴定/分解/重铸/宝石/合并/词缀/重随机/出售/幻化 | 合并/词缀/重随机/出售/幻化等 MMOItems 无原生事件的站仅能靠 CoreTools 通用事件（未装 CoreTools 时这些任务不可计数） |
| **Typewriter** | 交谈任务绑定对话进度（查询 fact / 触发对话） | 交谈任务回退为右键即完成 |
| **WorldGuard** | `region` 字段按 WorldGuard 命名区域判定（多边形/非矩形） | region 回退插件自定义区域 |
> 说明：CoreTools 为 MMOItems 付费配套工具。其工艺站（合并/词缀/重随机/出售/幻化等 MMOItems 无原生事件的站）在**确认操作成功**时派发通用事件 `StationItemEvent`（携带站名 + 被操作物品，失败操作会先被取消、不会派发该事件），本插件按 `getStation()` 站名映射到对应操作并计数；出售站不派发 `StationItemEvent`，由 `StationConfirmEvent` 兜底。强化/鉴定/分解/重铸/宝石同时由 MMOItems 原生事件覆盖，双来源已做时间去重避免重复计数。MythicDungeons 副本通关通过其完成事件反射监听，版本不兼容时自动跳过并告警。Typewriter 为 Kotlin 编写、网页面板配置的对话系统，其 fact 查询经反射尽力解析，若版本不兼容则自动回退。
---
## 进度存储
`config.yml` → `storage` 段，支持三种：
```yaml
storage:
type: yaml # yaml | sqlite | mysql
sqlite: { file: quests.db }
mysql:
host: localhost
port: 3306
database: minecraft
user: root
password: ""
useSSL: false
```
- `yaml`：默认，`data/quests.yml`，单服。
- `sqlite`：`data/quests.db`。
- `mysql`：多服共享，表 `quest_progress` 与 `player_stats`（点数/声望）。
---
## 命名区域 / WorldGuard 区域
任务里的 `region` 字段用于限定目标发生的区域，支持两种来源，**对任务配置零变更**：
1. **插件自定义区域**（config.yml `regions` 段，矩形区域，不依赖任何插件）：
```yaml
regions:
city:
world: world
min: { x: 0, y: -320, z: 0 }
max: { x: 100, y: 320, z: 100 }
```
2. **WorldGuard 命名区域**（软依赖）：若服务器**安装了 WorldGuard**（或同类支持命名区域的插件），`region` 字段可直接填 WorldGuard 的区域名，按其区域判定（支持多边形/非矩形区域）。
> 判定顺序：先查插件自定义区域（config.yml `regions`）→ 未命中且装有 WorldGuard 时，再按 WorldGuard 命名区域判定。装了 WorldGuard 但不想用，可忽略（只要区域名没冲突即可）。未安装 WorldGuard 时自动回退自定义区域，不影响任务运行。
---
[/MD]
