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

# 计分板、NPC 与权限集成

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

export const ScreenshotPlaceholder = ({image, src, title, caption, description, lang = "zh"}) => {
  const source = image || src;
  const label = title || caption || (lang === "en" ? "Gameplay screenshot" : "游戏截图");
  const [ready, setReady] = useState(false);
  const imageRef = useRef(null);
  useEffect(() => {
    const current = imageRef.current;
    setReady(Boolean(current && current.complete && current.naturalWidth > 0));
  }, [source]);
  return <figure className="km-screenshot">
      <div className="km-screenshot-frame">
        {source ? <img ref={imageRef} src={source} alt={label} className={ready ? "km-screenshot-image" : "km-screenshot-image km-screenshot-pending"} onLoad={() => setReady(true)} onError={() => setReady(false)} /> : null}
        {!ready ? <div className="km-screenshot-placeholder">
            <svg width="36" height="36" viewBox="0 0 36 36" fill="none" aria-hidden="true">
              <rect x="5" y="6" width="26" height="24" rx="4" stroke="currentColor" strokeWidth="1.5" />
              <circle cx="13" cy="13" r="2.5" stroke="currentColor" strokeWidth="1.5" />
              <path d="M6 26L14 19L19 23L24 16L31 24" stroke="currentColor" strokeWidth="1.5" strokeLinejoin="round" />
            </svg>
            <strong>{label}</strong>
            <p>{description || (lang === "en" ? "A real gameplay screenshot will be added here." : "此处预留真实游戏截图。")}</p>
          </div> : null}
      </div>
      <figcaption>{label}</figcaption>
    </figure>;
};

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

<h2 id="v11-integration-setup">
  安装与启用
</h2>

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

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

<h2 id="v11-placeholderapi">
  PlaceholderAPI 计分板显示
</h2>

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>
  占位符只用于展示。不要把缓存值作为扣款依据、权限判断或某次交易成功的证明；实际资金以钱包和交易收据为准。
</Note>

<ScreenshotPlaceholder title="计分板市场信息" description="此处预留真实游戏截图：市场状态、钱包余额与玩家主组的计分板显示。" lang="zh" />

<h2 id="v11-citizens">
  Citizens NPC 市场入口
</h2>

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

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

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

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

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

<ScreenshotPlaceholder title="NPC 集市入口" description="此处预留真实游戏截图：玩家右键指定 NPC，打开正常集市首页。" lang="zh" />

<h2 id="v11-luckperms">
  LuckPerms 主组与交易权限
</h2>

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

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

<h2 id="v11-integration-troubleshooting">
  显示或入口不可用时
</h2>

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

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


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