# Permissions

**Version:** 2.0.6

KyuubiSoft Shops checks its nodes with Hytale's permission system. Command syntax is on [Commands](./commands).

## Player nodes

| Permission | Default | Gates |
|------------|---------|-------|
| `ks.shop.user.browse` | allowed | `/ksshop browse`, `/ksshop search`, `/ksshop visit`, and opening someone else's shop with **F** on its merchant |
| `ks.shop.user.create` | allowed | Using the Shop Business License, `/ksshop create` |
| `ks.shop.user.edit` | allowed | `/ksshop edit`, `open`, `close`, `rename`, `deposit`, `transfer` |
| `ks.shop.user.delete` | allowed | `/ksshop delete` |
| `ks.shop.user.rate` | allowed | `/ksshop rate` |
| `ks.shop.user.collect` | allowed | `/ksshop collect` |
| `ks.rental.rent` | allowed | Renting a fixed-price stand (the market shows "No permission" instead of the Rent button) |
| `ks.rental.bid` | allowed | Bidding at a stand auction (same) |

**How the defaults work:** these nodes are checked as "allowed unless set". Every player can use them out of the box; to block one, set it to `false` for a player or group. A blocked player gets "You don't have permission to do this.". If your permission plugin answers "no" for nodes that are not set, grant the nodes explicitly (see the examples below).

## Admin node

| Permission | Default | Gates |
|------------|---------|-------|
| `ks.shop.admin` | not granted | `/ksshopadmin` (`/kssa`) with every subcommand, and the Shop Admin window (also when it is opened from its tile in KyuubiSoft Core's `/ksadmin` hub; `ks.admin` alone is not enough). The window checks it again on every click ("You lack the permission ks.shop.admin."). |

## Limits

These nodes raise a limit above the config value. Only explicit grants count (see [Wildcards](#wildcards)).

| Permission | Effect | Without the node |
|------------|--------|------------------|
| `ks.shop.limit.shops.N` | At most N shops per player | `playerShops.maxShopsPerPlayer` (3) |
| `ks.shop.limit.items.N` | At most N different offers per shop (never more than the 45 slots of the shop grid) | `playerShops.maxItemsPerShop` (45) |
| `ks.rental.limit.N` | At most N rental stands at the same time | `rentalStations.maxConcurrentRentalsDefault` (1) |

- N is checked from 1 to 200; the highest granted N wins.
- The config value is the floor: a node with a smaller N than the config value has no effect. To give a group fewer shops than everyone else, lower the config value and grant the larger N to the other groups.
- **Packed shops count toward the shop limit**, and so do shops on rented stands unless `rentalStations.rentalShopsCountTowardShopLimit` is `false`. The limit is also checked for the receiver of `/ksshop transfer`, when the offer is made and again on accept.
- The offer limit is read when the editor opens; it applies to the person editing (for server shops: the admin).

## Listing perks

| Permission | Effect |
|------------|--------|
| `ks.shop.list.permanent` | A new shop is listed in the market forever, for free. Buying a listing (editor or `/ksshop list`) turns an existing shop's listing permanent, for free. |
| `ks.shop.list.free` | Buying a listing costs nothing; the days are still limited to `listingMinDays`..`listingMaxDays` per purchase. |

Both only count when granted explicitly.

## Wildcards

A wildcard such as `*` or `ks.*` (for example an operator in LuckPerms) would match every `ks.shop.limit.shops.N` up to 200 and every listing perk. To prevent that, the plugin asks for a node no real setup grants (`ks.shop.__wildcard_probe.sentinel_check_zzz`). If that answers "yes", the player is treated as having a wildcard:

- the limit nodes fall back to the config values, and
- `ks.shop.list.permanent` and `ks.shop.list.free` count as not granted.

This also means a player with a wildcard cannot get a higher limit or a listing perk by an extra explicit grant; give staff accounts without the wildcard the nodes they need, or raise the config values. The `ks.shop.user.*`, `ks.rental.rent`/`bid` and `ks.shop.admin` nodes are not affected by the guard.

## What the nodes do not cover

- **The market window.** `/ksshop myshops`, `myrentals` and `rentalstations` open the market without a node; shop cards there open shops without checking `ks.shop.user.browse`.
- **Your own shop.** **F** on your own merchant and **Manage** in the market open the editor without checking `ks.shop.user.edit`.
- **Buying and selling.** There is no node for trading in a shop window or the market. The nodes `ks.shop.user.buy`, `ks.shop.user.sell` and `ks.shop.user.transfer` are announced to the permission system on the first join but are never checked.
- **Reviews.** The Reviews tab of the shop window does not check `ks.shop.user.rate`; only `/ksshop rate` does. Ratings are switched off for everyone in the config (`ratings.enabled` / admin window **General**).
- **The mailbox** and `/ksshop releaserental` have no node.
- **Items.** The license and the mailbox block have no extra item permission; using the license checks `ks.shop.user.create`.

---

## LuckPerms examples

### Staff gets the admin tools

```
/lp group admin permission set ks.shop.admin true
```

### Grant the player nodes explicitly

Only needed when your permission setup denies unset nodes:

```
/lp group default permission set ks.shop.user.browse true
/lp group default permission set ks.shop.user.create true
/lp group default permission set ks.shop.user.edit true
/lp group default permission set ks.shop.user.delete true
/lp group default permission set ks.shop.user.rate true
/lp group default permission set ks.shop.user.collect true
/lp group default permission set ks.rental.rent true
/lp group default permission set ks.rental.bid true
```

### VIP: 5 shops and 3 rental stands

```
/lp group vip permission set ks.shop.limit.shops.5 true
/lp group vip permission set ks.rental.limit.3 true
```

### Premium: 10 shops, free permanent listing

```
/lp group premium permission set ks.shop.limit.shops.10 true
/lp group premium permission set ks.shop.list.permanent true
```

There is no separate node for `/ksshop create`: the license and the command both use `ks.shop.user.create`, so the command cannot be blocked on its own.

### Guests may look but not open shops or rent

```
/lp group guest permission set ks.shop.user.create false
/lp group guest permission set ks.rental.rent false
/lp group guest permission set ks.rental.bid false
```