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. :::
Overview
Section titled “Overview”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.
One registry with KyuubiSoft Core
Section titled “One registry with KyuubiSoft Core”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 reloador 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
| File | Notes |
|---|---|
mods/kyuubisoft_achievements/configs/lootbags.json | Shipped 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.json | Your own bags and overrides (same id = override). Never overwritten |
Lootbag Types
Section titled “Lootbag Types”Type A: Fixed Items (Guaranteed)
Section titled “Type A: Fixed Items (Guaranteed)”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 } ] }}Type B: Random Pool
Section titled “Type B: Random Pool”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 } ] }}Type C: Hybrid (Guaranteed + Random)
Section titled “Type C: Hybrid (Guaranteed + Random)”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 } ] }}Field Reference
Section titled “Field Reference”Lootbag Definition
Section titled “Lootbag Definition”| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name of the lootbag |
description | string | Yes | Description text |
icon | string | Yes | Item ID for the icon |
rarity | string | No | Rarity tier (see below) |
items | array | No* | Fixed items (Type A) |
guaranteedItems | array | No* | Guaranteed items (Type C) |
pickCount | number | No* | Number of random picks |
allowDuplicates | boolean | No | Allow duplicate picks (default: false) |
pool | array | No* | Pool for random picks |
Item Definition
Section titled “Item Definition”| Field | Type | Required | Description |
|---|---|---|---|
itemId | string | Yes | Item ID (e.g., Ore_Gold) |
amount | number | No | Quantity (default: 1) |
weight | number | No* | Weight for random selection |
Rarity Values
Section titled “Rarity Values”| Rarity | Color | Typical Use |
|---|---|---|
common | Gray (#AAAAAA) | Starter rewards, simple achievements |
uncommon | Green (#55FF55) | Normal achievements |
rare | Blue (#5555FF) | Difficult achievements |
epic | Purple (#AA00AA) | Epic achievements |
legendary | Orange (#FFAA00) | End-game achievements |
Default Templates
Section titled “Default Templates”The plugin includes these pre-configured lootbags:
Basic Templates
Section titled “Basic Templates”| ID | Name | Type | Rarity |
|---|---|---|---|
starter_pack | Starter Pack | Fixed | common |
miner_reward | Miner’s Treasure | Fixed | uncommon |
combat_loot | Warrior’s Cache | Hybrid | rare |
explorer_chest | Explorer’s Chest | Random | epic |
legendary_hoard | Dragon’s Hoard | Hybrid | legendary |
welcome_gift | Welcome Gift | Fixed | common |
Tool & Resource Bundles
Section titled “Tool & Resource Bundles”| ID | Name | Type | Rarity |
|---|---|---|---|
copper_bundle | Copper Ore Bundle | Fixed | uncommon |
copper_tools | Copper Tool Set (new in file version 4) | Fixed | uncommon |
iron_tools | Iron Tool Set | Fixed | rare |
ore_bundle_common | Ore Bundle (Basic) | Fixed | common |
ore_bundle_rare | Ore Bundle (Rare) | Fixed | rare |
ore_bundle_epic | Ore Bundle (Epic) | Fixed | epic |
lumberjack_pack | Lumberjack Pack | Fixed | uncommon |
Activity Rewards
Section titled “Activity Rewards”| ID | Name | Type | Rarity |
|---|---|---|---|
food_crate | Food Crate | Random | common |
builder_bundle | Builder Bundle | Random | uncommon |
hunter_reward | Hunter’s Bounty | Random | uncommon |
social_gift | Social Gift | Fixed | common |
Playtime Rewards
Section titled “Playtime Rewards”| ID | Name | Type | Rarity |
|---|---|---|---|
playtime_bronze | Bronze Loyalty Reward | Fixed | common |
playtime_silver | Silver Loyalty Reward | Fixed | uncommon |
playtime_gold | Gold Loyalty Reward | Hybrid | rare |
Example: Achievement with Lootbag
Section titled “Example: Achievement with Lootbag”{ "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 minuteWeight Calculation
Section titled “Weight Calculation”For random pools, the probability of selecting an item is:
Probability = item_weight / total_weightExample:
"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: 130Creating Custom Lootbags
Section titled “Creating Custom Lootbags”- Open
custom/custom_lootbags.json(copycustom_lootbags.json.exampleif it does not exist yet) - 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 } ] }}- Reference it in an achievement:
{ "rewards": [ { "type": "lootbag", "lootbagId": "my_custom_lootbag" } ]}- Reload with
/ksadmin reload(see One registry with KyuubiSoft Core for when changes apply)
Best Practices
Section titled “Best Practices”- Balance weights carefully - Very low weights may frustrate players
- Use appropriate rarities - Match rarity to achievement difficulty
- Consider duplicates - Set
allowDuplicates: falsefor variety - Test lootbags - Grant the achievement to yourself with
/acadmin grantand open the bag in the Rewards tab - Descriptive names - Help players understand what they’re getting