These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!
Merchant is a container for
TradeOffers. Its most common variant is the
Merchant interface can be used to open trading windows.
TradeOffers can be added to and removed from
Merchants using TradeOfferData.
A trade offer consists of
a primary/first buying ItemStackSnapshot
an optional secondary buying
already used uses
maximal available uses
a flag to indicate whether experience orbs are spawned on trade
TradeOffers can be created using a
Builder or a TradeOfferGenerator.
TradeOfferBuilders are mainly used if you want to dynamically create
TradeOffers on the fly.
The following code block builds a new
TradeOffer that allows
Players to trade five
DIRT into three
block items. This trade offer has four initial uses, after that the
Merchant might need some time to offer this
TradeOffer offer = TradeOffer.builder() .firstBuyingItem(ItemStack.of(ItemTypes.DIRT, 5)) .sellingItem(ItemStack.of(ItemTypes.GRASS, 3)) .uses(0) .maxUses(4) .canGrantExperience(false) .build();
A TradeOfferListMutator is an interface that is invoked during
Villager level ups.
It can be used to replace existing
TradeOffers (e.g. higher tier) and add new
Its simplest and only API provided variant is the
TradeOfferListMutators for each level and
Career can be configured in the VillagerRegistry.
TradeOffer list in
Villagers might be generated lazily when the trading inventory is opened for the
TradeOfferGenerators are simple templates for new
TradeOffers. They are a variant of the
TradeOfferListMutator that will only add new entries and does not alter or remove any existing
TradeOfferGenerator tradeOfferGenerator = TradeOfferGenerator.builder() .setPrimaryItemGenerator(random -> ItemStack.of(ItemTypes.DIRT, random.nextInt(3) + 5)) .setSellingGenerator(random -> ItemStack.of(ItemTypes.GRASS, 5)) .startingUses(VariableAmount.baseWithVariance(2, 1)) .maxUses(VariableAmount.fixed(5)) .experienceChance(0.5) .build();
TradeOfferGenerator will randomly generate
TradeOffers that will
has 2-4 remaining initial uses
5 max uses
The chance that the generated
TradeOffer will grant experience is 50%.
You can use
ItemStackGenerators to dynamically apply enchantments or other custom data to the buying and
VillagerRegistry can be obtained from the GameRegistry. It will be used to configure the
TradeOfferListMutator that will be applied on a
VillagerRegistry villagerRegistry = this.game.getRegistry().getVillagerRegistry(); List<TradeOfferListMutator> generators = new ArrayList<>(villagerRegistry.getMutatorsForCareer(Careers.FARMER, 1)); generators.addAll(additionalFarmerLevel1TradeOffers()); villagerRegistry.setMutators(Careers.FARMER, 1, generators);
The lowest specifiable level-up mutator is level 1. This is equivalent to a newly spawned
Changes to the
VillagerRegistry will be lost on server restart and won’t have any impact on the
Villagers that have levelled up in the past.