CobblemonQuests

CobblemonQuests

你的 Cobblemon 服务器所需的参与循环。每日、每周、
精英、隐藏和可重复任务，全服社区
目标、排行榜、可配置音效，以及完整的
游戏内创作 + 自定义工具包——全部构建在简洁的
单屏 GUI 之上，管理员可逐槽位从
配置中重新排列，无需接触 Java。

功能亮点

面向玩家

• 6 种任务类型——每日、每周、精英每周、隐藏、可重复和普通（链式步骤）。
• 可重复任务永不轮换。想跑多少次就跑多少次；每个任务的累计完成次数都会被追踪并显示在方块上。
• 精英每周——一个额外困难的每周任务，奖励显著更好，显示在带光效的专属槽位中。
• 隐藏任务在触发条件匹配时（捕捉数量、物种、维度等）会隐形解锁，并位于专属的隐藏查看器 GUI 中，旁边还有你已完成任务的奖杯方块。
• 15 种目标类型——捕捉、对战 NPC、击败野生（与 PvE 胜利分开追踪）、升级、获得等级、进化、孵化蛋、投掷精灵球、使用经验糖果、访问生物群系 / 维度（带防乒乓去重）、捕捉闪光、捕捉传说、完成 PokeHunts、完成 raids。
• 单个 6 行任务 GUI——所有内容一目了然：第 0 行是排行榜方块 + 重置计时器，第 1–2 行是每日任务，第 3–4 行是每周任务，第 5 行是连续 / 里程碑 / 隐藏 / 可重复 / 关闭。再也不用翻子页面了。
• 服务器任务——全服共享目标，带实时 Boss 血条。每位玩家都能贡献。持续时间从 1 小时到 1 周。贡献前 3 名获得额外奖励；离线贡献者通过排队奖励系统在下次登录时发放。贡献排行榜带玩家头颅 + 奖牌。
• 排行榜——前 16 名玩家头颅金字塔，自己的排名带光效。平局现在按谁先达到该数值（基于时间戳）来打破，所以超过朋友能让你保持领先。
• 音效 + 视觉特效——任务完成、领取、里程碑、连续推进、隐藏发现、链式推进和社区目标完成时可配置音效。重大事件时标题 / 副标题闪烁。
• 领取系统——已完成任务会发光★ READY ★；可单独领取或点击全部领取。提供自动模式。
• 每日连续 + 终身里程碑——奖励一致性。里程碑 GUI 分页且完全可配置。
• 重随系统，带每轮硬性上限——daily-per-day 和 weekly-per-week（默认各 1 次）。无付费兜底。计数器在重随之前消耗，如果池无法生成替代品则退还，因此并发点击不会重复消耗。
• 聊天奖励横幅——每次奖励发放都会显示一行确认：★ +250 Stars / $ +5000 PokeDollars。格式可按服务器完全自定义。

面向管理员

