Skip to main content

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?​

PatternMatches
*All mob/block types (global fallback)
Trork_*All IDs starting with Trork_
Ore_GoldOnly 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