Loot Tables API

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

Field	Type	Required	Default	Description
Item	string	Yes	–	Item identifier
Weight	integer	No	0	Weight for random selection
Guaranteed	boolean	No	false	Always drops once; if Weight > 0, also participates in weighted rolls
Min	integer	No	1	Minimum amount
Max	integer	No	1	Maximum amount
Name	string	No	–	Optional custom name
Rarity	integer	No	–	Optional rarity metadata

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.