# Tokens Wiki Homepage

### Welcome to the wonderful land of the Tokens Official Documentation!

These documents are a work in progress as an upgrade from the preexisting [GitHub Wiki](https://github.com/TheCoolestPaul/Tokens/wiki). I am making this change for three reasons: 

1. I need to learn gitbook for other projects.
2. Gitbook looks much nicer than the default GitHub Wiki.
3. Gitbook is easier for me to make changes to/update.

Please, bare with me as I embark on trying to make this new documentation site contain more information. I am learning after-all.


# Commands

## Tokens Core Commands

> These commands are the backbone to Tokens.

| Command                              | Permission      | Description                                      |
| ------------------------------------ | --------------- | ------------------------------------------------ |
| `/tokens`                            | `tokens.use`    | Displays your Token balance.                     |
| `/tokens <username>`                 | `tokens.others` | Displays another user's Token balance.           |
| `/tokens buy <number>`               | `tokens.buy`    | Purchases a number of Tokens.                    |
| `/tokens give <player> <number>`     | `tokens.give`   | Gives a number of your Tokens to another player. |
| `/tokens set <username> <number>`    | `tokens.set`    | Set another user's Token balance.                |
| `/tokens add <username> <number>`    | `tokens.add`    | Adds Tokens to another user's balance.           |
| `/tokens remove <username> <number>` | `tokens.remove` | Removes Tokens from another user's balance.      |
| `/tokens reload`                     | `tokens.reload` | Reloads the plugin's configuration files.        |

## Tokens Redeem Commands

{% hint style="danger" %}
Each redeem command needs it's dependent plugin loaded into the server! You can learn more about that [here](/supported-plugins/plugins).
{% endhint %}

| Command                               | Permission               | Description                                                                                                  |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `/redeem`                             | `tokens.redeem`          | Displays very helpful text on how to redeem your Tokens.                                                     |
| `/redeem mcmmo <skill_name> <number>` | `tokens.redeem.mcmmo`    | Redeems a number of Tokens to boost a [mcMMO level](https://mcmmo.org/wiki/Primary_Skills) of your choosing. |
| `/redeem factions <number>`           | `tokens.redeem.factions` | Redeems a number of Tokens to boost a player's faction power.                                                |
| `/redeem money <number>`              | `tokens.redeem.sell`     | Redeems Tokens for Vault Money.                                                                              |


# Permissions

## Recommended permissions *everyone* has:

* *tokens.use* **/tokens** The base command for the plugin.
* *tokens.redeem* **/redeem** The command that lets players redeem Tokens.
* *tokens.give* **/tokens give** The command that allows players to give Tokens to each-other.

## Recommended permissions *admins* have:

* *tokens.others* **/tokens < username >** Used to see how many Tokens another player has.
* *tokens.set* **/tokens set** Used to set a player's Token amount.
* *tokens.add* **/tokens add** Used to add Tokens to a player.
* *tokens.remove* **/tokens remove** Used to take Tokens from a player.

## Recommended permissions *owners* have:

* *tokens.reload* **/tokens reload** Used to reload Tokens configuration files. Found in `/plugins/Tokens/`


# Default Files

### [config.yml](https://github.com/TheCoolestPaul/Tokens/blob/master/src/main/resources/config.yml)

### [messages.yml](https://github.com/TheCoolestPaul/Tokens/blob/release/src/main/resources/messages.yml)

### [keys.yml](https://github.com/TheCoolestPaul/Tokens/blob/release/src/main/resources/keys.yml)

With [**facelift-2**](https://github.com/TheCoolestPaul/Tokens/pull/78) comes a new way Tokens handles its `messages.yml` file. Tokens will now generate the things it needs in this file. Example: If there is an update that adds another message, Tokens will automatically add the new line to the file so you don't have to manually compare the last version's file to the new version each update.

Of course this doesn't apply to `keys.yml` because that file is entirely up to the user to fill out.


# Plugins

Tokens utilizes two kinds of plugin support, automatic support, and manual support. Manual support requires editing the `config.yml` file (found in the `/plugins/Tokens/` folder) in order to be used. mcMMO and Factions are an example of manual support plugins. ShopGUI+ and BossShopPro are a good example of automatically supported plugins.

## Manually Supported Plugins

* mcMMO
* Factions
* Vault Economies
* CombatLogX

## Automatically Supported Plugins

* Prison
* RankUp
* RankUp3
* [BossShopPro](/supported-plugins/bossshoppro)
* [PlaceholderAPI](/supported-plugins/placeholderapi)
* [ShopGui+](/supported-plugins/shopguiplus)


# BossShopPro

Tokens automatically implements into BossShopPro in three ways, as Points, as Rewards, and as a PriceType. For each implementation you can simply put `tokens`as the value. To see an example shop [click here](https://pastebin.com/UKhgMvxk), or you can find the usage for each type below.

## Rewards

Rewards in BSP is what you get when you purchase something. Here is an example of a shop item that exchanges $100 currency for 1 Token.

```
Money100forToken1:
    PriceType: money
    Price: 100
    MenuItem:
      - type:EMERALD
      - amount:1
      - name:&61 Token
      - 'lore:&cPrice: $%price%'
    Message: '&aYou''ve purchased &e%reward%&a for &e$%price%'
    InventoryLocation: 1
    ExtraPermission: ''
    RewardType: tokens
    Reward: 1
```

{% hint style="warning" %}
Notice how the reward type is `tokens` all lowercase with an 's' on the end.
{% endhint %}

## PriceType

PriceTypes in BSP is what you pay to purchase something. Here is an example of a shop item that exchanges 1 Token for $100 currency.

```
Token1For100Money:
    PriceType: tokens
    Price: 1
    MenuItem:
      - type:DIAMOND
      - amount:1
      - name:&6$100 Money
      - 'lore:&cPrice: %price%'
    Message: '&aYou''ve purchased &e$%reward%&a for &e%price%'
    InventoryLocation: 2
    ExtraPermission: ''
    RewardType: MONEY
    Reward: 100
```

{% hint style="warning" %}
Notice how the PriceType is `tokens` all lowercase with an 's' on the end.
{% endhint %}


# ShopGUI+

Tokens automatically hooks into ShopGUI+.

[ShopGUI+ Spigot Link](https://www.spigotmc.org/resources/6515/)

In order to use Tokens in ShopGUI+ you need to edit the `config.yml` file in the `/plugins/ShopGUIPlus/` folder. In the config file you need to add `- CUSTOM` below `economyTypes:` See below for an example

```
economyTypes:
    - VAULT
    - CUSTOM
```


# PlaceholderAPI

Tokens automatically hooks into PlaceholderAPI.

[PlaceholderAPI Spigot Page](https://www.spigotmc.org/resources/6245/)

Tokens has TWO placeholder tags, both with the prefix `tokens`.

* `%tokens_getTokens%`
* `%tokens_getTokensFormatted%`

`%tokens_getTokensFormatted%`will return a number WITH commas and `%tokens_getTokens%`will return just a number without commas.