KyuubiSoft 任务系统（剧情、日常、周常、任务商店）

KyuubiSoft Quest System

为 Hytale 服务器打造的一款完整的任务框架——包含每日与每周轮换任务、31 个剧情任务的 6 章节故事线、拥有完整对话树的 NPC 任务发放者、基于等级的经济奖励系统、游戏内代币商店、HUD 追踪、范围通知以及一个完整的可视化管理员面板。一切开箱即用，满足玩家和管理员的所有需求。

---

功能特性

每日与每周任务

• 3 个每日任务：每天在可配置的重置时间（默认：04:00）轮换
• 5 个每周任务：每周在可配置的日子（默认：周一）轮换
• 120 个每日任务，分布在 10 个池子中（采矿、伐木、挖掘、收割、战斗、伤害、制造、建筑、探索、在线时长）
• 48 个每周任务，分布在 3 个类别中（精通、挑战、旅程），每个任务最多 5 个目标
• 基于等级的选择——任务从加权池中抽取：普通、稀有、史诗、传说
• 重掷系统——每周期 1 次免费重掷，之后每次重掷消耗递增的代币（10 > 20 > 40 > …）
• 懒人重置——在重置期间离线的玩家下次登录时将获得新任务
• 每次完成任务可获得任务代币
• 可通过任务书或在指定的NPC处提交任务

剧情与章节任务

• 31 个剧情任务，横跨 6 个章节——从觉醒到荒芜之地
• 线性剧情推进，包含任务链和前置条件锁定
• 事实库——追踪故事状态（例如“met_npc_aldric”、“discovered_temple”）
• 触发系统——任务可在以下事件自动开始：首次加入、进入区域、与NPC互动、完成任务、事实变更
• 顺序目标——强制玩家按顺序完成目标
• 前置条件——根据已完成的任务、章节、成就或事实解锁任务
• 章节奖励——完成章节后的额外战利品袋、头衔和代币

支线任务

• 14 个支线任务——与特定NPC和区域相关的可选独立任务
• 基于剧情进度的前置条件
• 混合目标类型：战斗、收集、制造、探索

NPC 任务发放者

• 17 个独特的任务NPC，带有完整的对话树（提供、进行中、完成阶段）
• 基于优先级的选取——拥有多个任务的NPC会优先提供最相关的任务
• 任务选择对话框——当有 2 个或以上任务可用时，玩家通过选择界面挑选
• 多NPC任务——接受任务和提交任务由不同NPC负责（分裂NPC模式）
• 范围低语——当玩家走近时，NPC会发送情境感知的消息
• 挥手动画——当NPC有任务可提供时会挥手示意
• 306 个本地化对话键——所有NPC文本已完全翻译（英文 + 德文）

范围通知

• 范围提示HUD——显示附近的任务NPC及其距离和指南针方向
• 吐司弹出——任务开始、进度里程碑（25%、50%、75%）、任务完成
• 登录通知——登录时显示可用和可提交的任务（含NPC皮肤图标）
• 聊天消息——进度更新、代币余额变动、重掷确认
• 服务器广播——可选的全服完成公告

---

目标类型

类型	描述	反作弊
blocks_mined	挖掘特定方块（通配符：Ore_*）	PlacedBlockTracker 阻止挖掘自己放置的方块
blocks_chopped	砍伐树木和木头	—
blocks_dug	挖掘泥土、沙子或砾石	—
blocks_placed	放置特定方块	—
blocks_harvested	使用F键收割作物	—
flowers_picked	采摘花朵	—
kills	击杀特定生物（通配符：Goblin_*）	—
player_kills	PvP击杀	—
damage_dealt	造成总计X点伤害	—
damage_taken	承受总计X点伤害	—
items_collected	背包中拥有X件物品（实时扫描）	—
items_crafted	制造特定物品	—
items_consumed	食用食物或药水	—
distance_traveled	行走或奔跑距离（方块）	—
zones_discovered	发现命名区域（去重）	—
playtime_minutes	游戏时长	—
interact_npc	与特定NPC对话	—

