FAQ & Troubleshooting

FAQ & Troubleshooting

Common questions and solutions for the Lootbags system.

---

Frequently Asked Questions

General

Q: Does Lootbags require KyuubiSoft Core?

No. The Lootbags plugin works fully standalone. Core is an optional dependency that adds:

• Admin menu integration (access the lootbag admin panel from Core’s mod menu)
• Shared language settings via I18nContext
• Showcase NPC page opener (showcase_lootbag)

Without Core, all commands, the admin panel, and all features work normally.

Q: Does Lootbags require DynamicTooltipsLib?

No. DynamicTooltipsLib is optional. When installed, it provides enhanced rarity-colored tooltips on all lootbag items. Without it, standard item tooltips are used.

Q: How many lootbags are included?

120 lootbag items across 24 themed families and 5 rarity tiers. You can add unlimited custom lootbags.

Q: What languages are supported?

English (en-US) and German (de-DE) are included. You can add any language by placing a JSON file in the localization/ folder. The admin panel language dropdown also lists fr-FR, es-ES, pt-BR, ru-RU, pl-PL, tr-TR, and it-IT as options.

---

Lootbag Mechanics

Q: How do I open a lootbag?

Right-click the lootbag item in your hand. The lootbag is consumed and its contents are added to your inventory (or dropped on the ground if your inventory is full).

Q: How do I place a lootbag as a decorative block?

Sneak (crouch) + Right-click to place the lootbag as a decorative block instead of opening it. Placed lootbags display a rarity-colored glow effect.

Q: Can I disable the reveal animation?

Yes, two ways:

• Per player: /kslootbags settings animation off
• Globally: Set revealPageEnabled to false in config.json

When disabled, items go directly to inventory and a chat summary is shown.

Q: What happens if my inventory is full when opening a lootbag?

Items that cannot fit in your inventory are dropped at your feet as world items. You receive a notification indicating how many items were dropped.

Q: What is the opening cooldown?

The openCooldownMs setting (default: 1000ms) prevents spam-opening lootbags. After opening one lootbag, you must wait for the cooldown to expire before opening another.

Q: What does the drop multiplier do?

The dropMultiplier config (default: 1.0) is applied to all mob and block drop chances. Set it to 2.0 for a double-drop event, 0.5 for reduced drops, or 0.0 to temporarily disable all drops without removing rules.

---

Drops

Q: How do mob drops work?

When a mob dies, the system checks its role name (e.g., Trork_Warrior) against all patterns in the mob drop table. Matching entries are evaluated independently — each rolls its chance multiplied by the dropMultiplier. Successful drops spawn as world items at the mob’s death position.

Q: How do block drops work?

When a player breaks a block, the block’s type ID (e.g., Ore_Gold) is checked against all patterns in the block drop table. The process works the same as mob drops, with items spawning at the broken block’s position.

Q: How do wildcard patterns work?

Pattern	Matches
*	All mob/block types (global fallback)
Trork_*	All IDs starting with Trork_
Ore_Gold	Only the exact ID Ore_Gold

Multiple patterns can match the same mob or block. All matching entries are evaluated independently.

Q: Can the same mob trigger multiple drops?

Yes. If a mob matches multiple patterns (e.g., * and Trork_*), all matching entries are evaluated. Each entry rolls its chance independently.

---

Administration

Q: How do I give a lootbag to another player?

Two options:

• Command: /lbadmin give <lootbagId> [amount] gives the lootbag to yourself
• Admin Panel: In the Give tab, enter the player’s name in the Player field

Q: How do I create a custom lootbag?

See the Custom Lootbags guide. In short:

1. Create custom/custom_lootbags.json with your definition
2. Run /lbadmin reload

Or use the admin panel editor or the /lbadmin edit command.

Q: Where are admin panel edits saved?

All edits from the admin panel and /lbadmin edit command are saved to custom/custom_lootbags.json. The standard configs/lootbags.json is never modified.

Q: How do I reload config changes?

Run /lbadmin reload or click Reload configs in the admin panel’s Settings tab. This reloads lootbag definitions, drop tables, and localization files.

---

Troubleshooting

Mob drops are not working

Check the following:

1. Config toggles: Ensure enabled and dropEnabled are both true in config.json
2. Drop table patterns: Mob drops match against the NPC’s role name (e.g., Trork_Warrior), not the internal type ID. Use /lbadmin reload after editing the drop table.
3. Drop multiplier: Ensure dropMultiplier is not set to 0.0
4. Chance values: Chances are decimals from 0.0 to 1.0 in JSON (not percentages). A 0.05 value means 5%.
5. Console logs: Check server logs for [LootbagDrop] messages. The handler logs which NPC role/type it detected and how many drop entries matched.

Block drops are not working

Same checks as mob drops above. Block drops match against the block type ID (e.g., Ore_Gold, Ore_Cobalt).

”Lootbag not found” error when using give command

The item ID must match a registered lootbag definition exactly (case-sensitive). Use /lbadmin list to see all available IDs. Common format: Family_Lootbag (common rarity omits the suffix) or Family_Lootbag_Rarity (e.g., Golden_Lootbag_Legendary).

Admin panel does not open

• Ensure you have the kslootbagsadmin command permission (operator/admin access)
• Check the console for error messages from [KyuubiSoft Lootbag]

Changes not taking effect after editing JSON files

Run /lbadmin reload to reload all configuration files from disk. Changes made to JSON files are not picked up automatically.

Player stats show zero

Player statistics are loaded when a player connects. If the plugin was just installed, stats start at zero and accumulate as lootbags are opened. Stats are auto-saved every 5 minutes and on player disconnect.

Lootbag items go to the ground instead of inventory

When a player’s inventory is full, items are dropped at their feet. This is intentional behavior. A notification is sent to the player.

Custom lootbags not loading

1. Check that custom/custom_lootbags.json is valid JSON (no trailing commas, proper quoting)
2. Check the server console for error messages during loading
3. Ensure the file is in the custom/ directory inside the plugin data folder
4. Run /lbadmin reload after adding or modifying the file

Localization files not updating

Bundled language files (en-US.json, de-DE.json) are auto-updated when the internal _localization_version changes. If you have made manual edits to these files, the old version is backed up before updating. Custom language files are never overwritten.

DynamicTooltips not showing

1. Ensure DynamicTooltipsLib.jar is in the mods/ directory
2. Check the console for DynamicTooltips integration enabled on startup
3. If the log says DynamicTooltipsLib not found, the JAR is missing or not loading