原创 开源 工具 [Skript拓展] xiaojie-GUI - 为 Skript 带来现代化的发包 GUI 2.0.0

---

xiaojie-gui 将菜单融入 Skript：先创建菜单，再用字符串描述布局，将字符与物品绑定，
点击回调就写在绑定语句下方。布局、交互和刷新有了统一的写法，日后维护也更省心。
每行字符串对应一行格子，map key 按字符设置图标；需要指定位置时，
用 override slot 按格子编号设置即可。

插件提供分页、列表展示和点击冷却。菜单定义由玩家共享，每个人打开后则有自己的窗口，
可以停留在不同页面，使用各自的标题和专属图标。默认的 phantom 模式通过数据包呈现窗口，
图标无法取走，适合按钮菜单；需要存取、整理真实物品时，可以选择 static 模式，
由服务端创建真实物品栏，允许移动、交换和丢弃物品。

使用前也请留意边界：插件不自带命令、权限节点或配置文件，也不保存数据，入口与权限判断均由脚本安排。
目前没有提供文字输入语法；搜索词等输入可在关闭菜单后通过聊天或命令收集。
多名玩家不能共用同一份真实储物窗口，共享数据需要由脚本管理并通过图标展示。
页面可以添加，但不能直接删除；减少页数需要销毁菜单后重建。

容器名称沿用 Skript 的类型，但仅支持客户端有对应窗口的容器，例如箱子、投掷器、工作台和铁砧。
商人窗口仅支持 phantom 模式。
composter、chiseled bookshelf、decorated pot、
shelf、jukebox 以及玩家自己的 2×2 合成格不支持作为独立菜单窗口，
创建时会给出明确提示。

基本信息

• 目标环境：Paper 26.2、Java 25。plugin.yml 声明了 api-version: 26.2，
  更旧的服务端会拒绝加载。此处列出当前目标版本，不保证兼容所有后续版本。
• 必需插件：Skript 2.16.2、PacketEvents 2.13.0。两者均声明为 depend，
  缺少任意一个，插件都不会启用。
• 可选插件：SkBee。标题使用文本组件时需要它，例如 titled {_title} 中传入组件；
  仅使用字符串标题时无需安装，不影响其他功能。
• 命令与权限：插件自身不注册命令或权限节点。菜单的打开、翻页、关闭及访问条件由脚本决定。
• 配置与数据：不生成 config.yml 或数据目录，也不写入数据文件。

安装

1. 下载 xiaojiegui-<版本>.jar。
2. 将它与 Skript、PacketEvents 放进服务端的 plugins/ 目录。
3. 重启服务端，确认依赖与本插件均已启用。
4. 将脚本放进 plugins/Skript/scripts/，使用 /sk reload <脚本名> 加载。
   若使用下方示例，加载成功后还需在游戏内执行 /shop 才会打开菜单。

jar 内含 Kotlin 标准库及其 JetBrains 注解，均重定位至插件自己的包名
（io.github.heyhey123.xiaojiegui.libs.*），以避免与其他插件的副本冲突。
jar 未混淆，源码公开，可在仓库中查阅具体实现。

脚本重载时，插件会销毁全部菜单并关闭玩家窗口，再由新脚本在 on load 中重新创建。
建议将菜单定义放在这里；重复使用同一个 id 时，旧菜单会先被销毁。

从一段脚本开始

布局的三行对应菜单的三行，& 用于颜色码。< 和 > 在两页中都有位置，
不带 on page 的 map key 会作用于所有页，因此两页都能显示翻页按钮。
A 和 B 分别只出现在各自的页面，互不影响；两页中的 # 则统一显示为红色玻璃板。
先从这个小菜单起步，再按需要添上自己的内容即可。

特性

• 用字符安排布局。 with layout 一行一个字符串，每个字符代表一格；
  map key 为同一字符对应的格子设置图标，空格用于留空。
  指定位置的内容可用 override slot 设置，槽位编号从 0 开始。
