From Harvest Festival
Jump to navigation Jump to search

Shopaholic by itself does basically nothing. It simply gives you the tools to create the economy system yourself. This page will be a guide on how to use the mod to create shops, assign objects as shipping bins and adding sell values to items. When it comes to the shops they can be simple or they can be complicated. A basic shop can be done very easily but if you want to do something more complicated you will need to make use of the advanced system for shop editing instead.


Shipping has two elements to it. The sell value of an item and how you are able to ship items. By default the only method for shipping of items that can be done is by using the /shopaholic ship [hand/inventory] command.

Assigning Shipping Bins

In the context of the mod a shipping bin is an object that will sell some items for you. The money will then be added to your balance on the following day and can be tracked in the Economy Manager book. You can assign this functionality to a block, an item or an entity. To do this all you have to do is assign the object you want to the shopaholic:shipping_bin block/item/entity tag. With them assigned, right clicking a block with the assigned item or entity will ship the item the player is holding. When assigning an item. Everything except for that item in the players inventory will be added to the shipping.

Assigning Sell Values

Items or Item Tags can be assigned sell values. We do this using the Pengin-Lib database system. Simply create a csv file in data/NAMESPACE/database/item_values.csv. In order to use a tag. Simply prefix the item entry with tag:. Below is an example adding values to a few crops. And to the planks tag.


Custom Sell Values

Individual item stacks can have their own sell value that differs from their assigned value. You simply need to create an item with a the SellValue tag. It should be a long type.

Loot Table Functions

There are three functions added by Shopaholic to loot tables as well. So you can assign a custom sell value to items in the loot tables. They are the following.

Set Value

shopaholic:sell_value You can either set a 'value' field or you can use 'min' and 'max' to generate a value in a specific range. Hand for assigning a value to special items that normally have no value.

Ratio Value

shopaholic:ratio_value This will take the existing value in the shipping registry and multiply by the number you define in the 'ratio' field. This can be handy for making certain blocks drop an item that's worth less than normal.

Cap Value

shopaholic:cap_value This will take the existing value in the shipping registry and cap it off at this value meaning it cannot be worth more than the amount you define in the 'cap' field.




Shops can be created in one of three ways. Using the 'very simple' system. The 'simple' system or the 'advanced' system. They all require a basic setup though. One thing you will need to understand is how the shop system works. There are fiveelements to it. These are:

  • Vendors - The block/entity/item/command that is considered to have a shop, they can have multiple shops
  • Shop - These define the name and the action you need to open them, and have multiple departments
  • Department - These are the sections of each shop, they appear as tabs when you open the shop gui, each department can have multiple listings
  • Listings - These are the individual listings as they appear in the shop, they can have multiple sublistings but often will only have one, they control the stock level and cost formula
  • Sublistings - These are where the actual purchases are defined, the gold cost, material cost, and everything as such. When you assign more than one sublisting to a listing, each day a random sublisting will be chosen to be displayed in the shop.

Shops, Departments and Listings can also all be assigned #Condition Types. This will make them accessible or not depending on certain conditions.

Stock Mechanic

There is also the concept of stock level. And you can create different stock mechanics. By default Shopaholic includes three different types of stock levels. But you can define more in data/NAMESPACE/database/stock_mechanics.csv. Below are the default mechanics as an example.

ID,Max Stock,Replenish Rate

Cost Formula

These cannot currently be defined by you. But the mod includes four formulas by default.

Fields Explained

Formula Info
default This will just return the value that you define.
increasing_cost The price will go up as the stock level drops.

It is better to set a lower stock to see an effect.

decreasing_cost The price will go down as the stock level drops.

It is better to set a lower stock to see an effect.

shipping_value The item will cost the value defined as its shipping value

Basic Shop Setup

No matter if you're using the very simple, simple or advanced system. You will still have to setup either two or three initial files to get your shops functioning. These are vendors, shops and departments.


If you use the #Very Simple Shops system you can skip this step. Otherwise... We'll create a file in data/NAMESPACE/database/vendors.csv. This is where we define what types of things can open a shop. Below is a simple example. That makes the vanilla villager able to be interacted with to open a shop.


Vendor Types