目标匹配： 精确（Rock_Stone）、通配符（Ore_*）、分组（group:Stone）、属性（@consumable 匹配所有可食用物品）、多目标（["Ore_Iron", "Ore_Copper"]）或 any。

条件目标——限制在特定生物群系、区域、天气、时段、工具或最低等级内完成进度。

---

奖励类型

类型	描述
物品	给予指定数量的物品——随等级倍率缩放
任务代币	用于代币商店的内部货币
战利品袋	通过 KyuubiSoft Core 的战利品袋系统提供随机战利品
成就	解锁成就（成就系统集成）
头衔	授予游戏内头衔
指令	执行控制台或玩家指令

• 等级倍率——更高等级的任务会自动缩放奖励数量
• 自动暂存——如果背包已满，奖励将被保存，稍后可领取

---

任务等级

等级	颜色	权重	奖励倍率
普通	灰色	50	1.0x
稀有	蓝色	30	2.0x
史诗	紫色	15	3.0x
传说	橙色	5	5.0x

所有等级均可完全配置——可在 config.json 中新增、移除或重命名。权重越低，在每日/每周池中出现的概率越低。

---

连续活跃系统

保持活跃以获取额外奖励：

里程碑	所需天数	奖励
青铜	7 天	战利品袋 + 代币
白银	14 天	战利品袋 + 代币
黄金	21 天	战利品袋 + 代币
铂金	28 天	战利品袋 + 代币

• 防错过机制——采用“14 天内完成 7 天”的模式。错过一天不会立即中断连续记录。
• 宽限期——可配置的缓冲期，在连续记录重置之前生效
• 追踪每位玩家的当前连续记录和最长连续记录

---

任务代币商店

使用您赚取的代币购买专属物品。

• 常驻区域——始终可用的物品
• 每日轮换——每天可配置的轮换物品
• 购买限制——每件物品每日最大购买次数
• NPC 商人——专属代币商店NPC（citizen_5）
• 自定义物品——通过 custom/custom_quest_token_shop.json 添加您自己的物品

---

任务书 UI

使用 /ksquest 打开——所有任务内容的中心位置。

• 标签页导航：每日、每周、剧情、活跃、统计
• 活跃任务侧边栏——显示最多 20 个活跃任务及其各自的目标进度
• 任务详情——目标及进度、奖励、前置条件、难度徽章
• 提交信息——显示每个任务的完成地点（NPC名称+坐标或任务书）
• 等级徽章，带有颜色编码
• 领取奖励按钮（NPC提交任务会显示“在NPC处提交”）
• 重掷按钮，附带费用显示
• 任务追踪——最多将 5 个任务固定在HUD上
• 统计标签页——连续记录、代币、完成数、活跃数、每日/每周进度
• 完全本地化——所有文本支持多种语言

---

HUD 追踪器

在屏幕上实时显示任务进度。

• 同时追踪最多 5 个任务（可配置）
• 显示任务名称、每个任务最多 5 个目标以及进度
• 提交提示——当所有目标完成时，显示“在NPC名称处提交”或“打开任务书”
• 按等级颜色编码
• 6 个位置预设 + 自定义 X/Y 定位
• 每位玩家可独立设置——每位玩家保存自己的HUD偏好设置
• 集成 MHUD，以兼容其他HUD模组

玩家 HUD 设置（/ksquestsettings）

• 开关HUD
• 选择位置预设或设置自定义坐标
• 调整最大显示任务数（1-10）和每个任务的最大目标数（1-5）
• 开关进度显示和空状态消息

---

管理员面板

可通过 KyuubiSoft Core 控制台或 /ksquestadmin panel 访问——在游戏中管理一切。

任务编辑器

• 通过可视化编辑器创建、编辑、复制、删除任务
• 多语言名称与描述字段
• 目标构建器——选择类型、设置目标、数量和条件
• 奖励构建器——选择类型、设置物品、数量和倍率
• 前置条件编辑器——串联任务、要求成就或事实
• 等级分配、顺序开关、难度设置

池管理

• 查看和编辑每日/每周任务池
• 向轮换中添加或移除任务
• 调整等级权重

玩家管理

• 查看任意玩家的任务数据
• 重置数据、授予/撤销任务、调整代币
• 查看完成统计

