Loot Tables API

Binary-only library for loot generation.

Description

⚠️ This is an early-stage API (v0.1.1). The API may change and backward compatibility is not guaranteed.

This library provides a loot table service with support for:

• loot modes
• loot tiers
• weighted rolls
• guaranteed drops
• optional metadata (name, rarity)
• direct insertion into inventories
• configurable inventory placement (random / sequential)
• runtime config reload (admin command)

It is intended to be used as a dependency by other server plugins or mods.

Installing

Developers

1. Server setup (required)
2. Place the LootGenerator mod in the Mods folder.
3. Enable the mod in the world settings.

⚠️ Important The LootGenerator mod must be installed in the Mods folder and enabled in the world. Otherwise, the loot service will not be available.

2\. Add dependency

Add the dependency to your mod configuration files.

manifest.json

"Dependencies": {
  "nofrfa.vectome.loot:LootGenerator": "*"
}

pom.xml

<dependency>
  <groupId>nofrfa.vectome.loot</groupId>
  <artifactId>LootGenerator</artifactId>
  <version>0.1.1</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/libs/LootGenerator-0.1.1.jar</systemPath>
</dependency>

📦 Local library <your-mod>/libs/LootGenerator-0.1.1.jar

**Notes for developers** ⚙️

• The LootGenerator mod must be installed on the server and enabled in the world
• The version specified in systemPath must match the actual JAR version
• This library is binary-only

Usage

Getting the service

The loot service is registered automatically on startup and can be accessed globally.

⚠️ Important Prefer LootTableServices.getOrThrow() over get() to ensure the loot service is available.

Rolling loot (without inventory)

LootTableService lootService = LootTableServices.getOrThrow();

List<ItemStack> items = lootService.roll(
    "Default", // mode
    "Basic",   // tier
    3          // rolls
);

Returns a list of generated ItemStack.

Rolling loot directly into an inventory

LootInsertResult result = LootTableServices.getOrThrow().roll(
    "Default",
    "Rare",
    2,
    playerInventory
);

List<ItemStack> inserted = result.inserted();
List<ItemStack> remainder = result.remainder();

• inserted — items successfully placed into the inventory
• remainder — items that did not fit

Configuration

The configuration file is automatically created on first launch and can be safely edited afterward.

Configuration structure

{
  "Modes": {
    "Default": {
      "Tiers": {
        "Basic": [
          {
            "Item": "Item_Id",
            "Name": "CustomName",
            "Guaranteed": true,
            "Rarity": 5,
            "Weight": 10,
            "Min": 1,
            "Max": 5
          }
        ]
      }
    }
  }
}

Loot entry fields

Notes:

• Guaranteed entries are rolled once before weighted rolls
• Entries with Weight > 0 participate in weighted rolls regardless of Guaranteed
• A loot entry may drop multiple times if both Guaranteed and Weight are set
• Entries with Weight <= 0 do not participate in weighted rolls
• All values are normalized automatically on load

Admin Commands

These commands are intended for server administrators and developers. They do not add any gameplay features.

/lt reload — Reloads the loot configuration at runtime. Permission: loottables.reload

Compatibility

• API and behavior may change with future Hytale updates
• Backward compatibility is not guaranteed

Source Code

Not published.