Common

KattonVillagerTradeModificationApi

top.katton.api.modcommon/src/main/kotlin/top/katton/api/mod/KattonVillagerTradeModificationApi.kt

Configuration for a single trade to be appended to an existing [TradeSet] via [addVillagerTrade].

Members

Jump directly to declarations on this page.

• VillagerTradeAdditionConfigClass
• VillagerTradeAdditionConfig.costItemIdProperty
• VillagerTradeAdditionConfig.costBItemIdProperty
• VillagerTradeAdditionConfig.resultItemIdProperty
• VillagerTradeAdditionConfig.maxUsesProperty
• VillagerTradeAdditionConfig.xpProperty
• VillagerTradeAdditionConfig.priceMultiplierProperty
• addVillagerTradeFunction
• addVillagerTradeFunction

VillagerTradeAdditionConfig

VillagerTradeAdditionConfigCommonClass

class VillagerTradeAdditionConfig internal constructor( val tradeSet: ResourceKey<TradeSet>, )

Configuration for a single trade to be appended to an existing [TradeSet] via [addVillagerTrade].

Fields map directly to the public VillagerTrade constructor on supported MC 26.x versions: primary and optional secondary costs, result, maximum uses, XP, and price multiplier. These values remain stable across the supported versions.

VillagerTradeAdditionConfig.costItemId

VillagerTradeAdditionConfig.costItemIdCommonProperty

var costItemId: Identifier?

Item the merchant wants from the player.

VillagerTradeAdditionConfig.costBItemId

VillagerTradeAdditionConfig.costBItemIdCommonProperty

var costBItemId: Identifier?

Optional secondary cost.

VillagerTradeAdditionConfig.resultItemId

VillagerTradeAdditionConfig.resultItemIdCommonProperty

var resultItemId: Identifier?

Item the merchant gives back.

VillagerTradeAdditionConfig.maxUses

VillagerTradeAdditionConfig.maxUsesCommonProperty

var maxUses: Int

Maximum number of times the trade can be used.

VillagerTradeAdditionConfig.xp

VillagerTradeAdditionConfig.xpCommonProperty

var xp: Int

Villager XP awarded per trade.

VillagerTradeAdditionConfig.priceMultiplier

VillagerTradeAdditionConfig.priceMultiplierCommonProperty

var priceMultiplier: Float

Vanilla price multiplier (0.05 default; matches farmer baselines).

addVillagerTrade

addVillagerTradeCommonFunction

@ApiStatus.Experimental
@ApiStatus.Experimental fun addVillagerTrade(tradeSetKey: String, configure: VillagerTradeAdditionConfig.() -> Unit): Boolean

Appends a new trade entry to an existing villager / wandering trader [TradeSet].

tradeSetKey is a registry id from minecraft:trade_set, e.g. "minecraft:farmer/level_1" or "minecraft:wandering_trader/buying".

The mutation is staged through [VillagerTradeManager] and flushed during the standard reload cycle (after script execution, on the server thread). Calling this outside /katton reload is safe — the change is not visible until the server applies pending datapack mutations.

Returns false and logs a warning when:

• the server is offline,
• the trade-set id cannot be parsed,
• the configuration is missing required fields (cost / result).

addVillagerTrade

addVillagerTradeCommonFunction

@ApiStatus.Experimental
@ApiStatus.Experimental fun addVillagerTrade(tradeSetId: Identifier, configure: VillagerTradeAdditionConfig.() -> Unit): Boolean

Identifier overload of [addVillagerTrade].