Type Data Info
block Registry name of the block Interaction with the specified block will attempt to open a shop
command The COMMAND_NAME you wish to use Executing the command shopaholic shop open COMMAND_NAME will attempt to open a shop
entity Registry name of the entity Interaction with the specified entity will attempt to open a shop
item Registry name of the item Interaction with the specified item will attempt to open a shop


There are three methods you can use for creating the shops themselves. One is simpler than the other, but the other allows for more customisation.

Very Simple Shops

Create a a file under data/NAMESPACE/database/very_simple_shops.csv. Then you will define the shop details. The shop will by default open with a right click and use the default background textures. The ID that the shop uses will be generated from the name you define. It will remove all non alphanumerical characters, lowercase everything and replace spaces with underscores. I.e. "Farmer's Market' > "farmers_market" or "Caterpillar@497 Court 41!" > "caterpillar497_court_41". It will also use this as the vendor's id too.

Farmer's market,entity,villager

Simple Shops

Create a a file under data/NAMESPACE/database/simple_shops.csv. Then you will define the shop details. The shop will by default open with a right click and use the default background textures.

ID,Name,Vendor ID
farmers_market,Farmer's market,villager

Advanced Shops

Next we need to create data/NAMESPACE/database/shops.csv. This is where we define how the shop will be opened and the name of the shop as well as assigning the vendor to that shop. The following allows you to open a shop when you shift right click on a villager.

ID,Name,Background Texture,Extra Texture,Vendor ID,Opening Method
farmers_market,Farmer's market,default,default,villager,shift_right_click

Opening Methods

  • right_click
  • shift_right_click
  • script
  • command


And the final part of the basic setup is that we need to have at least one department in our shop. So we need to create data/NAMESPACE/database/departments.csv. Here we have to define an icon, which is only visible when you have multiple departments so you can just leave that field blank if you want. Same with the name for the department. Here I am defining two. Take note of the Icon. It's using the JSON syntax but we have double quotes as you need to escape the quotes in the CSV file. You do not HAVE to use the json format. You can simply put an item in the icon field if you so wish. The reason you can use the json is to allow for various different types of Icon. If you look at the Icon page you can see the different types supported. This is a format used throughout all Penguin-Lib mods. The below adds two departments (tabs) to the shop. Department IDs need to be completely unique from each other as they are used to identify the purchases

Shop ID,ID,Icon,Name

Further Information

With the three basic files setup. You have one of three options, although you can mix and match. You can either use the very simple, simple or advanced systems for adding listings to your shops. So take your pick...


Very Simple Listings

These can be used to add basic listings for each type of listing available. They will use the default formula and unlimited stock mechanic. They will use the item/entity etc as the ID. So you cannot have duplicate entries. You will simply need to create a csv file like data/NAMESPACE/database/very_simple_department_listings_TYPE.csv Making sure to replace TYPE with a the type of listing you want to use. For example if you wanted to add item listings you would create data/NAMESPACE/database/very_simple_department_listings_item.csv. #Listing Types. Below is an example of how these files should look. Some types like potion or item require a bit more work than just specifying their registry names so make sure to check listing types for information on that.

Department ID,Item,Gold

You can also put them all in one file if you wish instead, where it looks more like this data/NAMESPACE/database/very_simple_department_listings.csv

Department ID,Type,Data,Gold

Simple Listings

Simple listings are similar to the very simple format, you can use the _TYPE or the merged format here too data/NAMESPACE/database/simple_department_listings.csv. You can also define the stock mechanic using this format and must define your own ids.

Department ID,ID,Type,Data,Gold,Stock Mechanic

Advanced Listings

For the most part, you are likely to only want to make simple shops. But here is where things get pretty complicated. In order to add a listing. You are going to need a minimum of two files. One to define the listing, and then one to define the sublistings. There are also some other ones too that you can use. At this point I would recommend using different subfolders for each of your shops. So in my example I'd be putting these files in data/simple_shop/database/shops/farmers_market/ And I'd put the three basic files in the shops directory. Everything gets loaded properly, all files are merged in the end anyways.

Department Listings

