> For the complete documentation index, see [llms.txt](https://wiki.gpplugins.com/economyshopgui/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.gpplugins.com/economyshopgui/basics/how-to.md).
# 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**](https://www.spigotmc.org/resources/economyshopgui.69927/updates) of the update (Typically found on the [plugin's page](https://www.spigotmc.org/resources/economyshopgui.69927)) 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.
{% hint style="info" %}
Most of the time a plugin jar will be named after the plugin and following with the version name. Example: `EconomyShopGUI 3.0.8`
{% endhint %}
## How to find your plugin's files:
{% hint style="warning" %}
[Please read About YAML](/economyshopgui/file-configuration/about-yaml-yml-files.md) before editing your files! It DOES NOT tolerate any errors! [Validate it!](https://jsonformatter.org/yaml-validator)
{% endhint %}
* 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 the[`config.yml`](/economyshopgui/file-configuration/config.yml.md), `Example items.txt`,[`shops.yml`](/economyshopgui/file-configuration/shops.yml.md) and [`sections.yml`](/economyshopgui/file-configuration/sections.yml.md) 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++](https://notepad-plus-plus.org/downloads/) 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](/economyshopgui/file-configuration/config.yml.md), [Sections.yml](/economyshopgui/file-configuration/sections.yml.md), [Shops.yml](/economyshopgui/file-configuration/shops.yml.md), and [language](/economyshopgui/file-configuration/languages.md) pages for more details.
* Please Note that YAML does not tolerate any missconfiguration/errors. [Validate your file(s)](https://jsonformatter.org/yaml-validator) here before contacting support.
## How do I upgrade to premium?
* Purchase the Premium version on [SpigotMC](https://www.spigotmc.org/resources/economyshopgui-premium.104414/), [Songoda](https://songoda.com/marketplace/product/economyshopgui-premium-esgui-prem.595) or [Polymart](https://polymart.org/resource/economyshopgui-premium.908)
* Remove the free version (Jar file only!) from your server and install/upload the premium version.
* Then use the [Import command](/economyshopgui/basics/commands.md#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](/economyshopgui/basics/how-to.md#plugin-files).
To make sure you don't lose any date/modifications you made in the shops and sections config you can: M**ake 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](/economyshopgui/file-configuration/config.yml.md#config-version) 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](https://pastebin.com/DNF5frGr)) or the plugin is disabled. [You most likely have a error inside the new configuration files.](/economyshopgui/file-configuration/about-yaml-yml-files.md) Check [Troubleshooting](/economyshopgui/basics/troubleshooting.md) 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](/economyshopgui/file-configuration/shops.yml.md) and [sections.yml](/economyshopgui/file-configuration/sections.yml.md) config and then [restart/reload the server or reload the plugin](/economyshopgui/basics/troubleshooting.md#ts-05-restart-command).
## **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](https://www.spigotmc.org/resources/economyshopgui.69927/)/[bukkit](https://dev.bukkit.org/projects/economyshopgui)/[polymart](https://polymart.org/resource/456)/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//` 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:**
```yaml
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:'
```
## **How to alter player balances (as admin):**
* Please check the **commands for your vault-compatible ECONOMY plugin** (such as [essentials](https://essinfo.xeya.me/commands.html))
* [Vault](https://dev.bukkit.org/projects/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)](https://essinfo.xeya.me/commands.html), the command is [`/eco`](https://essinfo.xeya.me/commands.html) to alter player balances. [Please review the Essentials WIKI for much more info about it!!](https://essentialsx.netlify.app/wiki/Home.html)
## 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](/economyshopgui/file-configuration/sections.yml.md#mainshop-fill-item)), ***and*** use/enable the [fill-item](/economyshopgui/file-configuration/sections.yml.md#mainshop-fill-item) in the [sections.yml](/economyshopgui/file-configuration/sections.yml.md) 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 ` 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](/economyshopgui/file-configuration/shops.yml.md#nbt-data), but that requires premium) ex:
```yaml
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 (mc 1.20.4 and below)
components: '{"minecraft:custom_data":{ESGUI:{Voucher:5000}}}' # Premium feature/value only (mc 1.20.5 and above)
```
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 set economy handItem`
* **shop items**
* Command: `/editshop edititem 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**](/economyshopgui/file-configuration/config.yml.md#currency-formats).
#### 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* ](https://minecraft-heads.com/custom-heads/)*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}`
* **components:**
* **Description:** *Like the NBTData option, this specifies the item's raw component data for 1.20.5+*
* See this site on how to update NBTData to components:
* **Example:** `components:{"minecraft:consumable":{},"minecraft:food":{nutrition:5,saturation:7.0f}}`
* **ignored-tags:**
* **Description:** *Ignores NBT/component data on the item*
* **Example:** `ignored-tags:enchantments,trim,food`
## How to make an NPC shop:
{% hint style="success" %}
Note that we use [Citzens ](https://ci.citizensnpcs.co/job/Citizens2/)in this tutorial, any other NPC plugin will work if it supports clickable commands.
{% endhint %}
**1. Create the NPC with `/npc create Test` see their wiki** [**here** ](https://wiki.citizensnpcs.co/Commands)**for more info on how to use the commands.**
**2. Assign the shop command to the NPC with `/npc command add shop
` to open the shop section for the player that clicks it.**
{% hint style="info" %}
**You can also assign the command `/npc command add shop
` to the npc to open the main shop for the player instead of opening a section.**
{% endhint %}
{% hint style="info" %}
**If you want to restrict access to certain sections, you can add a permission check to the NPCs with the command**\
**`/npc cmd -l -r --permissions economyshopgui.shop. add shop
`**
**This requires that the interacting player has the specified section permission set to true to be able to access the NPC**
{% endhint %}
{% hint style="info" %}
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 ](https://wiki.citizensnpcs.co/NPC_Commands)for more info about the clickable commands.
{% endhint %}
**3.** ***Optional:*** Disable the [back button inside the config.yml](https://gpplugins.gitbook.io/economyshopgui/file-configuration/config.yml#disable-back-button) 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 \ \](/economyshopgui/basics/commands.md#commands)
## How to setup the DiscordSRV hook:
The [DiscordSRV hook](https://wiki.gpplugins.com/economyshopgui/file-configuration/config.yml#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](https://docs.discordsrv.com/Installation/).
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 ](https://docs.discordsrv.com/installation/initial-setup/#set-up-a-basic-channel-relay)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](https://wiki.gpplugins.com/economyshopgui/file-configuration/config.yml#discordsrv-hook).
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.
{% hint style="warning" %}
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.
{% endhint %}
#### 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
{% hint style="success" %}
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.
{% endhint %}
#### 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.
{% hint style="success" %}
Congratulations, you successfully migrated to the new shop structure. That wasn't hard, was it?
{% endhint %}
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: and
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
## How to use price modifiers via commands: *\*Premium only*
Price modifiers applied via commands are static modifiers that apply to the base price of a shop item for a specific player. These modifiers can be either be set for a whole section at once, or a specific shop item's buy and/or sell price.
* The `/eshop modifiers set SECTION/ITEM ` subcommand allows you to set new price modifiers for a player
* The value of price modifiers are a percent where 100% is the base price, for example:
* -75% means that the item will only cost 25% of the original price
* 350% means that the item will cost 3.5 times as much as the original price
* The `/eshop modifiers remove SECTION/ITEM [itemLoc] ` command will remove the specific price multiplier from the player
* The `/eshop modifiers check ` displays all price modifiers for the specific player
* This command can be used with the SECTION, ITEM or TYPE argument to search specific modifier(s)
## 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, you will click an item to open a different section. 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**
{% hint style="warning" %}
Make sure to reload the plugin after every step using `/sreload`
{% endhint %}
1. Create the primary section **Blocks**
* Use the `/editshop addsection` command
2. Create the sections **Wood**, **Stone** and **Glass**
* Use the `/editshop addsection` command
3. Enable the *sub-section* property for the **Wood**, **Stone** and **Glass Section**
* Use`/editshop editsection add sub-section true`
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 add section ` 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:
```yaml
enable: true
slot: 19
title: ''
hidden: false
display-item: false
fill-item:
material: AIR
nav-bar:
mode: INHERIT
item:
material: GRASS_BLOCK
displayname: '&2&lBlocks'
name: '&2&lBlocks'
```
The section config of **Wood** should look something like this
```yaml
enable: true
item:
material: OAK_LOG
displayname: Wood
slot: 4
sub-section: true
```
The shops config of **Blocks** should look somewhat like this
```yaml
pages:
page1:
items:
1:
material: OAK_PLANKS
displayname: Wood Blocks
buy: -1.0
sell: -1.0
section: Wood
2:
material: COBBLESTONE
displayname: Stone Blocks
buy: -1.0
sell: -1.0
section: Stone
3:
material: GLASS
displayname: Glass Blocks
buy: -1.0
sell: -1.0
section: Glass
```
## How to use ShopStands:
ShopStands 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.
ShopStands are similar to sign shops, but with a modern touch!
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](/economyshopgui/file-configuration/config.yml.md#shopstands-module) inside the config.yml
* After enabling it, reload the plugin using `/sreload`
* Give yourself a new shop stand to place down
* `/eshop shopstands give `
* 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
## Using JsonShopForms
The vanilla forms from the [Cumulus API](https://geysermc.org/wiki/geyser/forms/) are great for devices with smaller screens or even toutch screens which have no way of hovering over a item to see its tooltip, but they have some heavy limitations as they use a list view of items/buttons and ruin the look of the shop menus as the Geyser team did not design them for this.
To solve this, EconomyShopGUI has support for custom JSON forms which are designed to look like a regular chest with a grid layout of items.\
These forms have several advantages over vanilla forms or even the regular Geyser translated GUI's such as:
* Support for every inventory size (Unlike regular Geyser inventory's only support a half/full sized inventory)
* Easy support for custom GUI textures (Just like ItemsAdder font glyphs in titles)
* Easy support for custom item textures
* Items support stack sizes and durability bars, unlike regular forms which use plain item images as the icon
* A grid style instead instead of the list view of regular forms
* Small detail, but not to miss: No floating chest above the player when the shop is open
{% hint style="success" %}
Note that you can still use the default list styled forms without requiring the custom json pack, just enable [bedrock forms](/economyshopgui/file-configuration/config.yml.md#bedrock) inside the config and reload the plugin using /sreload
{% endhint %}
#### How to install and use
To be able to use forms at all for Bedrock players, you will need to setup Geyser and Floodgate on your server and enable the regular forms option.\
But assuming you already did that:
1. Purchase and download the pack from here or here, extract it to your desktop or open it up using a tool like WinRar
2. Drag and drop the 'JsonShopForms - Base - v1.0.0.zip' or .mcpack file inside the /packs folder of the Geyser-Spigot or Geyser-Velocity plugin folder
1. Folder name depends on the server type you are using
3. Enable the [use-grid-forms](/economyshopgui/file-configuration/config.yml.md#custom-bedrock-forms) config option in the config
4. Last step, simply restart your server so Geyser can reload the pack and you should see the custom forms when browsing /shop on bedrock clients!
### Using custom GUI textures
{% hint style="info" %}
This feature requires the custom JsonShopForms pack and uses the title of the inventory to tell the custom forms what texture to use as the background
{% endhint %}
#### Using the included textures
By default the pack comes with example files and textures out of the box for the latest default shop of the plugin as of version 7.2.1 or 6.3.1 of the premium version, and are located within a sub folder of the downloaded .zip which makes it really easy to get started
1. Within the downloaded .zip file there should be a sub folder called 'examples', from there copy the 'JsonShopForms - Example - v1.0.0.zip' or .mcpack file inside the /packs folder of the Geyser-Spigot or Geyser-Velocity plugin folder
1. Folder name depends on the server type you are using
2. From the /examples subfolder within the zip, also take out the config.yml, /shops and /sections folders within the EconomyShopGUI folder and replace them with your files
1. If you have existing settings in your config.yml, just make sure you copy over the navigation bar settings/items
2. If you want to keep your existing language file, simply copy over the `inventory-main-shop-title-bedrock` entry to your existing file
3. Enable the [use-grid-forms](/economyshopgui/file-configuration/config.yml.md#bedrock) config option in the config
4. Last step, simply restart your server so Geyser can reload the pack and ESGUI can reload its shops correctly and you should see the custom forms when browsing /shop on bedrock clients!
#### Using your own textures
If you bought your own GUI textures or have created some yourself, you can use these aswell instead of the examples
{% hint style="warning" %}
Before you start, make sure every texture file does **not** include any texture overflow of transparent pixels or anything else, we only need the texture!
* You can simply do this by uploading your texture to a site like [https://imageonline.io/trim-transparent/ ](https://imageonline.io/trim-transparent/)and downloading your image after that
{% endhint %}
1. Start by extracting the 'JsonShopForms - Base.zip' into a folder (on your desktop or any other place) and extract the files there
2. Then open /textures and then the /ui folder, copy and paste your custom GUI textures(without any transparent pixels, see above) here
3. Now open the /ui folder from within the root folder of the pack where you will see 3 different .json files, open the shop\_server\_form.json file in a text editor
4. With the file open, scroll down to the "custom\_texture": block, in which you will see the "controls": key which should be empty if you grabbed the Base version in step 1, this is the place you will define custom textures and/or offsets
5. To add a custom texture override, simply add something like this inside the two brackets:
1. Where *main\_shop* in `main_shop@shop_form.custom_texture_variant` is the key, which can be anything you want which helps you indentify the texture (Just make sure its not duplicated between different texture overrides)
2. `#texture_name` should be set to the file name of the texture you just copied into the /textures/ui folder in step 2 WITHOUT the file extension
3. If you have trimmed the texture file using something like the site mentioned earlier, you will have the raw sizes of your file, so on windows simply right click the file -> properties -> Details tab -> and set the `$texture_size` var to the width and height of your texture file
4. Optionally you can set a offset for the image to align itself properly over the items grid using the $offset var
{% hint style="info" %}
Two things to note here or else your texture will not work:
* The file name (without extension) cannot be longer then 16 characters
* Since bedrock JSON does not natively support matching a exact string, you will need to make sure that the same name cannot contain inside another texture's file name
* For example 'shop\_6.png' is the same as 'shop\_6\_paginated.png' for the pack atleast
{% endhint %}
Example main shop texture entry:
```json
{
"main_shop@shop_form.custom_texture_variant": {
"property_bag": {
"#texture_name": "main_shop" // Note that there is no .png after the name
},
"$texture_size": [176, 136],
"$offset": [0, 5]
}
}
```
6. Now copy the config section you just created to the controls list and repeat it for every texture you may want to use
* Look at the 'JsonShopForms - Example.zip' for a reference
7. Now change the version of the pack inside the `manifest.json` within the root folder, from 1.0.0 to something like 1.0.1
{% hint style="success" %}
Always change the latter version number, as it will save you time when updating the pack when a newer version comes out
{% endhint %}
8. When you made sure every file's JSON syntax is valid by using a site like [jsonlint ](https://jsonlint.com/)after you edited them, use a tool like 7-Zip to zip the contents of the folder again into a `JsonShopForms v1.0.1.zip` file
9. Drag and drop the .zip you just created into the /packs folder of Geyser and make sure to delete the old one
10. To tell ESGUI to use one of your textures for a certain GUI, you will need to set the bedrock title to something like ":texture:\:"
* Where is the actual file name of your texture(without the folder path) like we configured inside the 'shop\_server\_form.json' #texture\_name variable for that texture can be replaced with the title you want to appear on top of the GUI
Two options here depending on the GUI your texture is targetting:
* When you want to use this texture on shop pages, this can be done by setting the [bedrock-title](/economyshopgui/file-configuration/sections.yml.md#bedrock-title) config option for sections or for shop pages if you want different textures per shop (page)
* When your texture is for the main shop or transaction screens, you will have to copy the original language file key, and add `-bedrock` to the end of the key name, for example:
* Copy the entry `inventory-main-shop-title-bedrock: "&8&lServer Shop"` to something like `inventory-main-shop-title`**`-bedrock`**`: ":texture:main_shop:&8&lServer Shop"` to use the 'main\_shop' texture for the main shop GUI
* Copy the entry `inventory-howmuchbuy-title: "&8Buying &a&l> &r&8%item%"` to something like `inventory-howmuchbuy-title`**`-bedrock`**`: ":texture:buy_screen:&8Buying &a&l> &r&8%item%"` to use the 'buy\_screen' texture for the buy GUI
11. It should now show the correct texture when you did everything correctly, just use /sreload to reload the config files
{% hint style="info" %}
If seeing no background texture at all when opening the GUI and only the item icons/title, it means the texture name inside the title was not found inside the configured 'shop\_server\_form.json' file
{% endhint %}
{% hint style="warning" %}
Note that JSON files are very picky on its actual structure, and forgetting or leaving a extra comma or a bracket, it may break and when the pack is loaded in Geyser it will just not work So its important to check the JSON syntax of the file after every edit, with a site like [jsonlint](https://jsonlint.com/)
{% endhint %}
{% hint style="warning" %}
Also note that EVERY change you make inside the pack and push the version to your server requires the smallest version number to change, so like 1.0.0 -> 1.0.1 -> 1.0.2 -> 1.0.3 etc, cause if you don't do it, bedrock players will still use the old version which is cached by the client
{% endhint %}
### Using custom item textures within the shop forms
This step requires a resource pack for your items, similar to how it works on java, but this resource pack is made for Geyser:
The easiest way I found on how to do this is by joining your server with a Fabric client using the [Rainbow](https://geysermc.org/download/?project=other-projects\&rainbow=expanded) mod from GeyserMC
1. Once inside your java server, make sure your client has the resource pack loaded for the items you want to get the textures from, and get the items inside your inventory
2. With the items in your inventory, type '/rainbow create ', followed by '/rainbow auto inventory' which will map the items from your inventory into Geyser compatible assests for you, its that easy!
3. After that simply use '/rainbow finish' to complete the resource pack and click the unlined text in the chat saying 'Wrote pack to disk' to open its folder on your PC
4. When the folder is open, drag and drop the pack.zip file into Geyser's /packs folder
5. Lastly, to have Geyser automatically map the items to your textures, you will also need top copy the mappings .json files from within the compiled folder from Rainbow where you got the pack.zip from, simply copy all .json files from the custom\_mappings folder into the custom\_mappings folder of Geyser, followed by a server restart
Thats it, when running Geyser on the same server as ESGUI, it will automatically map the items inside the forms to the custom textures!
#### Letting ESGUI handle the item mappings on server networks
This step should only be required if you run Geyser on a proxy server like Velocity or Bungeecord, as ESGUI cannot automatically map the items with their custom textures unlike when Geyser is installed on the same server But don't worry, this step is easier as creating the resource pack in the first place
1. Simply open the generated pack.json from rainbow (Or one thats already in your Geyser /packs folder)
2. Now open the textures folder and open the item\_texture.json file
3. With the file open in a text editor, look at what the 'textures' value is set to, it should be like 'textures/halloween/witch\_hat\_icon' or textures/399
4. This is the texture path, now simply set that path to the [bedrock-texture](/economyshopgui/file-configuration/shops.yml.md#bedrock-texture) item option for the shop item that uses this texture, this can be done inside the shops config
## Obtaining item indexes of shop items
In several places(for example to edit a item using commands or using price placeholders) you will need the item index of the item inside the shop configuration.
This can simply be obtained by hovering with your mouse over a shop item inside a shop, which will display a gray line by default which mentions the item's section and itemIndex.
{% hint style="danger" %}
Note that this lore is only visible to OP players or users with the permission 'EconomyShopGUI.eshop.itemindexes'!
{% endhint %}
{% hint style="warning" %}
Note that this lore is only vivible if the *'admin-lore'* entry is listed under the [config option *'lore-arrengement'*](/economyshopgui/file-configuration/config.yml.md#lore-arrangement)!
{% endhint %}
Example item with section 'Prefixes' and itemIndex 'page1.items.10'
