Skip to content

Lootbags

Documentation for lootbags.json — lootbag templates used as achievement rewards.

:::info Not the standalone Lootbag Mod These are reward definitions, not droppable items. For the standalone Lootbags mod with 150 collectible bags (30 styles in 5 tiers), mob/block drops and a catalog window, see Lootbags Mod. :::

Lootbags are reward containers that players open to receive items. A lootbag reward waits in the Rewards tab of the achievement book (/ksrewards) until the player opens it. It is rolled once and the result is saved, so a relog never re-rolls it.

Since 3.0.0 there is one lootbag registry: KyuubiSoft Core’s. The bags of this mod’s lootbags.json (and custom/custom_lootbags.json) are registered there, so Core, Quests and other mods can use them by id. If Core already has its own standard or custom bag with the same id, Core’s bag wins.

  • With KyuubiSoft Core 2.9.2 or newer, a reload (/ksadmin reload or a save in the admin window) applies new, changed and removed bags at once.
  • With an older Core, only new bags apply at once; changed and removed bags apply after a restart (the reload message says so).

Features:

  • Three lootbag types - Fixed items, random pool, or hybrid
  • Weighted randomization - Control item drop chances
  • Rarity system - Visual distinction by rarity tier
  • Auto-export - Default templates are created automatically
FileNotes
mods/kyuubisoft_achievements/configs/lootbags.jsonShipped bags (version 4, 20 bags). Replaced when a new version ships a newer file; an older file is backed up
mods/kyuubisoft_achievements/custom/custom_lootbags.jsonYour own bags and overrides (same id = override). Never overwritten

The player receives all defined items.

{
"welcome_gift": {
"name": "Welcome Gift",
"description": "A small starter pack for new players",
"icon": "Furniture_Ancient_Chest_Small",
"rarity": "common",
"items": [
{ "itemId": "Food_Bread", "amount": 10 },
{ "itemId": "Furniture_Ancient_Torch", "amount": 16 },
{ "itemId": "Tool_Pickaxe_Wood", "amount": 1 }
]
}
}

The player receives X random items from a weighted pool.

{
"food_crate": {
"name": "Food Crate",
"description": "Provisions for your journey",
"icon": "Food_Bread",
"rarity": "common",
"pickCount": 3,
"allowDuplicates": true,
"pool": [
{ "itemId": "Food_Bread", "amount": 5, "weight": 50 },
{ "itemId": "Plant_Fruit_Apple", "amount": 8, "weight": 40 },
{ "itemId": "Food_Fish_Grilled", "amount": 3, "weight": 30 },
{ "itemId": "Potion_Health", "amount": 2, "weight": 10 }
]
}
}

The player receives guaranteed items plus X random items from the pool.

{
"playtime_gold": {
"name": "Gold Loyalty Reward",
"description": "For dedicated players",
"icon": "Ore_Gold",
"rarity": "rare",
"guaranteedItems": [
{ "itemId": "Ore_Gold", "amount": 25 }
],
"pickCount": 2,
"allowDuplicates": false,
"pool": [
{ "itemId": "Rock_Gem_Ruby", "amount": 1, "weight": 20 },
{ "itemId": "Rock_Gem_Emerald", "amount": 1, "weight": 20 },
{ "itemId": "Rock_Gem_Sapphire", "amount": 1, "weight": 20 },
{ "itemId": "Ore_Mithril", "amount": 5, "weight": 15 }
]
}
}