This is the first file we would need to create. This is where we define the listing object itself along with the stock mechanc and cost formula we wish to use. The file should be named department_listings.csv and as long as it's somewhere in data/NAMESPACE/database it will get loaded. Here's an example of using the departments I created much further above. Take note, no gold values or such are defined here.

Department ID,ID,Stock Mechanic,Cost Formula


This is where we can assign sublistings to the listing itself. In a file called sublistings.csv. We can define MULTIPLE sublistings and each day there is a roll of the dice and a sublisting is chosen randomly. My example only has one item but you can add multiple for the same listing for this purpose. You can even assign the weight, so that some things are chosen more frequently than others.

Department ID,Listing ID,ID,Type,Data,Gold,Weight

Sublisting Materials

This is how we assign materials other than gold to an item. You do not have to use the advanced system to setup your items in order to make use of this. Just make sure to use the correct ids if you use the simpler systems. The file name here should be sublisting_materials.csv. Here you can see that I assign a cost of 2 sticks and 2 of a certain material for each hoe.

Department ID,Listing ID,Sub ID,Item,Amount

Sublisting Display Data

It is possible to assign a different name, icon or tooltip to your sublistings than the one specified. This way you can deceive people or just use a more appropriate icon than the default one given! This is especially important if you use a command listing as this will just show the icon as a command block. Simply create a file called sublisting_display_data.csv. Here's an example file. For tooltips simply use /n if you wish to insert a new line. Take note that the tooltip field here is blank. When you leave a section blank it will use the default value instead. Or you can put "default".

Department ID,Listing ID,Sub ID,Icon,Name,Tooltip
class_selector,communicator,default,{""item"":""minecraft:leather""},Animal Communicator,


You can assign conditions to shops, departments or listings. In order to do this you will first need to choose the type of condition you want to create. And then create a condition_TYPE.csv file. In here you will need to define different types of data. And this will vary depending on which type you choose. So check out #Condition Types for information on each type. Here's just a couple basic examples from a datapack I created.

One per player condition



Compare conditions


ID,Comparator 1 ID,Less Than,Equal To,Greater Than,Comparator 2 ID

Assign the conditions

Now that you have created the data for the conditions you can assign them to a shop, department or listing. Simply create either shop_conditions.csv | department_conditions.csv | listing_conditions.csv and then assign them like so. (Use Department ID or Listing ID where appropriate)

Shop ID,Condition ID

Type Tables

Listing Types

Type Info Fields
bundle Add multiple listings as one item. This will allow you to add packages. Say able to buy a lead, name tag and cow all under one listing Uses the data field as an ID, that is then linked up with bundles.csv


command Execute a command The command to execute
department Open a department The department id
entity Spawn an entity The entity type to spawn
gold Used to display gold as the icon for selling items, does nothing otherwise Leave this blank
heal Heal the player The amount to heal
item Give an item The item to give
kubejs Calls kubejs to apply whatever you like to the player The id to use to call in the event so it will call shopaholic.listing.ID
potion Add a potion effect Uses an ID that it then grabs more information from potion_listings.csv with the fields ID,Duration,Amplifier,Is Ambient,Show Particles
player_status Add a custom value to the player data, using a comparator to get that value Uses an ID as the data field then grabs from player_statuses.csv the following fields ID,Field,Comparator ID
team_status Add a custom value to the penguin team data, using a comparator to get that value Uses an ID as the data field then grabs from team_statuses.csv the following fields ID,Field,Comparator ID

Condition Types

