Getting Started

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. KyuubiSoft Core is optional but recommended.

server/
  mods/
    lootbag.jar
    core.jar        (optional — admin menu, language settings, showcase integration)

:::tip Core is optional The Lootbags plugin works fully standalone. Core adds admin menu integration, shared language settings, and showcase NPC support. DynamicTooltipsLib is also optional and adds enhanced item tooltips. :::

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,
  "openCooldownMs": 1000,
  "dropMultiplier": 1.0
}

• 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
• Adjust openCooldownMs to control the delay between openings (default: 1 second)
• Set dropMultiplier to 2.0 for a double-drop event or 0.5 for reduced drops

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
• See Custom Lootbags for creating your own lootbag definitions
• See Admin Panel for a detailed guide to the in-game management UI
• See FAQ & Troubleshooting if you encounter issues