QuestPlus
概览
QuestPlus 为 TypeWriter 的 Quest 扩展增加了护送目标、每日任务轮换和战斗状态事实。在护送任务中，NPC 沿着道路网络从一个检查点走向下一个检查点，玩家必须保证它存活并紧随其后。临时任务定义决定一组任务何时可用，以及当天选取哪些任务。
护送使用 Quest、Basic、RoadNetwork 和 Entity 扩展：路线来自道路网络，NPC 是一个实体实例，而玩家的指南针或路径流来自 QuestCodex 的 Quest 指南针，因为护送目标是可定位的。
NPC 头顶的任务状态指示器（npc_status_override）不属于 QuestPlus。它们由 UiCore 及其名牌提供。
功能
- 护送目标 — NPC 沿着一条由道路节点组成的路线行走，在每个检查点暂停，并且必须到达终点。
- 失败与重置规则 — 玩家必须保持在守护半径内，NPC 可能被怪物伤害，并且可以设置时间限制。
- 检查点触发器 — 开始、检查点、失联、重新跟上、重置、完成和失败触发器，以及每个检查点的伏击触发器。
- 护送显示 — 可选的计分板和 Boss 血条，显示检查点、时间和生命值。
- 护送动作 — 在任意序列中开始、推进、重置和停止护送。
- 临时任务 — 轮换的任务池：按星期几、小时和 cron 设置可用性，每天选取一定数量的任务，并设有完成上限。
- 战斗状态 — 在玩家攻击或被攻击后的若干秒内为
1的事实。 - 可隐藏的目标 — 在其任务被追踪之前隐藏某个目标。
- 占位符 — 护送进度、生命值和时间，以及当天的任务和距离下一次轮换的倒计时。
安装
- 安装 QuestPlus 声明为依赖项的 TypeWriter 扩展 Quest、Basic、RoadNetwork 和 Entity。
- 可选：安装 QuestCodex，以便向玩家显示护送路径点。
- 将 QuestPlus 的 JAR 放入
plugins/Typewriter/extensions/并重启服务器。 - 使用 RoadNetwork 扩展为你的护送路线构建一个道路网络，参见快速上手。
快速上手
创建一个护送任务：
- 在 TypeWriter 网页面板中，使用 RoadNetwork 扩展创建一个道路网络，并放置你的 NPC 必须经过的节点。请保持边是最新的：如果无法计算出路径，NPC 就无法到达其节点。
- 添加一个 Path Escort Activity 条目。设置
roadNetwork，在nodes中按行走顺序列出节点 id，并将idleActivity设为路线结束后 NPC 的行为。 - 为你的护送 NPC 创建一个实体实例，并将其
activity设为这个 Path Escort Activity。该实例必须属于某个处于激活状态的受众，因为 QuestPlus 使用的是 TypeWriter 已经为其运行的展示。 - 添加一个 Escort Objective 条目。设置
quest、npc（你的实体实例）和display。调整maxHealth、guardRadius、loseToleranceSec、spawnRadius和startRadius，以及可选的globalTimeLimitSec。 - 链接触发器：将
onEscortComplete链接到成功时应当发生的事情（例如为下一个任务步骤设置事实的动作），将onEscortFail链接到失败处理。 - 让玩家接近护送对象。当目标受众中的玩家进入第一个节点的
startRadius范围内时，护送会自行开始。若想改为通过对话或事件启动，请使用带有objective的 Escort Start。 - 每当 NPC 在检查点停下时，使用 Escort Next（例如在一句对话之后或伏击被清除之后）让它走向下一个检查点。
- 发布并测试：NPC 会出现在第一个节点附近，当你进入其
startRadius范围内时，护送开始。
使用 /escort debug resolve <objective> 来检查第一个节点和各个半径是否已被解析。
在 ambushes 中填写 checkpointIndex 和 triggers。当护送到达该检查点时，触发器会触发一次，例如用于通过另一个扩展生成怪物。
工作原理
护送开始时，QuestPlus 会为该 NPC 创建一个只有被护送的玩家才能看到的隐形生命值载体。guardRadius 范围内的附近怪物会以它为目标。NPC 会因怪物的攻击而损失生命值（mobHitDamage），并且可以再生（regenPerSec）。玩家无法伤害它。如果开启 invulnerable，它将受到完全保护。
NPC 走向下一个道路节点（NPC 进入该节点的 nodeReachRadius 范围内即视为到达），然后等待，直到某个 Escort Next 动作放行它。到达检查点时会触发 onCheckpoint 和对应的伏击触发器。在最后一个节点之后，触发 onEscortComplete。
重置。 当 NPC 死亡或玩家死亡，或者玩家在超过 guardRadius 的距离上停留 loseToleranceSec 秒时，护送会回到其上一个检查点，并且 NPC 的生命值恢复满。玩家超出范围时触发 onEscortLost，回来时触发 onEscortRecovered。重置时触发 onEscortReset。
失败。 当 globalTimeLimitSec 耗尽、玩家退出、NPC 消失，或执行了 Escort Stop 时，护送失败。触发 onEscortFail。
Escort Reset 动作会取消护送，并且不触发任何失败触发器。
临时任务
Temporary Quest Definition 是一个受众筛选器。只有当它处于激活状态时，其 children 才会显示给玩家：
- 可用性。 它在所列出的
daysOfWeek上、在设置了的startTime和endTime（HH:mm）之间，以及在设置了的cronExpression匹配时处于激活状态。 - 每日选取。 每天从
quests中随机选取questsPerDay个任务。对于给定的某一天和条目，选取结果是确定的，会在resetTime变化，并保存在由artifact引用的 Temporary Quest Artifact 中。 - 完成上限。 当
maxCompleted大于0时，完成了当天那么多个任务的玩家将不再看到这些子项。计数器保存在构件中，并随着新的一天重置。
每日选取通过占位符和完成计数公开。筛选器本身不会隐藏未被选中的任务：请在你的菜单中使用占位符，或者设计你的任务可用性，使得只有你展示的任务才能被接取。
战斗状态
当玩家在最近 thresholdSeconds（默认 10）秒内攻击过某个实体或被某个实体攻击过时，Combat Status Fact 为 1，否则为 0。可在条件中使用它，以便在战斗期间阻止快速旅行、对话或登出奖励。它只追踪涉及玩家的战斗。
占位符
用于 MiniMessage 文本的 MiniPlaceholders 标签。
护送，针对被护送的玩家。当没有护送处于激活状态时，数值为中性值。
| 占位符 | 返回 |
|---|---|
<escort_checkpoint> | 当前检查点，格式为 n/total，未激活时为 0/0。 |
<escort_time> | 已经过的秒数，或者当目标设有时间限制时为剩余秒数。 |
<escort_health>、<escort_health_max> | 护送 NPC 的生命值及其最大值，未激活时为 0。 |
<escort_is> | 有护送处于激活状态时为 1。 |
<escort_is_max> | 到达最后一个检查点时为 1。 |
临时任务，其中 id 是 Temporary Quest Definition 条目的 id。
| 占位符 | 返回 |
|---|---|
<tempquest_active_quests:id> | 今日任务的 id，以逗号分隔。 |
<tempquest_time_remaining:id> | 距离下一次轮换的时间，格式为 HH:MM:SS。 |
<tempquest_quests_per_day:id> | 每天选取的任务数量。 |
<tempquest_quest_name:id:n> | 当天第 n 个任务的显示名称，从 1 开始。 |
<tempquest_quest_desc:id:n> | 第 n 个任务的显示文本。 |
命令
| 命令 | 说明 |
|---|---|
/escort debug start <objective> | 为你自己开始一次护送（仅限玩家）。 |
/escort debug stop | 停止你的护送。 |
/escort debug skipnode | 将你的护送推进到下一个检查点。 |
/escort debug scan | 立即运行自动开始扫描。 |
/escort debug resolve <objective> | 输出某个目标的第一个节点和各个半径。 |
<objective> 是 Escort Objective 的 id 或名称。该命令需要 questplus.escort.debug。
权限
| 权限 | 授予 |
|---|---|
questplus.escort.debug | /escort debug。它没有默认值，因此除非你授予，否则只有管理员拥有它。 |
条目
9 个条目，由扩展源码生成。
动作4
- Escort NextAdvance escort to next checkpoint
- Escort ResetReset escort objective
- Escort StartStart an escort objective
- Escort StopStop the current escort objective
目标1
- Escort ObjectiveEscort an NPC along a route
事实1
- Combat Status FactCombat Status Fact
受众1
- Temporary Quest DefinitionActivates a rotating subset of quests each day
活动1
- Path Escort ActivityMoving along a path for escort
构件1
- Temporary Quest ArtifactStores today's quests and reset time
故障排查
NPC 始终不出现。 日志显示 "npc instance missing" 或 "has no display registered in the AudienceManager"。目标的 npc 必须是属于某个处于激活状态的受众的实体实例。请运行 /escort debug resolve <objective> 并检查该实例是否存在。
日志显示 "is missing a path_escort_activity"。 用作 npc 的实体实例必须将 Path Escort Activity 作为其 activity。
"node ... not found" 或 "has no nodes"。 该 activity 的 nodes 列出了不在所选 roadNetwork 中的 id，或者列表为空。编辑网络后请重新选择这些节点。
"navigation ... ended N blocks away from the node. The road network could not produce a walkable path; recalculate its edges." NPC 无法走到该节点。请重新计算道路网络的边，并检查节点之间的地形。
护送不会自行开始。 玩家必须在该目标的受众中（任务处于激活状态且目标的 criteria 为真），与第一个节点位于同一个世界，并且在其 startRadius 范围内。否则请使用 Escort Start 启动。只有当玩家在第一个节点的 spawnRadius 范围内时，NPC 才会生成。
护送立即重置。 玩家距离超出 guardRadius 的时间超过了 loseToleranceSec，或者 NPC 正在被怪物的攻击打死。请提高半径或容忍时间，降低 mobHitDamage，或开启 invulnerable。
NPC 在每个节点都停下而不继续前进。 这是有意设计的：它会在每个检查点等待 Escort Next。
临时任务全部被隐藏。 该定义只在其 daysOfWeek 上、startTime 和 endTime 之间，以及 cronExpression 匹配时才处于激活状态。请检查这些设置以及 maxCompleted 上限。
相关扩展
- QuestCodex — 通往护送路径点的指南针和路径。
- UiCore — NPC 头顶的任务状态指示器（
npc_status_override）。