> ## 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.

# 计分板、NPC 与权限集成

> 将市场状态和钱包显示到计分板，通过 Citizens NPC 打开集市，并读取 LuckPerms 主组。

这些可选集成提供显示与入口。基础市场不依赖它们；未安装或 API 不兼容时，对应集成不可用，原版 GUI、钱包和交易仍按自身规则运行。

## 安装与启用

1. 安装与当前服务端匹配的 PlaceholderAPI、Citizens 或 LuckPerms，只选择需要的集成。
2. 使用 Citizens 时，在 `config.yml` 登记允许打开市场的 NPC ID。
3. 正常重启服务器，检查对应插件已启用，再验证显示或入口。

`integrations` 配置在启动时读取，修改后需要正常重启；`/km reload` 不更新这部分配置。具体构件和已验证范围见[兼容说明](https://www.kitemc.asia/kitemarket/compatibility.md)，安装成功不等于所有版本组合均已认证。

## PlaceholderAPI 计分板显示

KiteMarket 在 PlaceholderAPI 可用时登记 `kitemarket` 扩展。将以下占位符填写到支持 PlaceholderAPI 的计分板、全息文字或其他显示插件中：

| 占位符 | 内容 |
| - | - |
| `%kitemarket_state%` | 当前市场初始化状态 |
| `%kitemarket_network_id%` | 当前市场网络 UUID |
| `%kitemarket_wallet_coins_available%` | `coins` 钱包可用余额 |
| `%kitemarket_wallet_coins_frozen%` | `coins` 钱包冻结余额 |
| `%kitemarket_luckperms_primary_group%` | LuckPerms 已加载玩家的主组 |

将钱包占位符中的 `coins` 替换为自己的币种 ID。例如 `points` 对应 `%kitemarket_wallet_points_available%`。余额按该币种的实际精度格式化，不附加币种名称；在显示插件中另行设置标签即可。

钱包值来自异步刷新、有效期15秒的只读缓存，不阻塞占位符线程。市场未就绪、缓存过期或查询失败时返回空值，而不是假零余额。主组用户尚未加载或 LuckPerms 不可用时同样为空。

> [!NOTE]
>
> 占位符只用于展示。不要把缓存值作为扣款依据、权限判断或某次交易成功的证明；实际资金以钱包和交易收据为准。

计分板市场信息

## Citizens NPC 市场入口

在 `config.yml` 中明确登记 NPC ID：

```yaml theme={null}
integrations:
  citizens:
    npc-ids: [12, 27]
```

将 `12`、`27` 替换为自己服务器的真实 NPC ID。默认空列表不为任何 NPC 开放入口，ID 必须是非负整数。

玩家右键登记的 NPC 后，打开与 `/km` 相同的集市首页。未登记的 NPC 不会触发市场；已经被其他插件取消的点击事件也不处理。玩家权限、会话、报价和最终交易确认继续由 KiteMarket 检查。

NPC 只是打开界面，不会自动充值、购买、供货或竞拍。

NPC 集市入口

## LuckPerms 主组与交易权限

LuckPerms 集成只通过公开 API 读取已经加载的玩家主组，用于 `%kitemarket_luckperms_primary_group%` 等显示。它不会为离线用户加载资料或主动授予权限。

交易模式、数量、价格、费用和发布限制使用玩家有效的 Bukkit 权限，不按显示出的主组名称直接决定权限。在 LuckPerms 中配置对应权限节点，随后按[命令与权限](https://www.kitemc.asia/kitemarket/commands.md)及[费用与限制](https://www.kitemc.asia/kitemarket/v1-1/economy.md)检查实际结果。

## 显示或入口不可用时

| 现象 | 检查方式 |
| - | - |
| 显示原占位符文字 | 确认显示插件支持并启用 PlaceholderAPI，且 PlaceholderAPI 已正常加载 |
| 钱包或主组为空 | 检查市场就绪、玩家资料和缓存状态；不要把空值当作0 |
| 右键 NPC 没有市场界面 | 核对真实 NPC ID、配置已重启、Citizens 状态和玩家权限 |
| 权限修改未产生预期结果 | 检查有效权限和首条匹配策略，不只查看主组名称 |

界面主题与物品身份属于独立能力：ItemsAdder 界面见[界面接入](https://www.kitemc.asia/kitemarket/dlc.md)，真实业务 ID 与高级条件见[物品与容器](https://www.kitemc.asia/kitemarket/trading/items.md)。


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