Codex

发现图鉴，包含可解锁的分类、配方书和可收集碎片。

私有v0.0.3任务与剧情

依赖TypeWriter0.9BasicGUIQuest可选Quest Codex可选

专为 BornToCraft 服务器网络打造。此扩展仅作参考文档，不对外分发。

支持

概述

Codex 是一本发现日志。你定义分类（怪物图鉴、传说典籍、地点列表）以及其中的物品，每个物品或分类都通过 TypeWriter 的条件（criteria）解锁：一个 fact、一个任务状态、一个权限，或条件可以检查的任何内容。被锁定的条目仍然可见，并带有它们自己的 lore，因此玩家能看到还剩下什么可以发现。你还可以添加配方分类，当玩家点击某个配方时，会在一个小型工作台视图中显示原版合成配方。

该扩展还包含一个碎片系统：玩家可以拾取的可收集物品，被分组为套组，当集齐足够多的碎片时会触发一个 sequence。一切都是 TypeWriter 条目，在网页面板中构建，菜单则由 GUI 扩展渲染。

该扩展运行于 TypeWriter 的 BTC 构建版（BTC Core，Paper/Folia），此处的文档仅供参考。

功能

• 发现分类 — 对物品分组，并通过 parentCategory 支持嵌套的子分类。
• 基于条件的解锁 — 分类和物品根据条件解锁；被锁定的条目可以显示它们自己的物品和 lore。
• 完成度计数器 — 已解锁、已锁定、总数和百分比，可用于分类图标，也可作为占位符。
• 配方书 — 根据 recipeKey 显示原版配方的材料和成品。
• 解锁触发器 — 当某个分类、物品或配方首次为某位玩家解锁时触发，并会被保存，因此永远不会触发两次。
• 四种菜单布局 — 每个分类可使用 PAGINATED、SCROLLABLE、FRAME 或 SIMPLE。
• 全局图鉴菜单 — 一个通过标记来放置分类图标的 GUI 布局，并继承共享的菜单底板。
• 可收集的碎片 — 拾取一件物品即可收集一块碎片，并在某个组完成时触发一个触发器。
• 打开命令和动作 — 通过命令、对话或任何触发器来打开某个分类。

安装

1. 安装 GUI 扩展（BTC 构建版中为 GuiAndDialogs）和 TypeWriter 的 Basic 扩展。没有它们，Codex 不会加载。
2. 可选：如果你想根据任务进度解锁条目，请安装 Quest 扩展和 Quest Codex 扩展。
3. 将 Codex 的 JAR 放入 plugins/Typewriter/extensions/，然后重启服务器。
4. 如果你使用解锁触发器，请添加一个 Codex Unlock artifact；如果你使用碎片，请添加一个 Fragment Storage artifact。

快速上手

构建一个包含两个物品的“森林生物”分类：

1. 在 TypeWriter 网页面板中，打开一个 manifest 页面，添加一个 Discovery Codex Category 条目。
2. 将 category 设为一个唯一的标识符，例如 forest_creatures，并设置 title、rows（例如 3）和 icon。
3. 将 itemSlotRange 设为要填充的槽位，例如 10-16（数字从 1 开始），并选择 guiLayout。
4. 在 items 中添加一个物品：entryId 为 wolf，设置解锁时显示的 item、之前显示的 lockedItem，并在 criteria 中填入表示“玩家见过狼”的 fact。添加 unlockedLore 和 lockedLore。
5. 在一个 static 或 sequence 页面条目中添加一个 Open Discovery Codex 动作，将 definition 设为你的分类，并通过 NPC、物品或对话选项来触发它。你也可以使用 /tw codex open forest_creatures。
6. 发布并打开图鉴。条件不满足的物品会保持锁定。

没有条件的物品

criteria 列表为空的物品始终处于解锁状态。请为每个想要隐藏的物品添加条件。

工作原理

一个分类要么显示它的子分类和配方分类（当其他分类把它指定为 parentCategory 时），要么显示它自己的物品。每次为玩家构建菜单时，都会评估分类条件和物品条件。

菜单

每个 Discovery Codex Category 都是一个拥有 rows 行（1 到 6）的独立物品栏菜单。物品放在 itemSlotRange 的槽位中（例如 1-25，从 1 开始计数），或者从 startSlot 开始按行或按列填充。按钮有默认位置：上一页在槽位 0，下一页在槽位 8，信息在槽位 4，返回在槽位 44。默认使用箭头和书，可以用 previousButton、nextButton、infoButton 和 backButton 替换。返回按钮只有在该分类是从父分类打开时才会出现。background 物品会填满所有空闲槽位。

guiLayout 字段决定当物品无法放在一页内时如何排列：PAGINATED（翻页按钮）、SCROLLABLE（滚动按钮）、FRAME（每行一个框架）或 SIMPLE（全部放在一个屏幕上）。

分类图标的名称和 lore（iconName、iconLore、lockedIconLore）可以使用 {unlocked}、{locked}、{total} 和 {percent}，这些会在图标显示于父分类或全局菜单中时被替换。其他 lore 字段（物品、信息和导航按钮）会按书写的原样显示，即使它们的帮助文本列出了占位符。

entryId 与某个 Recipe Category 的 entryId 匹配的叶子物品，在被点击时会打开配方视图。配方视图会在 craftingGridSlots 中显示合成格，在 resultSlot 中显示成品；如果某个配方没有在服务器上注册，则会显示一个名为 “Recipe not found” 的屏障物品。

