Kzeroko KTM2

Loot API

Register ordered reload-time edits and weighted replacements.

Updated Oct 23, 2026 3 min read

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.

CategoryOutcomeWeight
EquipmentNone9535
EquipmentCommon equipment300
EquipmentUncommon equipment140
EquipmentRare equipment50
Gem-likeNone8815
Gem-likeFusible Gem600
Gem-likeSmithing Stone Shard450
Gem-likeSmithing Stone125
Gem-likeSmithing Stone Chunk35
MiscNone10000
MiscVeilglass Seal25

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

MethodSideContract
LootAPI.patch(id)Common setupCreates a patch builder.
LootAPI.register(patch)Common setupRegisters a unique ID; duplicate registration throws.
LootAPI.replace(item)Common setupWeighted replacement builder with chance, target count and optional NBT copy.
LootAPI.stripNbt()Common setupNBT-rule builder; default clears all, with regex and item overrides available.
priority, table, tables, namespace, pathPrefix, excludeNamespace, sourcesBuilderOrdering and intersecting selection.
replaceTable, clearPools, addPool, functionBuilderWhole-table operations and appended content; supplied JSON is copied.
replaceItem, removeItems, itemFunctionBuilderRecursive item operations preserving unrelated entry data.
pools, entries, editBuilderAdvanced 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.