NPC 任务

重要提示：这是NPC 对话插件的一个附加插件。在安装 NPC 任务之前，必须确保 NPC 对话已安装并能正常运行。

支持服务器 - https://discord.gg/DRxwt8Qg2W

NPC 任务是 NPC 对话插件的一个附加插件。此插件通过全面的任务和前置要求功能扩展了 NPC 对话。必须先安装 NPC 对话，因为 NPC 任务依赖于它才能运行。此插件使服务器管理员能够创建复杂、可交互的 NPC 任务系统，无需任何编程知识。

该插件与主 NPC 对话插件无缝协作，会自动检测其是否已安装，并在整个对话系统中启用任务功能。安装此插件后，每个对话页面上的每个按钮都将具备配置前置要求和奖励的能力。

主要功能包括多种类型的前置要求，例如玩家背包中必须拥有特定物品的物品要求、玩家必须首先与其他 NPC 交互的 NPC 前置要求，以及通过 API 与其他插件集成的自定义要求。奖励系统同样灵活，支持物品奖励、自定义插件奖励和执行控制台命令。

该插件会追踪所有玩家与 NPC 的交互，从而实现连续的任务进度。如果玩家未完成必要的前置要求，他们将无法访问 NPC 或按钮。这允许创建分支剧情和复杂的任务链，其中 NPC 的交互顺序至关重要。

一个强大的功能是“最后按钮”系统，它允许将任何按钮标记为最终交互。当玩家点击最后按钮时，对话会关闭，他们将无法再与该 NPC 交互。这对于完成故事情节或在完成后锁定内容非常完美。当玩家在点击最后按钮后尝试与 NPC 交互时，他们将看到一个带有自定义消息的“完成页面”。

该插件包含一个可通过 `/npcquest` 命令访问的全面管理界面。此界面提供所有任务相关设置的便捷配置，无需手动编辑 JSON 文件。管理员可以选中 NPC、对话页面和单个按钮来配置其前置要求和奖励。

配置指南:

安装:

前提：在安装 NPC 任务之前，必须安装并运行 NPC 对话插件。

1. 首先安装并配置 NPC 对话插件
2. 将 NPC 任务的 JAR 文件放入服务器的 mods 文件夹
3. 重启服务器
4. 该插件将自动检测并与 NPC 对话集成

访问管理界面:

使用命令 `/npcquest` 或 `/npcquests` 打开任务配置界面。您需要拥有 `npcquests.admin` 权限才能使用此命令。

基本设置:

1. 从顶部的下拉菜单中选中一个 NPC
2. 为该 NPC 选中一个对话页面
3. 选中要配置的按钮（下一页、上一页、关闭、自定义按钮 1 或自定义按钮 2）
4. 根据需要配置前置要求和奖励
5. 点击“保存”以保存更改

前置要求类型:

物品要求：
物品要求会检查玩家在点击按钮前是否在背包中拥有特定物品。您可以为单个按钮添加多个物品要求。

添加物品要求：
- 在“物品 ID”字段中输入物品 ID（例如：Plant_Fruit_Apple）
- 在“数量”字段中输入所需数量
- 如果您希望在满足要求时移除物品，请勾选“消耗”复选框
- 点击“添加物品要求”

移除物品要求：
- 在列表中找到该要求
- 点击其旁边的“移除”按钮

物品 ID 必须与 Hytale 的物品系统完全匹配。常见的物品 ID 包括 Plant_Fruit_Apple、Ore_Iron、Weapon_Sword_Wooden 等。

NPC 前置要求：
NPC 前置要求要求玩家必须先与其他 NPC 交互，然后才能访问某些按钮或 NPC。这会创建任务链，玩家需要按特定顺序与 NPC 交谈。

添加 NPC 前置要求：
- 导航到 npcs.json 文件，搜索 NPC 并复制 NPC ID。
- 点击“添加 NPC 前置要求”

移除 NPC 前置要求：
- 在列表中找到该前置要求
- 点击其旁边的“移除”按钮

NPC 前置要求会在以下情况检查：
- 玩家尝试与 NPC 交互时（检查要求页面的按钮前置条件）
- 玩家点击已配置 NPC 前置要求的按钮时

如果未满足前置要求，玩家将看到一条可自定义的失败消息，并且无法继续。

自定义要求：
自定义要求通过 RequirementChecker API 与其他插件集成。这允许 NPC 对话检查来自其他插件（如经济系统、等级系统或自定义任务追踪器）的条件。

