Loot API
Register ordered reload-time edits and weighted replacements.
LootAPI delegates to the internal loot implementation. Patches are immutable recipes evaluated during table loading; ordinary loot rolls do not repeat selectors or recursive edits.
Entry point
Use net.kzeroko.isekaiexpansion.api.LootAPI. Builder result types are internal implementation contracts returned by this facade. Data-pack authors should use loot patch JSON.
Common tasks
Replace an entry while preserving its selection rules
LootAPI.register(LootAPI.patch(new Identifier("example", "dungeon_rewards"))
.priority(20)
.namespace("minecraft").pathPrefix("chests/")
.replaceItem(new Identifier("minecraft", "emerald"), new Identifier("minecraft", "diamond"))
.build());
Construct a weighted output function
var replacement = LootAPI.replace(Items.EMERALD)
.chance(0.5F).target(Items.DIAMOND, 1, 1)
.target(Items.IRON_INGOT, 3, 2, 4).build();
Attach that function through a normal loot builder. For a patch’s JSON function method, serialize with the normal loot-function serializer; functions execute only after an entry has won its pool roll.
Shared chest pickup
LootAPI.addChestPickups(id, builder) adds 3 independent pools to paths beginning chests/: equipment, gem-like materials and miscellaneous pickups. Each pool rolls once without a luck bonus and can add at most 1 item. A chest can receive all 3 categories together. Each pool totals 10025 weight, preserving each item’s existing probability; chance is its weight divided by 10025.
| Category | Outcome | Weight |
|---|---|---|
| Equipment | None | 9535 |
| Equipment | Common equipment | 300 |
| Equipment | Uncommon equipment | 140 |
| Equipment | Rare equipment | 50 |
| Gem-like | None | 8815 |
| Gem-like | Fusible Gem | 600 |
| Gem-like | Smithing Stone Shard | 450 |
| Gem-like | Smithing Stone | 125 |
| Gem-like | Smithing Stone Chunk | 35 |
| Misc | None | 10000 |
| Misc | Veilglass Seal | 25 |
PackLootPatches constructs the isekaiexpansion:chest_pickups/common, isekaiexpansion:chest_pickups/uncommon and isekaiexpansion:chest_pickups/rare tables from EquipmentAPI.entries() during resource loading. Each table chooses 1 matching catalogue item uniformly. Category chances stay fixed as the catalogue grows. Their exact-table replacement patches use priority 20 and IDs isekaiexpansion:loot/chest_pickups/common, isekaiexpansion:loot/chest_pickups/uncommon and isekaiexpansion:loot/chest_pickups/rare. These table paths do not receive another chest pickup.
Reference
| Method | Side | Contract |
|---|---|---|
LootAPI.patch(id) | Common setup | Creates a patch builder. |
LootAPI.register(patch) | Common setup | Registers a unique ID; duplicate registration throws. |
LootAPI.replace(item) | Common setup | Weighted replacement builder with chance, target count and optional NBT copy. |
LootAPI.stripNbt() | Common setup | NBT-rule builder; default clears all, with regex and item overrides available. |
priority, table, tables, namespace, pathPrefix, excludeNamespace, sources | Builder | Ordering and intersecting selection. |
replaceTable, clearPools, addPool, function | Builder | Whole-table operations and appended content; supplied JSON is copied. |
replaceItem, removeItems, itemFunction | Builder | Recursive item operations preserving unrelated entry data. |
pools, entries, edit | Builder | Advanced callbacks; return null from an entry callback to remove it. |
Threading and lifecycle
Register during mod initialisation before world loading. Callbacks execute in the server resource-loading path and must not mutate worlds or entities. Capture immutable callback state. Resource-manager snapshots are cached weakly; registering clears the cache for subsequent table loads, not already-built tables.
The Fabric modification phase follows the default phase and accepts replaced tables too. Another mod deliberately ordered after this phase can still modify the result. Data-pack patches override code patches by ID. Empty recipes select no tables, so disabled overrides do not serialize tables unnecessarily.