# Configuration

All files live in the plugin's data folder `mods/kyuubisoft_lootbag/`. Most settings can also be changed in the [admin panel](./admin-panel), which writes the same files.

## Files

```
mods/kyuubisoft_lootbag/
  config.json                  main switches
  configs/
    lootbags.json              the 150 shipped bags
    drop_tables.json           creature and mining drop rules (+ .bak)
  custom/
    custom_lootbags.json       your bags and your edits of shipped bags (+ .bak)
  localization/
    <lang>.json                9 languages (+ <lang>.json.backup-v<n> after updates)
  data/
    players/<uuid>.json        per player (+ .bak)
    latest_drops.json          latest finds of the server
```

| File | Written by the plugin | Edited by you |
|------|-----------------------|---------------|
| `config.json` | When missing; when settings or drop rules are saved in the admin panel | Yes, then `/lbadmin reload` |
| `configs/lootbags.json` | Only when missing | Better not: put changes into `custom/custom_lootbags.json` |
| `configs/drop_tables.json` | When missing; when drop rules are saved in the admin panel (old file kept as `.bak`) | Yes, then `/lbadmin reload` |
| `custom/custom_lootbags.json` | Every save in the admin panel's Bags section and every `/lbadmin edit` (old file kept as `.bak`) | Yes, then `/lbadmin reload` |
| `localization/<lang>.json` | When missing or older than the jar's version | Yes, but see [Languages](#languages) |
| `data/...` | Automatically | No |

:::caution
Edit the JSON files while the server is stopped, or run `/lbadmin reload` right after. A save from the admin panel overwrites `config.json`, `drop_tables.json` or `custom_lootbags.json` with what the server has in memory.
:::

---

## config.json

The shipped file:

```json
{
  "enabled": true,
  "revealPageEnabled": true,
  "dropEnabled": true,
  "openCooldownMs": 1000,
  "dropMultiplier": 1.0
}
```

Two more fields exist since 2.0.0. They are `true` when missing and are added to the file on the next save from the admin panel.

| Field | Type | Default | Effect | Admin panel |
|-------|------|---------|--------|-------------|
| `enabled` | boolean | `true` | Master switch. Off: right-click opening, F on a placed bag, all drops and the catalog stop (`/kslootbags`, `/kslootbags crate`, the `showcase_lootbag` NPC and "View in catalog" answer "Lootbags are turned off on this server."). `/kslootbags stats` and `settings` keep working | Settings: "Lootbags active" |
| `revealPageEnabled` | boolean | `true` | Off: no opening window for anyone, every opening is listed in the chat. On: each player decides with `/kslootbags settings animation` | Settings: "Show result window" |
| `dropEnabled` | boolean | `true` | Off: creatures and mining drop no bags. Giving bags and opening them still work | Drop rules: "Drops active" |
| `openCooldownMs` | number | `1000` | Milliseconds between two openings of the same player (right-click and "Open another"). A click during the cooldown does nothing | Settings: "Open cooldown" (0 to 600000) |
| `dropMultiplier` | number | `1.0` | Multiplies the chance of every drop rule. `2.0` doubles all chances, `0` stops all drops. The catalog shows chances with the multiplier applied | Drop rules: "Drop factor" (0 to 100) |
| `showDropSources` | boolean | `true` | Shows the *Where to find* section in the catalog: which rules drop the bag and how likely | Settings: "Show drop sources" |
| `ignorePlacedBlocks` | boolean | `true` | Blocks that players placed drop no bags when broken (no place-and-break farming of ore) | Drop rules: "Ignore self-placed blocks" |

:::note[How the placed-block protection works]
While `dropEnabled` and `ignorePlacedBlocks` are on, the plugin remembers every block a player places that matches a block drop rule (other blocks never drop bags, so they are not tracked). Breaking such a block drops no bag, no matter who breaks it. A placement is remembered for 6 hours, at most 200,000 placements are kept (the oldest are forgotten first), and the list lives in memory only: after a restart, blocks placed earlier count as natural again.
:::

---

## Bag files

`configs/lootbags.json` holds the 150 shipped bags. `custom/custom_lootbags.json` holds your own bags and your changed copies of shipped bags. Both are loaded at start and on `/lbadmin reload`, the custom file second: a bag in the custom file **replaces** the shipped bag with the same ID completely.

Both files are a JSON object with the bag ID as key. The shipped uncommon Copper bag:

```json
{
  "Copper_Lootbag": {
    "name": "Copper Lootbag (Uncommon)",
    "rarity": "uncommon",
    "guaranteedItems": [
      { "itemId": "Ore_Copper", "amount": 8 },
      { "itemId": "Ingredient_Bar_Copper", "amount": 5 }
    ],
    "pickCount": 2,
    "allowDuplicates": false,
    "pool": [
      { "itemId": "Tool_Pickaxe_Crude", "amount": 1, "weight": 25 },
      { "itemId": "Ingredient_Bar_Copper", "amount": 3, "weight": 25 },
      { "itemId": "Tool_Hatchet_Crude", "amount": 1, "weight": 25 },
      { "itemId": "Tool_Pickaxe_Copper", "amount": 1, "weight": 25 }
    ]
  }
}
```

Every Copper bag gives 8 Copper Ore and 5 Copper Ingots, plus 2 different items of the 4 in the pool (each has a 50 % chance per bag).

A wrapped form `{ "configVersion": 1, "lootbags": { ... } }` is read as well.

### Bag fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | text | `"Lootbag"` | Name of the bag. For shipped bags the windows show the translated style name as long as `name` is the shipped one; any other name is shown as it is. Custom bags always show their `name` |
| `description` | text | none | Extra line in the item tooltip (only with DynamicTooltipsLib) |
| `rarity` | text | `"common"` | Tier: `common`, `uncommon`, `rare`, `epic`, `legendary`. Unknown values count as common |
| `visualItemId` | text | none | Existing lootbag item whose model, icon and look a **new** bag borrows, e.g. `"Golden_Lootbag"`. See [Custom Lootbags](./custom-lootbags#the-item-of-a-new-bag) |
| `items` | list | none | Fixed items, always given (same effect as `guaranteedItems`) |
| `guaranteedItems` | list | none | Items that are always in the bag |
| `pool` | list | none | Random pool; each entry has a `weight` |
| `pickCount` | number | `0` | How many items are drawn from the pool. `0` = nothing is drawn |
| `allowDuplicates` | boolean | `false` | `true`: every draw uses the whole pool, the same item can come twice. `false`: a drawn item leaves the pool for the rest of this opening |
| `icon` | text | | Read but not used in 2.0.4 |

**Item entries** have `itemId` and `amount` (at least 1, `0` or missing counts as 1). Pool entries also have `weight` (at least 1). The chance of a draw is the entry's weight divided by the total weight of the entries still in the pool.

### How a bag is opened

1. Every fixed and guaranteed item is added.
2. `pickCount` items are drawn from the pool by weight (without duplicates: at most as many as the pool has).
3. Items whose ID does not exist on the server are skipped and logged. If nothing is left, the bag is **not** used up.
4. One bag of that kind is taken from the hotbar, the items go into the inventory (hotbar first), and whatever does not fit is dropped at the player's feet.

The catalog and the opening window show the **chance per bag**: the probability that an item is among the drawn ones of one opening, with all draws counted (exact up to 200,000 possible draw orders, otherwise from a fixed sample; with duplicates `1 - (1 - p)^picks`).

---

## Drop rules (drop_tables.json)

Two lists of patterns: `mobDrops` for creatures, `blockDrops` for blocks broken by players. Each pattern holds one or more entries.

The shipped file:

```json
{
  "mobDrops": {
    "*":         [ { "itemId": "Default_Lootbag", "chance": 0.02 } ],
    "Trork_*":   [ { "itemId": "Bone_Lootbag", "chance": 0.05 },
                   { "itemId": "Crimson_Lootbag_Common", "chance": 0.01 } ],
    "Scarak_*":  [ { "itemId": "Crimson_Lootbag", "chance": 0.03 },
                   { "itemId": "Crystal_Lootbag_Common", "chance": 0.01 } ],
    "Kweebec_*": [ { "itemId": "Mossy_Lootbag", "chance": 0.04 },
                   { "itemId": "Sakura_Lootbag_Common", "chance": 0.01 } ]
  },
  "blockDrops": {
    "Ore_*":           [ { "itemId": "Copper_Lootbag", "chance": 0.03 } ],
    "Ore_Gold*":       [ { "itemId": "Golden_Lootbag_Common", "chance": 0.05 } ],
    "Ore_Adamantite*": [ { "itemId": "Crystal_Lootbag", "chance": 0.02 },
                         { "itemId": "Crystal_Lootbag_Epic", "chance": 0.005 } ],
    "Ore_Cobalt*":     [ { "itemId": "Ocean_Lootbag", "chance": 0.04 } ]
  }
}
```

`Crystal_Lootbag_Epic` does not exist; the plugin maps it to `Crystal_Lootbag` (the epic Crystal bag) when it loads the rules. The admin panel writes the mapped ID on its next save.

### Entry fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `lootbagId` | text | | Bag ID to drop. `itemId` is accepted as well (the shipped file uses it; the admin panel writes `lootbagId`) |
| `chance` | number | | Chance per kill or per broken block, `0.05` = 5 %. Multiplied by `dropMultiplier` |
| `minAmount` | number | `1` | Smallest number of bags dropped |
| `maxAmount` | number | `1` | Largest number of bags dropped (random between min and max) |

### Patterns

| Pattern | Matches |
|---------|---------|
| `*` | Everything |
| `Trork_*` | Every ID that starts with `Trork_` |
| `Ore_Gold` | Exactly `Ore_Gold` |

Only a single `*` or one `*` at the end works; `*_Gold` or `Ore_*_Big` match nothing.

- **Creatures** are matched by their NPC role name (for example `Trork_Warrior`) and, when it differs, by their NPC type ID. Every NPC death counts, whoever or whatever killed it; player deaths never drop bags. The bags appear on the ground where the creature died.
- **Blocks** are matched by the block type ID (for example `Ore_Gold_Basalt`). Only blocks broken by a player count. The bags appear at the block's position.
- **Every matching entry rolls on its own.** A Trork with the shipped rules rolls the `*` entry and both `Trork_*` entries, so it can drop up to three bags.
- A rule whose bag ID does not exist never drops. The server log names it at start, and the admin panel shows the row in red.

---

## Languages

The plugin ships `en-US`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `ru-RU`, `pl-PL`, `tr-TR` and `it-IT` in `localization/`. The files carry `_localization_version` 11. When the jar brings a newer version, the plugin renames your file to `<lang>.json.backup-v<old>` and writes the new one, so copy your own changes over again after an update.

Which language a player sees:

1. The language picked with `/kslang`, `/lbadmin lang` or the KS settings window (`/kssettings`, with KyuubiSoft Core), stored in `mods/kslang/prefs.json` and shared by all KyuubiSoft mods (re-read at most every 5 seconds). It only counts while the server lets players choose.
2. Otherwise the server's default player language, if one is set.
3. Otherwise the language the client reports, matched to the closest shipped language (for example `de-AT` uses `de-DE`).
4. Otherwise `en-US`. Missing keys fall back to `en-US` as well.

The default player language and the "players may choose" switch are set in the Language tab of Core's `/ksadmin` hub (KyuubiSoft Core 2.8.0 or newer) and apply to every KyuubiSoft mod.

What comes from where:

| Text | Source |
|------|--------|
| Windows, chat messages, the opening summary | The plugin's `localization/<lang>.json`, in the player's language |
| Bag names in the windows | `lootbag.style.<Style>` and `lootbag.tier.<tier>`, joined by `lootbag.name.format` (`"{0} ({1})"`): "Crystal Lootbag (Epic)", in German "Kristallbeutel (Episch)". Group headers use `lootbag.group.<group>` |
| Item names in the windows and in the chat summary | Hytale's own item translations, in the client's language |
| Tooltips (DynamicTooltipsLib) | The plugin's language files, in the client's language (not the `/kslang` choice) |
| Bag names in the hotbar | The item files inside the jar, which carry English and German names (for example "Copper Lootbag (Uncommon)", in German "Kupfer Beutebeutel"). They are not the names the plugin windows use |
| Chance numbers | The decimal separator of `lootbag.decimal` (`.` in English, `,` in German) |

**Adding a language:** copy `en-US.json` to `<code>.json` (for example `nl-NL.json`) in `localization/`, translate the values and restart the server. Every `.json` file in the folder is loaded, except names that start with `custom_` or contain `.backup` or `.example`. The language is used for players whose client or `/kslang` choice is exactly that code.

---

## Player data

`data/players/<uuid>.json` is loaded when a player joins and saved when the player leaves, every 5 minutes and when the server stops. The file is written to a temporary file first and then moved into place; the previous version stays as `.bak` and is used when the main file cannot be read.

| Field | Content |
|-------|---------|
| `totalOpened`, `totalCommon` ... `totalLegendary` | Bags opened, overall and per tier (the bag's tier at the time it was opened) |
| `totalItemsReceived` | Items received (each item of an opening counts once) |
| `perLootbagOpened` | Opened count per bag ID |
| `openings` | The last 50 openings with bag, time and items (History tab) |
| `showRevealPage` | The player's `/kslootbags settings animation` choice |
| `lootHistory` | Text history of 1.x, still read, no longer written or shown |

`data/latest_drops.json` keeps the last 30 openings on the server (player, bag, best item). It is saved every 5 minutes and when the server stops.

---

## Reload

`/lbadmin reload` and the **Reload** button of the admin panel reload `config.json`, both bag files and `drop_tables.json`. Language files are only read at server start. See [Commands](./commands#lbadmin-reload).