# API & Integration

KyuubiSoft Lootbags has **no public Java API and fires no events**. Other plugins and systems work with it through the bag items, which are normal Hytale items, and through a few hooks into KyuubiSoft Core and DynamicTooltipsLib.

:::caution[CoreAPI lootbag methods are not this mod]
`CoreAPI.getLootbagDefinition()`, `lootbagExists()`, `getAllLootbags()` and `grantLootbag()` in KyuubiSoft Core belong to Core's own lootbag templates (`com.kyuubisoft.core.lootbag`). They do not see the bags of this mod and do not hand out its items. See [Achievement Lootbag Templates](https://wiki.kyuubisoft.com/hytale/achievement-system/lootbags).
:::

---

## Handing out bags

Every bag is an item with its bag ID as item ID. Anything that can give items can give bags:

| Way | Example |
|-----|---------|
| `/lbadmin give` | `/lbadmin give Golden_Lootbag_Legendary 3` (to yourself) |
| Admin panel, Give | Any online player, also a whole set of one style |
| Hytale's `/give` command, also when other plugins run it as a command reward | The bag ID as item, e.g. `Golden_Lootbag_Legendary` |
| Item rewards of other mods (quests, achievements, shops, Season Pass) | Reward type *item* with the bag ID |

Custom bags work the same way once they have an item (see [Custom Lootbags](./custom-lootbags#the-item-of-a-new-bag)).

:::note
The Season Pass reward type "lootbag" rolls one of KyuubiSoft Core's lootbag templates and gives its contents directly. To hand out a bag of this mod from the Season Pass, use an *item* reward with the bag ID.
:::

---

## KyuubiSoft Core

| Hook | What it does |
|------|--------------|
| Admin menu entry | "Lootbag Admin" (`lootbag`) in Core's admin menu (`/ksadmin`). Opens the [admin panel](./admin-panel) for players with `ks.lootbag.admin` |
| NPC page opener `showcase_lootbag` | A Core citizen with the ID `showcase_lootbag` opens the [catalog](./ui-pages#catalog) for every player who talks to it. Useful for a lootbag showroom or a spawn NPC |
| Language settings | The mod registers itself as "Lootbag" in Core's language settings |
| Helpers | Inventory access, placed-block lookups and player lookups come from Core, which is why Core is required |

---

## DynamicTooltipsLib

When DynamicTooltipsLib is installed, the mod registers the tooltip provider `kyuubisoft:lootbag` at default priority. It adds the tier (in its color), the bag's `description`, the contents ("4 guaranteed + 3 random"), "Right-click to open" and "/kslootbags shows what is inside" to every bag item, in the client's language. See [UI Pages](./ui-pages#tooltips).

---

## Shared language choice (KsLang)

Like every KyuubiSoft mod, Lootbags ships its own copy of KsLang. The language a player picks with `/kslang` or `/lbadmin lang` is stored in `mods/kslang/prefs.json` and used by all KyuubiSoft mods. Each mod also adds its name to `mods/kslang/mods.json`. The first KyuubiSoft mod that loads registers the `/kslang` command.

---

## Data files for tools

Tools that read the data while the server is stopped can use:

| File | Content |
|------|---------|
| `mods/kyuubisoft_lootbag/data/players/<uuid>.json` | Per player: totals per tier, `perLootbagOpened`, the last 50 `openings` with their items |
| `mods/kyuubisoft_lootbag/data/latest_drops.json` | The last 30 openings on the server: `player`, `bagId`, `itemId`, `amount`, `time` (milliseconds) |
| `mods/kyuubisoft_lootbag/configs/drop_tables.json` | Drop rules |
| `mods/kyuubisoft_lootbag/configs/lootbags.json`, `custom/custom_lootbags.json` | Bag definitions |

The format is described on [Configuration](./configuration). While the server runs, the plugin rewrites these files from memory.

---

## Java classes

The plugin's classes (`com.hytale.lootbag.LootbagPlugin.getInstance()`, `getRegistry()`, `getService()`) are public, but they are internal and change between versions without notice. If you build on them, expect to adapt your code with every Lootbags update.