• 两种模式，各有所长。 phantom（虚拟）适合无法取走图标的按钮菜单；
  static（真实）允许存取物品，适合储物交互。插件不负责持久化，储物内容需由脚本保存或返还。
• 每位玩家拥有自己的窗口。 页码、窗口标题和专属图标可以分别设置，不影响其他玩家。
  用 the menu window of player 取得当前窗口，
  用 the menu viewers of {_menu} 列出正在查看菜单的玩家。
• 按需添加页面。 创建时的布局是第 1 页，insert page 添加页面，
  turn to page 翻页，on page turn 处理翻页事件。各页可有自己的布局和标题。
  翻页只清除原页面管理的格子，其余位置的物品保留；但各页并非独立储物空间，目标页图标仍可能覆盖同一位置的内容。
• 列表区域统一更新。 将物品列表映射给一个 key，再用
  set the menu list of the menu window of player to {结果::*} 为玩家填充列表。
  超出区域容量的项目不会显示，并非丢弃物品；未填满的格子会清空，整个窗口只刷新一次。
  the menu list index 返回所点结果的序号，从 1 开始；点击非列表格时没有值，便于区分结果与按钮。
• 拖拽作为一次交互处理。 一次有效的多格拖拽只触发一次 on menu interact，
  涉及的格子由 the dragged slots 读取，cancel event 取消整次操作。
  单格拖拽按普通点击处理，不提供拖拽列表。拖拽只能放入物品，不能取出；记录放入操作时，应同时考虑点击与拖拽。
• locked icons 保护菜单图标。 在 static 模式下，
  布局图标不能被取走、替换或丢弃，涉及受保护格子的拖拽会整次拒绝，未受保护的空格仍可存取物品。
  锁定不阻止格子回调，购买按钮仍可响应；phantom 本身就不允许移动窗口物品。
• 沿用 Skript 的点击类型。 on menu interact 中的 the click type
  与 the event-clicktype 返回相同的值，可用 left mouse button、
  left mouse button with shift、double click 等字面量判断。
  具体按下的数字键可用 the pressed number key 读取，范围为 1 到 9，其他点击时没有值。
• 点击冷却控制交互频率。 click delay 决定两次点击的最小间隔：
  create menu 中可写 with 500 ms click delay，
  build a menu 中可写 click delay: 500。
  两种写法的默认值分别为 50 毫秒和 5 毫秒。冷却内的点击不会触发事件或格子回调，排查无响应时可先检查此项。
• 常见错误有明确提示。 不支持的容器、越界页码或在菜单事件之外使用事件值等情况，
  会给出可读报错或控制台说明，便于定位脚本问题。

完整语法与示例
各条语法的参数和示例见仓库文档。中文指南位于
docs/ 目录，
文件名如 docs/guide/xxx.zh-CN.md，与英文指南对应。
也可在 SkriptHub 上的插件页 按名称搜索语法（英文界面）。

2.0.0 更新说明
新增

• 列表页。 将列表映射给 key 后，可用 set the menu list 为单个玩家更新列表区域，
  再通过 the menu list index 识别所选结果，适合物品浏览器等场景。
• 图标锁定。 locked icons 为 static 菜单保护布局图标，
  拦截普通点击、Shift 点击、数字键、副手交换、丢弃、双击收集及涉及这些格子的拖拽。
  运行时可用 lock the icons of %menu% / unlock the icons of %menu% 切换。
• 多格拖拽支持。 修复旧版多格拖拽未进入菜单交互事件的问题。
  有效的多格拖拽现在只触发一次交互，可通过 the dragged slots 读取涉及的格子，
  并用 cancel event 取消整次操作；单格拖拽仍按普通点击处理。

变更

• 更新目标运行环境。 Paper 26.2、Skript 2.16.2、PacketEvents 2.13.0、Java 25。
  plugin.yml 声明 api-version: 26.2，更旧的服务端会拒绝加载。
• 标题直接传值，不加前缀。 例如 titled "主菜单" 或
  update title of page 1 in {_menu} to "第一页"。string: 与
  component: 是内部语法分支标记，不属于脚本写法。旧版会将前缀一并显示，2.0.0 起会明确报错。
  颜色码 &6、&l 及 Adventure 的 &x&f&f&5&5&0&0 十六进制写法仍可使用。
