# Rental Stands

**Version:** 2.0.6

Rental stands are shop spots that admins place at fixed positions (a spawn plaza, a market street). Players do not need a license for them: they rent a stand for a number of days at a fixed price, or win it at a timed auction. While the rental runs the stand is their shop. When it ends, stock and till go to the renter's mailbox and the stand is free again.

:::note
The pictures on this page are design previews of the in-game windows. Names and values are examples.
:::

---

## The stand in the world

A free stand is a merchant NPC at the stand's position. Its name plate shows the offer:

- fixed price: `Plaza [100g/day]`
- auction: `Plaza [AUCTION 500g]` (the minimum bid, then the current high bid)

**F** on it opens the market on the **Rental stands** tab with that stand selected. When the stand is rented, the renter's merchant stands there instead (with the renter's skin) and works like any player shop.

---

## Creating stands (admins)

| Way | Result |
|-----|--------|
| `/kssa createrental <name> [pricePerDay] [maxDays]` | Fixed-price stand at your position, facing your direction |
| `/kssa createrentalauction <name> [minBid] [bidIncrement] [durationMinutes] [rentalDays]` | Auction stand; the first round starts at once |
| Admin window, **Rental stands**, **+ New stand here** | Fixed-price stand "New stand N" with the config defaults; switch it to auction and adjust the values in the stand editor |

Missing values come from `rentalStations.default*` in `config.json`. Type the numbers in the order shown; a word that is no number, or too many words, creates nothing and shows the usage. A name with spaces goes in double quotes. The commands print the stand's UUID, which `/kssa forceexpirerental`, `/kssa deleterental` and `/ksshop releaserental` need; `/kssa listrentals` shows it again. Everything else is easier in the admin window: rename (up to 40 characters), change prices and days, switch the mode (only while the stand is free and has no bid), restart a resting auction, end a rental, teleport, delete. See [Admin Panel](./admin-panel#rental-stands).

---

## The Rental stands tab

The market's tab lists every stand of the server, auctions first, then by name. Filters: **All**, **Free**, **Auction**, **Rented**, each with a count. Each row shows the name, the mode (Auction / Fixed price), a state line and a price:

| State | Line |
|-------|------|
| Free fixed-price stand | "Free · 40 m away" and the price per day |
| Running auction | "Auction running · ends in 2 h 10 min" ("· you lead" when you lead), the high bid or minimum bid |
| Auction closing | "Auction is closing ..." (between the end and the next check) |
| Resting auction | "No auction running" |
| Rented by you | "Your rental · 3 d 4 h left" |
| Rented by someone else | "Rented to Steve · 3 d 4 h left" |

Below the list: "You can rent up to 1 stands at once (0 taken)." and, when rental shops are listed for free, a note about that. The tab updates every second while it is open.

---

## Renting a fixed-price stand

![Rental stands tab, fixed-price stand](../../../../assets/player-shops/shops-rentals-fixed.png)
*A free fixed-price stand: price, duration, total and when the rental ends.*

The detail shows **Price** per day, **At most** N days at a time, **Location**, **Market listing** (free while the rental runs, or the normal listing fee), and **Your rentals** N of your limit. Below:

