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

# Scoreboards, NPCs and permissions

> Display market status and wallets on scoreboards, open the market through Citizens NPCs and read LuckPerms primary groups.

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>;
};

These optional integrations provide displays and entry points. The base market does not depend on them. A missing plugin or incompatible API makes its integration unavailable while the vanilla GUI, wallets and trading retain their normal rules.

<h2 id="v11-integration-setup">
  Installation and activation
</h2>

1. Install builds of PlaceholderAPI, Citizens or LuckPerms that match your server. Choose only the integrations you need.
2. For Citizens, register the permitted NPC IDs in `config.yml`.
3. Restart normally, confirm the corresponding plugins are enabled and check the display or entry point.

`integrations` configuration is read at startup. Changes require a normal restart; `/km reload` does not update it. See [compatibility](/en/kitemarket/compatibility) for specific builds and verified combinations. Successful installation does not certify every version combination.

<h2 id="v11-placeholderapi">
  PlaceholderAPI scoreboard displays
</h2>

KiteMarket registers the `kitemarket` expansion when PlaceholderAPI is available. Add these placeholders to a scoreboard, hologram or other display plugin that supports PlaceholderAPI:

| Placeholder | Content |
| - | - |
| `%kitemarket_state%` | Current market initialization state |
| `%kitemarket_network_id%` | Current market network UUID |
| `%kitemarket_wallet_coins_available%` | Available balance in the `coins` wallet |
| `%kitemarket_wallet_coins_frozen%` | Frozen balance in the `coins` wallet |
| `%kitemarket_luckperms_primary_group%` | The primary group of an already-loaded LuckPerms user |

Replace `coins` in wallet placeholders with your currency ID. For example, `points` uses `%kitemarket_wallet_points_available%`. Balances use the currency's actual precision without appending its display name; add a label in the display plugin.

Wallet values come from an asynchronously refreshed read-only cache with a 15-second lifetime, without blocking the placeholder thread. Unready services, expired caches and failed queries return an empty value instead of a fabricated zero balance. An unloaded LuckPerms user or unavailable LuckPerms provider also returns an empty group.

<Note>
  Placeholders are for display. Do not use cached values to authorize a debit, grant permissions or prove a trade succeeded. Wallet records and trade receipts contain the actual result.
</Note>

<ScreenshotPlaceholder title="Market scoreboard information" description="Reserved for a real gameplay screenshot showing market status, wallet balances and the player's primary group." lang="en" />

<h2 id="v11-citizens">
  Citizens NPC market entry
</h2>

Register specific NPC IDs in `config.yml`:

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

Replace `12` and `27` with actual NPC IDs on your server. The default empty list enables no NPC entry points. IDs must be non-negative integers.

Right-clicking a registered NPC opens the same market home as `/km`. Other NPCs do not trigger the market, and clicks already cancelled by another plugin are ignored. KiteMarket still checks player permissions, sessions, quotes and final trade confirmation.

NPCs only open the interface; they never automatically deposit funds, buy, supply or bid.

<ScreenshotPlaceholder title="NPC market entry" description="Reserved for a real gameplay screenshot of a player right-clicking a configured NPC to open the normal market home." lang="en" />

<h2 id="v11-luckperms">
  LuckPerms primary groups and trading permissions
</h2>

The LuckPerms integration reads the primary group of an already-loaded user through its public API, for displays such as `%kitemarket_luckperms_primary_group%`. It does not load offline users or grant permissions.

Trading modes, quantities, prices, fees and publication limits use effective Bukkit permissions rather than the displayed primary-group name. Configure the relevant permission nodes in LuckPerms, then verify the result against [commands and permissions](/en/kitemarket/commands) and [fees and restrictions](/en/kitemarket/v1-1/economy).

<h2 id="v11-integration-troubleshooting">
  Unavailable displays or entry points
</h2>

| Symptom | What to check |
| - | - |
| The original placeholder text is displayed | Confirm the display plugin supports and enables PlaceholderAPI, and PlaceholderAPI loaded successfully |
| Wallet or group value is empty | Check market readiness, player data and cache state; do not interpret an empty value as zero |
| Right-clicking the NPC does not open the market | Check the actual NPC ID, restarted configuration, Citizens status and player permissions |
| A permission edit does not have the expected effect | Check effective permissions and the first matching policy, not just the primary-group name |

Interface themes and item identity are separate capabilities. See [ItemsAdder integration](/en/kitemarket/dlc) for interfaces and [items and containers](/en/kitemarket/trading/items) for real business IDs and advanced conditions.


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