> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.asia/llms.txt
> Use this file to discover all available pages before exploring further.

# ItemsAdder 接入

KiteMarket 提供完整原版 GUI 和 ItemsAdder v4 兼容。服主与开发者可以使用自己的资源制作配置主题或 Java 呈现器，自用、免费分发或独立销售，**无需额外的 KiteMC 主题授权**。交易、真实物品、输入校验和确认仍由共用服务端流程处理。

> [!TIP]
>
> **先准备主题资源**
>
> 插件不内置 IA 主题资源。可以安装服主自有主题、第三方主题或公开的 MIT 开发示例；没有主题时继续使用完整原版界面。

## 安装自己的主题

1. 取得合法的 ItemsAdder v4 运行插件和配套 ProtocolLib，确认支持目标服务器；已有代表组合见[兼容说明](https://www.kitemc.asia/kitemarket/compatibility.md)。仅有 API JAR 不能运行。
2. 按主题说明安装其独立 ItemsAdder 命名空间，将 KiteMarket 主题声明放入 `plugins/KiteMarket/themes/*.yml`。Java 主题还需安装提供者插件。可运行配置和 Java 示例见[界面与第三方开发](https://www.kitemc.asia/kitemarket/ui-development.md)。
3. 按实际 IA 指南手动 `/iareload`，等待加载完成，再 `/iazip` 重建和下发资源包；KiteMarket 不代替管理员执行第三方重建命令。
4. 登记**实际下发且包含主题的资源包**的 SHA-1（40位十六进制）及 UUID。临时启用 `gui.itemsadder.diagnostics: true` 并 `/km reload`，可从 `[KITEMARKET_PACK]` 读取观察到的 UUID、SHA-1和 URL。登记后重新 `/km reload`，再关闭诊断。
5. 玩家成功加载指定包后使用 `/km ui itemsadder example-ia`，或配置该主题为默认后 `/km ui auto`。用 `/km ui` 核对实际界面和回退原因。

示例中 `example-ia` 必须是已经安装的主题 ID；资源包身份占位值必须替换为实际观察值：

```yaml theme={null}
gui:
  renderer: auto
  auto-order: [itemsadder, vanilla]
  default-themes:
    itemsadder: example-ia
  itemsadder:
    enabled: true
    diagnostics: false
    pack-sha1: "REPLACE_WITH_ACTUAL_40_HEX_SHA1"
    pack-id: "REPLACE_WITH_ACTUAL_SENT_UUID"
```

未安装 IA 主题时使用 `gui.default-themes: {}`。第三方主题也可通过 `requires` 登记自己的包身份，详见开发指南。无效候选保留当前有效配置，主题无需登记 KiteMC 商品 ID 或下载端点。

### 入服后的自动下发

v1.1 的 Paper 1.21.11／Java 21／ItemsAdder 4.0.16 代表组合采用入服后下发。在 `plugins/ItemsAdder/config.yml` 中设置：

```yaml theme={null}
resource-pack:
  auto_apply:
    enabled: true
    before_join: false
```

执行 `/iareload`，等待完成，再正常重新连接并成功加载资源包。此组合已确认自动下发后的配置主题和 Java 页面；入服前下发的完整身份关联尚未确认。未确认指定包时，KiteMarket 保留主题偏好并回退原版。

## 使用与回退

| 玩家入口 | 行为 |
| - | - |
| `/km ui auto` | 按配置顺序尝试已就绪的提供者与默认主题 |
| `/km ui vanilla` | 使用完整原版 GUI，无需资源包 |
| `/km ui itemsadder example-ia` | 选择已安装的自有主题；未就绪时说明原因并回退 |
| `/km ui` | 显示请求偏好、实际界面和主题可用状态 |

偏好按市场网络和玩家保存，换服保持一致；主题缺失或回退不覆盖原偏好。切换保留发布草稿，不重复提交交易。两种界面共用真实物品、订单版本、报价、最终背包重查和操作编号。

资源注册、适配器及玩家对**指定资源包的成功加载**都需就绪；发送或接受不等于加载成功。拒绝、失败、对应包丢弃／移除或不匹配时回退，无关资源包不清空 IA 就绪记录。断线、换节点、全量移除和 IA 重载后重新确认。更新内容需使用新的实际下发 UUID 和对应摘要，不能只在 KiteMarket 配置中生成随机 UUID，也不能给已登记 UUID 换摘要。

## 开发自己的界面

基础库存布局、共用页面和金额输入保留；开发者可使用自己的字体图片、按钮物品图标及逐页配置。SDK 的动作／输入仍接受服务端校验，不能以主题绕过确认或直接扣款。完整示例、页面／模板清单和生命周期说明见[开发指南](https://www.kitemc.asia/kitemarket/ui-development.md)。

### 覆盖完整页面与结果状态

自有主题可为整包、批量、容器、领取分类、业务条件、搜索收藏、订阅通知、风险复核、自动化和管理工具分别配置背景。单品出售显示单价与购买数量，整包显示总价和完整内容；批量页按独立订单呈现。费用与资产去向读取真实服务端快照，不由主题自行计算或改写。

继续使用54槽容器和默认36格列表，真实商品名称、附魔、Lore与数量保留。主题仅改变功能图标和背景；`schema: 1` 的 `pages.<模板 ID>.state-font-images` 可按服务端结果状态选择背景，未匹配时使用本页背景。

新增页应按[页面与动作清单](https://www.kitemc.asia/kitemarket/ui-development/pages.md)安装和核对。缺失资源、不可用页面或 Java 提供者卸载时回退原版，保留主题偏好与草稿。重载执行候选校验，错误模板不替换上一份有效配置。页面可用性、实际引擎兼容性与资源包就绪仍需分别确认。

迁移时保留主题声明、资源和玩家偏好，先备份再更新，见[运维说明](https://www.kitemc.asia/kitemarket/operations.md)。公开示例的 MIT 许可仅覆盖示例内注明的源码与资源，其他主题遵循各自许可。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.