- **Duration** with **-**, **+** and quick picks 1 d / 3 d / 7 d (only those up to the stand's maximum).
- **Total**, **Balance after**, **Rental ends** (date).
- **Rent · [total]**, or a disabled button: "No permission", "Rental limit reached", "Not enough Gold".
- "How it works": rent it, stock it under My shops > Manage, extend in time.

Renting:

- needs `ks.rental.rent` and a free slot in your rental limit (`maxConcurrentRentalsDefault`, raised by `ks.rental.limit.N`);
- takes days x price per day from your wallet at once;
- creates your shop at the stand, named like the stand, with your merchant, always in the stand's world (wherever you rent from; if that world is not loaded, the merchant appears when it loads). By default it counts toward your shop limit for opening further shops (`rentalShopsCountTowardShopLimit`, see [Configuration](./configuration#rentalstations));
- lists the shop in the market for free until the rental ends when `rentalShopsListFree` is on (default).

Only one player can rent a stand: the second one gets "This slot has just been rented by someone else."

---

## Bidding at an auction

![Rental stands tab, auction](../../../../assets/player-shops/shops-rentals-auction.png)
*An auction stand: live clock, high bid, your status, the bid controls and the bid history.*

The detail shows:

- **Auction ends in** with a live clock (hh:mm:ss, red in the last minute).
- **High bid** and by whom ("by you"), or "no bids yet".
- Your status: "You are the highest bidder" (with "If you win, you rent it for 7 days"), "You have been outbid" or "You have not bid yet".
- **Minimum bid now**, **Step** ("at least 10 Gold above the high bid"), **The winner rents** N days, **Late bids** ("in the last 30 s extend it by 30 s").
- **Your bid** with **-** / **+** (one step) and **+10**, **+50**, **+100**, then **Bid · [amount]**. Disabled with "No auction running", "Auction is closing", "No permission", "You already lead" or "Bid above your balance".
- "Gold is only taken from the winner when the auction ends."
- **Bids**: the last 8 bids with name, age and amount.

Rules:

- Bidding needs `ks.rental.bid`. The first bid must be at least the minimum bid, every later bid at least the high bid plus the step. You cannot outbid yourself.
- Your wallet must cover the bid when you place it, but nothing is taken yet.
- **Anti-sniping:** a bid in the last `auctionAntiSnipingSeconds` (30) seconds moves the end back by the same time.
- **Outbid:** the player who led gets a chat message if online ("You have been outbid on 'Plaza'. Current high bid: 650 Gold.").
- **Ending soon:** when `auctionEndingSoonSeconds` (60) are left, every online player gets one chat message with the stand and the current bid.
- The name plate of the stand shows the current bid.

### When the auction ends

Ended auctions are settled by a check that runs every 60 seconds:

| Situation | Result |
|-----------|--------|
| A winner who can pay | The bid is taken from the winner's wallet, the winner rents the stand for its rental days, gets "You won the auction for 'Plaza'! ..." in chat (if online) and the bid history is cleared |
| The winner can no longer pay | The win is forfeited ("Your win of 'Plaza' was forfeited ..."), all bids are cleared and a new round starts |
| No bids | `onEmptyAuction`: `RESTART` starts a new round, `VACANT` lets the auction rest until an admin presses **Restart auction**, `DELETE` deletes the stand |

The winner's shop and merchant are placed in the stand's world, whether the winner is online or not; if that world is not loaded, the merchant appears when it loads next.

With `onEmptyAuction: DELETE` the stand's placeholder shop and its merchant are removed together with the stand. If the database refuses to delete the placeholder, the stand is kept and rests like `VACANT` (its merchant comes back), and the server log says so; delete it later in the admin window. A placeholder that an earlier version left behind after such a delete counts as a server shop: remove it with `/kssa deleteadmin <shopId>` or **Delete** in the admin window's **All shops**.

---

## While you rent

- Manage the shop like any other: **F** on your merchant or **Manage** in the market's **My shops** tab opens the [editor](./ui-pages#shop-editor).
- Shops on rental stands cannot be packed up, cannot be deleted with `/ksshop delete` and cannot be transferred with `/ksshop transfer`; end the rental instead.
- The shop window shows customers "Rented stand · 3 d left".
- A closed rental shop shows no `[CLOSED]` on its name plate.

### Extending (fixed-price stands only)

In **My shops**, the rental block of the shop has days **-** / **+** (1 to `extendMaxDays`, default 7) and **Extend · [cost]**. The days are added to the end of the rental at the stand's price per day; the free listing is extended with it. There is no upper limit for the total. Stands won at auction cannot be extended ("Won at auction - it cannot be extended.").

### Ending a rental

**End rental** in **My shops**, then confirm, or `/ksshop releaserental <slotId>`. Stock and till go to your mailbox, the stand is free again. For fixed-price stands you get `releaseEarlyGoldRefundFraction` x the paid days left back as a money mail "Rental refund" (0 by default; the confirmation names the amount). Auction stands give no refund.

---

## When a rental ends

A rental ends when its time is up (checked every 60 seconds), when the renter ends it, when an admin ends it (`/kssa forceexpirerental`, **End rental** in the admin window, deleting the shop) or when the stand is deleted. Then:

1. The shop is closed and emptied: every offer with stock and the till go to the renter's mailbox ("Stock of Plaza (rental ended)", "Funds of Plaza (rental ended)").
2. The renter's shop and merchant are removed.
3. The free stand's merchant appears again.
4. An auction stand starts a new round when `onEmptyAuction` is `RESTART`; with `VACANT` or `DELETE` its auction rests until an admin restarts it.
5. The renter gets a chat message if online ("Your rental of 'Plaza' has expired ..." or "An admin ended your rental ...").

---

## Configuration

All values in `config.json` → `rentalStations`, also in the admin window under **Settings → Rental stands**:

| Field | Default | Meaning |
|-------|---------|---------|
| `enabled` | `true` | Rental stands on or off (restart) |
| `rentalShopsListFree` | `true` | Rented shops are listed in the market for free |
| `rentalShopsCountTowardShopLimit` | `true` | Rented shops count toward the shop limit (`config.json` only, not in the admin window) |
| `defaultPricePerDay` | `100` | Price per day of new fixed-price stands |
| `defaultMaxDays` | `7` | Longest rental at once (fixed price) and rental days of the auction winner, for new stands |
| `defaultMinBid` | `500` | Minimum first bid of new auction stands |
| `defaultBidIncrement` | `10` | Bid step of new auction stands |
| `defaultAuctionDurationMinutes` | `60` | Round length of new auction stands |
| `maxConcurrentRentalsDefault` | `1` | Stands per player at the same time |
| `onEmptyAuction` | `RESTART` | `RESTART`, `VACANT` or `DELETE` |
| `auctionAntiSnipingSeconds` | `30` | Late-bid extension, 0 = off |
| `auctionEndingSoonSeconds` | `60` | "Ending soon" broadcast, 0 = off |
| `extendMaxDays` | `7` | Most days per extension |
| `releaseEarlyGoldRefundFraction` | `0.0` | Refund share for ending a fixed-price rental early |

Details on every field: [Configuration](./configuration#rentalstations).

---

## Permissions

| Node | Effect |
|------|--------|
| `ks.rental.rent` | Renting fixed-price stands (allowed unless set) |
| `ks.rental.bid` | Bidding at auctions (allowed unless set) |
| `ks.rental.limit.N` | At most N stands at the same time (explicit grants only, never below the config value) |

See [Permissions](./permissions).

---

## Data

- `shop_rental_slots`: one row per stand with its settings (mode, price, days, auction values) and state (renter, end of the rental, end of the auction, high bid and bidder).
- `shop_rental_bids`: the bids of the current round. They are deleted when the auction is won, forfeited, the stand switches to fixed price or is deleted.
- The renter's shop is a normal row in `shop_shops` that points to its stand.

Change these tables only while the server is stopped; the plugin keeps the stands in memory and saves them every 60 seconds.