Skip to main content

Getting Started

This guide walks you through setting up the Lootbags plugin on your Hytale server.

1. Install the Plugin​

Place the lootbag.jar file into your server's mods/ directory. The Lootbags plugin requires KyuubiSoft Core.

server/
  mods/
    lootbag.jar
    core.jar        (required — TrackingService, DynamicTooltips, ModMenuRegistry)

Start the server. On first launch the plugin creates its data folder and extracts all default configs.

2. Verify First Launch​

After the server starts, check the console for:

[KyuubiSoft Lootbag] Config loaded: enabled=true, revealPage=true, drops=true
[KyuubiSoft Lootbag] Loaded 120 lootbag definitions
[KyuubiSoft Lootbag] Loaded drop tables: 5 mob types (8 entries), 3 block types (4 entries)

The plugin data folder is created at:

server/
  mods/
    lootbag/
      config.json
      configs/
        lootbags.json        (120 standard lootbag definitions)
        drop_tables.json     (mob and block drop rules)
      custom/
        custom_lootbags.json.example

3. Basic Configuration​

Global Toggles​

Edit config.json to control the master switches:

{
  "enabled": true,
  "revealPageEnabled": true,
  "dropEnabled": true
}
  • Set dropEnabled to false if you want lootbags as rewards only (no random drops)
  • Set revealPageEnabled to false to force direct mode for all players

Drop Tables​

Edit configs/drop_tables.json to define which mobs and blocks drop lootbags:

{
  "mobDrops": {
    "*": [
      { "lootbagId": "Default_Common", "chance": 0.03, "minAmount": 1, "maxAmount": 1 }
    ],
    "Skeleton_*": [
      { "lootbagId": "Bone_Uncommon", "chance": 0.08, "minAmount": 1, "maxAmount": 1 }
    ]
  },
  "blockDrops": {
    "Ore_*": [
      { "lootbagId": "Copper_Common", "chance": 0.02, "minAmount": 1, "maxAmount": 1 }
    ]
  }
}

Use * for a global fallback, or specific patterns like Skeleton_* for targeted drops.

Custom Lootbags​

To add your own lootbag types, create custom/custom_lootbags.json:

{
  "MyServer_EventBag": {
    "name": "Event Lootbag",
    "rarity": "epic",
    "guaranteedItems": [
      { "itemId": "Gold_Ingot", "amount": 10 }
    ],
    "pickCount": 2,
    "pool": [
      { "itemId": "Diamond", "amount": 1, "weight": 5 },
      { "itemId": "Emerald", "amount": 3, "weight": 15 }
    ]
  }
}

This file is never overwritten by plugin updates.

4. Test It​

Open a Lootbag​

  1. Give yourself a lootbag: 
    /lbadmin give Default_Common
  2. Right-click the lootbag item to open it
  3. Watch the reveal animation, then collect your items

Test Drop System​

  1. Ensure dropEnabled is true
  2. Kill a mob or break a block that matches your drop table patterns
  3. Lootbags appear in your inventory on successful drop rolls

Manage via Admin Panel​

  1. Open the admin panel: 
    /lbadmin panel
  2. Browse all lootbags in the Catalog tab
  3. Give items in the Give tab
  4. Edit drop rules in the Drops tab
  5. Check server stats in the Statistics tab
  6. Toggle features in the Settings tab

Preview Contents​

Preview what a lootbag can contain:

/lbadmin preview Golden_Rare

List All Lootbags​

/lbadmin list

5. Player Features​

Players have two commands available:

  • View stats: /kslootbags stats (alias: /lb stats)
  • Toggle animation: /kslootbags settings animation off (alias: /lb settings animation off)

Players can also:

  • Right-click a lootbag item to open it
  • Sneak + Right-click to place it as a decorative block with a rarity glow

6. Reload After Changes​

After editing any config file, reload without restarting:

/lbadmin reload

Next Steps​

  • See Commands for the full command reference
  • See Configuration for all config fields and lootbag definition formats