设置编辑器

• 通过UI编辑所有配置值
• 重置时间、任务数量、连续活跃设置、等级系统、通知阈值
• 实时重载——保存后更改立即生效
• 默认配置禁用标志——跳过基础任务，仅加载自定义内容

调试工具

• /ksquestadmin debugmode——在聊天中实时追踪，显示所有事件和任务匹配
• /ksquestadmin complete——强制完成任意任务用于测试

---

指令

玩家指令

指令	别名	描述
/ksquest	/questbook, /qb	打开任务书
/ksquestsettings	—	打开HUD设置

管理员指令

指令	描述
/ksquestadmin panel	打开管理员面板
/ksquestadmin reload	重载配置
/ksquestadmin resetme	重置自己的任务数据（测试用）
/ksquestadmin debugmode	开关实时调试追踪
/ksquestadmin tokens [amount]	给自己代币
/ksquestadmin complete <questId>	强制完成任务
/ksquestadmin start <questId>	强制开始任务
/ksquestadmin testfirstjoin	模拟首次加入触发器
/ksquestadmin testzone <zone>	模拟区域发现
/ksquestadmin testnpc <npcId>	模拟NPC互动

权限：questbook.admin

---

配置

KyuubiSoft-Quests/
├── config.json                  # 主设置（重置、等级、经济、HUD）
├── quests.json                  # 每日、每周和支线任务定义
├── story_quests.json            # 剧情任务定义
├── chapters.json                # 章节定义与推进
├── daily_pool.json              # 每日轮换池
├── weekly_pool.json             # 每周轮换池
├── quest_npc_profiles/          # NPC任务发放者档案
│   ├── guide_finn.json          # 示例：向导芬恩（新手任务）
│   └── ...                      # 包含 17 个NPC档案
├── data/
│   └── <uuid>.json              # 每位玩家的任务数据（自动管理）
├── custom/
│   └── custom_*.json            # 任务和池的自定义覆盖
└── localization/
    ├── en-US.json               # 英文翻译（约 800 个键）
    └── de-DE.json               # 德文翻译（约 800 个键）

任务定义示例

{
  "id": "daily_mine_stone",
  "type": "daily",
  "category": "gathering",
  "difficulty": "easy",
  "icon_item": "Tool_Pickaxe_Iron",
  "objectives": [
    {
      "id": "obj_1",
      "type": "blocks_mined",
      "target": "Rock_Stone*",
      "count": 50
    }
  ],
  "rewards": [
    { "type": "quest_tokens", "amount": 3 },
    { "type": "item", "item_id": "Ore_Iron", "amount": 5 }
  ],
  "options": {
    "repeatable": true,
    "tier": "common",
    "weight": 50,
    "pool": "mining"
  }
}

---

面向模组开发者

通过公共 QuestAPI 访问任务系统：

QuestAPI api = QuestAPI.getInstance();

// 事件监听器
api.onQuestStarted((player, questId) -> { ... });
api.onQuestCompleted((player, questId) -> { ... });
api.onQuestAbandoned((player, questId) -> { ... });

// 查询
Set<String> allQuests = api.getAllQuestIds();
Set<String> dailyQuests = api.getQuestsByType("daily");

// 事实数据库
String value = api.getPlayerFact(player, "met_finn");
api.setPlayerFact(player, "discovered_temple", "true");
boolean result = api.checkFactConditions(player, conditions);

---

反作弊

• PlacedBlockTracker——阻止挖掘自己放置的方块以获取任务进度（30分钟过期，可配置）
• 区域去重——每个目标内每个区域仅计数一次（防止传送门刷取）
• 前置条件验证——无法开始未解锁的任务
• 完成检查——无法在未完成所有目标的情况下领取奖励
• NPC提交保护——分配给NPC的任务无法通过任务书提交
• 重掷保护——无法重掷已开始的任务，每日最大重掷次数

---

兼容性

• 集成：成就系统、MHUD
• 服务器：Hytale 专用服务器
• Java：21+

---

支持

• Discord：KyuubiSoft Discord

KyuubiSoft 用心打造