LootTweaker Mod — Guide

Mechanics

To effectively use LootTweaker, it is important to understand the hierarchy of the Minecraft loot system:

Loot Table: The top-level object (e.g., minecraft:entities/cow or minecraft:chests/simple_dungeon). It contains one or more Loot Pools.
Loot Pool: A group of potential loot entries. Each pool has a set number of 'rolls' (how many times it attempts to pick an entry).
Loot Entry: The actual item, loot table, or empty result that can be picked. Entries have weights and qualities.
Conditions: Requirements that must be met for a pool or entry to be valid (e.g., killed_by_player).
Functions: Modifications applied to the item after it is picked (e.g., setting stack size, damage, or enchantments).

Weight and Quality

Loot selection is based on Weight. The chance of an entry being picked is its weight divided by the total weight of all valid entries in the pool.

Quality modifies the weight based on the player's Luck attribute using the formula: Effective Weight = floor(weight + (quality * luck))

ZenScript API

The mod uses several classes to interact with loot data. You must import these at the top of your script.

import loottweaker.LootTweaker;
import loottweaker.LootTable;
import loottweaker.LootPool;
import loottweaker.Conditions;
import loottweaker.Functions;

LootTable Methods

LootTweaker.getTable(String tableName): Returns a reference to an existing loot table.
LootTweaker.newTable(String tableName): Creates a brand new loot table.
table.addPool(String name, int minRolls, int maxRolls, int minBonusRolls, int maxBonusRolls): Adds a new pool to the table.
table.getPool(String name): Retrieves an existing pool for modification.
table.removePool(String name): Removes a pool entirely.
table.clear: Removes all pools from the table.

LootPool Methods

pool.addItemEntry(IItemStack stack, int weight): Adds a simple item entry.
pool.addItemEntry(IItemStack stack, int weight, int quality, LootFunction[] functions, LootCondition[] conditions, String name): Adds a complex item entry.
pool.addLootTableEntry(String tableName, int weight): Adds an entry that triggers another loot table.
pool.addEmptyEntry(int weight): Adds a chance for 'nothing' to drop.
pool.removeEntry(String entryName): Removes a specific entry by name.
pool.setRolls(int min, int max): Sets the number of times the pool is rolled.
pool.setBonusRolls(int min, int max): Sets bonus rolls based on luck.

Conditions and Functions

Conditions and Functions allow for fine-tuned control over when loot drops and how it appears.

Common Conditions

Method	Description
`Conditions.killedByPlayer`	The entity must be killed by a player.
`Conditions.randomChance(float chance)`	A flat percentage chance (0.0 to 1.0).
`Conditions.randomChanceWithLooting(float chance, float multiplier)`	Chance that increases with the Looting enchantment.
`Conditions.parse(DataMap json)`	Allows using raw JSON for complex vanilla or modded conditions.

Common Functions

Method	Description
`Functions.setCount(int min, int max)`	Sets the stack size of the dropped item.
`Functions.setDamage(float min, float max)`	Sets the durability/damage (0.0 to 1.0).
`Functions.setNBT(DataMap nbt)`	Applies NBT data to the item.
`Functions.enchantRandomly(String[] enchants)`	Applies a random enchantment from the list.
`Functions.enchantWithLevels(int min, int max, boolean treasure)`	Enchants the item as if using an enchantment table.
`Functions.smelt`	Smelts the item (e.g., drops Cooked Beef instead of Raw Beef).
`Functions.lootingEnchantBonus(int min, int max, int limit)`	Adds extra items based on the Looting level.

Advanced: Custom ZenScript Functions

LootTweaker allows for entirely custom logic using the Functions.zenscript method. This allows you to modify the item stack based on complex variables like the random number generator or the loot context.

somePool.addItemEntry(<minecraft:potato>, 1, 0, [
 Functions.zenscript(function(input, rng, context) {
 return input.withDisplayName("Super Potato");
 })
], []);

Example Scripts

Modifying Mob Drops

This script removes Mutton from Sheep and adds a chance to drop an Apple instead.

val sheep = LootTweaker.getTable("minecraft:entities/sheep");
val main = sheep.getPool("main");

main.removeEntry("minecraft:mutton");
main.addItemEntry(<minecraft:apple>, 20, 0, [Functions.setCount(1, 3)], [Conditions.killedByPlayer]);

Adding Loot to Dungeon Chests

This script adds a 10% chance to find a Diamond in simple dungeon chests.

val dungeon = LootTweaker.getTable("minecraft:chests/simple_dungeon");
val extra = dungeon.addPool("rare_loot", 1, 1, 0, 0);

extra.addItemEntry(<minecraft:diamond>, 10);
extra.addEmptyEntry(90);