FieldTypeRequiredDescription
namestringYesDisplay name of the lootbag
descriptionstringYesDescription text
iconstringYesItem ID for the icon
raritystringNoRarity tier (see below)
itemsarrayNo*Fixed items (Type A)
guaranteedItemsarrayNo*Guaranteed items (Type C)
pickCountnumberNo*Number of random picks
allowDuplicatesbooleanNoAllow duplicate picks (default: false)
poolarrayNo*Pool for random picks
FieldTypeRequiredDescription
itemIdstringYesItem ID (e.g., Ore_Gold)
amountnumberNoQuantity (default: 1)
weightnumberNo*Weight for random selection
RarityColorTypical Use
commonGray (#AAAAAA)Starter rewards, simple achievements
uncommonGreen (#55FF55)Normal achievements
rareBlue (#5555FF)Difficult achievements
epicPurple (#AA00AA)Epic achievements
legendaryOrange (#FFAA00)End-game achievements

The plugin includes these pre-configured lootbags:

IDNameTypeRarity
starter_packStarter PackFixedcommon
miner_rewardMiner’s TreasureFixeduncommon
combat_lootWarrior’s CacheHybridrare
explorer_chestExplorer’s ChestRandomepic
legendary_hoardDragon’s HoardHybridlegendary
welcome_giftWelcome GiftFixedcommon
IDNameTypeRarity
copper_bundleCopper Ore BundleFixeduncommon
copper_toolsCopper Tool Set (new in file version 4)Fixeduncommon
iron_toolsIron Tool SetFixedrare
ore_bundle_commonOre Bundle (Basic)Fixedcommon
ore_bundle_rareOre Bundle (Rare)Fixedrare
ore_bundle_epicOre Bundle (Epic)Fixedepic
lumberjack_packLumberjack PackFixeduncommon
IDNameTypeRarity
food_crateFood CrateRandomcommon
builder_bundleBuilder BundleRandomuncommon
hunter_rewardHunter’s BountyRandomuncommon
social_giftSocial GiftFixedcommon
IDNameTypeRarity
playtime_bronzeBronze Loyalty RewardFixedcommon
playtime_silverSilver Loyalty RewardFixeduncommon
playtime_goldGold Loyalty RewardHybridrare

{
"id": "welcome",
"category": "social",
"iconItem": "Furniture_Ancient_Chest_Small",
"difficulty": "easy",
"trigger": {
"type": "playtime_minutes",
"count": 1
},
"rewards": [
{ "type": "lootbag", "lootbagId": "welcome_gift" }
]
}

Localization:

achievements.name.welcome=Welcome!
achievements.desc.welcome=Play for 1 minute

For random pools, the probability of selecting an item is:

Probability = item_weight / total_weight

Example:

"pool": [
{ "itemId": "Food_Bread", "amount": 5, "weight": 50 }, // 50/130 = 38.5%
{ "itemId": "Plant_Fruit_Apple", "amount": 8, "weight": 40 }, // 40/130 = 30.8%
{ "itemId": "Food_Fish_Grilled", "amount": 3, "weight": 30 }, // 30/130 = 23.1%
{ "itemId": "Potion_Health", "amount": 2, "weight": 10 } // 10/130 = 7.7%
]
// Total weight: 130

  1. Open custom/custom_lootbags.json (copy custom_lootbags.json.example if it does not exist yet)
  2. Add your lootbag definition:
{
"existing_lootbags": { ... },
"my_custom_lootbag": {
"name": "My Custom Reward",
"description": "A special reward",
"icon": "Furniture_Ancient_Chest_Small",
"rarity": "epic",
"guaranteedItems": [
{ "itemId": "Ore_Gold", "amount": 50 }
],
"pickCount": 3,
"allowDuplicates": false,
"pool": [
{ "itemId": "Rock_Gem_Diamond", "amount": 1, "weight": 10 },
{ "itemId": "Rock_Gem_Ruby", "amount": 2, "weight": 30 },
{ "itemId": "Rock_Gem_Emerald", "amount": 2, "weight": 30 },
{ "itemId": "Ingredient_Bar_Gold", "amount": 10, "weight": 30 }
]
}
}
  1. Reference it in an achievement:
{
"rewards": [
{ "type": "lootbag", "lootbagId": "my_custom_lootbag" }
]
}
  1. Reload with /ksadmin reload (see One registry with KyuubiSoft Core for when changes apply)

  1. Balance weights carefully - Very low weights may frustrate players
  2. Use appropriate rarities - Match rarity to achievement difficulty
  3. Consider duplicates - Set allowDuplicates: false for variety
  4. Test lootbags - Grant the achievement to yourself with /acadmin grant and open the bag in the Rewards tab
  5. Descriptive names - Help players understand what they’re getting