• 游戏内自定义几乎所有面向玩家的字符串、槽位、物品、颜色和按钮。无需编辑 jar，无需 Java。每个 GUI 都是 config/cobblemonquests/gui/ 下自己的 HOCON 文件：
• main_menu.conf、detail_menu.conf、stats_menu.conf、milestone_menu.conf、leaderboard_menu.conf、repeatable_menu.conf
• 设置每个按钮的 slot（0–53）。设置每个菜单的 rows（1–6）。切换任意按钮的 visible 标志。用任意物品 id 替换玻璃板填充物。自定义进度条字符、颜色、长度、括号。通过 name-format 重新排序任务名称各部分。按进度 / 稀有度 / 字母顺序 / 状态 / id 排序任务。
• 自定义命令按钮 — 将无限额外按钮放入任意 GUI：存储链接、Discord、投票、原版命令快捷方式。每个条目需要 slot、item、name、lore、glow，以及一个带有 {player} 替换的 command 模板。
• 事件命令钩子 — 当以下任意事件发生时触发控制台命令：quest-complete、milestone-reached、streak-milestone、claim。接入 Discord webhook、广播消息、发放外部物品——全部无需重新编译。
• 管理员右键快捷操作 — 拥有管理员权限时右键任意任务方块，即可内联打开 完成 / 重置进度 / 查看详情。
• 任务浏览器 — 按类型分页（全部 / 每日 / 每周 / 普通 / 精英 / 隐藏 / 重复），按稀有度 + 分类筛选，可排序，分页显示。可扩展至数百个任务。
• 任务编辑器 + 任务创建向导 — 完整的游戏内 CRUD。循环切换类型 / 分类 / 稀有度，设置目标，通过 4 步向导构建奖励，保存到磁盘，复制，删除（两次点击确认），实时预览。
• 4 步奖励向导 — 选择分类（货币 / 物品 / crate 钥匙 / 命令）→ 浏览 + 选择（物品浏览器带有 全部 / Cobblemon / 球 / 糖果 / 原版 标签页和完整注册表分页）→ 设置数量 → 回顾 + 确认。
• 每项奖励的 display 覆盖 — 用自定义 MiniMessage 替换任意奖励的描述文本。非常适合品牌化奖励，或将原始 padmin givekey 命令隐藏在简洁的 <aqua>Special Reward</aqua> 行后面。
• 奖励显示重命名映射 — rewards.display-names 将任意物品 id 或钥匙 id 全局映射到自定义名称。服务器可以发布完全品牌化的提示框集，而无需逐项编辑奖励。
• 链浏览器 + 编辑器 + 向导（管理员端）— 完整的游戏内链编写，带有步骤选择器、内联任务创建、重排箭头、难度标签、可循环开关、链完成奖励。
• 服务器任务浏览器 + 编辑器 + 向导 — 创建服务器范围的目标，包含目标类型、目标值、持续时间（1 小时到 1 周）、基础奖励，以及前三名贡献者额外奖励。活跃目标管理仪表板：停止、重置、提升进度、实时查看贡献者。
• 玩家管理 GUI — 检查任意在线玩家：活跃任务、连续天数、星星余额、总完成数、可重复运行次数。管理员操作：授予星星、重置每日 / 每周任务、清除玩家数据（两次点击确认）。每次点击都会重新检查管理员权限——会话中途降权会立即生效。
• 配置编辑器 — 多页中心：重掷上限 / 池权重 / 开关 / GUI 布局。每个都是带有保存功能的简洁子页面。
• GUI 布局编辑器 — 可视化 54 格网格。点击任意格子循环切换其角色。保存会写入 gui/player_main.conf 并自动重载。
• 诊断与测试命令：
• /quests admin debug events — 每个追踪器的触发次数 + 最后触发时间戳 + 最后详情。几秒内分诊“我的任务不推进”报告。
• /quests admin debug stars <player> — 打印权威星星余额 + 终身收入。
• /quests admin testkey <player> <key> [amount] — 实时调用 crate-key 桥接，无需等待任务即可验证你的模板。
• /quests admin testcommand <player> <command...> — 通过奖励使用的同一 SafeDispatch 管道试运行任意命令奖励模板。

奖励

• 宝可梦币（Impactor 主货币）
• 星星——现在通过可配置的经济命令（默认：eco deposit {amount} {currency} {player}）发放，因此更新的是真正的 Impactor 货币账户。本地 JSON 账本仅作为排行榜缓存镜像。
• 物品——任意 Minecraft / Cobblemon 物品 id，带溢出处理。
• 钥匙——全局命令模板加上按钥匙覆盖映射（integrations.crate-key-commands），因此 lunar 可以路由到 Pebble’s Crates，vote 可以路由到 ExcellentCrates，同一服务器上无需在其他地方分支。默认模板开箱即指向 Pebble’s Crates（padmin givekey {player} {amount} {key}）。
• 自定义命令——控制台执行，带 {player} 占位符，通过统一的 SafeDispatch 管道运行，能捕获拼写错误、缺失节点和重入，而不是静默吞掉它们。
• 所有发放都是原子的，带 8 字符交易 ID 的审计日志记录，并且对离线玩家具有韧性——社区目标奖励和星星奖励会排队进入 pendingRewards，并在下次登录时通过 ★ You have rewards waiting! ★ 聊天横幅发放。

集成

• Impactor——宝可梦币 + 星星货币，软依赖。
• PokeHunts——加载时自动挂钩；任务类型 COMPLETE_POKEHUNT。
• Raids——加载时自动挂钩；任务类型 COMPLETE_RAID。
• LuckPerms——可选，用于权限节点查找；如果提供者失败，会干净地回退到 op 级别，并给出一次性 WARN。
• Pebble’s Crates / ExcellentCrates / CMI——任何钥匙插件都可以通过按钥匙覆盖映射工作。
• 公共 API——任何模组都可以调用 ExternalEventApi 来提供任务进度，而无需类路径依赖。

