# Configuration

**Version:** 1.0.0

The board is configured in `mods/kyuubisoft_orders/config.json`. The limits of the quest and achievement triggers are in `integration.json` next to it. Both files are written with the default values on the first start.

- **Most options are also in the admin window** (`/ksorderadmin`, section **Rules**). Changes there apply at once and are written to the file right away.
- **`/ksorderadmin reload` reads the files again** (together with the language files). You can also edit the files while the server is stopped. A change made in the admin window later writes the whole `config.json` again.
- **Values out of range are repaired** at the start and on reload, so a hand-edited file never stops the mod. The ranges are listed below. A `config.json` that cannot be read at all is kept as `config.json.broken` and not overwritten; the defaults apply until you fix it.

---

## Overview

```json
{
  "configVersion": 1,
  "limits": { ... },
  "rewards": { "coinsAllowed": true, "itemsAllowed": true },
  "kinds": { "guildOrders": true, "directOrders": true },
  "fee": { "percent": 0 },
  "blacklist": [],
  "notices": { ... },
  "suspicion": { ... },
  "retention": { "closedOrderDays": 14, "logDays": 30 }
}
```

`configVersion` is managed by the mod; leave it as it is.

---

## Limits

In the admin window: **Rules** → **Limits**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `limits.maxOpenPerPlayer` | `5` | 0–100 | Open orders one person may have at the same time. Server orders do not count. `0` = players cannot post |
| `limits.minQuantity` | `1` | 1–`maxQuantity` | Smallest quantity of an order |
| `limits.maxQuantity` | `9999` | 1–9,999 | Largest quantity of an order |
| `limits.durationsDays` | `[1, 3, 7]` | 1–30 each | Durations offered when posting, in days. An empty list falls back to 1, 3 and 7 |
| `limits.maxRewardStacks` | `3` | 1–9 | Stacks an item reward may have. Only in the file |

In the admin window the durations are buttons: 1, 3 and 7 days plus any other value from the file, at most five. A click switches one on or off; the last one cannot be switched off. Other values (up to 30 days) can only be added in the file.

A coin reward needs at least 1 coin per piece and can be at most 1,000,000,000,000.

---

## Rewards and kinds

In the admin window: **Rules** → **Rewards and kinds**. All four are switches that apply at once.

