Quest Codex
Quest Codex 扩展提供一个完全可自定义的 GUI 系统，让玩家浏览、追踪并管理按层级类别组织的任务。每个菜单都通过由 GUI 扩展驱动的声明式布局池构建 —— 没有硬编码菜单，可无限自定义。
功能
- 层级类别 — 通过父/子关系嵌套类别。子类别继承其父类别的可见性。
- 布局池 — 通过声明式布局池设计每个菜单。占位符（
SORT_SLOT、CATEGORY_SLOT、QUEST_SLOT）会自动注入。 - 可滚动任务列表 — 任务与类别槽位遵循
scrollable、paginated和frame视口 —— 可构建任意大小的滚动任务网格（自 0.3.0 起）。 - 动态排序 — 在 全部 → 未开始 → 进行中 → 已完成 之间循环，每种模式有独立的按钮显示（标签、Lore、自定义物品）。
- 任务追踪 — 通过 QuestExtension 的原生追踪系统，以优先级指示器追踪活动任务。
- 完整音效设计 — 为菜单打开、点击、滚动以及任务追踪/取消追踪事件配置音效。
- BlueMap 集成 — 在 BlueMap 上显示任务图标，带动态标签与可见性规则（BTC 版本）。
- 布局池 — 通过声明式布局池设计每个菜单。占位符（
架构
条目库
配置
- Quest Codex Config — 全局音效、默认行数与消息模板。
类别系统
- Quest Category — 定义带标题、图标、父级和可见性条件的类别。
- Quest Assignment — 将任务条目链接到某个类别，带排序与按状态覆盖。
菜单与显示
- Category Menu — 用声明式布局池、占位符槽位和按模式的排序按钮来设计菜单。
- Quest Lore — 按任务和按状态覆盖 Lore 文本行。
快速开始
-
1. 添加全局配置（可选） — 在页面 JSON 中创建一个 Quest Codex Config 条目以自定义音效和消息。没有它扩展也能开箱即用 —— 它使用合理的默认值。
json { "type": "quest_codex", "id": "my_codex_config", "defaultRows": 5, "nowTrackingMessage": "<green>Now tracking: {quest}</green>" }将它放到plugins/Typewriter/pages/下任意已编译的页面中。→ Quest Codex Config -
2. 定义类别 — 添加一个 Quest Category 条目。它在图鉴中定义一个逻辑任务组，包含显示标题、图标以及用于嵌套的可选父级。关键字段： -
category—— 唯一的内部名称（例如main_quests） -title—— 向玩家显示的标题（MiniMessage） -icon—— 在父级/类别列表中显示的物品 -parent—— 顶层留空，或设置以进行嵌套 → Quest Category -
3. 分配任务 — 添加一个 Quest Assignment 条目，将你的 QuestExtension 任务链接到某个类别。可控制排序与按状态覆盖。
json { "type": "quest_assignment", "id": "assign_main", "category": "main_quests", "questRefs": ["quest:quest_main_1", "quest:quest_main_2"], "orders": [0, 1] }→ Quest Assignment -
4. 设计菜单 — 为每个你想要自定义 GUI 的类别添加一个 Category Menu 条目。使用布局池来放置：-
CATEGORY_SLOT—— 自动注入的类别图标（主菜单） -QUEST_SLOT—— 自动注入的任务按钮（类别菜单） -SORT_SLOT—— 自动注入的动态排序按钮 - 标准 GUI 物品 —— 装饰物品、填充、静态按钮 布局池使用 CUSTOM guiType。一切都是基于位置的：将物品放在 (x, y) 坐标处。→ Category Menu -
5. 打开菜单 — 通过命令访问图鉴：
/tw codex → 图鉴主菜单（自 0.3.0 起） /tw codex <category> → 某个特定类别示例：-/tw codex main_quests—— 打开主线任务类别 -/tw codex daily_tasks—— 打开每日任务 > 主菜单： 要么创建一个category为空且带CATEGORY_SLOT标记的category_menu条目，要么将中枢构建为 GUI 扩展的open_gui菜单，其按钮运行codex:open <category>，并在配置的mainMenuTrigger中引用它 —— 这样/tw codex和图鉴的BACK按钮就会打开它。
命令
| 命令 | Permission | 说明 |
|---|---|---|
/tw codex | typewriter.codex.open | 打开图鉴主菜单（空类别的 category_menu，或配置的 mainMenuTrigger）。 |
/tw codex <category> | typewriter.codex.open | 直接打开某个特定的任务类别。支持 Tab 补全。 |
占位符
前缀： %typewriter_*%
全局占位符
| 占位符 | 返回 | 示例 |
|---|---|---|
%typewriter_total_quests% | 所有类别的任务总数 | 42 |
%typewriter_total_completed% | 已完成任务总数 | 15 |
%typewriter_total_in_progress% | 进行中任务总数 | 5 |
%typewriter_total_not_started% | 未开始任务总数 | 22 |
%typewriter_total_progress% | 已完成/总数（已格式化） | 15/42 |
按类别的占位符
将 <name> 替换为类别标识符（例如 main_quests）。
| 占位符 | 返回 | 示例 |
|---|---|---|
%typewriter_category_<name>% | 该类别的任务总数 | 10 |
%typewriter_category_<name>_completed% | 该类别已完成数 | 3 |
%typewriter_category_<name>_in_progress% | 该类别进行中数 | 2 |
%typewriter_category_<name>_not_started% | 该类别未开始数 | 5 |
%typewriter_category_<name>_progress% | 进度（已格式化） | 3/10 |
别名：
_inprogress%和_notstarted%也可用。
模板变量（用于 @Placeholder 字段）
| 变量 | 上下文 | 替换为 |
|---|---|---|
{quest} | 消息模板 | 任务的显示名称 |
{completed} | 进度消息 | 已完成任务数量 |
{total} | 进度消息 | 该类别的任务总数 |
权限
| Permission | 说明 |
|---|---|
typewriter.codex.open | 打开任务图鉴。 |
依赖
| Extension | 是否必需 | 用途 |
|---|---|---|
| QuestExtension | 必需 | 核心任务引擎。 |
| GUI Extension | 必需 | 菜单渲染与布局池系统。 |
| PlaceholderAPI | 可选 | 用于 @Placeholder 字段。 |