• 页码从 1 开始。 创建时的布局始终是第 1 页，不存在 page 0。
  with page N 只决定 open menu 默认显示哪一页，不改变页数；
  同时修复旧版设置该选项后未创建初始页、导致菜单无法打开的问题。
• 调整旧语法。 旧的 gui 写法（create a gui …、
  the player's gui、if player has a gui open:）已移除，
  请改用菜单语法与 the menu session of player。
  the viewers of {_menu} 会匹配 Skript 2.16 自带的 viewer[s] 属性并返回空值，
  请改为 the menu viewers of {_menu}；all players viewing {_menu} 保持不变。
  模式改用普通文本，receptaclemode 类型已移除。

修复

• 标题语法异常。 修复带标题的语法执行时抛出内部异常、导致菜单未能创建的问题。
• 翻页清理范围。 不再清空整个窗口，仅清除原页面管理的格子。其他格子的物品保留，
  但仍可能被目标页图标覆盖，不能据此将每页当作独立仓库。
• 固定容器的格子数量。 工作台 10 格，信标和讲台各 1 格，附魔台 2 格，锻造台 4 格，制图台 3 格。
  修正数量后，避免了玩家背包显示与点击位置错位。
• 扩展可用容器。 木桶、末影箱、发射器、附魔台、制图台、合成器不再报
  Unsupported inventory type。其中附魔台与制图台在 Skript 中分别写作
  enchanting table inventory、cartography table inventory。
• 标题更新与事件取消。 update title of page N 只更新正在查看第 N 页的玩家，
  不再影响其他页的窗口标题。cancel event 也能在 on menu open
  与 on page turn 中正确阻止打开和翻页。

完整改动清单还包括 the occupied slots of %menusession% 窗口读取、
the pressed number key 数字键判断等，见
Releases 与仓库中的 docs/CHANGELOG-zh.md。

使用须知

• 修改标题会重新打开窗口。 协议没有单独修改标题的操作；phantom 会延后到下一个 tick 更新，
  static 则在同一 tick 内完成。若窗口已关闭，待执行的重开操作会失效。
• 文字输入需要另行安排。 原版客户端打开容器时，无法直接使用聊天栏、命令或暂停菜单。
  需要输入文字或退出游戏时，请先关闭容器窗口；插件目前不提供文字输入语法。
• 同 id 菜单会替换旧定义。 再次 create menu 会先销毁旧菜单并关闭其窗口，
  因此可在 on load 中按同一 id 重建。
• 不支持的容器会明确报错。 composter、chiseled bookshelf、
  decorated pot、shelf、jukebox 以及玩家自己的 2×2 合成格
  不能作为独立菜单窗口，create menu 会提示 Unsupported inventory type。
• 取消事件不会撤销已执行的回调。 格子回调先执行，之后才判定 on menu interact
  的取消状态。扣款、发奖等操作应在回调内先检查条件，必要时使用 stop，不能依赖事后取消来回滚。
• 控制台提示使用英文。 jar 中的 lang/default.lang 仅提供 Skript 报错所需的类型名，
  例如 menu、menu window，不会改变服务器向玩家显示的文字。

链接

• 源码仓库：源码与完整文档，中文指南位于
  docs/guide/xxx.zh-CN.md。
• 下载与更新日志：各版本 jar 与详细改动。
• 文档目录：快速上手，以及菜单、页面、
  填充、标题、模式、窗口、事件、条件与拖拽指南。
• SkriptHub 上的插件页：按名称检索语法（英文界面）。
• CONTRIBUTION.md：
  构建方法、测试服务端与代码风格说明。
• 问题反馈：报告问题或提出疑问。

许可协议
项目采用 AGPL-3.0，完整条文见仓库的 LICENSE。
该许可证允许商业使用；修改、分发或通过网络提供修改版服务时的具体义务，请参阅 AGPL-3.0 条款。