添加自定义要求：
- 输入要求 ID（由另一个插件通过 API 注册）
- 输入所需数量（对于布尔检查，使用 0）
- 点击“添加自定义要求”

移除自定义要求：
- 在列表中找到该要求
- 点击其旁边的“移除”按钮

要求 ID 必须由另一个使用 NPC 对话 API 的插件注册。请联系其他插件的开发者以了解可用的要求 ID。

奖励类型:

物品奖励：
当玩家点击已配置奖励的按钮时，物品奖励会给予玩家物品。您可以为单个按钮添加多个物品奖励。

添加物品奖励：
- 在“物品 ID”字段中输入物品 ID
- 在“数量”字段中输入给予数量
- 点击“添加物品奖励”

移除物品奖励：
- 在列表中找到该奖励
- 点击其旁边的“移除”按钮

物品会给予到玩家的背包。如果背包已满，根据服务器设置，物品可能会掉落或丢失。

自定义奖励：
自定义奖励通过 RewardProvider API 与其他插件集成。这允许 NPC 对话授予来自其他插件（如经济系统、经验系统或自定义奖励追踪器）的奖励。

添加自定义奖励：
- 输入奖励 ID（由另一个插件通过 API 注册）
- 输入给予数量
- 点击“添加自定义奖励”

移除自定义奖励：
- 在列表中找到该奖励
- 点击其旁边的“移除”按钮

奖励 ID 必须由另一个使用 NPC 对话 API 的插件注册。请联系其他插件的开发者以了解可用的奖励 ID。

控制台命令：
当点击具有奖励的按钮时，控制台命令会执行服务器命令。命令以控制台身份执行，意味着它们拥有完全权限，并且可以使用管理员命令。

添加控制台命令：
- 在“命令”字段中输入完整命令（例如：give @p Plant_Fruit_Apple --quantity=5）
- 点击“添加控制台命令”

移除控制台命令：
- 在列表中找到该命令
- 点击其旁边的“移除”按钮

命令支持像 `@p` 这样的占位符，代表触发按钮的玩家。所有命令都以控制台权限执行。

要求页面配置:

要求页面是一个特殊的对话页面，当玩家首次与 NPC 交互但未满足访问主对话的前置要求时显示。您可以通过从“页面”下拉菜单中选中“要求页面”来配置此页面。

NPC 前置要求失败消息：
此消息会在玩家未与必需的前置 NPC 交谈时显示给他们。您可以使用 `{PREREQNPC}` 占位符代表前置 NPC 名称，使用 `{NPC}` 占位符代表当前 NPC 名称。

未满足要求标题：
当未满足要求时，此标题会显示在对话标题栏中。留空则使用页面标题。

关闭按钮文本：
当未满足要求时，关闭按钮上显示的文本。留空则使用默认文本。

最后按钮功能:

最后按钮功能允许将任何按钮标记为与 NPC 的最终交互。当玩家点击最后按钮时：

1. 对话立即关闭
2. 此次交互被标记为已完成
3. 玩家无法再与此 NPC 交互

如果玩家在点击最后按钮后尝试与 NPC 交互，他们将看到完成页面而不是正常的对话。

启用最后按钮：
1. 选中您想要设为最后按钮的 NPC、页面和按钮
2. 勾选“标记为最后按钮”复选框
3. 配置完成页面设置（见下文）
4. 点击“保存”

完成页面配置:

当玩家在点击最后按钮后尝试与 NPC 交互时，会显示完成页面。在启用最后按钮复选框时，在管理界面中配置此页面。

完成页面标题：
显示完成页面时，对话标题栏中显示的标题。

完成页面消息：
向玩家解释他们已经完成此次交互的主要消息。

完成关闭按钮文本：
完成页面的关闭按钮上显示的文本。

数据存储:

所有任务配置数据都存储在 JSON 文件中，位于服务器数据目录中的 `Hyronix_NPC Quests` 文件夹内。`interactionHistory.json` 文件会追踪哪些玩家与哪些 NPC 交互过，包括哪些交互被标记为已完成。

数据文件夹结构：
- `Hyronix_NPC Quests/`
- `npcs/`（单个 NPC JSON 文件）
- `interactionHistory.json`（玩家交互追踪）

交互追踪:

该插件会自动追踪所有玩家与 NPC 的交互。此追踪用于：
- 检查 NPC 前置要求
- 在启用最后按钮时防止重复交互
- 维护任务进度状态

交互历史记录按玩家存储，并在服务器重启后保持不变。要重置玩家的交互历史，您可以手动编辑或删除 `interactionHistory.json` 中的条目。

