Essentials' "/buy" Command

Getting Started

This command is made possible by the popular Spigot plugin Skript (fork by bensku).
I (Toby) have searched the SkriptLang, SkriptHub, SkUnity, Spigot, Bukkit, and even PlanetMinecraft for similar scripts or plugins, but alas found nothing that did what I needed (even if it did more than I needed, I could've just removed certain features, but I couldn't even find that). I'm using this feature on my server the Rising Dawn Network so users can immediately purchase an item (with in-game currency) rather than going to a physical shop on the server. This script has been working well ever since, so I've decided to publish it for general use. Comments have been added to the script file so you may easily understand how almost everything works and how to properly set up this script.

This Skript has been tested to work with at least the following:
Skript = v2.4.1
SkQuery = v3.6.5
Minimum required version: v3.6.2*
skript-yaml = v1.3.2
Minimum required version: v1.2.1*
PaperSpigot = version git-Paper-162 (MC: 1.15.2)

Though this skript has been tested to work in 1.15.2, this should work with versions lower. If it doesn't, make sure of the following:
- The version of Skript you are using works with your server version
- The version of SkQuery you are using works with your server version
- The version of Essentials/EssentialsX you are using works with your server version
- The version of skript-yaml you are using works with your server version
- The version of Vault you are using works with your server version

If you've done all of the above and it still doesn't work, send me (Toby) a direct message on Discord or reply to the "Discussions" page on SkUnity and I'll see if I can help. If not, it might be a Skript bug. However, the #1 reason this skript is not working is because the plugins needed to run are not made for the server version you are running. Generally speaking, the main page of the plugin (be it on Bukkit or Spigot) has a small list of versions the plugin can work for; though some say 1.9-1.15, it doesn't necessarily mean the version you downloaded will work for that specific version you're running. Check the main page for details.

* = While these appear to be the lowest working versions for this script, they have not been tested; USE AT YOUR OWN RISK

DISCLAIMER & NOTICE

You Are Allowed to:
- Make edits to this file to best suit your needs.
You Are NOT Allowed to:
- Upload this file to other plugin-sharing sites without prior consent
- Upload this file to other plugin-sharing sites and calling it your own

TobyMinceraft IS NOT affiliated with:

  1. Mojang - the copyright-holders of "Minecraft"

  2. Njol - the Skript plugin's original creator

  3. bensku - the (current) maintainer of the Skript plugin

