GUI
GUI 扩展是 Typewriter 的中央菜单系统。它提供 9 种可配置的布局引擎（外加仅 API 组件）、23 种物品栏类型、键鼠交互、持久物品存储以及完整的 MiniMessage 格式支持。几乎所有其他扩展的菜单都依赖它。
即将推出：一个基于网页的所见即所得（WYSIWYG）编辑器，支持拖放、与游戏内一致的实时预览、CSS-flexbox 自动布局、菜单状态、图块地图以及多提供方资源包支持。
功能
- 9 种布局引擎 — Simple、Composite、Scrollable、Paginated、Frame、Flex、Storage、Book、Merchant —— 外加通过 Kotlin API 提供的 Iterator、Slider 和 ReactiveSlot。
- 23 种物品栏类型 — 箱子、熔炉、铁砧、附魔台、锻造台、商人、书本等。
- 滚动与导航 — 可滚动布局，带可配置的上/下/左/右按钮。滚动按钮锚定在视口上。多帧、各区域相互独立。
- 持久存储 — 由产物支撑的物品存储 —— 按玩家或按群组。累积模式用于进度追踪。可配置点击动作。
- 存储占位符 — 槽位名称和 Lore 中的动态占位符
{stored_name}、{stored_amount}、{stored_max}。 - MiniMessage — 标题、物品名称和 Lore 完整支持 MiniMessage。颜色、渐变、悬停/点击事件。
- 点击交互 — LEFT、RIGHT、SHIFT、DOUBLE_CLICK、DROP、SWAP_OFFHAND、NUMBER_KEY、SCROLL —— 按槽位或全局。
- 动画 — 平滑的槽位过渡，带可配置缓动（linear、ease-in、ease-out）。
- 输入对话框 — 通过 Paper 对话 API，在菜单交互过程中弹出文本输入提示。
架构
条目库
动作
- Open GUI — 主入口。定义一个带标题、布局、物品、交互和存储的物品栏 GUI。
配置
- GUI Settings — 全局默认值：音频配置、存储点击行为映射、技能树节点。
指南
- 介绍 — 系统如何运作、术语，以及分步创建你的第一个菜单。
产物
- GUI Storage — 持久存储产物。按玩家或按群组的物品持久化，支持累积。
快速开始
-
1. 创建一个 Open GUI 条目 — 创建一个 Open GUI 动作条目。这一个条目就定义了某个菜单的全部内容：核心设置： -
title—— 物品栏标题（MiniMessage + PlaceholderAPI） -guiType—— 物品栏类型：CUSTOM、CHEST、MERCHANT、BOOK、ANVIL等（23 种） -size—— 对于CUSTOM类型：SIZE_9到SIZE_54布局（选择其一）： -simple—— 显式 x,y 坐标，配合count/direction/gap/repeatY生成网格图案 -scrollable—— 带滚动按钮的视口，内部布局滚动 -frame—— 多个独立区域，各自拥有子布局 -paginated—— 离散页面，带上一页/下一页导航 -composite—— 按 Z 顺序堆叠的子布局 -book—— 作为成书的 MiniMessage 页面 -merchant—— 带自定义物品的村民交易 物品与交互： - 用item、displayName、lore定义槽位 —— 用x/y/count/direction定位 - 为每个槽位附加interactionList：LEFT、RIGHT、SHIFT_LEFT、SHIFT_RIGHT、DOUBLE_CLICK、DROP等 - 附加triggers以在点击时触发 Typewriter 动作 存储（可选）： - 为任意槽位添加storage以持久化物品 - 使用占位符{stored_name}、{stored_amount}、{stored_max}→ Open GUI 条目参考 -
2. 从其他扩展链接 — 一旦你的 GUI 条目存在，就可以从任何需要菜单的其他扩展中引用它：- QuestCodex ——
quest_codex_settings使用 GUI 布局来浏览任务 - Shops —— 商店菜单使用 GUI 布局来展示物品 - BattlePass、Crates、Pets、Party、Profiles、Cosmetics、Dungeon、BTCSky…… —— 它们的菜单都使用 GUI 扩展 只需在另一个扩展的菜单配置中引用 Open GUI 动作条目的 ID。> GUI 扩展是 20 多个其他扩展的必需依赖。
布局类型
SimpleLayout
物品放置在虚拟网格上的显式 (x, y) 坐标处。最适合静态菜单、装饰和背景。支持 count、direction、gap 和 repeatY 生成网格图案。
ScrollableLayout
用滚动支持包裹一个子布局。自定义滚动按钮（UP/DOWN/LEFT/RIGHT）锚定在视口上 —— 内容滚动时它们不会移动。最适合长物品列表。
FrameLayout
将屏幕划分为独立区域。每个帧拥有自己的位置、大小和子布局（通常是可滚动的）。最适合仪表盘、侧边栏和多窗格面板。每个可滚动区域必须拥有唯一 ID，以正确隔离滚动。
PaginatedLayout
离散页面，带上一页/下一页导航按钮。最适合多页菜单和大型集合。
CompositeLayout
按 Z 顺序叠放多个子布局。最适合叠层和复杂 UI。
BookLayout
将 MiniMessage 页面渲染为一本成书。最适合 Lore、指南和对话。
MerchantLayout
定义带输入物品和一个结果的村民交易。最适合商店和交易。
交互参考
所有支持的交互
| 交互 | 触发 |
|---|---|
LEFT | 鼠标左键 |
RIGHT | 鼠标右键 |
SHIFT_LEFT | Shift + 左键 |
SHIFT_RIGHT | Shift + 右键 |
MIDDLE | 鼠标中键 |
DOUBLE_CLICK | 双击 |
NUMBER_KEY_1..9 | 快捷栏按键 1-9 |
DROP | Q 键 |
DROP_ALL | Ctrl+Q |
SWAP_OFFHAND | F 键 |
用法： 每个槽位用 interactionList 设置点击动作，globalInteractions 用于整个菜单的按键绑定。
GUI 类型参考
全部 23 种受支持的物品栏类型
| 类型 | 说明 |
|---|---|
CUSTOM | 可配置箱子（1-6 行） |
CHEST | 标准箱子 |
FURNACE | 熔炉 |
BLAST_FURNACE | 高炉 |
SMOKER | 烟熏炉 |
BEACON | 信标 |
ENCHANTING_TABLE | 附魔台 |
GRINDSTONE | 砂轮修复 |
CARTOGRAPHY_TABLE | 制图台修改 |
ANVIL | 铁砧修复/重命名 |
LOOM | 织布机（旗帜图案） |
SMITHING_TABLE | 锻造台 |
STONECUTTER | 切石机 |
CRAFTING_TABLE | 工作台 |
BREWING_STAND | 酿造台 |
HOPPER | 漏斗 |
DROPPER | 投掷器 |
DISPENSER | 发射器 |
BARREL | 木桶 |
SHULKER_BOX | 潜影盒 |
ENDER_CHEST | 末影箱 |
MERCHANT | 商人交易 |
BOOK | 成书 |
存储与累积
- 标准存储：点击以存入/取出物品。所有点击行为均可通过 GUI Settings 全局配置。
- 存储占位符：
{stored_name}、{stored_amount}、{stored_max}在槽位的displayName和lore中动态解析 forceStorage: true（默认）：不可堆叠物品（剑、工具、盔甲）也可存储- 累积模式：设置
requiredItem+requiredAmount—— 物品被消耗，达到阈值时触发onReachRequired - 群组存储：通过
group条目在玩家之间共享存储（例如岛屿团队） - 临时槽位：关闭后移除的物品（
temporary = true） onFill/onEmpty触发器：在槽位状态变化时触发 Typewriter 动作
完整细节请参阅 GUI Storage Artifact。
占位符
存储占位符
在存储槽位的 displayName 和 lore 中解析：
| 占位符 | 说明 |
|---|---|
{stored_name} | 所存物品的显示名称 |
{stored_amount} | 槽位中当前物品数量 |
{stored_max} | 槽位的最大容量 |
引擎占位符
GUI 标题和物品 Lore 也可通过 @Placeholder 字段支持 Typewriter 引擎占位符和 PlaceholderAPI。
命令
此扩展不提供独立命令。所有菜单交互都通过 Typewriter 条目进行。
权限
无自定义权限。GUI 访问由引用 Open GUI 动作的条目控制。
依赖
| Extension | 是否必需 | 用途 |
|---|---|---|
| (无) | - | 这是一个基础扩展。20 多个其他扩展依赖它。 |
| PlaceholderAPI | 可选 | 用于标题、名称和 Lore 中的 @Placeholder 字段。 |