按钮配置:

您可以配置以下按钮的前置要求和奖励：
- 下一页按钮：前进到下一个对话页面的按钮
- 上一页按钮：返回到上一个对话页面的按钮
- 关闭按钮：关闭对话的按钮
- 自定义按钮 1：第一个可自定义的按钮（如果在对话页面上启用）
- 自定义按钮 2：第二个可自定义的按钮（如果在对话页面上启用）

每个按钮可以有：
- 多个物品要求
- 多个 NPC 前置要求
- 多个自定义要求
- 多个物品奖励
- 多个自定义奖励
- 多个控制台命令
- 最后按钮状态

按钮工作流程:

当玩家点击按钮时，按顺序发生以下事情：

1. 检查前置要求：
- 物品要求：检查玩家是否拥有所需物品
- NPC 前置要求：检查玩家是否与要求的 NPC 交谈过
- 自定义要求：使用已注册的要求检查器进行检查

2. 如果任何要求失败：
- 向玩家显示失败消息
- 不给予奖励
- 按钮操作不继续

3. 如果所有要求都通过：
- 消耗要求的物品（如果启用了消耗）
- 给予奖励：
- 物品奖励添加到背包
- 自定义奖励由已注册的奖励提供者处理
- 执行控制台命令

4. 如果启用了最后按钮：
- 对话关闭
- 交互被标记为已完成
- 玩家无法再次与此 NPC 交互

5. 如果未启用最后按钮：
- 正常的按钮操作继续（页面更改、关闭对话等）

任务系统使用指南

本指南说明如何将任务系统与 NPC 对话结合使用，特别是 `quest:` 类型的奖励和要求 ID。

快速开始：如何制作一个任务
按照以下 3 个简单步骤制作一个基本任务（命名为 'quest_a'）：

1. 开始按钮（让玩家接受）
- 奖励 ID：quest:start:quest_a
- 要求 ID：quest:status:quest_a:AVAILABLE
- 结果：按钮仅在玩家没有此任务时显示。点击它可开始任务。

2. 完成按钮（让玩家完成）
- 奖励 ID：quest:complete:quest_a
- 要求 ID：quest:active:quest_a
- 结果：按钮仅在玩家拥有此任务时显示。点击它可完成任务。

3. 下一页按钮（让玩家继续）
- 要求 ID：quest:completed:quest_a
- 结果：玩家无法点击“下一页”，直到他们完成任务。

奖励 ID（要执行的操作）

1. quest:start:<quest_id>
- 描述：开始指定的任务（将状态设置为 ACTIVE）。
- 注意：如果任务已经是 ACTIVE 或 COMPLETED 状态，则不执行任何操作。

2. quest:complete:<quest_id>
- 描述：完成指定的任务（将状态设置为 COMPLETED）。

3. quest:set_status:<quest_id>:<status>
- 状态：LOCKED, AVAILABLE, ACTIVE, COMPLETED。

要求 ID（检查任务状态）

1. quest:active:<quest_id>
- 条件：玩家必须拥有 ACTIVE 状态的任务。

2. quest:completed:<quest_id>
- 条件：玩家必须拥有 COMPLETED 状态的任务。

3. quest:status:<quest_id>:<status>
- 条件：玩家必须精确拥有指定的状态。

示例：4按钮设置（'quest_a' 的生命周期）

此设置允许一个 NPC 使用 4 个按钮处理任务的整个流程。

1. 自定义按钮 1: "接受任务"
- 要求：quest:status:quest_a:AVAILABLE
- 奖励：quest:start:quest_a
- 逻辑：初始只显示此按钮。点击它开始任务并使此按钮消失。

2. 自定义按钮 2: "完成任务"
- 要求：quest:active:quest_a
- 奖励：quest:complete:quest_a
- 逻辑：仅在你拥有任务时出现。点击它完成任务。（你也可以在这里添加物品要求！）

3. 下一页按钮（默认导航）
- 要求：quest:completed:quest_a
- 逻辑：此按钮在你完成任务之前是“灰色”或隐藏的。仅在完成后允许移动到下一个对话页面。

4. 关闭按钮（默认导航）
- 要求：（无）
- 逻辑：始终可用，以便玩家可以离开对话。

提示

- 多个要求：您可以将任务要求与物品结合（例如，必须拥有 5 个苹果并且任务必须是活动的）。
- 性能：任务在玩家实体上本地处理。

权限:

