Skip to main content


The shops module is an easy way to add shop functionality to a map with a GUI interface. Players interact with mobs, such as Villagers, which are shopkeepers where they can buy items using currencies. Shops have categories of items, and each category can store up to 28 unique items. Players can also buy a kit, instead of individual items, or use muiltiple currencies to purchase items.

Shop Element

<shops> </shops>A node containing the shops for this map.Shop Elements
<shop> </shop>An individual shop.Category Elements

Shop Sub-Elements

<shop> </shop>An individual shop.Shop Elements
<category> </category>RequiredA category that can hold up to 28 items.Items

Shop Attributes

idRequiredUnique identifier used to reference this shop from other places in the XML.String
nameThe display name for the shop.Formatted Text

Category Attributes

idRequiredUnique identifier used to reference this category from other places in the XML.String
nameThe display name for the category.Formatted Text
materialThe item to display as an icon for the category.Material Name

Item Attributes

Items have unique attributes when used in a shop, usually for currency purchases. Items can be purchased with multiple currencies using the <payment> tag.

currencyThe currency needed to purchase.Material Name
priceThe amount of a currency needed to purchase.Number
kitThe kit to give to players purchasing the item.Kit
colorSet the currency's display text color. This is used for associating colors with different currency tiers.Chat Color Name


<!-- Item where a kit is defined. -->
<!-- Icon will be a stick but kit can give anything -->
<item name="Magic Wand" material="stick" price="100" currency="blaze powder" kit="magic-kit">

<!-- Multiple Payment requirements-->
<item material="diamond sword" amount="1">
<enchantment level="2">sharpness</enchantment>
<payment price="10" currency="diamond"/>
<payment price="20" currency="stick"/>

<!-- Custom currency uses a child <item> under <payment> -->
<item material="diamond sword" amount="1">
<payment price="1">
<!-- Item name is shown under the cost lore instead of the raw material name -->
<item name="`bEnchanted Diamond" material="diamond">
<enchantment level="2">sharpness</enchantment>


Shopkeepers are invulnerable and immovable entities that hold a single shop type and are spawned at match load. Each shop type can have an unlimited number of shopkeepers. There are no limitations to how many players can have a shop open simultaneously.

Shopkeepers must use a single location provider, multiple inner points or regions are not allowed.

Shopkeeper Element

<shopkeepers> </shopkeepers>A node containing a set of shopkeepers for this map.Shopkeeper Elements
<shopkeeper> </shopkeeper>An individual shopkeeper.Shopkeeper Attributes

Shopkeeper Attributes

nameThe display name of this shopkeeper, shown above the entity if present.Formatted Text
mobThe mob type for this shopkeeper to appear as.Creature TypeVillager
shopRequiredA previously defined shop to use.Shop ID


<!-- There's no limit to how many shopkeepers can be in a -->
<!-- match, as long as each <shop> has at least 1 keeper. -->
<!-- A shop keeper for the "Items" shop (defaults to villager) -->
<shopkeeper name="`5Purple `7Item Shop" shop="purple-item-shop">
<point yaw="0" pitch="10">-88.5,13,-103.5</point>

<!-- You can define a mob attribute to set the entity type -->
<shopkeeper name="`4Red `dMagic Shop" mob="Witch" shop="magic-shop" />
<shop id="item-shop" name="`bItems">
<!-- You can have an multiple categories, each category will hold up to 28 items -->
<category id="weapons" name="`cWeapons" material="stone sword">
<!-- Free item -->
<item material="wooden sword" amount="1" price="0"/>

<!-- Currency & Price in same line -->
<item material="stone sword" amount="1" price="3" currency="emerald" />

<!-- Payment as sub-element but only using a single currency -->
<item name="Cool TNT" material="tnt" amount="5">
<payment price="5" currency="gunpowder"/>
<!-- Seperate "food" page in shop -->
<category id="food" name="`aFood" material="apple">
<item material="apple" name="Tasty Apple" amount="100" price="10" currency="gold ingot"/>
<item material="carrot" name="Crunchy Carrot" amount="50" price="4" currency="gold ingot"/>
<!-- You can define as many <shops> as needed -->