Skip to content

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
FileWritten by the pluginEdited by you
config.jsonWhen missing; when settings or drop rules are saved in the admin panelYes, then /lbadmin reload
configs/lootbags.jsonOnly when missingBetter not: put changes into custom/custom_lootbags.json
configs/drop_tables.jsonWhen missing; when drop rules are saved in the admin panel (old file kept as .bak)Yes, then /lbadmin reload
custom/custom_lootbags.jsonEvery save in the admin panel’s Bags section and every /lbadmin edit (old file kept as .bak)Yes, then /lbadmin reload
localization/<lang>.jsonWhen missing or older than the jar’s versionYes, but see Languages
data/...AutomaticallyNo

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.

FieldTypeDefaultEffectAdmin panel
enabledbooleantrueMaster 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 workingSettings: “Lootbags active”
revealPageEnabledbooleantrueOff: no opening window for anyone, every opening is listed in the chat. On: each player decides with /kslootbags settings animationSettings: “Show result window”
dropEnabledbooleantrueOff: creatures and mining drop no bags. Giving bags and opening them still workDrop rules: “Drops active”
openCooldownMsnumber1000Milliseconds between two openings of the same player (right-click and “Open another”). A click during the cooldown does nothingSettings: “Open cooldown” (0 to 600000)
dropMultipliernumber1.0Multiplies the chance of every drop rule. 2.0 doubles all chances, 0 stops all drops. The catalog shows chances with the multiplier appliedDrop rules: “Drop factor” (0 to 100)
showDropSourcesbooleantrueShows the Where to find section in the catalog: which rules drop the bag and how likelySettings: “Show drop sources”
ignorePlacedBlocksbooleantrueBlocks that players placed drop no bags when broken (no place-and-break farming of ore)Drop rules: “Ignore self-placed blocks”

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.

FieldTypeDefaultDescription
nametext"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
descriptiontextnoneExtra line in the item tooltip (only with DynamicTooltipsLib)
raritytext"common"Tier: common, uncommon, rare, epic, legendary. Unknown values count as common
visualItemIdtextnoneExisting lootbag item whose model, icon and look a new bag borrows, e.g. "Golden_Lootbag". See Custom Lootbags
itemslistnoneFixed items, always given (same effect as guaranteedItems)
guaranteedItemslistnoneItems that are always in the bag
poollistnoneRandom pool; each entry has a weight
pickCountnumber0How many items are drawn from the pool. 0 = nothing is drawn
allowDuplicatesbooleanfalsetrue: 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
icontextRead 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.

  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).


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.

FieldTypeDefaultDescription
lootbagIdtextBag ID to drop. itemId is accepted as well (the shipped file uses it; the admin panel writes lootbagId)
chancenumberChance per kill or per broken block, 0.05 = 5 %. Multiplied by dropMultiplier
minAmountnumber1Smallest number of bags dropped
maxAmountnumber1Largest number of bags dropped (random between min and max)
PatternMatches
*Everything
Trork_*Every ID that starts with Trork_
Ore_GoldExactly 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.

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:

TextSource
Windows, chat messages, the opening summaryThe plugin’s localization/<lang>.json, in the player’s language
Bag names in the windowslootbag.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 summaryHytale’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 hotbarThe 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 numbersThe 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.


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.

FieldContent
totalOpened, totalCommon … totalLegendaryBags opened, overall and per tier (the bag’s tier at the time it was opened)
totalItemsReceivedItems received (each item of an opening counts once)
perLootbagOpenedOpened count per bag ID
openingsThe last 50 openings with bag, time and items (History tab)
showRevealPageThe player’s /kslootbags settings animation choice
lootHistoryText 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.


/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.