Type Info File Data
and Combine multiple conditions. Will only return true if they're all true. condition_and.csv ID,Condition ID
block_state Check for a block state condition_block_state.csv ID,State Name,State Value
compare Compare two integer values condition_compare.csv ID,Comparator 1 ID,Less Than,Equal To,Greater Than,Comparator 2 ID See #Comparator Types
entity_nearby Check if an entity is in a nearby range condition_entity_nearby.csv ID,Entity,Range
entity_has_nbt_tag Check if the entity interacted with has nbt data condition_entity_has_nbt_tag.csv ID,Data
has_pet Check if the player has pet not too far away (must use a tameable entity) condition_has_pet.csv ID,Entity
in_dimension Check if the position is in a certain dimension condition_in_dimension.csv ID,Dimension
kubejs Calls kubejs to check if the condition is valid uses the event "shopaholic.condition.ID" where ID is the id specified in the csv file. condition_kubejs.csv ID
named Check if the vendor is named ??? (Uses regex) condition_named.csv ID,Name
not Combine multiple conditions. Will only return true if they're all false condition_not.csv ID,Condition ID
or Combine multiple conditions. Will return true if any of them do. condition_or.csv ID,Condition ID
opening_hours Specify the opening hours of the shop by weekday where 6000 = 6AM and 23000 = 11PM condition_opening_hours.csv ID,Mon Open,Mon Close,Tue Open,Tue Close,Wed Open,Wed Close,Thu Open,Thu Close,Fri Open,Fri Close,Sat Open,Sat Close,Sun Open,Sun Close
per_player Limit the amount each player can purchase. Can only be applied to listings. condition_per_player.csv ID,Max
player_has_nbt_tag Check if the player has nbt data condition_player_has_nbt_tag.csv ID,Data
player_named Check if the player is named ??? (Uses regex) condition_player_named.csv ID,Name
season Requires Simply Seasons Checks the current season condition_season.csv ID,Season
season_days Requires Simply Seasons Takes the season length and multiplies it by the days value passed in condition_season_days.csv ID,Days
season_predicate Requires Simply Seasons Checks the current season using the predicates from simply seasons condition_season_predicate.csv ID,Season Predicate
shipped Check if the player has shipped the item or item tag (use 'tag:'). Use the amount in the id. i.e. shipped_1000. You can use this id multiple times to merge in different items to the requirement. condition_shipped.csv ID,Item
time Check if the time is between certain hours condition_time.csv ID,Open,Close
tile_entity_has_nbt_tag Check if the tile entity has nbt data condition_tile_entity_has_nbt_tag.csv ID,Data

Comparator Types

Type Info Data
add Add the comparators. Add entries in comparator_add.csv ID,Comparator ID
block_tag_on_target Checks if the block has a block tag comparator_block_tag_on_target.csv ID,Tag
can_see_sky Returns 1 if the block can see the sky, 0 otherwise N/A
item_in_hand Returns the stack count of the held items (both hands). Can use item or tag (use 'tag:')comparator_item_in_hand.csv ID,Item
item_in_inventory Returns the stack counts of the items in the players inventory. Can use item or tag (use 'tag:') comparator_item_in_inventory.csv ID,Item
kubejs Calls kubejs to get the value uses the event "shopaholic.comparator.ID" where ID is the id specified in the csv file. comparator_kubejs.csv Use event.setValue(number) and event.getValue() ID
light_level Returns the light level of the location N/A
number A fixed number comparator_number.csv ID,Number
player_health Returns the players health level N/A
player_status Returns the player status specified comparator_player_status.csv ID,Status
player_x Returns the players x coordinate N/A
player_y Returns the players y coordinate N/A
player_z Returns the players z coordinate N/A
rain_level Returns 2 if thundering, 1 if raining, 0 if clear N/A
redstone_level Returns the redstone level of the location N/A
shipped Returns the stack counts of the items shipped by the player. Can use item or tag (use 'tag:') comparator_shipped.csv ID,Item
team_status Returns the penguin team status specified comparator_team_status.csv ID,Status
temperature Returns the temperature of the location N/A
vendor_health Returns the vendors health level or 0 if not applicable N/A
vendor_x Returns the vendors x coordinate N/A
vendor_y Returns the vendors y coordinate N/A
vendor_z Returns the vendors z coordinate N/A

Example Datapacks

The examples use the advanced system.

Simple Shops

Adds a shop to the farmer npc when you SHIFT+RIGHT click them. And also makes it so that you can sell wheat, beetroot, melons and pumpkins with the /shopaholic ship command or by right clicking soul campfire.

Class Selector

Use the /shopaholic open class_selector command, this will give you a shop with one of four options. "Animal Communicator", "Miner", "Lumberjack", "Fisherman". You will not be able to open the shop again once you have selected your option. The communicator should allow you to buy animal products from cows, pigs or chickens. The miner will let you sell ingots/gems/dusts to a store opened with /shop open sell . The lumberjack will be able to sell their wood on /shop open sell and the fisherman sell fish under /shop open sell.