# Getting Started

**Version:** 1.0.0 (not released yet, not tested in game)

## 1. Install the mod

1. Stop the server.
2. Put `KyuubiSoftOrders-1.0.0.jar` into the server's `mods/` folder.
3. Optional: add the KyuubiSoft mods you want the board to work with (see [the list on the start page](https://wiki.kyuubisoft.com/hytale/orders/#optional-kyuubisoft-mods)). For coin rewards and the item picker you need KyuubiSoft Core.
4. Start the server.

```
mods/
  KyuubiSoftOrders-1.0.0.jar
```

No other mod is needed to start the board. The textures of the windows are inside the jar.

---

## 2. Files after the first start

```
mods/
  kyuubisoft_orders/
    config.json            all settings (see Configuration)
    integration.json       limits of the quest and achievement triggers
    orders.json            open orders and the orders closed in the last 14 days
    players.json           known player names, notice settings and unread notices
    boxes/<uuid>.json      the pickup box of one person
    boxes/00000000-0000-0000-0000-000000000000.json   the server box
    journal/<id>.json      bookings that are still running
    log/<yyyy-MM-dd>.jsonl the protocol, one line per booking, kept 30 days
    localization/          language files, one folder per area
  kslang/                  language choice shared by all KyuubiSoft mods
```

Some files and folders only appear once they have something to store.

Every booking is saved before an inventory or a wallet is touched, and the orders and pickup boxes it changes are saved right after it. Everything else is written every 60 seconds and when the server stops. Each file is written to a temporary file first, forced onto the disk and then moved into place.

The log shows lines like these during the start:

```
[Orders] Loaded 9 language(s), ...
[Orders] Loaded 0 order(s), 0 pickup box(es), 0 player(s)
[Orders] Ready, commands /ksorder and /ksorderadmin
[Orders] Economy connected through Core: coin rewards are on
[Orders] Links: core, economy, item_picker, hub, settings
```

Without an economy the line says `No economy connected: only item rewards (checked again every 30 s)`. Without any KyuubiSoft mod the `Links` line says `none (chat lines only, item rewards only)`.

:::caution[A file that cannot be read pauses the board]
If `orders.json`, a pickup box or a booking file cannot be read at the start, the board keeps a copy as `<file>.broken`, overwrites nothing and pauses: no posting, delivering or collecting until the file is repaired or removed and the server restarted. The log and the admin overview name the file.
:::

---

## 3. First steps for players

### Post an order

1. Type `/ksorder` and open the **New order** tab.
2. **1 · Item:** click **Open picker ›** and choose the item, or click one of the items you were looking for recently.
3. **2 · Quantity:** type it, or click one of the quick amounts (50, 100, 200, 500, as far as the server allows them).
4. **3 · Reward:**
   - **Coins:** the total reward. At least 1 per piece, so 200 pieces need at least 200. Coins need a connected economy.
   - **Items:** pick up to 3 stacks from your inventory, undamaged only. They go into escrow exactly as they are, with all their properties.
5. **4 · Duration:** 1, 3 or 7 days by default.
6. **5 · Visibility:** **All**, **Guild** (only with KyuubiSoft Guilds and when you are in a guild) or **Directly to …** with the name of one person.
7. The right side shows the summary, what is **Held now** and the fee (0 % unless the admin set one). Click **Post order**.

When something is missing the button says what, for example "Item missing", "Not enough in wallet" or "Limit reached". The reward is taken at once: coins from your wallet, items from your inventory. You can have 5 open orders at the same time by default.

### Deliver into an order

1. Open the **Board** tab and click an order. Your own orders are not on the board.
2. The right side shows the reward, the price per piece and "You have 34 matching in your inventory".
3. Set the amount with **–**, **+** or **All** and click **Deliver**.

You get your share at once: coins into your wallet, item rewards into your inventory. What does not fit waits in your pickup box. Only undamaged items without special properties count; enchanted or soulbound items and heirlooms do not.

In chat it works too: `/ksorder list` shows the board with order numbers, `/ksorder deliver 412 34` delivers 34 pieces into order 412. Without an amount you deliver as many as possible.

### Collect your pickup box

The pickup box holds the goods others delivered into your orders, refunds of withdrawn or expired orders, and reward shares that did not fit into your inventory. The number on the **Pickup box** tab shows how many entries wait.

1. Open the **Pickup box** tab.
2. Click **Collect all**, or select one entry and click **Collect only this**.

What does not fit into your inventory stays in the box; nothing drops on the ground. Coins go straight into your wallet. In chat: `/ksorder collect` collects everything, `/ksorder list box` lists the entries and `/ksorder collect 2` collects entry 2.

### Withdraw or post again

1. Open the **My orders** tab and select an order.
2. **Withdraw** asks once more ("Withdraw this order?"); click **Yes, withdraw**.

The unpaid rest of the reward goes back to your pickup box; goods already delivered stay there. For a closed order, **Post again** fills **New order** with the item, the rest quantity and the same price per piece. In chat: `/ksorder list mine` and `/ksorder withdraw 412`.

---

## 4. First steps for admins

1. **Give yourself the admin node.** Add `ks.orders.admin` to your player or staff group. See [Permissions](./permissions).
2. **Open the admin window.** Type `/ksorderadmin`, or click the **Order Board** tile in the `/ksadmin` hub if KyuubiSoft Core is installed.
3. **Check the economy.** The **Overview** says "Economy connected · main currency ..." or "No economy connected · item rewards only".
4. **Check the rules.** On **Rules** you set the orders per person, the quantities, the durations, the fee, which rewards and kinds are allowed, the block list and the notice channels. Changes apply at once and are written to `config.json`. See [Configuration](./configuration).
5. **Post a server order** (optional). Click **Create server order** on the **Overview** or under **Orders**, or choose **Server** under **Visibility** in your own order window. The reward comes from the server; nothing is taken from you. Delivered goods land in your pickup box.
6. **Watch for unclear bookings.** If the overview shows "1 unclear booking waits for your decision", click **Check**. See [FAQ](./faq#what-is-an-unclear-booking).

---

## Next steps

- [Commands](./commands) for the full syntax
- [Configuration](./configuration) for every option
- [UI Pages](./ui-pages) for what players and admins see