General How-To's:

Learn how to update EconomyShopGUI without losing any modifications.

Updating/Installing plugins

When there is a new version available to download, it is important to read the changelogs of the update (Typically found on the plugin's page) for major updates that require a configuration change or config files to be updated.

• Make backups of your files before updating! While we do not expect files to be lost/overwritten, it can happen)

Once you have read the changelogs its time to update the plugin jar, its easy. You just need to replace the old plugin jar that is located in your server plugins folder with the new one.

• It is best practice to Delete the old plugin jar file, and Upload a fresh copy manually to minimize any potential corruption issues.

Most of the time a plugin jar will be named after the plugin and following with the version name. Example: EconomyShopGUI 3.0.8

How to find your plugin's files:

Please read About YAML before editing your files! It DOES NOT tolerate any errors! Validate it!

• First you need to find your plugins folder inside your server's file system. (Please consult your serverhost's support/documentation on how to access your files!)

• Once inside the plugins folder; Open the EconomyShopGUI (*EconomyShopGUI-Premium if you have Premium) folder.

• Here you will find theconfig.yml, Example items.txt,shops.yml and sections.yml files. (the file extension (.yml/.txt ) may be hidden)

• Open the file from your serverhost's file manager, or use a program such as notepad++ or any other text editor on your local machine. (these are the simplest methods, but you can also use FTP/file sync programs as well which require some more steps, see the application and serverhost documentation for more.)

• Now you can start editing your config/shops/sections! See Config.yml, Sections.yml, Shops.yml, and language pages for more details.

• Please Note that YAML does not tolerate any missconfiguration/errors. Validate your file(s) here before contacting support.

How do I upgrade to premium?

• Purchase the Premium version on SpigotMC, Songoda or Polymart

• Remove the free version (Jar file only!) from your server and install/upload the premium version.

• Then use the Import command to copy your old files from the free version of the plugin. That easy!

  • Optionally remove the free version's files after importing them to the premium version.

Updating shops and sections config without losing any modification (Backup files)

To update these configs you need to first locate the plugin folder.

To make sure you don't lose any date/modifications you made in the shops and sections config you can: Make a backup of the files to another location and remove the current ones. Or rename the config files from shops.yml to shops-old.yml and sections.yml to sections-old.yml. (anything not the original filename.)

If the plugin can't find the shops, sections, languages or config yml files, it will create new files with the defaults (options, values, prices, displaynames, etc...) when the plugin is next loaded with /sreload or server restart/reload.

Now you have the 2 shops and 2 sections configs (New and Old). If you did it right, the current configs that are used by the plugin are named shops.yml and sections.yml and are located inside the plugin folder of EconomyShopGUI.

Now the most important step, you need to copy all data/modifications you made in the old config files to the new ones but make sure to keep any core updated modifications in the new config (like option names, functions, ...), otherwise it might cause the plugin to not function correct.

• As ESGUI is updated, the format of some keys and other settings change and the config-version: # in the config.yml is updated to facilitate automatic updates of file formatting and settings.

• If you find something is not working, please verify the format of the keys/settings in your files is up-to-date with this wiki and recent changelogs!

If you did it right, restart/reload the server or reload the plugin and the shop ingame will have the new configuration files with all of your modification from previous versions.

If you are getting errors in console (Like this one) or the plugin is disabled. You most likely have a error inside the new configuration files. Check Troubleshooting for more common issues.

Updating shops and sections config

If you don't want to keep any modifications you made, updating is that simple as removing the old shops.yml and sections.yml config and then restart/reload the server or reload the plugin.

How to update/install a plugin:

1. When Updating plugins read the change-logs for your plugin(s), these will be posted to the Updates tab of the plugin page. You may need to make additional changes other than just replacing the .jar file.

2. Download the .jar from spigot/bukkit/polymart/etc plugin page. -NOT your serverhost's 'install plugin button' thing/page, these are notoriously buggy/unreliable and outdated!

3. Upload to your server-host's plugins/ folder (AND delete any previous versions of that plugin you may have, DON'T leave duplicates!)

4. Restart the server, (at this point it should be working!)

