Quest Codex
概览
Quest Codex 为玩家提供一本任务书。主菜单列出分类（主线故事、支线任务、地下城……），每个分类会打开其任务列表，点击进行中的任务即可追踪它。任务本身是你用 TypeWriter 官方 Quest 扩展创建的：Quest Codex 只负责整理和显示它们。
每个界面都由你自己绘制。菜单是 GUI 扩展的一个布局，你在其中放置标记物品：QUEST_SLOT 标记会被替换为玩家的任务，CATEGORY_SLOT 标记会被替换为分类，SORT_SLOT 标记会被替换为排序按钮。标记周围的一切（边框、标题、按钮、滚动、分页）都是普通的 GUI 内容。
除了菜单之外，该扩展还增加了可在重新连接后保留的多任务追踪、对被中断的对话或过场动画的恢复、客户端 GPS 路径点和定位栏圆点、通过页面授予的自定义 Minecraft 成就，以及 BlueMap 上的任务图标。
功能
- 分类 — 可嵌套的分类，带有顺序、图标、可见性和完成条件，以及按状态区分的消息。
- 任务分配 — 将任务放入某个分类，设置其顺序，并按状态覆盖图标、名称、lore 和可见性。
- 布局池 — 你用 GUI 布局设计每个菜单；codex 会填充
QUEST_SLOT、CATEGORY_SLOT、TRACKED_QUEST_SLOT和SORT_SLOT标记。 - 排序按钮 — 在全部、未开始、进行中和已完成之间循环，每种模式都有标签、图标和 lore。
- 多任务追踪 — 同时追踪多个进行中的任务；最后一个是官方 HUD 追踪器的主要任务。
- 被追踪任务菜单 — 专门列出玩家正在追踪的任务的菜单。
- 路径点 — 仅数据包的文本、方块和信标图层，指向某个目标、位置或实体，另有原版定位栏的变体。
- 交互恢复 — 在断开连接后恢复进行中的对话或过场动画。
- 成就 — 在面板中定义 Minecraft 成就标签页，并通过动作授予。
- BlueMap 图标 — 在 BlueMap 上放置带弹窗的任务图标。
安装
- 在 Paper 或 Folia 服务器上安装 TypeWriter，并安装其官方 Quest 扩展，它定义了 Quest Codex 所显示的任务。
- 安装 GUI 扩展（0.18 或更新版本）。
- 可选：安装 PacketEvents（TypeWriter 已经需要它）以使用路径点，并安装 BlueMap 以使用地图图标。
- 从 GitHub Releases（上方摘要面板中的按钮）下载 Quest Codex 的 JAR，放入
plugins/Typewriter/extensions/并重启服务器。 - 为你的玩家授予
typewriter.codex.open权限，参见下方的“权限”。
快速上手
构建一个带有一个分类的任务日志：
- 在一个**静态（static）**页面上，添加一个 Quest Codex Tracking Data 条目。被追踪的任务就保存在这里。
- 在一个**清单（manifest）**页面上，添加一个 Quest Codex Global Settings 条目。将
trackingArtifact设为该构件，并检查maxTrackedQuests和音效。 - 添加一个 Quest Category 条目，
category为main_quests，title例如<gold>Main Story，并设置一个icon。 - 添加一个 Quest Assignment 条目，
category为main_quests，并在questRefs中填入你的任务。orders是可选的。 - 创建两个仅用作布局容器的 Open GUI 条目。在第一个
main_gui中，添加一个id为main的simple布局，将mainLayoutId设为main，guiType设为CUSTOM，size设为SIZE_36。添加一个物品，buttonPrefix为codex_button:，buttonType为CATEGORY_SLOT，x为 1，y为 1，count为 7，direction为right。在第二个quests_gui中做同样的设置，但使用标记QUEST_SLOT，并在最下面一行添加一个CLOSE物品。 - 添加一个 Category Menu，
category留空，rows为4，menu设为main_gui。这就是主菜单。 - 再添加第二个 Category Menu，
category为main_quests，rows为4，menu设为quests_gui。 - 发布，然后在游戏中运行
/tw codex。点击分类，再点击一个进行中的任务来追踪它。
物品栏是根据 Category Menu 的 rows 构建的，而不是根据 Open GUI 的 size。如果二者不同，低于较小高度的槽位会被丢弃，并且控制台会在启动时发出警告。
一个标记槽位显示一个任务。使用 count、direction、gap 和 repeatY 可将一个标记铺展到整个网格：count 为 7、direction 为 right、repeatY 为 3 即可得到 21 个任务槽位。没有 direction 时，标记保持为单个槽位。任务按阅读顺序填充标记，并通过 PAGE_NEXT 按钮翻到下一页任务。
工作原理
启动时，扩展会加载分类、分配和菜单。玩家打开菜单时，它会在解析布局之前，将布局中的每个标记改写为带索引的标记（QUEST_SLOT#0、QUEST_SLOT#1……），因此标记在 scrollable、paginated 和 frame 布局中的行为就像普通槽位一样。渲染时，每个标记会被替换为第 n 个任务或分类。
菜单
哪些条目组成菜单
Category Menu 是你要打开的条目。它的 menu 字段指向一个 Open GUI 条目，该条目只提供布局池、主布局、窗口类型和音效。请不要自己去触发那个 Open GUI。
Category Menu 的 category | 菜单 | 必须包含的标记 |
|---|---|---|
| 空 | 列出根分类的主菜单 | CATEGORY_SLOT |
| 分类名称 | 该分类的任务 | QUEST_SLOT |
@tracked | 玩家正在追踪的任务 | TRACKED_QUEST_SLOT |
每个已定义的分类都需要一个 Category Menu，否则打开它不会有任何反应，并且控制台会在启动时指出这一点。
标记与按钮
将 buttonPrefix 设为 codex_button:，并将 buttonType 设为以下之一：
buttonType | 作用 |
|---|---|
CATEGORY_SLOT | 一个分类图标，带有其标题、进度 {completed}/{total}、点击提示和状态消息。点击会打开该分类。 |
QUEST_SLOT | 一个任务。图标跟随其状态，名称和 lore 来自任务、分配和 Quest Lore 条目。点击进行中的任务会追踪或取消追踪它。 |
TRACKED_QUEST_SLOT | @tracked 菜单中的一个被追踪任务。空槽位会保留你自己的物品并保持无反应，因此它就是你的空状态。 |
SORT_SLOT | 排序按钮。在 Category Menu 的 sortDisplay 中配置每种模式。 |
PAGE_NEXT、PAGE_PREV | 切换到任务或分类的下一页或上一页。 |
SCROLL_UP、SCROLL_DOWN、SCROLL_LEFT、SCROLL_RIGHT | 滚动菜单。 |
BACK | 如果有主菜单则返回主菜单，否则返回 mainMenuTrigger 条目，再否则返回上一个菜单，再否则关闭。 |
CLOSE | 关闭菜单。 |
SORT | 作为普通导航槽位放置的排序按钮。 |
导航按钮会保留你配置的物品、名称和 lore；仅当槽位没有物品时，才会使用内置的箭头、屏障或漏斗。
请将标记放在属于 menu 所引用的 Open GUI 的 simple 布局中。位于其他布局类型中，或位于共享底盘布局中的标记不会被建立索引，并保持隐藏。
底盘、视图与标签页
若要构建带标签页的任务书，请将 Category Menu 的 baseMenuId 设为一个共享的 Open GUI 外壳，并添加 views、defaultViewId 和 breadcrumbSeparator，做法与视图、标签页和继承中完全相同。pushHistoryOnViewSwitch 会让“返回”回到上一个标签页。根布局具有 _extended 变体的底盘会自动获得十行的画布。
任务显示
- 对于未开始、进行中和已完成，任务图标默认分别为书、时钟和绿宝石。可在 Quest Assignment 中按状态覆盖它（
notStartedItem、inProgressItem、completedItem）。 notStartedName、inProgressName和completedName会替换任务名称，对应的 lore 字段会添加行。使用hideWhenNotStarted、hideWhenInProgress和hideWhenCompleted可按状态隐藏任务。- Quest Lore 条目会按状态为任务添加行，可作用于一个分类或所有分类。
- 任务顺序首先遵循
orders，然后是questRefs的顺序。分类还会列出其子分类的任务。 - 主菜单只列出顶级分类（没有
parent的分类）。子分类通过/tw codex <category>或运行codex:open <category>的按钮打开。
配置
Quest Codex Global Settings 条目包含与菜单无关的选项。只创建一个；没有它时会使用默认值。
- 音效 —
soundOnOpen、soundOnSwitch、soundOnClick、soundOnTrack、soundOnUntrack。 - 追踪 —
multiTrackingEnabled、maxTrackedQuests（至少为 1）和trackingArtifact。没有构件时，被追踪的任务只保存在内存中，并且控制台会在启动时发出警告。该构件是一个文件，一旦玩家开始使用，就必须保持其artifactId不变。 - 恢复 —
recoveryEnabled、recoveryArtifact、recoveryRetentionSeconds（10 到 86400）和recoveryRestoreDelayTicks（1 到 20）。当玩家在对话或过场动画期间离开时，会保存快照，并在玩家重新加入后不久恢复。没有构件时，恢复功能被禁用。 - 消息 —
nowTrackingMessage、stoppedTrackingMessage、questInactiveMessage、questCompletedMessage、trackingLimitMessage（{quest}、{max}）、categoryProgressMessage（{completed}、{total}），以及分类和任务 lore 上的提示。 - 导航标签 —
navLabels设置每个内置按钮（next、previous、up、down、left、right、back、close、sort）的名称。仅当带标签的槽位没有自己的物品时才会使用：带有物品的槽位保留其自身的名称和 Lore。 - 排序按钮 —
sortTexts设置每种排序模式的标签（allLabel、notStartedLabel、activeLabel、completedLabel）以及 Lore 行hint。若某个 Category Menu 在其sortDisplay中为某种模式设置了label或lore，则保留其自身的设置。 - 菜单标题 —
mainMenuTitle和trackedQuestsTitle是在对应的 Category Menu 的title为空时使用的标题。 - 命令错误 —
unknownCategoryMessage是/tw codex <category>针对不存在的分类显示的错误（{category}）。 - 主菜单后备 — 当没有主 Category Menu 时会触发
mainMenuTrigger，例如你自己的某个 Open GUI，其按钮运行codex:open <category>。
路径点与定位栏
Quest Codex Waypoint 是一个受众条目：将它连接到受众筛选器，以选择谁能看到它。它的 target 可以是固定位置、可定位的目标、被追踪的目标（选择方式为 HIGHEST_PRIORITY、FIRST、CLOSEST、ALL 或 ONE_PER_QUEST）或一个实体。它的 layers 由文本图层（占位符 {icon}、{distance}、{distance_m}、{distance_km}、{elevation}、{direction}、{vertical_direction}、{target}、{world_name}、{height_diff} 和 {eta}）、方块图层和信标图层组合而成。displayMode 为 HUD_LOCKED（默认）、WORLD_DIRECTIONAL、TARGET_ANCHORED 或 ADAPTIVE，每个图层都可以覆盖它。所有内容都通过数据包发送；世界中不会保存任何实体。
Quest Codex Locator Bar 会在原版定位栏上以圆点显示相同的目标，这需要 Minecraft 1.21.6 或更新版本，并可与 3D 路径点搭配使用。
成就与 BlueMap
- Advancement Definition 描述一个成就。没有
parent的会成为一个标签页。它们会在启动时写入世界文件夹中名为questcodex_advancements的数据包，并且在内容发生变化时服务器会重新加载其数据，因此新增定义需要重启。成就只能通过 Grant Advancement 动作获得。 - BlueMap Icon 会在启动时，在其所在世界的 BlueMap 地图上放置一个带有标签和弹窗的标记。在
description中，<objectives>会被替换为该任务的目标。
命令
所有命令都是 /typewriter 的子命令，通常输入为 /tw，并且需要 typewriter.codex.open。
| 命令 | 说明 |
|---|---|
/tw codex | 打开主菜单：category 为空的 Category Menu，否则为 mainMenuTrigger 条目。 |
/tw codex tracked | 打开被追踪任务菜单。 |
/tw codex <category> | 打开一个分类。Tab 补全会列出已定义的分类。 |
菜单按钮还可以运行这些内部命令：codex:open <category>、codex:tracked、codex:quest <quest_id> 和 codex:nav <action>。请在你自己的 GUI 菜单的按钮中使用 codex:open 和 codex:tracked。
权限
| 权限 | 授予 |
|---|---|
typewriter.codex.open | 所有 /tw codex 命令。扩展以仅限管理员的默认值声明了它，它会出现在你的权限插件中：请把它授予可以使用 /tw codex 的组。 |
通过 Category Menu 动作或菜单按钮打开菜单不需要权限。
占位符
PlaceholderAPI 占位符，使用 typewriter 扩展。它们需要一名玩家。
| 占位符 | 返回 |
|---|---|
%typewriter_total_quests% | 所有分类中的任务数量。 |
%typewriter_total_completed%、%typewriter_total_in_progress%、%typewriter_total_not_started% | 该玩家在每种状态下的任务数量。 |
%typewriter_total_progress% | 已完成数除以总数，例如 15/42。 |
%typewriter_category_<name>% | 该分类中的任务数量。 |
%typewriter_category_<name>_completed%、_in_progress%、_not_started% | 该分类中处于该状态的任务。 |
%typewriter_category_<name>_progress% | 该分类已完成数除以总数。 |
%typewriter_codex_tracked_count%、_limit% | 被追踪的任务数量及其上限。 |
%typewriter_codex_tracked_multi_enabled%、_has_any% | true 或 false。 |
%typewriter_codex_tracked_ids%、_names%、_names_lines% | 被追踪任务的 id 或名称，以逗号分隔或每行一个。 |
%typewriter_codex_tracked_primary_id%、_primary_name% | 官方追踪器所显示的主要任务。 |
%typewriter_codex_tracked_has_<quest_id>% | 该任务是否被追踪。 |
%typewriter_codex_tracked_<n>_id%、_name%、_status%、_primary% | 第 n 个被追踪任务的详细信息，从 1 开始。没有时为空。 |
%typewriter_codex_tracked_<n>_objective_count%、_objectives%、_objectives_lines%、_priority% | 第 n 个被追踪任务的可见目标。 |
<name> 是分类名称，匹配时不区分大小写。更多详情请参见占位符、命令和权限。
条目
12 个条目，由扩展源码生成。
动作2
- Category MenuCategory Menu Configuration
- Grant AdvancementGrant Advancement
受众2
- Quest Codex Locator BarQuest Codex Locator Bar
- Quest Codex WaypointQuest Codex Waypoint
构件2
- Quest Codex Recovery ArtifactQuest Codex Recovery Data
- Quest Codex Tracking ArtifactQuest Codex Tracking Data
清单6
- Advancement DefinitionAdvancement Definition
- Bluemap IconAdds an icon to BlueMap for a specific quest
- Quest AssignmentQuest Assignment to Category
- Quest CategoryQuest Category
- Quest CodexQuest Codex Global Settings
- Quest LoreQuest Additional Lore
故障排查
/tw codex 没有任何反应。 没有 category 为空的 Category Menu，也没有 mainMenuTrigger。控制台会记录 Main menu could not open 及其原因。对于分类，请创建一个 category 与 Quest Category 的 category 相同的 Category Menu。
菜单打开后里面什么都没有。 控制台会在启动时报告原因：所引用的 Open GUI 中没有任何槽位带有该菜单所需的标记（CATEGORY_SLOT、QUEST_SLOT 或 TRACKED_QUEST_SLOT）、menu 为空或不是 Open GUI、布局池为空，或者 mainLayoutId 不在其中。标记需要 buttonPrefix 为 codex_button:。
较低几行的槽位缺失。 Category Menu 的 rows 小于 Open GUI 的 size。请将两者设置为相同的行数。
任务之间相隔一个槽位，而不是中间空一个槽位。 gap 是步长：1 表示相邻，2 则留出一个空槽位。在 Quest Codex 0.3.0 之前编写的菜单把 gap 当作间距使用，因此请将该值翻倍。与装饰物发生冲突时会报告 Slot overlap 警告。
多个标记堆叠在同一个格子上。 该标记有 count 但没有 direction，或者位置落在网格之外。请设置 direction。
某个分类中缺少一个任务。 该任务被其当前状态对应的某个 hideWhen... 选项隐藏，当前的排序模式将其过滤掉了，或者分配无法解析它（控制台中出现 Quest '...' could not be resolved）。
重启后被追踪的任务消失。 trackingArtifact 为空，或其 artifactId 发生了变化。不再处于进行中状态的任务会从被追踪列表中移除。
路径点不显示。 路径点条目必须位于玩家所匹配的受众之内，任务必须被追踪，并且目标必须是可定位的。带有 {icon} 的文本图层在设置 icon 之前会一直为空。
服务器不认识新的成就。 定义是在启动时写入的；添加后请重启。图标不是物品的定义会被跳过并给出警告。