Codex Global Menu 动作会打开一个由 GUI 布局池构建的中枢菜单。放置 codex_button:CODEX_CATEGORY 标记（使用 count、gap 和 direction 来重复它们），每个标记会被填入一个顶层分类，按 order 排序。没有匹配标记的分类不会显示，没有分类的标记则保持为空。CODEX_BACK 用于返回，CODEX_INFO、CODEX_PAGE_NEXT 和 CODEX_PAGE_PREV 在此版本中只是纯装饰性物品。

CODEX_RECIPE 标记用于显示配方：按在布局中出现的顺序（与 CODEX_CATEGORY 相同），第 N 个标记显示第 N 个配方的图标。所有 Recipe Categories 的配方会被合并为一个扁平列表，分类按 order 排序，配方按各自列表的顺序排列。点击已解锁的配方会打开其详情视图。配方多于标记时，多出的配方不会显示；标记多于配方时，多出的标记保持为空。

标记间距

在 count 标记中，gap 是步长，而不是间距：1 表示槽位并排，2 表示它们之间隔一个空槽。Codex 使用共享的 GUI 公式。这与自 Quest Codex 0.3.0 起适用于 Quest Codex 标记的规则相同，因此从较旧的 Quest Codex 菜单复制来的布局可能需要把 gap 加倍。布局参考请参阅 GUI 扩展。

当设置了 baseMenuId 时，分类菜单本身可以在共享底板中打开（请使用 3 行或更少的 rows，以便它们适合内容区域）。UiCore 扩展也可以显示图鉴：它的 Codex 界面会通过在分类标识符和名称中查找 fragment、place、region、item 或 recipe 等关键词，把顶层分类归入四个标签页（Bestiary、Items、Places 和 Fragments），其余的一律归入 Bestiary。

配置

该扩展没有配置文件。状态保存在两个 artifact 中，两者都会在更改后几秒以及 TypeWriter 卸载时保存：

• Codex Unlock 记录每位玩家已经触发过哪些解锁触发器。
• Fragment Storage 按组记录每位玩家已收集的碎片。

命令

命令	说明
/tw codex open <category> [targets]	为你自己或选定的玩家打开具有该 category 标识符的分类。别名：/tw dcx open。

除了访问 TypeWriter 命令本身之外，该命令没有自己的权限检查。条件不满足的分类会回复 “This codex is locked”，未知的标识符则会回复 “Unknown category”。

扩展还注册了一个供菜单点击使用的内部命令 /codexmenu（category、recipecat、recipe）。它只对玩家有效，并非用于手动输入。

占位符

这些是 discoverycodex expansion 的 MiniPlaceholders 标签，可用于任何支持占位符的 MiniMessage 文本。请将 cat 替换为 category 标识符，将 item 替换为物品的 entryId。标识符可以包含下划线。

占位符	返回值
<discoverycodex_category_unlocked:cat>	该分类中玩家已解锁的物品数量。
<discoverycodex_category_total:cat>	该分类中的物品数量。
<discoverycodex_category_locked:cat>	玩家尚未解锁的物品数量。
<discoverycodex_category_percent:cat>	已解锁物品的百分比，范围 0 到 100。
<discoverycodex_category_name:cat>	分类条目的名称。
<discoverycodex_item_unlocked:item>	该物品为 true 或 false。

条目

10 个条目，由扩展源码生成。

动作2

• Codex Global MenuOpen a codex global menu
• Discovery Codex OpenOpen a discovery codex category

构件2

• Codex Unlock ArtifactStores which codex unlock triggers already fired for each player
• Fragment ArtifactStores player fragment collection data

清单6

• Discovery Codex CategoryDefines a discovery codex category
• Discovery Codex Recipe CategoryDefines a discovery codex recipe category
• Fragment Collection ConfigGlobal fragment collection settings
• Fragment DefinitionA collectible fragment piece definition
• Fragment GroupA set of fragments to collect together
• Treasure Hunt DefinitionA treasure hunt with progressive hints and compass guidance

故障排查

扩展无法加载。 Codex 需要 Basic 和 GUI（GuiAndDialogs）扩展。请在 TypeWriter 的启动日志中查看缺少的依赖。

解锁触发器始终不触发。 日志会显示 “No CodexUnlockArtifactEntry configured: skipping unlock triggers”。请向已发布的页面添加一个 Codex Unlock artifact。没有它时，触发器会被有意跳过，以免每次重启后奖励被再次发放。

解锁触发器触发一次后就再也不触发了。 这是预期行为：每个触发器对每位玩家只触发一次，记录存储在 artifact 中。若要再次测试，请使用新玩家，或从 artifact 中删除他们的数据。

物品落在了错误的槽位，或最后一个槽位是空的。 itemSlotRange 从 1 开始计数（1-25 表示物品栏的槽位 0 到 24）。超出菜单大小的槽位会被忽略，超出槽位数量的物品会进入下一页。

某个配方显示 “Recipe not found”。 recipeKey 必须是服务器上已注册配方的命名空间键，例如 minecraft:iron_pickaxe。其他插件添加的配方使用它们自己的命名空间。

碎片没有被收集。 玩家必须拾取该物品：它必须与 customItem 匹配（当 customItem 为空时则与 displayItem 匹配），并且日志中不能出现 “No FragmentArtifactEntry found”。请添加一个 Fragment Storage artifact。已经收集的碎片不会被再次消耗。

碎片组始终无法完成。 requiredCount 默认为 0，表示 fragments 中列出的每一块碎片；大于列表长度的数字会被限制为列表长度。该组的 groupId 必须与其碎片的 fragmentGroup 是同样的文本。

全局菜单中的标记相隔一个槽位。 gap 是步长，因此请使用 gap 为 2，以便在标记之间留出一个空槽。

相关扩展

• GUI — 菜单引擎、布局和标记。
• Quest Codex — 任务菜单；Codex 是它的可选搭档。
• UiCore — 可以在其自己的界面中渲染图鉴。