| Option | Default | Meaning |
|--------|---------|---------|
| `rewards.coinsAllowed` | `true` | Coin rewards are allowed. They also need a connected economy, see [Coins and the economy](#coins-and-the-economy) |
| `rewards.itemsAllowed` | `true` | Item rewards from the inventory are allowed |
| `kinds.guildOrders` | `true` | Guild orders are allowed. They also need KyuubiSoft Guilds |
| `kinds.directOrders` | `true` | Orders directly to one person are allowed |

Switching a kind off only stops new orders of that kind. Running orders stay until they end.

---

## Fee

In the admin window: **Rules** → **Fee**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `fee.percent` | `0` | 0–50 | Percent of a coin reward that is taken **on top** of the reward when the order is posted. Rounded down, kept and never refunded, also when the order is withdrawn or expires. `0` = no fee |

The fee only applies to coin rewards. Item rewards and server orders have no fee. Example with 10 %: a reward of 1,000 coins takes 1,100 coins from the wallet; 1,000 are held in escrow for the people who deliver.

---

## Block list

In the admin window: **Rules** → **Block list**.

| Option | Default | Meaning |
|--------|---------|---------|
| `blacklist` | empty | Item ids nobody can post or deliver. An entry is an exact item id (upper and lower case do not matter) or a pattern with `*`, for example `Weapon_*` or `*_Legendary` |

- A blocked item can be neither the wanted item nor part of an item reward, and it cannot be delivered.
- The list is checked after the item choice: blocked items still show up in the item picker, but the board refuses them.
- In the admin window an entry may have letters, digits and `_ - . : *`, up to 96 characters, and the list holds up to 200 entries. The **×** next to an entry takes it off the list.

---

## Notices

In the admin window: **Rules** → **Notices**. Each switch turns a channel off for everyone. Players turn their own channels off in `/kssettings` (with KyuubiSoft Core); a channel the admin switched off stays off for them.

| Option | Default | Meaning |
|--------|---------|---------|
| `notices.toast` | `true` | A card at the top of the screen while the player is online |
| `notices.chat` | `true` | A chat line while the player is online |
| `notices.whisperstone` | `true` | A note on the whisper stone while the player is offline. Only with KyuubiSoft Whisperstone |
| `notices.loginSummary` | `true` | One summary line at the next login with what happened while the player was away |
| `notices.maxUnread` | `50` | Notices kept per person for the login summary (1–500); the oldest are dropped. Only in the file |

Who gets what is on [UI Pages](./ui-pages#notices).

---

## Unusual patterns

The **Unusual** box of the admin overview shows hints. Nothing is blocked or removed on its own. Server orders do not count. Only in the file.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `suspicion.windowDays` | `7` | 1–60 | Days the hints look back |
| `suspicion.concentrationMinDeliveries` | `5` | 2–1000 | Deliveries a person needs in that time before the next rule counts |
| `suspicion.concentrationPercent` | `75` | 50–100 | "Delivers almost only to one person": at least this share of a person's deliveries went to the same person |
| `suspicion.priceFactor` | `5.0` | 1.5–100 | "Reward far above / below usual": an open coin order pays this many times more or less per piece than the median of the other open coin orders of that item (at least three of them) |
| `suspicion.expiredMin` | `5` | 1–1000 | "Lets many orders expire": at least this many expired orders of one person in that time |

---

## Retention

Only in the file.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `retention.closedOrderDays` | `14` | 1–90 | Days a closed order stays in `orders.json`: in **My orders**, in the admin window and for the unusual patterns |
| `retention.logDays` | `30` | 1–365 | Days the protocol keeps its bookings |

Pickup box entries never run out; they stay until they are collected.

---

## Quest and achievement triggers

With KyuubiSoft Quests or Achievements, the board reports three trigger types. The **target** is the item id of the order, so an objective can ask for one item or for `any`.

| Type | Goes to | Amount | Counts only when |
|------|---------|--------|------------------|
| `order_post` | The person who posted the order | 1 | Not a server order; the reward is worth at least `minCoins` coins or is an item reward; at most `postsPerDay` times per person and day |
| `order_deliver` | The person who delivered | Pieces delivered | The delivery's own share is worth at least `minCoins` coins or at least one item; at most `partnerPerDay` deliveries per deliverer and order owner per day. Deliveries into server orders always count |
| `order_fulfil` | The person whose own order is now complete | 1 | Not a server order; the reward is worth at least `minCoins` coins or is an item reward; at most `partnerPerDay` times per order owner and the person with the last delivery per day |

The limits stop players from farming the triggers with a second account. They are in `integration.json`:

```json
{ "goals": { "enabled": true, "minCoins": 10, "partnerPerDay": 3, "postsPerDay": 3 } }
```

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `goals.enabled` | `true` | | Off = no trigger is sent at all |
| `goals.minCoins` | `10` | 0 or more | Coins a reward or a share must be worth to count. `0` = every coin reward counts. Item rewards always count with at least one piece |
| `goals.partnerPerDay` | `3` | 0–1000 | See the table above. `0` = these triggers never count |
| `goals.postsPerDay` | `3` | 0–1000 | See the table above. `0` = posting never counts |

The counters live in memory and start again at midnight (server time) and after a restart. A player who is offline when the trigger happens (typically when their order is filled) gets it at the next login. The board adds no quests or achievements of its own; admins build their own on these types.

---

## Coins and the economy

The board has no money of its own. Coin rewards go through **KyuubiSoft Core**'s economy connection, in the **main currency** only:

- Core's own server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) (Core 2.10.0 or newer), or
- a different economy that Core connects to.

Without Core, or while Core finds no economy, the board offers item rewards only: the **Coins** choice is greyed out ("items only, no economy connected"), and coins in pickup boxes stay there until an economy is back. The board checks every 30 seconds whether an economy is connected. Rewards that waited for the economy are paid into the wallet when the player logs in again.

- Amounts are always shown the way the economy formats them, with its own currency name. The board never writes a fixed unit such as "gold" behind a number.
- Coins only leave a wallet when an order is posted (reward and fee into escrow). They reach a wallet as the share of a delivery (paid right after it), or when a refund or other coins are collected from the pickup box.
- The board relies on the economy's answer. If an economy fails internally after it moved coins and still answers "not paid", the board cannot notice that.

### Coin bookings in the Kronen history

With Kronen (Core 2.10.0 or newer), every coin booking of the board names its order in the history, in the reader's language. The source is shown as **Order Board**.

| Booking | Shown in the history |
|---------|----------------------|
| Posting an order | "Order #412 posted · reward held in escrow"; with a fee "Order #412 posted · reward and fee held in escrow" |
| The share of a delivery | "Delivery reward · order #412" |
| The share of a delivery into a server order (paid by the server) | "Delivery to the server · order #412" |
| The unpaid rest of an order that ended | "Unpaid rest back · order #412" |
| Coins given back after an admin checked an unclear booking | "Given back after a check · order #412" |
| Several entries of different orders, or of different kinds, collected at once | "Collected from the pickup box" |

An older Core pays the same amounts, only without these reasons.

---

## Languages

The texts of all windows, commands and messages are in `mods/kyuubisoft_orders/localization/<area>/<language>.json` (areas `admin`, `core`, `integration`, `ui`; languages `en`, `de`, `es`, `fr`, `it`, `pl`, `pt-BR`, `ru`, `tr`). Missing files are written at the start, and keys missing in your copy come from the jar. When a newer version brings newer texts, the file is replaced and your old one is kept as `<language>.json.backup-v<old version>`. `/ksorderadmin reload` reads changed language files again.

Each player's language comes from `/kslang`, which all KyuubiSoft mods share.