5. Optionally/As-Needed: check the config folder for your plugins (inside the plugins/<plugin_name>/ folder) and configure the plugin how you want, should you want to change any of the default settings the plugin has created. (READ the Documentation/WIKI/Comments!) (Changing plugin settings will require either that plugin's internal reload command, or a server restart)

How to override a command using commands.yml:

The commands.yml is a configuration located inside your main server folder(aka the folder where your server .jar is located) and can be used to override commands from a specific plugin.

• Open the commands.yml config located in your main server folder

• Add the shop command and override it to always use EconomyShopGUI, this should look something like EconomyShopGUI:shop $1-

  • EconomyShopGUI:shop means it will use the /shop command of EconomyShopGUI.

    • Note that if you're using the Premium version, it should be EconomyShopGUI-Premium:shop instead

  • $1- means any following command arguments will be used, this is important!

• Save the file, followed by a server restart to load the changes made.

The final commands.yml should look something like this where the shop and sell command is overriden to always use the EconomyShopGUI command:

command-block-overrides: []
ignore-vanilla-permissions: false
aliases:
  icanhasbukkit:
  - version $1-
  shop:
  - EconomyShopGUI:shop $1-
  sell:
  - EconomyShopGUI-Premium:sellall $1- # If using the Premium version,
                                       # the syntax is 'EconomyShopGUI-Premium:<command>'

How to alter player balances (as admin):

• Please check the commands for your vault-compatible ECONOMY plugin (such as essentials)

• Vault is an API (Middle-man, and does not have any commands.)

• ESGUI Does Not store or handle player balances. Your Economy plugin stores it, and Vault connects everything together.

• If using Essentials(X), the command is /eco to alter player balances. Please review the Essentials WIKI for much more info about it!!

How to make a hidden shop: (Workaround)

You can make a 'hidden shop' with this work-around until we add an official setting/code to hide shops in the future:

• setup shop.yml items

• setup section.yml shop/section as a glass pane with an ambiguous displayname ([like ""(same as the fill-item), and use/enable the fill-item in the sections.yml so no-one will ever suspect)

• setup permissions so everyone can access normal/other shops (define EVERY node in permissions system. and DO NOT USE the EconomyShopGUI.shop.all node)

• If needed: Lastly, if needed: have an NPC run the /shop <section> <player> as console -or- assign permission for the hidden shop to your VIP group so they can access it via command (or click the 'fake' fill item in the GUI).

How to store/share money as an item:

(alternative to keeping it in your vault/Economy plugin or a /pay command)

Configure an item to have enchants or tags that cannot be replicated in survival and set it to have the same buy and sell price. (It would be better to use hidden NBT tags, but that requires premium) ex:

  1000:
    material: PAPER
    name: "&a$5000 Voucher"
    buy: 5000
    sell: 5000
    lore:
    - "&a$5000 Voucher"
    - "Buy/Sell in the servershop to redeem"
    NBTData: {ESGUI:{Voucher:5000}} #Premium feature/value only

Note: This is the same thing as withdrawing money from the bank in real life. If you loose it, it's gone forever. The currency withdrawn/deposited is the can be used anywhere when in the 'bank/vault-eco-plugin' (not just ESGUI)

How to create custom item economy's: *Premium feature

Item economys are already a unique feature of the plugin, but it becomes even more powerfull when you can create your own currency's using custom ingame items.

How to:

EconomyShopGUI wouldn't comply its plugin tag if there wasn't an easy command to format the item for you.

To set the economy to an custom item from your inventory on

• sections

  • Command: /editshop editsection <section> set economy handItem

• shop items

  • Command: /editshop edititem <section> <item> set economy handItem

which will automatically try to format the item from your hand as an valid item economy and apply it to the specific section/item. No need to go thru the hassle of formatting it yourself!

Additionally you can copy the formatted value from your config to the default economy provider.

Format:

Examples:

• Custom item economy using a player skull

  • Format: economy: ITEM:material:PLAYER_HEAD name:&6&lCustom coin skullowner:Notch id:Creator

• Custom item currency using custom name, lore and custom model data

  • Format: economy: ITEM:material:ARROW name:&6&lSniper ammo lore:&cThis ammo can be used for the following guns:\n&aBarret\n&aP90 CustomModelData:1003 id:Bullets

• Custom item currency using enchantments and NBTData

  • Format: ITEM:material:Diamond name:&9Real money enchantments:SHARPNESS:5,EFFICIENCY:3,MENDING,UNBREAKING:2 NBTData:{Damage:5}

Cutom currency displaynames:

Using the ID of the currency you can set the displayname, this is the name which is used to display the currency to the user on shop items.

The first step would be to give the currency a ID using the 'id' flag, see the above examples for how it should be done.

After that you will have to use the ID to set a custom display format inside the config.yml, see an example of how it would look like using a custom item economy here.

Allowed item options:

• id

  • Desciption: The ID of the item economy, this is used for easily setting the currency's singular and plural form

  • Example: id:Bullets

• material - The type of the item

  • Description: The type of the item.

  • Example: material:ARROW

• name - The name of the item. Supports chat and hex colors.

  • Description: The name of the item. Supports chat and hex colors.

  • Example: name:&9&lCustom coin

• lore

  • Description: The lore of the item. Supports chat and hex colors. Multiple lines are split using '\n'.

  • Example: lore:This is a custom message\n&cYou can use &4&lcustom &ccolors aswell!

• skullowner

  • Description: The skull owner of the item

  • Example: skullowner:Notch

• skull-texture

  • Description: The skull texture of the item, valid values can be grabbed from this site.

  • Example: skull-texture:eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA 6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvM2ZkYWI0MDQzNGVkNWQwMWY1OGM0NWNhMGM5ZmFkYTQ2NjJlMTc3MmZmNDNlMjk3NDk3OTQ0MGE1Y2ZlMTVjOSJ9fX0=

• enchantments

  • Description: The enchantments of the item. Multiple values are split using ,

  • Example: enchantments:SHARPNESS:5,EFFICIENCY:5,MENDING,ecoenchants:BLAST_MINING:3,advancedenchants:STRIKE:2,excelentenchants:BLAST_MINING:3

• potiontypes

  • Description: The potion effects of the item. Multiple values are split using ,

  • Example: potiontypes:FIRE_RESISTANCE,STRONG_HARMING,LONG_INVISIBILITY

• stew-effect

  • Description: The stew effect for this SUSPICIOUS_STEW. Multiple values are split using ,

  • Example: stew-effect:WITHER,POISON

• instrument

  • Description: The goat horn sound when played

  • Example: instrument:ADMIRE

• CustomModelData

  • Description: The CustomModelData for the item

  • Example: CustomModelData:1003

• NBTData

  • Description: Sets the raw data of the item

  • Example: NBTData:{Damage:50,HideFlags:127}

How to make an NPC shop:

Note that we use Citzens in this tutorial, any other NPC plugin will work if it supports clickable commands.

1. Create the NPC with /npc create Test see their wiki here for more info on how to use the commands.

2. Assign the shop command to the NPC with /npc command add shop <section> <p> to open the shop section for the player that clicks it.

You can also assign the command /npc command add shop <p> to the npc to open the main shop for the player instead of opening a section.

Note that this command will be executed as the console meaning that the player doesn't need permissions to open the specified shop section. Use -p to run the command as the player. See their wiki here for more info about the clickable commands.

3. Optional: Disable the back button inside the config.yml so the player cannot go back to the main shop and open another shop section. (This allows your server to have NPC only shops)

4. Optional: To prevent players from accessing the shops via commands/gui you need to do the following with your permissions system/plugin: Set the following for all players/groups you don't want to have access to the /shop command (usually the default group):

4a. DISABLE/FALSE/NEGATE access to EconomyShopGUI.shop (/shop command itself)

4b. ALLOW/TRUE access to EconomyShopGUI.shop.all (or specific shop section(s), allows access to specific shop sections)

If setting up a specific/single shop as NPC only: Do NOT use the EconomyShopGUI.shop.all node. Setup permissions for the default group for every shop-section you want everyone to have access to (ie: EconomyShopGUI.shop.redstone , etc..). And do NOT define/allow access to the shop(s) section you only want accessible via NPC. Players will access this shop via the NPC who will run a command as console: /shop <section> <NPC-plugin-variable-for-the-player>

How to setup the DiscordSRV hook:

The DiscordSRV hook allows the plugin to log shop transactions made either thru the GUI or sell commands to a specific discord channel. See below on how to set this up for your server.

1. Start by setting up DiscordSRV itself and make sure it works. You can find a how to guide on their website.

2. When DiscordSRV works, you firstly need to configure the channel you want to send logs to inside the DiscordSRV config.yml itself. See their documentation here on how to setup a channel.

3. After creating and enabling the channel in DiscordSRV, reload the plugin using /discordsrv reload, then you will have to enable the discord hook inside the config.yml from EconomyShopGUI. enable-discordsrv-hook: true

4. Add the channel name(Not ID) to the channel option under the DiscordSRV hook settings.

5. Configure the chat message which will be send to discord to your likings. For default it uses a embed styled message but you can use the raw: "" option to make it send a raw message instead.

6. Finally you need to reload EconomyShopGUI using /sreload and when done correctly you will see the configured message inside your discord channel when purshing/selling items!

Migration of data to V2:

This section will explain how to migrate your current shop layout to EconomyShopGUI v6/EconomyShopGUI Premium v5 using the migration command.

It is recommended to create a backup of your current shop data before migration, just in case. This includes the shops.yml, sections.yml, config.yml and the database if you are using the premium version.

Start by updating the plugin like normal

• Download the latest version of EconomyShopGUI from your favorite plugin site.

• Stop the server

• Remove the old version of EconomyShopGUI(Premium)

  • Jar file only! Do not delete the plugin folder obiviously!

• Restart the server

At this point the plugin will create the default shop layout, so the next steps are only required if you want to keep your current shop layout.

Using the migration command

• Use command /eshop migrate economyshopgui V1toV2 --override to start migration to new file structure

  • The --override flag will override the default shops layout

• Now simply reload the shops layout using command /sreload.

Congratulations, you successfully migrated to the new shop structure. That wasn't hard, was it?

If you're using the premium version of the plugin, you might also follow the next step to migrate your database. Only required if you want to keep limited stock and sell limit data for shop items.

Migrating the database *Premium only

• Before migrating your database, just make sure there is a backup, we will not be responsible for any dataloss if you haven't made backups!

• Make sure all your shops and sections have already been migrated to the new file structure and they are loaded in EconomyShopGUI using /sreload, because migrating the database will only migrate items which exists in your current shop layout!

• Use command /eshop migrate economyshopgui V1toV2 --database to start migration to the new database structure

  • --database flag will try to migrate the data for limited stock and sell limits for items

  • Everything except DynamicPricing data will not be kept

At this point, your done if the migration command didn't report a error, simply restart your server once more to successfully reload all changes!

How to use ItemsAdder to use an image as shop background: *Premium only, requires ItemsAdder

Using ItemsAdder you can set up a custom image from your Resource Pack to show as a background for your shop.

As a precondition for this you'll have to have ItemsAdder set up and running and have the following prepared:

• The images you want to use, located in the resource pack of your /ItemsAdders/contents/ folder. For this example, the images will be called filename_1 and filename_2

• Additional Information on how to set up ItemsAdder can be found on their Wiki: https://itemsadder.devs.beer/first-install and https://itemsadder.devs.beer/plugin-usage/adding-content/guis

1. To use the image for the main shop UI:

   1. Open your used language file and replace the inventory-main.shop-title: with '::offset_0::filename_1::offset_0::filename_2:' with offset being the horizontal offset of the image.

   2. Use /sreload to view the placement of the images in the shop

   3. Experiment with different offset values to make the images fit to your liking.

2. To use the image for a section:

   1. Do the same as 1) but instead of setting the main shop title in the language file, replace the shops title in it's section file

Using the PlaceholderAPI expansion:

Currently all placeholders are a premium only feature

The placeholder expansion is hard coded into the plugin itself, so it isn't requried to install any expansion from the ECloud.

Transaction placeholders:

Note that the transaction placeholders require the option advanced-transaction-log: inside the config.yml to be enabled.

Player placeholders

Top player purchasing items:

• %esgui_player_most_bought_items_current_month%

  • Player name which bought the most amount of items the current month

• %esgui_player_most_bought_items_current_week%

  • Player name which bought the most amount of items the current week

• %esgui_player_most_bought_items_current_day%

  • Player name which bought the most amount of items today

Top player selling items:

• %esgui_player_most_sold_items_current_month%

  • Player name which sold the most amount of items the current month

• %esgui_player_most_sold_items_current_week%

  • Player name which sold the most amount of items the current week

• %esgui_player_most_sold_items_current_day%

  • Player name which sold the most amount of items today

Item placeholders

Top purchased item:

• %esgui_most_bought_item_current_month%

  • Item displayname which was purchased the most the current month

• %esgui_most_bought_item_current_week%

  • Item displayname which was purchased the most the current week

• %esgui_most_bought_item_current_day%

  • Item displayname which was purchased the most today

Top sold item:

• %esgui_most_sold_item_current_month%

  • Item displayname which was sold the most the current month

• %esgui_most_sold_item_current_week%

  • Item displayname which was sold the most the current week

• %esgui_most_sold_item_current_day%

  • Item displayname which was sold the most today

Creating SubSections in a shop:

SubSections are sections that can only be opened by clicking on a specific item in an existing section the same way as you click on an item in the main menu.

Other than that SubSections are essentially the same as any other section and are edited and used the same way, either by editing the section and shop file directly or using the editshop and editsection commands.

To make subsections within another section you need the following:

• A primary section, similar to the main menu, where the clickable items will be in. For this example we will call this Blocks

• Any number of secondary sections, which will contain the items you want to sell. For this example we will call these Wood, Stone and Glass

• An item in the Blocks section for each subsection you want to have. For this example we'll use the materials Oak Plank, Cobblestone and Glass

Make sure to reload the plugin after every step using /sreload

1. Create the sub sections Wood, Stone and Glass

   • Use the /editshop addsection command

2. Enable the sub-section property for them

   • Use/editshop editsection <sectionName> add sub-section true

3. Create the primary section Blocks

   • Use the /editshop addsection command

4. Add three shop items to the Blocks section, one being a plank, one being cobblestone and one being glass

   • Use the /editshop additem and /editshop edititem commands

5. Add the section property to the items and use the respective section names (Wood, Stone and Glass)

   • Use the /editshop edititem Blocks <itemIndex> section <subSection> command

Finally open the Blocks section and verify that the subsection items are working, then you can fill them with content.

The section config of Blocks should look similar to this:

enable: true
slot: 19
title: ''
hidden: false
sub-section: true
display-item: false
fill-item:
  material: AIR
nav-bar:
  mode: INHERIT
item:
  material: GRASS_BLOCK
  displayname: '&2&lBlocks'
  name: '&2&lBlocks'

The shops config of Blocks should look somewhat like this

pages:
  page1:
    items:
      1:
        material: OAK_PLANKS
        displayname: Wood
        buy: -1.0
        sell: -1.0
        section: Wood

      2:
        material: COBBLESTONE
        displayname: Stone
        buy: -1.0
        sell: -1.0
        section: Stone

      3:
        material: GLASS
        displayname: Glass
        buy: -1.0
        sell: -1.0
        section: Glass

How to use ShopStands:

Shop stands is a seperate module within EconomyShopGUI adding a new variant of physical shops. Unlike NPC shops, these shops open a custom buy/sell menu for the item itself instead of a whole section.

This feature comes within its own module, meaning that when disabled, it won't affect performance at all.

Creating a new shop stand

• By default this module is disabled, if not already enabled, enable it inside the config.yml

  • After enabling it, reload the plugin using /sreload

• Give yourself a new shop stand to place down

  • /eshop shopstands give <type> <section> <itemIndex>

• Simply place the item on the location you want to create the shop stand

  • Done, your ShopStand is now ready to use

Using a shop stand:

• To open the buy menu: Left click the shop stand

• To open the sell menu: Right click the shop stand

• To open the admin GUI of a shop stand: Shift click the shop stand