唯一需要的权限是用于访问 `/npcquest` 命令的 `npcquests.admin`。一旦配置完成，所有任务逻辑和要求都会自动为所有玩家工作。

提示和最佳实践:

1. 在创建任务链之前先规划好。画出需要以何种顺序与哪些 NPC 交谈。

2. 使用有意义的 NPC 名称和对话内容，自然地引导玩家完成您的任务链。

3. 彻底测试您的任务链。确保前置要求正确工作，并且奖励能正确给予。

4. 谨慎使用最后按钮功能。仅在您真正希望阻止进一步交互时才将按钮标记为最后按钮。

5. 如果您与自定义插件集成，请记录您的需求 ID 和奖励 ID。这会使配置更容易。

6. 对于物品或自定义奖励无法处理的复杂奖励场景，请使用控制台命令。

7. 在配置前置要求或奖励后，务必保存更改。未保存的更改将会丢失。

8. 管理界面会显示所有已配置的前置要求和奖励。在游戏中测试之前，使用它来验证您的配置。

故障排除:

问题：未检查前置要求
解决方案：确保在添加前置要求之前选中了正确的 NPC、页面和按钮。确保在做出更改后点击了“保存”。

问题：未给予奖励
解决方案：验证是否满足了前置要求。奖励仅在满足所有要求时触发。检查物品 ID 是否正确，以及自定义奖励 ID 是否已注册。

问题：NPC 前置要求不工作
解决方案：确保前置 NPC 已在 NPC 对话中配置。前置 NPC 必须存在且可访问。验证交互历史记录是否被正确追踪。

问题：最后按钮未能阻止交互
解决方案：确保您保存了最后按钮的配置。检查 `interactionHistory.json` 文件是否正确写入。

问题：无法访问管理界面
解决方案：验证您是否拥有 `npcquests.admin` 权限。检查 NPC 对话插件是否已安装并工作。确保 NPC 任务附加组件已成功加载且没有错误。

问题：自定义前置要求或奖励不工作
解决方案：验证另一个插件是否已将其 RequirementChecker 或 RewardProvider 注册到 NPC 对话。检查插件之间的要求 ID 和奖励 ID 是否精确匹配。

高级功能:

NPC 任务附加组件包含对 RequirementChecker 和 RewardProvider API 的支持。其他插件可以注册自定义的需求检查器和奖励提供者，从而允许 NPC 对话与其他服务器系统深度集成。

面向开发者的 NPC 对话 API 文档:

入门:

获取插件实例：
NPCDialogPlugin plugin = NPCDialogPlugin.getInstance();
if (plugin == null) {
return; // NPC Dialog not installed
}

需求检查器 API:

注册玩家在 NPC 对话中必须满足的自定义要求。

接口：com.hytale.npcdialog.api.RequirementChecker

方法：
boolean checkRequirement(Player player, String requirementId)
如果玩家满足要求，则返回 true。

String getErrorMessage(String requirementId)
可选。返回自定义错误消息或 null 以使用默认消息。

注册：
plugin.registerRequirementChecker("economy.money", new RequirementChecker() {
@Override
public boolean checkRequirement(Player player, String requirementId) {
// Check if player has enough money
return hasEnoughMoney(player);
}

@Override
public String getErrorMessage(String requirementId) {
    return "You do not have enough money.";
}

});

奖励提供者 API:

注册可通过 NPC 交互给予玩家的自定义奖励。

接口：com.hytale.npcdialog.api.RewardProvider

方法：
boolean giveReward(Player player, String rewardId, double amount)
如果奖励成功给予，则返回 true。

String getRewardMessage(String rewardId, double amount)
返回在给予奖励时显示的消息。

注册：
plugin.registerRewardProvider("economy.money", new RewardProvider() {
@Override
public boolean giveReward(Player player, String rewardId, double amount) {
// Give money to player
return addMoney(player, amount);
}

@Override
public String getRewardMessage(String rewardId, double amount) {
    return "You received " + amount + " coins!";
}

});

用法:

一旦注册，管理员就可以在 NPC 任务管理界面中使用您的需求 ID 和奖励 ID。使用描述性的、带命名空间的 ID，例如 "yourplugin.feature.requirement"。

清理:

在插件关闭时注销：
plugin.unregisterRequirementChecker("economy.money");
plugin.unregisterRewardProvider("economy.money");

分发声明:
未经 明确并显著注明 Hyronix Studios 版权所有 及模组名称，禁止重新分发或与第三方设置捆绑。否则，不允许重新分发。