TobyMinceraft IS affiliated with:

  1. Rising Dawn Network (the server's owner)

Plugins / Skript Addons (Required)

Skript (fork by bensku)
- Download: https://github.com/SkriptLang/Skript/releases
- Continuously Maintained Docs: https://docs.skunity.com
- Unofficial Discord (Skript Chat): https://discord.gg/0l3WlzBPKX7WNjkf
- Unofficial Discord (SkUnity): http://discord.gg/q7UM6vJ

skript-yaml (by Sashie)
- Download: https://github.com/Sashie/skript-yaml/releases
- Docs: https://docs.skunity.com/syntax/search/addon:Skript-yaml

SkQuery (by TheLimeGlass)
- Download: https://github.com/SkQuery/SkQuery/releases
- Docs: https://docs.skunity.com/syntax/search/addon:SkQuery

Plugins / Skript Addons (Optional)

Essentials (fork by drtshock)
- Reason: Required if you want to configure prices in-game using /setworth
- Download: https://www.spigotmc.org/resources/essentialsx.9089/
- Wiki: https://github.com/EssentialsX/Essentials/wiki
- Discord Support: https://discord.gg/casfFyh

Vault (by Sleakes)
- Reason: Required by Essentials
- Download: https://dev.bukkit.org/projects/vault

Installing

Now that you've got the required and optional plugins installed, it's time to dive into getting this skript onto your server.

  1. If you haven't done so already, download the file from the SkUnity page (if you want me to also upload to Spigot, let me know in the "Discussions" page on SkUnity)
    Direct link to download: https://forums.skunity.com/resources/skworth.1029/

  2. Make sure you have the required plugins as mentioned above; restart server once you've added them

  3. Upload the skript file to your server in the folder plugins/Skript/scripts

  4. Restart the server or run "/sk reload worth.sk" to load the Skript file

Making Sense of this Skript

At first glance, this may seem like it's all over the place, but I can assure you after reading through this guide, you'll understand how this Skript works. As time goes by, I'll be making the Skript faster and (hopefully) easier to understand (no promises), and adding more features such as update checking.

Config/Script File Version: 1.1

options
- This section will cover a lot of the internal things that you can configure.
- You can configure the messages in the skript, but since they are in the command code, they are more apt to breaking; be careful!
- Should you break something beyond repair, download the script again, replace the file on your server, and re-edit the file.

file-location (string)
- Default value: plugins/Essentials/worth.yml
- The location at which your custom "worth.yml" file is, IF it is different than the default file from Essentials.
- While this allows you to use your own worth.yml files from other plugins (if there are any), it is sensitive as if you do not specify the ".yml" extension, the file will not be properly loaded
- If this skript does not find the worth.yml file at either of the two locations, it will automatically disable itself. To re-enable it, simply type "/skript:sk enable worth.sk" in-game or remove the "/" and enter it in console

worth (string in quotes)
- Default value (including quotes): "worth"
- This is an internal option and should only be changed if another yml-based skript file uses the cache storage name as the same thing.
- Only change this value if you know what you are doing!

tag (string)
- Default value: &7[&6Essentials&7]&e
- What you want to show up before the configured chat messages sent by this Skript (color and formatting codes supported)
- Also commonly referred to as a "prefix"

offset (integer)
- Default value: 10- This is in case you want the buy price to be higher than the selling price of your items (calculated last)- Calculation is made in the following formula:SellingPriceOfItem X Offset = PurchasePriceOfItem
- Example: if an item is worth $7 (using the Essentials /sell command) and you set the offset to 2, the price to purchase the item will be $14 (7x2=14)
- If you don't want an offset (if you want items to be bought at same price as sold), set this value to 1. The file has a fail-safe to prevent you from having shop items for lower than their worth value.

balance (string)
- Default value: player's balance
- This is used quite a bit in this Skript, as it controls whether or not the player has enough money to purchase the requested item.
- If you aren't using Essentials or a vault-compatible economy plugin and instead using your own Skript variable, you can specify it here. Here's an example of what I'm using on the Rising Dawn Network HardcorePlus server:
balance: {doritos::%player's uuid%}
- If you are not using a Vault-compatible economy plugin or Skript, then this skript file will not work!

item-purchase-permission (string)
- Default value: essentials.sell
- What permission do you want players to have to be able to purchase items? This is handy if you want players to only use the command in certain worlds (plugins such as LuckPerms and PermissionsEx support per-world permissions; use Google to find out how)
- Default permission is the selling permission from the Essentials plugin, but can be almost ANYTHING

item-worth-permission (string)
- Default value: essentials.worth
- What permission do you want players to have to be able to see an item's worth and cost? Also handy if you use per-world permissions.
- Again, the default is that from the Essentials plugin, but (again) can be almost ANYTHING.

admin-notify-permission (string)
- Default value: skworth.notify
- What permission do you want players to have to be able to see when another player has purchased an item? You can also configure if console receives these messages

notify-console (boolean)
- Default value: true
- Do you want item purchase messages to be sent to the server console?
- This is true by default, but allows true or false

notify-admins (boolean)
- Default value: true
- Do you want admins to see when players purchase items using this script?
- This is true by default, but allows true or false

inventory-space (integer)
- Default value: 1
- How many inventory slots do you want the player to have before they receive their items?
- When the player asks for an item using /buy, they must have at least 1 space in order to receive the item, otherwise the transaction will be cancelled.
- By default, Essentials doesn't drop extra items on the ground if the player's inventory is full; to bypass this, set this value to 0 and set the "drop-items-if-full" value in the Essentials config.yml to "true". If you are not using Essentials, you do not have to worry about the items not being given to the player; if they don't get the items because the lag was cleared with a plugin such as ClearLag, unfortunately there isn't much you can do about it, however a purchase message will be automatically sent to console when a user buys something, the total used to purchase the item, and amount of items bought
- Also by default, Essentials limits giving players items to a max of 64. I am not sure if this value can be changed, and will not be doing so here.

console-startup (boolean)
- Default value: true
- Do you want this skript to send a message every time the skript is loaded / re-loaded?
- Set this value to false if you'd rather not spam the console

Permissions & Commands

This Skript uses permissions rather than server operator status to run the commands. They are as follows:
- essentials.worth = Access to the /skworth command (for ease of use with Essentials) (configurable)
- essentials.sell = Access to the /buy command (for ease of use with Essentials) (configurable)
- skworth.notify = Used to send admins notifications when someone uses the /buy command

-= Commands =-

/skbuy
Description: Purchase an item in-game; usable by players ONLY
Aliases: /skworth:skbuy, /buy, /essentials:buy, /purchase, /skworth:purchase
Usage: /buy <item_name> [<quantity>]
Example: /buy oak_log 2
Permission: essentials.sell (default - configurable)
Note: if second argument (quantity) is not specified, will default to 1

/skworth
 Aliases: /cost, /essentials:cost, /skworth:cost, /skworth:skworth, /skworth:cost
Description: Get both the selling value and purchase price of an item; used by BOTH players and console
Usage: /skworth <item_name> [<quantity>]
 Example: /skworth oak_log 2 = Selling price of 2 Oak Logs & Purchase price of 2 Oak Logs
Permission: essentials.worth (default - configurable)
Note: if second argument (quantity) is not specified, will default to 1

/skworthconfig
Aliases: /skworth:skworthconfig
Description: View all of the script's configurable options directly in-game or in console; executable by players (if you're in console, go view the file yourself)
Usage: /skworthconfig
Example: /skworthconfig
Permission: skworth.admin (default - configurable)

Additional Notes

  1. This Skript file has a fail-safe; if neither the Essentials worth file nor your custom worth file exist in the locations you have specified, the skript will automatically disable itself.

  2. The "/buy" command can ONLY be used by players in SURVIVAL mode. The "/buy" command can ONLY be used by players; "/skworth" can be used by console and players

  3. If you make an edit to your worth.yml file, simply give the skript a reload, and it will properly update values in the memory

  4. If you discover the skript worth values of items do not match those specified in your worth.yml file (and you have not made any significant changes to the actual code - options are fine), simply give the skript file a reload and you should be fine. If not, go to the Discussions tab of the resource page and send a message

  5. DO NOT leave a review asking for support - This gives the script a bad ranking, and makes you seem like a terrible person to others; only the creator of the plugin/script can leave a comment on a review, while any other person can post a comment in the "Discussions" tabs; so if a user has an answer to your question you put in the review section, the only way they'll be able to help you is if they send you a direct message. TL;DR use the Discussions tab to ask for support; I (Toby) am not very active on Spigot or SkUnity, so send me a direct message instead on Discord: TobyMinceraft#5995 (don't send a friend request; they will be ignored); you can also find me on the SkUnity discord server and can tag me there if needed.

  6. This script file DOES NOT let you set the selling worth of an item using a command; that is controlled by Essentials (or any other plugin that has that feature); if you add an item manually, reload the script for the changes to take effect