Configuration
All files live in the plugin’s data folder mods/kyuubisoft_lootbag/. Most settings can also be changed in the admin panel, which writes the same 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 |
data/... | Automatically | No |
config.json
Section titled “config.json”The shipped file:
{ "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” |
Bag files
Section titled “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:
{ "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
Section titled “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 |
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
Section titled “How a bag is opened”- Every fixed and guaranteed item is added.
pickCountitems are drawn from the pool by weight (without duplicates: at most as many as the pool has).- Items whose ID does not exist on the server are skipped and logged. If nothing is left, the bag is not used up.
- 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)
Section titled “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:
{ "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
Section titled “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
Section titled “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 bothTrork_*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
Section titled “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:
- The language picked with
/kslang,/lbadmin langor the KS settings window (/kssettings, with KyuubiSoft Core), stored inmods/kslang/prefs.jsonand shared by all KyuubiSoft mods (re-read at most every 5 seconds). It only counts while the server lets players choose. - Otherwise the server’s default player language, if one is set.
- Otherwise the language the client reports, matched to the closest shipped language (for example
de-ATusesde-DE). - Otherwise
en-US. Missing keys fall back toen-USas 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
Section titled “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
Section titled “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.