安全与可靠性

• 每次操作都会重新检查权限——会话中途降级也能生效。每个管理 GUI 的每个 open() 和点击都有内部 requiresAdmin() 守卫。
• 绕过权限是显式仅限的，并且现在受配置门控。 cobblemonquests.bypass.reroll-cost 和 cobblemonquests.bypass.rate-limit 只有在 config.conf 中匹配的 permissions.bypass.* 标志设置为 true 时才会生效。仅授予 LP 节点不再足够——因此被遗忘的通配符继承无法静默禁用新的重随上限。
• 每玩家速率限制适用于重随和管理命令。
• 审计日志位于 logs/cobblemonquests-audit.log，记录每次任务分配、完成、奖励发放、重随、管理操作、隐藏发现、里程碑跨越、社区目标变更、配置重载和管理测试命令，带有 8 字符 base36 交易 id。
• 分配时快照——任务定义在分配时快照，因此配置编辑永远不会追溯更改奖励。
• 反利用去重适用于“访问 N 个生物群系 / 维度”目标——只有不同的生物群系 / 维度 id 才计数。乒乓刷取已死。
• SafeDispatch——模组运行的每条控制台命令（奖励、星星、钥匙）的单一规范路径。将结果 < 1 视为硬失败，并带有包含已解析命令字符串的 WARN。重入守卫防止奖励模板意外回调模组时出现无限循环。

一句话电梯演讲

把你的 Cobblemon 服务器变成玩家为了明天而登录的地方，
而不仅仅是今天。

设置

1. 将 cobblemonquests-1.8.0.jar 放入 mods/，与 Cobblemon 以及（可选）Impactor 放在一起。
2. 启动服务器。首次启动时会写入默认配置、示例任务（9 个日常、7 个周常、1 个精英、1 个隐藏、3 个可重复）、一个初始任务链以及 2 个服务器任务模板。
3. 管理员可以运行 /quests 查看玩家中心，运行 /quests admin 打开管理面板。
4. 使用游戏内向导创建任务、任务链和服务器任务——或手动编辑 config/cobblemonquests/ 文件。
5. 使用游戏内配置编辑器调整重随上限、池权重和开关——或编辑 config.conf 并运行 /quests admin reload。

命令

/quests                     Open the quest hub
/quests stats               Open the stats page
/quests leaderboard         Open the leaderboard
/quests reroll <slot>       Reroll a quest (per-rotation cap applies)
/quests admin               Open admin panel
/quests admin reload        Reload config + quests
/quests admin give <p> <q>  Give a quest to a player
/quests admin complete <p> <q>  Force-complete a quest
/quests admin reset <p>     Reset a player's dailies
/quests admin resetweek <p> Reset a player's weeklies
/quests admin goal set <id> Activate a server quest
/quests admin goal stop     Stop the active server quest
/quests admin goal reset    Reset server quest progress
/quests admin goal progress <n>  Set progress manually
/quests admin debug events  Tracker activity dashboard
/quests admin debug stars <p>    Print Stars balance + lifetime
/quests admin testkey <p> <key> [n]   Test crate-key template live
/quests admin testcommand <p> <cmd...>  Test any command template

/cq 是 /quests 的简写别名。

兼容性

• Minecraft 1.21.1 / Fabric
• 硬性依赖：Cobblemon 1.7.3+、Fabric API、Java 21
• 软性依赖：Impactor（PokéDollar + Stars 货币）、LuckPerms（权限节点 + 前缀）、PokeHunts（自动挂钩）、Raids（自动挂钩）、任意 crate 插件（Pebble’s、ExcellentCrates、CMI 等——可按钥匙配置）
• 与 PokeBuilder 和 StaffChat（同样来自 souljagger）和平共存。

路线图

• 队伍 / 多人任务——随队伍系统更新推出
• NPC 交互——右键点击 Cobblemon NPC 打开 /quests
• 任务商店——花费 Stars 购买专属物品
• 季节性 / 活动任务——限时任务池
• 面向玩家的任务链界面——任务链后端 + 管理员创作今日已发布；玩家查看器将随队伍更新一同回归

许可证

MIT——可 fork、修改、再分发。